CLAUDE.md

1# CLAUDE.md
2 
3This file provides guidance to Claude Code when working with code in this repository.
4 
5## Project Overview
6 
7Official MCP reference server implementations. This is an npm workspaces monorepo containing 7 servers (4 TypeScript, 3 Python) under `src/`. Each server is a standalone package published to npm or PyPI.
8 
9## Monorepo Structure
10 
11```
12src/
13  everything/          TS  @modelcontextprotocol/server-everything    (reference server, all MCP features)
14  filesystem/          TS  @modelcontextprotocol/server-filesystem    (file operations with Roots access control)
15  memory/              TS  @modelcontextprotocol/server-memory        (knowledge graph persistence)
16  sequentialthinking/  TS  @modelcontextprotocol/server-sequential-thinking  (step-by-step reasoning)
17  fetch/               Py  mcp-server-fetch                           (web content fetching)
18  git/                 Py  mcp-server-git                             (git repository operations)
19  time/                Py  mcp-server-time                            (timezone queries and conversion)
20```
21 
22## Build & Test Commands
23 
24### TypeScript servers
25 
26```bash
27# Single server
28cd src/<server> && npm ci && npm run build && npm test
29 
30# All TS servers from root
31npm install && npm run build
32```
33 
34- Build: `tsc` (target ES2022, module Node16, strict mode)
35- Tests: **vitest** with `@vitest/coverage-v8` (required for new tests)
36- Node version: **22**
37 
38### Python servers
39 
40```bash
41cd src/<server> && uv sync --frozen --all-extras --dev
42 
43# Run tests (if tests/ or test/ directory exists)
44uv run pytest
45 
46# Type checking
47uv run pyright
48 
49# Linting
50uv run ruff check .
51```
52 
53- Build system: **hatchling** (`uv build`)
54- Package manager: **uv** (not pip)
55- Python version: **>= 3.10** (per-server `.python-version` file)
56- Type checking: **pyright** (enforced in CI)
57- Linting: **ruff**
58 
59## Code Style
60 
61### TypeScript
62 
63- ES modules with `.js` extension in import paths
64- Strict TypeScript typing for all functions and variables
65- Zod schemas for tool input validation
66- 2-space indentation, trailing commas in multi-line objects
67- camelCase for variables/functions, PascalCase for types/classes, UPPER_CASE for constants
68- kebab-case for file names and registered tools/prompts/resources
69- Verb-first tool names (e.g., `get-file-info`, not `file-info`)
70- Imports grouped: external first, then internal
71 
72### Python
73 
74- Type hints enforced via pyright
75- Async/await patterns (especially in fetch server with pytest-asyncio)
76- Follow existing module layout per server
77 
78## Contributing Guidelines
79 
80**Accepted:** Bug fixes, usability improvements, enhancements demonstrating MCP protocol features (Resources, Prompts, Roots -- not just Tools).
81 
82**Selective:** New features outside a server's core purpose or highly opinionated additions.
83 
84**Not accepted:** New server implementations (use the [MCP Server Registry](https://github.com/modelcontextprotocol/registry)), README server listing changes.
85 
86## CI/CD Pipeline
87 
88Both TypeScript and Python workflows use **dynamic package detection** (find + jq matrix strategy):
89 
901. `detect-packages` -- finds all `package.json` / `pyproject.toml` under `src/`
912. `test` -- runs tests per package
923. `build` -- compiles and type-checks per package
934. `publish` -- on release events only (npm for TS, PyPI trusted publishing for Python)
94 
95## MCP Protocol Reference
96 
97The repo is configured with an MCP docs server (`.mcp.json`) pointing to `https://modelcontextprotocol.io/mcp`. For schema details, reference `https://github.com/modelcontextprotocol/modelcontextprotocol/tree/main/schema` which contains versioned schemas in JSON and TypeScript formats.
98 
99## Key Patterns
100 
101- Each server registers capabilities via `registerTools(server)`, `registerResources(server)`, `registerPrompts(server)` functions
102- Tool annotations: set `readOnlyHint`, `idempotentHint`, `destructiveHint` per MCP spec
103- Transport support: stdio (default), SSE (deprecated), Streamable HTTP
104- All PRs are reviewed against the [PR template](.github/pull_request_template.md) checklist -- ensure MCP docs are read, security best practices followed, and changes tested with an LLM client
105