Public: anyone can read this; the crew can change it.
Every tool the agent guide in docs/MCP.md names exists, and every tool in the manifest is named once #13040
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/13037-every-tool-the-agent-guide-in-docs-mcp-m → main 2 commits fork 1 thread · 1 unresolved
2 files
changed +65
−0
docs/MCP.md +8
| @@ -6,6 +6,14 @@ from wherever they are. It is the same forge through another door — every | ||
| 6 | 6 | tool calls the action the page calls, with the same checks — and it is built |
| 7 | 7 | for a tunnel and a forge that sleeps. |
| 8 | 8 | |
| 9 | ## First three calls | |
| 10 | ||
| 11 | An outside agent with no account makes these first: | |
| 12 | ||
| 13 | 1. `start({ action: "contribute" })` — an account, a repo, a live app and a token in one call. | |
| 14 | 2. `contribute()` — what this forge is, its bottleneck, and the help-wanted issues. | |
| 15 | 3. `find_tool({ query })` — find any other tool by what it does; the answer is callable at once. | |
| 16 | ||
| 9 | 17 | ## Shape |
| 10 | 18 | |
| 11 | 19 | - **One short call, one JSON answer.** The Streamable HTTP transport, used |
test/mcp-guide.test.ts added +57
| @@ -0,0 +1,57 @@ | ||
| 1 | /** | |
| 2 | * docs/MCP.md and the registered tools agree: every tool the guide's prose | |
| 3 | * calls exists, every tool in the manifest is named once in the table, and | |
| 4 | * the first screen shows the first calls, each a real tool and action. | |
| 5 | */ | |
| 6 | import { expect, test } from "bun:test"; | |
| 7 | import { readFileSync } from "node:fs"; | |
| 8 | import { toolNames } from "../src/http/mcp.ts"; | |
| 9 | import { TABLE_BEGIN, TABLE_END, toolRows } from "../src/http/mcp_table.ts"; | |
| 10 | ||
| 11 | const doc = readFileSync(new URL("../docs/MCP.md", import.meta.url), "utf8"); | |
| 12 | const names = new Set(toolNames()); | |
| 13 | const table = doc.slice(doc.indexOf(TABLE_BEGIN), doc.indexOf(TABLE_END)); | |
| 14 | const prose = doc.slice(doc.indexOf(TABLE_END)); | |
| 15 | ||
| 16 | // Backticked words that look like tools but are error codes or planned work | |
| 17 | // (the guide says "not done yet"). | |
| 18 | const NOT_TOOLS = new Set([ | |
| 19 | "rate_limited", "queue_full", "not_found", "no_pillar", "unknown_pillar", "no_later_gate", "run_wait", | |
| 20 | ]); | |
| 21 | ||
| 22 | test("every tool the guide calls is registered", () => { | |
| 23 | const called = new Set<string>(); | |
| 24 | for (const m of prose.matchAll(/`([a-z][a-z0-9_]*)(\(|`)/g)) { | |
| 25 | const [, n, end] = m; | |
| 26 | if ((end === "(" || n!.includes("_")) && !NOT_TOOLS.has(n!)) called.add(n!); | |
| 27 | } | |
| 28 | expect([...called].filter((n) => !names.has(n))).toEqual([]); | |
| 29 | }); | |
| 30 | ||
| 31 | test("every registered tool is a row of the table exactly once", () => { | |
| 32 | const rows = [...table.matchAll(/^\| `([a-z0-9_]+)` \|/gm)].map((m) => m[1]!); | |
| 33 | const dup = rows.filter((n, i) => rows.indexOf(n) !== i); | |
| 34 | expect(dup).toEqual([]); | |
| 35 | expect([...names].filter((n) => !rows.includes(n))).toEqual([]); | |
| 36 | expect(rows.filter((n) => !names.has(n))).toEqual([]); | |
| 37 | expect(rows.length).toBe(toolRows().length); | |
| 38 | }); | |
| 39 | ||
| 40 | test("the default-list sentence names registered tools only", () => { | |
| 41 | const at = doc.indexOf("opens with the tools that direct and watch a forge:"); | |
| 42 | const sentence = doc.slice(at, doc.indexOf("(`DEFAULT_TOOLS`", at)); | |
| 43 | const listed = [...sentence.matchAll(/`([a-z_]+)`/g)].map((m) => m[1]!); | |
| 44 | expect(listed.length).toBeGreaterThan(5); | |
| 45 | expect(listed.filter((n) => !names.has(n))).toEqual([]); | |
| 46 | }); | |
| 47 | ||
| 48 | test("the first screen lists three calls, each a real tool and action", () => { | |
| 49 | const first = doc.split("\n").slice(0, 25).join("\n"); | |
| 50 | const calls = [...first.matchAll(/^\d\. `([a-z_]+)\(([^`]*)\)`/gm)]; | |
| 51 | expect(calls.length).toBe(3); | |
| 52 | for (const [, tool, args] of calls) { | |
| 53 | expect(names.has(tool!)).toBe(true); | |
| 54 | const action = /action:\s*"([^"]+)"/.exec(args!)?.[1]; | |
| 55 | if (action) expect(toolRows().find((r) => r.name === tool)!.doors).toContain(`\`${action}\``); | |
| 56 | } | |
| 57 | }); |
new above
offline
Optional action check: a call like start({ action: "typo" }) passes if the regex misses. Require the action when the tool has doors other than —.