CLAUDE.md

Project root. Cursor users: save as AGENTS.md.

Part of Build Your First MCP Server (TypeScript) by Admin

Project rules: my first MCP server

What we are building

A small MCP server in TypeScript that gives an AI assistant three tools over a local notes folder: list_notes, read_note and search_notes. It runs over stdio and is used from Claude Code or Claude Desktop.

Stack

Node.js 20+, TypeScript, ES modules
@modelcontextprotocol/sdk (official TypeScript SDK)
zod for tool input schemas

Rules

Never write to stdout except through the MCP transport. Use console.error for logs (stdout is the protocol channel).
Every tool validates input with zod and returns a clear text error instead of throwing.
Read-only: no tool may create, change or delete files.
Only files inside NOTES_DIR can be read. Resolve paths and reject anything outside it (no ../ escapes, no symlinks out).
Keep tool descriptions short and specific: the model chooses tools by reading them.
After each change run: npm run build. Fix type errors before moving on.

Source, 18 lines

# Project rules: my first MCP server

## What we are building
A small MCP server in TypeScript that gives an AI assistant three tools over a local notes folder:
list_notes, read_note and search_notes. It runs over stdio and is used from Claude Code or Claude Desktop.

## Stack
- Node.js 20+, TypeScript, ES modules
- @modelcontextprotocol/sdk (official TypeScript SDK)
- zod for tool input schemas

## Rules
- Never write to stdout except through the MCP transport. Use console.error for logs (stdout is the protocol channel).
- Every tool validates input with zod and returns a clear text error instead of throwing.
- Read-only: no tool may create, change or delete files.
- Only files inside NOTES_DIR can be read. Resolve paths and reject anything outside it (no ../ escapes, no symlinks out).
- Keep tool descriptions short and specific: the model chooses tools by reading them.
- After each change run: npm run build. Fix type errors before moving on.