Two files, one repository
modelcontextprotocol/servers ships 2 formats across 2 indexed files. The question worth asking is whether the second one says anything the first does not.
CompareCLAUDE.md ↔ AGENTS.md
| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 18 | 6 | 0% |
| Commands | 0 | 7 | 6 | 0% |
| Section tags | 3 | 7 | 0 | 30% |
What each file covers
Sections
0 shared · 18 only in A · 6 only in B- − CLAUDE.md
- − Project Overview
- − Monorepo Structure
- − Build & Test Commands
- − TypeScript servers
- − Single server
- − All TS servers from root
- − Python servers
- − Run tests (if tests/ or test/ directory exists)
- − Type checking
- − Linting
- − Code Style
- − TypeScript
- − Python
- − Contributing Guidelines
- − CI/CD Pipeline
- − MCP Protocol Reference
- − Key Patterns
- + MCP "Everything" Server - Development Guidelines
- + Build, Test & Run Commands
- + Code Style Guidelines
- + Extending the Server
- + High-level
- + When adding a new feature
Commands
0 shared · 7 only in A · 6 only in B- − git/ Py mcp-server-git (git repository operations)
- − npm install && npm run build
- − uv run pytest
- − uv run pyright
- − uv run ruff check .
- − tsc
- − uv build
- + npm run build
- + npm run watch
- + npm run start:stdio
- + npm run start:sse
- + npm run start:streamableHttp
- + npm run prepare
Section tags
3 shared · 7 only in A · 0 only in B- − setup
- − lint-format
- − architecture
- − types
- − deployment
- − monorepo
- − agent-behaviour
- build
- test
- code-style
Line diff
modelcontextprotocol/servers · CLAUDE.md
@@ −1 @@
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
modelcontextprotocol/servers · src/everything/AGENTS.md
@@ +1 @@
1# MCP "Everything" Server - Development Guidelines
2
3## Build, Test & Run Commands
4
5- Build: `npm run build` - Compiles TypeScript to JavaScript
6- Watch mode: `npm run watch` - Watches for changes and rebuilds automatically
7- Run STDIO server: `npm run start:stdio` - Starts the MCP server using stdio transport
8- Run SSE server: `npm run start:sse` - Starts the MCP server with SSE transport
9- Run StreamableHttp server: `npm run start:streamableHttp` - Starts the MCP server with StreamableHttp transport
10- Prepare release: `npm run prepare` - Builds the project for publishing
11
12## Code Style Guidelines
13
14- Use ES modules with `.js` extension in import paths
15- Strictly type all functions and variables with TypeScript
16- Follow zod schema patterns for tool input validation
17- Prefer async/await over callbacks and Promise chains
18- Place all imports at top of file, grouped by external then internal
19- Use descriptive variable names that clearly indicate purpose
20- Implement proper cleanup for timers and resources in server shutdown
21- Handle errors with try/catch blocks and provide clear error messages
22- Use consistent indentation (2 spaces) and trailing commas in multi-line objects
23- Match existing code style, import order, and module layout in the respective folder.
24- Use camelCase for variables/functions,
25- Use PascalCase for types/classes,
26- Use UPPER_CASE for constants
27- Use kebab-case for file names and registered tools, prompts, and resources.
28- Use verbs for tool names, e.g., `get-annotated-message` instead of `annotated-message`
29
30## Extending the Server
31
32The Everything Server is designed to be extended at well-defined points.
33See [Extension Points](docs/extension.md) and [Project Structure](docs/structure.md).
34The server factory is `src/everything/server/index.ts` and registers all features during startup as well as handling post-connection setup.
35
36### High-level
37
38- Tools live under `src/everything/tools/` and are registered via `registerTools(server)`.
39- Resources live under `src/everything/resources/` and are registered via `registerResources(server)`.
40- Prompts live under `src/everything/prompts/` and are registered via `registerPrompts(server)`.
41- Subscriptions and simulated update routines are under `src/everything/resources/subscriptions.ts`.
42- Logging helpers are under `src/everything/server/logging.ts`.
43- Transport managers are under `src/everything/transports/`.
44
45### When adding a new feature
46
47- Follow the existing file/module pattern in its folder (naming, exports, and registration function).
48- Export a `registerX(server)` function that registers new items with the MCP SDK in the same style as existing ones.
49- Wire your new module into the central index (e.g., update `tools/index.ts`, `resources/index.ts`, or `prompts/index.ts`).
50- Ensure schemas (for tools) are accurate JSON Schema and include helpful descriptions and examples.
51 `server/index.ts` and usages in `logging.ts` and `subscriptions.ts`.
52- Keep the docs in `src/everything/docs/` up to date if you add or modify noteworthy features.
53
@@ −1 +1 @@
1−# CLAUDE.md
1+# MCP "Everything" Server - Development Guidelines
22
3−This file provides guidance to Claude Code when working with code in this repository.
3+## Build, Test & Run Commands
44
5−## Project Overview
5+- Build: `npm run build` - Compiles TypeScript to JavaScript
6+- Watch mode: `npm run watch` - Watches for changes and rebuilds automatically
7+- Run STDIO server: `npm run start:stdio` - Starts the MCP server using stdio transport
8+- Run SSE server: `npm run start:sse` - Starts the MCP server with SSE transport
9+- Run StreamableHttp server: `npm run start:streamableHttp` - Starts the MCP server with StreamableHttp transport
10+- Prepare release: `npm run prepare` - Builds the project for publishing
611
7−Official 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.
12+## Code Style Guidelines
813
9−## Monorepo Structure
14+- Use ES modules with `.js` extension in import paths
15+- Strictly type all functions and variables with TypeScript
16+- Follow zod schema patterns for tool input validation
17+- Prefer async/await over callbacks and Promise chains
18+- Place all imports at top of file, grouped by external then internal
19+- Use descriptive variable names that clearly indicate purpose
20+- Implement proper cleanup for timers and resources in server shutdown
21+- Handle errors with try/catch blocks and provide clear error messages
22+- Use consistent indentation (2 spaces) and trailing commas in multi-line objects
23+- Match existing code style, import order, and module layout in the respective folder.
24+- Use camelCase for variables/functions,
25+- Use PascalCase for types/classes,
26+- Use UPPER_CASE for constants
27+- Use kebab-case for file names and registered tools, prompts, and resources.
28+- Use verbs for tool names, e.g., `get-annotated-message` instead of `annotated-message`
1029
11−```
12−src/
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−```
30+## Extending the Server
2131
22−## Build & Test Commands
32+The Everything Server is designed to be extended at well-defined points.
33+See [Extension Points](docs/extension.md) and [Project Structure](docs/structure.md).
34+The server factory is `src/everything/server/index.ts` and registers all features during startup as well as handling post-connection setup.
2335
24−### TypeScript servers
36+### High-level
2537
26−```bash
27−# Single server
28−cd src/<server> && npm ci && npm run build && npm test
38+- Tools live under `src/everything/tools/` and are registered via `registerTools(server)`.
39+- Resources live under `src/everything/resources/` and are registered via `registerResources(server)`.
40+- Prompts live under `src/everything/prompts/` and are registered via `registerPrompts(server)`.
41+- Subscriptions and simulated update routines are under `src/everything/resources/subscriptions.ts`.
42+- Logging helpers are under `src/everything/server/logging.ts`.
43+- Transport managers are under `src/everything/transports/`.
2944
30−# All TS servers from root
31−npm install && npm run build
32−```
45+### When adding a new feature
3346
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
41−cd src/<server> && uv sync --frozen --all-extras --dev
42−
43−# Run tests (if tests/ or test/ directory exists)
44−uv run pytest
45−
46−# Type checking
47−uv run pyright
48−
49−# Linting
50−uv 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−
88−Both TypeScript and Python workflows use **dynamic package detection** (find + jq matrix strategy):
89−
90−1. `detect-packages` -- finds all `package.json` / `pyproject.toml` under `src/`
91−2. `test` -- runs tests per package
92−3. `build` -- compiles and type-checks per package
93−4. `publish` -- on release events only (npm for TS, PyPI trusted publishing for Python)
94−
95−## MCP Protocol Reference
96−
97−The 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
47+- Follow the existing file/module pattern in its folder (naming, exports, and registration function).
48+- Export a `registerX(server)` function that registers new items with the MCP SDK in the same style as existing ones.
49+- Wire your new module into the central index (e.g., update `tools/index.ts`, `resources/index.ts`, or `prompts/index.ts`).
50+- Ensure schemas (for tools) are accurate JSON Schema and include helpful descriptions and examples.
51+ `server/index.ts` and usages in `logging.ts` and `subscriptions.ts`.
52+- Keep the docs in `src/everything/docs/` up to date if you add or modify noteworthy features.
10553
