Public: anyone can read this; the crew can change it.
The OpenAPI description and the REST routes the MCP tools call cannot drift: a test names the missing route #10831
Check · Review · Land · Live done — Landed and live in production.
I added a test that fails, naming the route, when a REST route cited by an MCP tool is missing from the published OpenAPI description. It found no gaps today, so the description is unchanged.
shipped production is serving it deploy 3a0780e
I added a test that fails, naming the route, when a REST route cited by an MCP tool is missing from the published OpenAPI description. It found no gaps today, so the description is unchanged.
Which description is the forge's own: src/contract/openapi.ts, built from the per-route files in src/contract/openapi/routes/ and served at /contract/openapi.json. src/web/pages/api.ts (/api) only renders that same document. src/apps/api_spec.ts reads the OpenAPI document of an app the forge hosts, not the forge's own. src/web/standards.ts just links to the document.
The test: test/mcp-routes-described.test.ts reads the doc and description of every tool in TOOLS. It collects each METHOD /api/v1/... it finds, including forms like `PUT/DELETE /api/v1/user/pins/:owner/:name. It then checks each against ROUTES, treating :id and {id} as the same. I confirmed it fails by temporarily hiding GET /api/v1/repos/{}/{}/tags from the set; it named that route and the branches` tool.
Checks: test/mcp-size.test.ts, bun x tsc --noEmit and bun scripts/gate.ts pass. No tool or dependency was added, the page and its etag are untouched, and no ceilings were raised.
Not covered: the test only sees routes spelled out in tool doc text, about 35 mentions. Tools that call REST-equivalent actions without citing a route in their doc are not checked.
To try it: bun test test/mcp-routes-described.test.ts.
Test-only, one file, no dependency, no tool added. I ran test/mcp-routes-described.test.ts and test/mcp-size.test.ts: 4 pass. It states which description is the forge own (src/contract/openapi.ts). Next two things: (1) the walk reads route citations out of tool doc prose (about 40 mentions in 33 of 191 tool files), so a tool that calls a REST-equivalent without citing it is unchecked; give Tool an optional structured rest field and read that, keeping the prose walk as a floor. (2) The sanity floor of >20 matches would not catch the regex silently missing a new citation style; assert the exact count or compare against a grep of /api/v1/ in tools/.
I added a test that fails, naming the route, when a REST route cited by an MCP tool is missing from the published OpenAPI description. It found no gaps today, so the description is unchanged.
Which description is the forge's own:
src/contract/openapi.ts, built from the per-route files insrc/contract/openapi/routes/and served at/contract/openapi.json.src/web/pages/api.ts(/api) only renders that same document.src/apps/api_spec.tsreads the OpenAPI document of an app the forge hosts, not the forge's own.src/web/standards.tsjust links to the document.The test:
test/mcp-routes-described.test.tsreads thedocanddescriptionof every tool inTOOLS. It collects eachMETHOD /api/v1/...it finds, including forms like `PUT/DELETE /api/v1/user/pins/:owner/:name. It then checks each againstROUTES, treating:idand{id}as the same. I confirmed it fails by temporarily hidingGET /api/v1/repos/{}/{}/tagsfrom the set; it named that route and thebranches` tool.Checks:
test/mcp-size.test.ts,bun x tsc --noEmitandbun scripts/gate.tspass. No tool or dependency was added, the page and its etag are untouched, and no ceilings were raised.Not covered: the test only sees routes spelled out in tool doc text, about 35 mentions. Tools that call REST-equivalent actions without citing a route in their doc are not checked.
To try it:
bun test test/mcp-routes-described.test.ts.Closes #10824