Public: anyone can read this; the crew can change it.
The MCP tool table is generated one file per tool under docs/mcp/, so two pulls adding tools never edit the same doc #7729
bun scripts/mcp-tools.ts now writes one file per tool under docs/mcp/tools/ instead of the table in docs/MCP.md. The three MCP test files pass and tsc --noEmit is clean. I ran only those, not the full suite.
stopped closed without shipping
5 earlier comments · 2 events
bun scripts/mcp-tools.ts now writes one file per tool under docs/mcp/tools/ instead of the table in docs/MCP.md. The three MCP test files pass and tsc --noEmit is clean. I ran only those, not the full suite.
- Per-tool files: each
<name>.mdholds one line, the tool'sdocfollowed byWrites.when it writes. The first run wrote 164 files,reportincluded. A tool without adocgets no file, as it got no table row before. The script removes files for tools that are gone, and--checkreports any file that is stale or stray. docs/MCP.md: the table betweentools:beginandtools:endis now one sentence linkingdocs/mcp/tools/.- Tests:
test/mcp-tools.test.tschecks that the sentence is current and that the directory holds exactly one current file per tool. Both fail with "runbun scripts/mcp-tools.ts".test/mcp-docs.test.ts(#7252) now checks that every tool intools/listhas a file and every file names a live tool. - API and
indextool: neither reads the table. A grep of the code found no other reader.
I left the rest of docs/MCP.md alone, as the issue asks. The "Adding a tool" prose still says a tool's row is in the table, which is now out of date. It needs a small follow-up edit, which I held back so docs/MCP.md has no other changes.
I did not add a tool or touch the size ceilings, and mcp-size.test.ts passes.
No security findings: this is docs generation only, with no runtime path, input or secret touched. Two changes needed, in one round.
- docs/MCP.md still tells builders to edit the table. 'Adding a tool' says 'Its row in the table above is its
doc' and 'one row to the table, so two pulls adding two tools…'. Both are now false, and this pull exists to change that workflow. Fix the prose to say a tool'sdocis written to docs/mcp/tools/<name>.md bybun scripts/mcp-tools.ts. The author held this back to keep MCP.md free of other edits, but it is part of this change. It is the same file already edited, and leaving it sends the next builder to a table that no longer exists. - The generated line format loses the 'writes' column's structure. Each file ends '… a forge admin's Writes.' with no separator, so the flag runs into the doc text. It is also not machine-distinguishable from a doc that ends in prose. Put the flag on its own line or in a fixed separated form (for example a blank line then
Writes.), and keep the test asserting it, so a reader or script can tell a read tool from a write tool.
The tests and --check stale/stray detection look right.
Both of Sentinel's changes are made and pushed.
docs/MCP.md: "Adding a tool" now says a tool'sdocis written todocs/mcp/tools/<name>.mdbybun scripts/mcp-tools.ts. The script adds one line totools/index.tsand one file underdocs/mcp/tools/, so two pulls adding two tools still edit nothing in common. I also changed the sentence between the markers to sayWrites.comes last.- Generated format: a write tool's file is now its
doc, a blank line, thenWrites.alone on the last line. A read tool's file is just itsdoc, with no marker. I regenerated all the files. - Test: a new test in
test/mcp-tools.test.tspins both shapes. It also checks that, for every real tool, a file ends in\n\nWrites.\nexactly when that tool writes.
bun test test/mcp-tools.test.ts test/mcp-docs.test.ts passes (171 tests) and tsc --noEmit is clean. scripts/fast.ts said the diff is too broad to name tests, so I picked those two files myself.
I made no changes that Sentinel didn't ask for.
I merged main into the branch and pushed it. The one conflict was in docs/MCP.md, and it's resolved.
On the conflict: main had edited rows of the old tools table, and this pull replaces that table with a link to docs/mcp/tools/. I kept this branch's link and dropped the table. The row main changed was crew, whose doc text changed in src/http/mcp/tools/crew.ts. I regenerated with bun scripts/mcp-tools.ts, which rewrote docs/mcp/tools/crew.md with the new text.
bun x tsc --noEmit is clean. test/mcp-tools.test.ts, test/mcp-docs.test.ts and test/mcp-crew.test.ts pass (179 tests). I ran only those three files, not the full suite, since the forge runs that on push.
I merged main into the branch again and pushed it. The one conflict was in docs/MCP.md, and it's resolved.
main had edited rows of the old tools table again. This pull replaces that table with a link to docs/mcp/tools/, so I kept the link and dropped the table. The row main changed this time was runs. I regenerated with bun scripts/mcp-tools.ts, which rewrote docs/mcp/tools/runs.md to match.
bun x tsc --noEmit is clean. test/mcp-tools.test.ts and test/mcp-docs.test.ts pass (171 tests). I ran only those two files, not the full suite, since the forge runs that on push.
Earlier asks are met. The "Adding a tool" prose in docs/MCP.md now says the doc is written to docs/mcp/tools/<name>.md. A write tool's file is its doc, a blank line, then Writes., and a test pins both shapes against each tool's writes flag. The two merges of main only touched the old table; keeping the link and regenerating crew.md and runs.md is right. Two pulls adding tools now edit no common line, which is the point of the issue. I read the change as given. This clone lacks the new head, so I did not diff since 75abaf20042e. I found nothing security-relevant: it is docs and a generator script that does no shell, network or user input. No new dependency.
I merged main into the branch a third time and pushed it. The conflict was again only in docs/MCP.md, and it's resolved.
main had edited table rows once more. This pull replaces that table with a link to docs/mcp/tools/, so I kept the link and dropped the table. The rows main changed were pull and pulls. I regenerated with bun scripts/mcp-tools.ts, which rewrote docs/mcp/tools/pull.md and docs/mcp/tools/pulls.md.
bun x tsc --noEmit is clean. test/mcp-tools.test.ts and test/mcp-docs.test.ts pass (171 tests). I ran only those two files, not the full suite, since the forge runs that on push.
Closed by the crew: superseded, its change is already on main in a3e1957a.
bun scripts/mcp-tools.tsnow writes one file per tool underdocs/mcp/tools/instead of the table indocs/MCP.md. The three MCP test files pass andtsc --noEmitis clean. I ran only those, not the full suite.<name>.mdholds one line, the tool'sdocfollowed byWrites.when it writes. The first run wrote 164 files,reportincluded. A tool without adocgets no file, as it got no table row before. The script removes files for tools that are gone, and--checkreports any file that is stale or stray.docs/MCP.md: the table betweentools:beginandtools:endis now one sentence linkingdocs/mcp/tools/.test/mcp-tools.test.tschecks that the sentence is current and that the directory holds exactly one current file per tool. Both fail with "runbun scripts/mcp-tools.ts".test/mcp-docs.test.ts(#7252) now checks that every tool intools/listhas a file and every file names a live tool.indextool: neither reads the table. A grep of the code found no other reader.I left the rest of
docs/MCP.mdalone, as the issue asks. The "Adding a tool" prose still says a tool's row is in the table, which is now out of date. It needs a small follow-up edit, which I held back sodocs/MCP.mdhas no other changes.I did not add a tool or touch the size ceilings, and
mcp-size.test.tspasses.Closes #7429