|
| 1 | +# MCP reference servers |
| 2 | + |
| 3 | +This repository holds the official Model Context Protocol reference servers: |
| 4 | +seven standalone packages under `src/`, four in TypeScript (published to npm) |
| 5 | +and three in Python (published to PyPI). They are reference implementations, |
| 6 | +meant to show how each part of the protocol is used, not general-purpose |
| 7 | +products. |
| 8 | + |
| 9 | +**This file holds the _rules_: the conventions a reviewer cites against a diff.** |
| 10 | +It is loaded in full at the start of every session, so it stays resident and must |
| 11 | +be complete enough to work from on its own. Procedures (multi-step recipes with |
| 12 | +commands and live IDs) belong in skills under `.claude/skills/`, which load on |
| 13 | +demand. A rule that must never silently drop out of context goes here; a recipe |
| 14 | +that can be re-read from disk goes in a skill. |
| 15 | + |
| 16 | +Every rule in this file is true of the repository as it stands. A rule whose |
| 17 | +machinery does not exist yet is added by the change that builds that machinery, |
| 18 | +not in advance. |
| 19 | + |
| 20 | +## Skills index |
| 21 | + |
| 22 | +| Skill | Covers | How it loads | |
| 23 | +| ----- | ------ | ------------ | |
| 24 | + |
| 25 | +There are no skills in this repository yet. A PR that adds a skill under |
| 26 | +`.claude/skills/<name>/SKILL.md` adds its row to this table in the same change, |
| 27 | +and the table never lists a skill that does not exist. |
| 28 | + |
| 29 | +## Project structure |
| 30 | + |
| 31 | +``` |
| 32 | +servers/ |
| 33 | +├── src/ One directory per server; each publishes on its own |
| 34 | +│ ├── everything/ TS @modelcontextprotocol/server-everything npm Exercises every MCP feature; the protocol showcase |
| 35 | +│ ├── filesystem/ TS @modelcontextprotocol/server-filesystem npm File operations, access limited to allowed directories / Roots |
| 36 | +│ ├── memory/ TS @modelcontextprotocol/server-memory npm Knowledge-graph persistence |
| 37 | +│ ├── sequentialthinking/ TS @modelcontextprotocol/server-sequential-thinking npm Step-by-step reasoning |
| 38 | +│ ├── fetch/ Py mcp-server-fetch PyPI Fetches web content and converts it for LLMs |
| 39 | +│ ├── git/ Py mcp-server-git PyPI Git repository operations |
| 40 | +│ └── time/ Py mcp-server-time PyPI Time and timezone conversion |
| 41 | +├── scripts/ Release tooling (release.py) |
| 42 | +├── docs/ Design documents |
| 43 | +├── .github/workflows/ typescript.yml, python.yml (per-package CI), release.yml (dispatch-only publish), |
| 44 | +│ claude.yml (@claude mentions), readme-pr-check.yml |
| 45 | +├── RELEASING.md How publishing works and how to recover a failed publish |
| 46 | +└── CONTRIBUTING.md What contributions are accepted |
| 47 | +``` |
| 48 | + |
| 49 | +The four TypeScript servers are **npm workspaces** of the root `package.json`. |
| 50 | +The three Python servers are independent `uv` projects, each with its own |
| 51 | +`pyproject.toml`, `uv.lock` and `.python-version`. Every server versions and |
| 52 | +publishes independently. |
| 53 | + |
| 54 | +A server may carry its own `AGENTS.md` for guidance that only applies inside it |
| 55 | +(`src/everything/AGENTS.md` does). Claude Code loads a nested `AGENTS.md` when |
| 56 | +it reads a file in that directory, not at session start, so **a rule that |
| 57 | +applies repo-wide goes in this file, never only in a nested one.** |
| 58 | + |
| 59 | +### New and rewritten files open with a purpose header |
| 60 | + |
| 61 | +A file you create, or substantially rewrite, opens with a comment stating what |
| 62 | +the file is for and the reasoning behind it: the first comment in the file, |
| 63 | +**after any shebang**. `#!/usr/bin/env node` must stay on line 1 of an |
| 64 | +executable entry point, or the published bin stops working. This is not a bulk |
| 65 | +migration: files you only touch in passing keep their current form. Read that |
| 66 | +header rather than restating its reasoning in this file, since a duplicated |
| 67 | +rationale goes stale silently. |
| 68 | + |
| 69 | +## Development setup |
| 70 | + |
| 71 | +Node **22** for the TypeScript servers. Python **>= 3.10** for the Python |
| 72 | +servers, at the version each server's `.python-version` pins. Python |
| 73 | +dependencies are managed with **`uv`, never `pip`**. |
| 74 | + |
| 75 | +```sh |
| 76 | +# TypeScript: one install at the root covers all four workspaces |
| 77 | +npm install |
| 78 | +npm run build # every workspace |
| 79 | +npm test -w src/<server> # one workspace (vitest, with coverage) |
| 80 | + |
| 81 | +# Python: per server |
| 82 | +cd src/<server> |
| 83 | +uv sync --frozen --all-extras --dev |
| 84 | +uv run pytest |
| 85 | +uv run --frozen pyright |
| 86 | +uv run ruff check . |
| 87 | +uv build |
| 88 | +``` |
| 89 | + |
| 90 | +### Before pushing |
| 91 | + |
| 92 | +For every package your change touches, run the checks CI runs for it and make |
| 93 | +sure they pass: |
| 94 | + |
| 95 | +- **TypeScript**: `npm test` and `npm run build` in that workspace |
| 96 | + (`.github/workflows/typescript.yml`). |
| 97 | +- **Python**: `uv run pytest`, `uv run --frozen pyright` and `uv build` in that |
| 98 | + server (`.github/workflows/python.yml`). |
| 99 | + |
| 100 | +Also run `uv run ruff check .` in each Python server you touch. CI does not run |
| 101 | +it yet, so nothing but you keeps it clean; every server passes it today, and a |
| 102 | +change must not add a finding. |
| 103 | + |
| 104 | +### Dependencies |
| 105 | + |
| 106 | +- **Pin a transitive dependency with an `overrides` entry** in the root |
| 107 | + `package.json`, not with `npm audit fix`, which "resolves" an advisory with no |
| 108 | + upward escape by silently downgrading. |
| 109 | +- **When you bump a devDependency that several TypeScript workspaces declare** |
| 110 | + (`typescript`, `vitest`, `@vitest/coverage-v8`, `@types/node`, …), bump it in |
| 111 | + every workspace that declares it. Their ranges already differ; do not widen the |
| 112 | + skew. |
| 113 | +- **A Python dependency change updates that server's `uv.lock`** in the same |
| 114 | + commit (`uv lock`). CI installs with `--frozen` / `--locked` and fails on a |
| 115 | + stale lockfile. |
| 116 | + |
| 117 | +## Project status and direction |
| 118 | + |
| 119 | +| Branch | Role | PRs target it? | |
| 120 | +| --------- | ------------------------------------------------------------------------------ | -------------------------------------------------------- | |
| 121 | +| `v2/main` | **Develop.** All active work lands here. | **Yes**, every PR | |
| 122 | +| `main` | **Release.** The default branch, and what users see. Not a development branch. | **No**, it only receives milestone merges from `v2/main` | |
| 123 | + |
| 124 | +Cut feature branches from **`origin/v2/main`**. **Never open a PR against |
| 125 | +`main`.** There is no `v1` line in this repository. |
| 126 | + |
| 127 | +- **Repo**: https://github.com/modelcontextprotocol/servers |
| 128 | +- **Project board**: [Servers V2 (#43)](https://github.com/orgs/modelcontextprotocol/projects/43) |
| 129 | + |
| 130 | +Publishing is described in [`RELEASING.md`](./RELEASING.md). It is a deliberate |
| 131 | +maintainer action (`release.yml` runs on `workflow_dispatch` only), never a side |
| 132 | +effect of a merge. |
| 133 | + |
| 134 | +## Contributing |
| 135 | + |
| 136 | +What the repository accepts is in [`CONTRIBUTING.md`](./CONTRIBUTING.md). Read it |
| 137 | +rather than a summary. In short: bug fixes, usability improvements and changes |
| 138 | +that demonstrate MCP protocol features (Resources, Prompts, Roots, not just |
| 139 | +Tools) are welcome; other new features are selective; **new server |
| 140 | +implementations are not accepted** (they belong in the |
| 141 | +[MCP Server Registry](https://github.com/modelcontextprotocol/registry)), and |
| 142 | +neither are README server-listing changes. |
| 143 | + |
| 144 | +**Pull requests are opened by the repository maintainers.** Anyone else, org |
| 145 | +members with write access included, files a detailed issue instead: the problem, |
| 146 | +how to reproduce it, the expected behavior, and, if a fix was prototyped, the |
| 147 | +prompt that produced it rather than a diff. An agent working for someone who is |
| 148 | +not a maintainer produces that issue, not a PR. The maintainers decided this on |
| 149 | +#4861; where `CONTRIBUTING.md` or the PR template still describe the older open |
| 150 | +PR flow, this rule governs. |
| 151 | + |
| 152 | +**Every PR references an issue.** The PR body's first line is |
| 153 | +`Closes #<ISSUE_NUMBER>`. A PR with no linked issue has no board card, so the |
| 154 | +work is invisible to the board. If there is no issue yet, create it first. This |
| 155 | +holds for a maintainer's own one-line fix as much as for a feature. |
| 156 | + |
| 157 | +- **Temporary exception: Dependabot PRs.** Dependabot still opens issue-less PRs |
| 158 | + (weekly GitHub Actions bumps, and security-fix PRs). They are exempt until the |
| 159 | + change that replaces them with issue-filing sweeps lands and removes this |
| 160 | + exception. No other PR is exempt. |
| 161 | + |
| 162 | +Every PR answers the checklist in |
| 163 | +[`.github/pull_request_template.md`](./.github/pull_request_template.md): |
| 164 | +the MCP documentation was read for the feature touched, the change follows MCP |
| 165 | +security best practices, the server's README is updated, and a **server-facing |
| 166 | +change was tested with an LLM client**, with what was asked and what came back |
| 167 | +recorded in the PR. |
| 168 | + |
| 169 | +## Maintenance rules |
| 170 | + |
| 171 | +- When adding, removing, renaming, or changing the purpose of a file or folder, |
| 172 | + update the entry that describes it: the root `README.md`, the server's own |
| 173 | + `README.md`, and the tree in this file. |
| 174 | +- A change to a server's tools, resources, prompts, configuration or environment |
| 175 | + variables updates **that server's `README.md`** in the same PR. |
| 176 | +- A change to how packages are versioned or published updates |
| 177 | + [`RELEASING.md`](./RELEASING.md). |
| 178 | +- When a rule changes, update this file. When a procedure changes, update the |
| 179 | + skill that owns it, not this file. Link to a document rather than copying it: |
| 180 | + two copies of a command sequence or an ID are worse than one, because the stale |
| 181 | + copy is indistinguishable from the live one. |
| 182 | + |
| 183 | +## Issue-driven work style |
| 184 | + |
| 185 | +All work is driven by items on the Servers V2 board (#43). |
| 186 | + |
| 187 | +- **Before starting work, check the board for the relevant item.** |
| 188 | +- **Every board item is a real GitHub issue.** No draft cards. Before creating an |
| 189 | + issue, search for a matching one in every state; **never create a duplicate**. |
| 190 | +- **Only issues go on the board, never PRs.** A PR is tracked through its linked |
| 191 | + issue's card. |
| 192 | +- **Label every issue and every PR `v2`**, at create time. It marks work tracked |
| 193 | + by this workflow. |
| 194 | +- **Label every issue with exactly one type label**: `bug`, `enhancement`, |
| 195 | + `documentation` or `question`. A PR needs no type label; it is classified |
| 196 | + through the issue it closes. |
| 197 | +- **Label an issue that concerns one server with its scope label** |
| 198 | + (`server-everything`, `server-filesystem`, `server-memory`, |
| 199 | + `server-sequentialthinking`, `server-fetch`, `server-git`, `server-time`). |
| 200 | + An issue that concerns the repository as a whole carries none. |
| 201 | +- **Every issue you create gets a milestone.** Milestones are release buckets, |
| 202 | + so pick by when the work ships. The one exception: an issue that arrives |
| 203 | + unboarded stays unmilestoned in `Incoming` until a maintainer approves it. |
| 204 | +- **Every board item has a Priority** (a board field, not a label). |
| 205 | +- **`Incoming` ⇔ no milestone; every Status past it ⇔ milestoned.** Assigning |
| 206 | + the milestone _is_ the approval act, so the two go together. `Todo` asserts a |
| 207 | + maintainer signed off, so never park an unreviewed issue there. An issue you |
| 208 | + create through the normal flow skips `Incoming`, because filing it was the |
| 209 | + approval. |
| 210 | +- **`Done` means the work shipped**: its PR merged, or it is a parent whose last |
| 211 | + sub-issue closed. A duplicate, won't-fix, not-planned or superseded issue |
| 212 | + shipped nothing, so its card is **deleted** rather than moved to Done. |
| 213 | +- **When work begins**, assign the issue to yourself, set Status to |
| 214 | + **In Progress**, and create a branch named |
| 215 | + `v2/<type>/<ISSUE_NUMBER>-<slug>` (for example |
| 216 | + `v2/fix/4810-filesystem-symlink-escape`) from `origin/v2/main`. |
| 217 | +- **When work is complete**, run the checks under |
| 218 | + [Before pushing](#before-pushing), open a PR against `v2/main` labeled `v2` |
| 219 | + with `Closes #<ISSUE_NUMBER>` as the body's first line, and set Status to |
| 220 | + **In Review**. |
| 221 | +- ⚠️ Closing keywords only auto-link and auto-close for PRs targeting the |
| 222 | + default branch (`main`). A PR against `v2/main` gets a cross-reference only, |
| 223 | + so **link it explicitly** with the `addCloseIssueReferences` GraphQL mutation |
| 224 | + right after opening it. **On merge, close the issue by hand and move its card |
| 225 | + to Done.** Keep the `Closes` line anyway. |
| 226 | +- **After opening a PR, run a Copilot review loop to convergence, unprompted.** |
| 227 | + Request a review, wait for the round to post or for Copilot's session to end |
| 228 | + without one, answer every comment, and request again only when you pushed a |
| 229 | + fix. Stop on the **first** clean round (no confirming round), a round holding |
| 230 | + only out-of-scope findings, or two rounds in a row that end without a review. |
| 231 | +- **If new tasks are discovered during development, create issues** for them |
| 232 | + and put them on the board, rather than widening the current PR. |
| 233 | + |
| 234 | +## Responding to code reviews |
| 235 | + |
| 236 | +- It is not necessary to implement every suggestion. |
| 237 | +- **Judge each suggestion against the issue the PR closes.** Fix defects in what |
| 238 | + the PR added. Decline, with a reason, suggestions that expand the PR beyond |
| 239 | + what the issue calls for (pre-existing behavior, new capabilities, hardening |
| 240 | + the issue did not ask for), and file an issue for any that is worth doing on |
| 241 | + its own. |
| 242 | +- You may implement a suggestion differently, or skip one for a good reason. |
| 243 | +- **Reply to each review comment in its own thread**, saying what was done or |
| 244 | + why it was not. A rollup comment elsewhere cannot be connected back to the |
| 245 | + thread it answers, so the thread stays open showing a finding and no reply. |
| 246 | + Then post a PR-level summary **in addition**, because inline replies go hidden |
| 247 | + once the fix is pushed. A finding in a review's "Suppressed comments" block has |
| 248 | + no thread, so the summary is the only place to answer it. |
| 249 | + |
| 250 | +## Always test new or modified code |
| 251 | + |
| 252 | +- **New or changed behavior comes with tests.** TypeScript servers use |
| 253 | + **vitest** (with `@vitest/coverage-v8`), with tests in the server's |
| 254 | + `__tests__/` directory. Python servers use **pytest** (`pytest-asyncio` where |
| 255 | + the server is async), with tests in the server's `tests/` directory (`test/` in |
| 256 | + `time`). |
| 257 | +- **Test at the protocol level where you can**: drive the server through an MCP |
| 258 | + client over an in-memory transport and assert on what comes back, rather than |
| 259 | + only calling internal functions. |
| 260 | +- **In tests that expect error output, suppress it from the console.** |
| 261 | + |
| 262 | +## Waiting on long-running work |
| 263 | + |
| 264 | +**When you are waiting for something to finish, arm a notifier and stop. Never |
| 265 | +spend turns polling.** The harness re-invokes you when a backgrounded task exits, |
| 266 | +so a per-turn `echo`, `tail` or `grep` of a log delivers nothing the notification |
| 267 | +would not, burns turns, and buries the result under no-op turns. |
| 268 | + |
| 269 | +- **One notification ("tell me when this finishes")**: background the command |
| 270 | + itself, or a single loop that exits on the condition. |
| 271 | +- **Many ("tell me on each occurrence")**: a monitor over a stream that emits one |
| 272 | + line per event. |
| 273 | +- **State the harness cannot observe** (a CI run, a remote review queue) does |
| 274 | + need polling, but inside **one backgrounded loop that exits when the condition |
| 275 | + holds**, at an interval matched to how fast the state changes (30s or more for |
| 276 | + a remote API). |
| 277 | +- ⚠️ **If a notifier is already armed, wait for it.** Re-checking by hand |
| 278 | + alongside it is the polling this rule forbids. |
| 279 | + |
| 280 | +## MCP protocol |
| 281 | + |
| 282 | +- **Look protocol questions up; do not answer them from memory.** The repo |
| 283 | + configures the `mcp-docs` MCP server (`.mcp.json`, |
| 284 | + `https://modelcontextprotocol.io/mcp`). For schema details use the versioned |
| 285 | + schemas (JSON and TypeScript) in |
| 286 | + [modelcontextprotocol/schema](https://github.com/modelcontextprotocol/modelcontextprotocol/tree/main/schema). |
| 287 | +- **Transports**: stdio is the default and every server supports it. |
| 288 | + `everything` also serves Streamable HTTP and HTTP+SSE. **HTTP+SSE is |
| 289 | + deprecated**: keep what exists working, and never make it the default or the |
| 290 | + recommended option in new code or docs. |
| 291 | +- **Tool annotations**: every tool you add or change sets `readOnlyHint`, |
| 292 | + `idempotentHint` and `destructiveHint` to values that match what it actually |
| 293 | + does. |
| 294 | +- **Tool names**: verb-first (`get-file-info`, not `file-info`). A new tool |
| 295 | + follows the naming convention of the server it joins: kebab-case in |
| 296 | + `everything`, snake_case in the others. **Never rename a published tool**: a |
| 297 | + tool name is part of the server's interface, and renaming it breaks every |
| 298 | + client configuration and prompt that uses it. |
| 299 | +- **Resources and prompts** registered in `everything` are kebab-case too. |
| 300 | +- **Registration**: in `everything`, each feature area exports a |
| 301 | + `registerTools(server)` / `registerResources(server)` / |
| 302 | + `registerPrompts(server)` function and is wired into that area's `index.ts`. |
| 303 | + The other TypeScript servers register directly on the server |
| 304 | + (`server.registerTool(...)`). Follow the pattern of the server you are in. |
| 305 | + |
| 306 | +## TypeScript instructions |
| 307 | + |
| 308 | +- Use TypeScript for all new code, with strict typing for every function and |
| 309 | + variable. |
| 310 | +- **ES modules**: relative imports carry the `.js` extension |
| 311 | + (`import { x } from "./lib.js"`). |
| 312 | +- **Validate tool input with Zod schemas**, with descriptions on the fields. |
| 313 | +- **Naming**: camelCase for variables and functions, PascalCase for types and |
| 314 | + classes, UPPER_CASE for constants, kebab-case for new file names. |
| 315 | +- **Imports** at the top of the file, external packages first, then internal |
| 316 | + modules. |
| 317 | +- Prefer `async`/`await` over callbacks and raw promise chains. |
| 318 | +- **NEVER use `any` as a type.** |
| 319 | +- **NEVER suppress errors in the TypeScript configuration or with a lint |
| 320 | + directive** as a way of satisfying the compiler. |
| 321 | +- **AVOID double casts (`as unknown as T`).** Prefer a type guard, a narrower |
| 322 | + single cast, or fixing the underlying type. When one is genuinely unavoidable |
| 323 | + (a documented gap in a third-party type, for example), it carries an inline |
| 324 | + comment saying why it is safe and why nothing better works. |
| 325 | +- **NEVER leave a promise floating.** Every promise is awaited, returned, |
| 326 | + terminated with `.catch(…)`, or explicitly discarded with `void` plus a |
| 327 | + one-line comment saying why the caller cannot await it. A floated call reads |
| 328 | + like an awaited one minus a keyword, and its unhandled rejection surfaces |
| 329 | + somewhere else entirely. |
| 330 | +- **Clean up** timers, intervals, subscriptions and child processes when the |
| 331 | + server shuts down or a transport closes. |
| 332 | +- Handle errors with `try`/`catch` and return clear error messages to the |
| 333 | + client, as an MCP error result where the protocol calls for one. |
| 334 | + |
| 335 | +## Python instructions |
| 336 | + |
| 337 | +- **Type hints everywhere, and pyright-clean**: CI runs `uv run --frozen pyright` |
| 338 | + on every Python server. |
| 339 | +- **Lint with `ruff`** (`uv run ruff check .`). |
| 340 | +- Follow the server's existing module layout |
| 341 | + (`src/<server>/src/mcp_server_<name>/`) and its async style; test async code |
| 342 | + with `pytest-asyncio` where the server already uses it. |
| 343 | +- Manage dependencies with `uv` and commit the updated `uv.lock` (see |
| 344 | + [Dependencies](#dependencies)). |
| 345 | +- Builds use **hatchling** through `uv build`; do not add another build backend. |
0 commit comments