Skip to content

Commit 9511de6

Browse files
cliffhallclaude
andcommitted
docs: add AGENTS.md with the repo's rules; delete CLAUDE.md
Ports the Inspector's AGENTS.md shape, keeping only rules that are true on v2/main today: project structure, development setup and pre-push checks for both languages, branch table, contributing (issues, not PRs, with a temporary Dependabot exception to "every PR references an issue"), maintenance rules, issue-driven board rules for modelcontextprotocol#43, review etiquette, testing baseline, waiting on long-running work, MCP protocol idioms, and TypeScript and Python instructions. Every CLAUDE.md section is mapped per the inception doc's section 4, and CLAUDE.md is deleted with no pointer file: Claude Code reads AGENTS.md directly. src/everything/AGENTS.md keeps only its server-specific guidance; its generic style rules moved to the root file, since a nested AGENTS.md loads only when a file in that directory is read. Closes modelcontextprotocol#4862 Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: cliffhall <[email protected]>
1 parent e780241 commit 9511de6

3 files changed

Lines changed: 356 additions & 122 deletions

File tree

‎AGENTS.md‎

Lines changed: 345 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,345 @@
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

Comments
 (0)