Adding or changing an MCP tool no longer has to edit docs/MCP.md: the tool table stops being a checked, committed file #8313

Adding or changing an MCP tool no longer touches docs/MCP.md. bun scripts/mcp-tools.ts now writes only src/http/mcp/tools/index.ts, and says so when it runs: "current: src/http/mcp/tools/index.ts, the only file this writes" and "docs/MCP.md is not written". The live list in /llms.txt's ## MCP tools replaces the table.

What to look at

• The /llms.txt line shows each tool's doc. The issue assumed this section was built from doc, but src/web/llms_tools.ts used description, which never contains the doc text. Each line now reads doc ?? description, so /llms.txt shows the argument signature and fuller text the table showed. report is now listed there too (setMcpTools([...TOOLS, REPORT_TOOL]) in src/http/server.ts), since the table had a row for it. test/llms-tools.test.ts was updated to expect this: the test was right before, and this is an intended change in behaviour.
• test/mcp-tools.test.ts:

- The "docs/MCP.md's tool table is current" test is gone. - A new test checks that every tool's doc (or its description when it has none), report included, is its line in the tools section. - Another adds a fixture tool file in a temp directory. It checks that the index gains exactly one line, that the script writes no file but the index, and that the fixture's doc reaches the live list. - The code-point ordering test now checks byName directly.

• I deleted test/mcp-docs.test.ts. Its two tests ("every tool in tools/list has a row in docs/MCP.md" and its reverse) still read the table. With the script no longer writing rows, a new tool would have needed a hand-written row, which defeats the issue. Completeness is still covered: the index-equals-files test, toolNames, and the /llms.txt test.
• Tree gates: TREE_GATES in src/checks/shared_red.ts still named the removed tests, and shared-red.test.ts requires every gate to name a test that exists. I dropped those names and narrowed the #7906 shared-red test to the index gate alone.
• Comments: the doc comments in src/http/mcp/shared.ts and src/http/mcp.ts and the "Add an MCP tool" line in CLAUDE.md now point at /llms.txt.

Not done: docs/MCP.md is unchanged, as the issue asks. Its table and its "Adding a tool" paragraph are now stale; the next issue removes them.

Checks: bun scripts/gate.ts, bun x tsc --noEmit, bun scripts/mcp-tools.ts --check, and the tests for this change all pass (mcp-tools, llms-tools, shared-red, mcp-size, held-relieves-map, plus 12 suites that read /llms.txt or list tools). scripts/fast.ts said the diff was too broad to pick tests for, so I chose these myself.

Try it: bun scripts/mcp-tools.ts, then curl …/llms.txt and find the ## MCP tools section: every tool is listed by its doc, report included.

🤖 Generated with Claude Code

Closes #8304

Adding or changing an MCP tool no longer touches docs/MCP.md. bun scripts/mcp-tools.ts now writes only src/http/mcp/tools/index.ts, and says so when it runs: "current: src/http/mcp/tools/index.ts, the only file this writes" and "docs/MCP.md is not written". The live list in /llms.txt's ## MCP tools replaces the table.

What to look at

• The /llms.txt line shows each tool's doc. The issue assumed this section was built from doc, but src/web/llms_tools.ts used description, which never contains the doc text. Each line now reads doc ?? description, so /llms.txt shows the argument signature and fuller text the table showed. report is now listed there too (setMcpTools([...TOOLS, REPORT_TOOL]) in src/http/server.ts), since the table had a row for it. test/llms-tools.test.ts was updated to expect this: the test was right before, and this is an intended change in behaviour.
• test/mcp-tools.test.ts:

- The "docs/MCP.md's tool table is current" test is gone. - A new test checks that every tool's doc (or its description when it has none), report included, is its line in the tools section. - Another adds a fixture tool file in a temp directory. It checks that the index gains exactly one line, that the script writes no file but the index, and that the fixture's doc reaches the live list. - The code-point ordering test now checks byName directly.

• I deleted test/mcp-docs.test.ts. Its two tests ("every tool in tools/list has a row in docs/MCP.md" and its reverse) still read the table. With the script no longer writing rows, a new tool would have needed a hand-written row, which defeats the issue. Completeness is still covered: the index-equals-files test, toolNames, and the /llms.txt test.
• Tree gates: TREE_GATES in src/checks/shared_red.ts still named the removed tests, and shared-red.test.ts requires every gate to name a test that exists. I dropped those names and narrowed the #7906 shared-red test to the index gate alone.
• Comments: the doc comments in src/http/mcp/shared.ts and src/http/mcp.ts and the "Add an MCP tool" line in CLAUDE.md now point at /llms.txt.

Not done: docs/MCP.md is unchanged, as the issue asks. Its table and its "Adding a tool" paragraph are now stale; the next issue removes them.

Checks: bun scripts/gate.ts, bun x tsc --noEmit, bun scripts/mcp-tools.ts --check, and the tests for this change all pass (mcp-tools, llms-tools, shared-red, mcp-size, held-relieves-map, plus 12 suites that read /llms.txt or list tools). scripts/fast.ts said the diff was too broad to pick tests for, so I chose these myself.

Try it: bun scripts/mcp-tools.ts, then curl …/llms.txt and find the ## MCP tools section: every tool is listed by its doc, report included.

🤖 Generated with Claude Code