An agent reads a fork family's iterations through an MCP iterations tool, as GET /api/v1/repos/:owner/:name/iterations does #9151

I added an iterations MCP tool that returns the same { forks, lanes } as GET /api/v1/repos/:owner/:name/iterations. The new test, test/mcp-tools.test.ts, test/mcp-size.test.ts, bun scripts/gate.ts and bun x tsc --noEmit all pass. I did not call keep_plan for the plan on the issue.

• Tool: src/http/mcp/tools/iterations.ts takes owner and name. It calls iterationsOf and lanesOf from core/iterations.ts, the same two functions the API route calls. A repository the caller cannot read answers not_found. A family with no pins answers empty lists. The tool is read-only.
• Doc: the doc string names both arguments and the shape of the answer, and test/mcp-tools.test.ts accepts it.
• Listing: index.ts is regenerated with bun scripts/mcp-tools.ts. /llms.txt builds its tool list from each tool's doc, so the tool appears there with no separate edit. I did not check the here manifest or the served /llms.txt directly.
• Test: test/mcp-iterations.test.ts covers the three cases from the issue. It checks the tool's answer equals the API's for the same caller, a stranger gets not_found on a private repository, and a pinless family returns empty lists.

The tool takes owner and name as the issue asks, while builds takes a single repo string. I left that difference in place.

I did not add an action or kind to an existing tool. The issue asks for a registered iterations tool, and the size test still passes.

To try it, call the iterations tool with { "owner": "ada", "name": "game" } against /mcp.

Closes #9126

I added an iterations MCP tool that returns the same { forks, lanes } as GET /api/v1/repos/:owner/:name/iterations. The new test, test/mcp-tools.test.ts, test/mcp-size.test.ts, bun scripts/gate.ts and bun x tsc --noEmit all pass. I did not call keep_plan for the plan on the issue.

• Tool: src/http/mcp/tools/iterations.ts takes owner and name. It calls iterationsOf and lanesOf from core/iterations.ts, the same two functions the API route calls. A repository the caller cannot read answers not_found. A family with no pins answers empty lists. The tool is read-only.
• Doc: the doc string names both arguments and the shape of the answer, and test/mcp-tools.test.ts accepts it.
• Listing: index.ts is regenerated with bun scripts/mcp-tools.ts. /llms.txt builds its tool list from each tool's doc, so the tool appears there with no separate edit. I did not check the here manifest or the served /llms.txt directly.
• Test: test/mcp-iterations.test.ts covers the three cases from the issue. It checks the tool's answer equals the API's for the same caller, a stranger gets not_found on a private repository, and a pinless family returns empty lists.

The tool takes owner and name as the issue asks, while builds takes a single repo string. I left that difference in place.

I did not add an action or kind to an existing tool. The issue asks for a registered iterations tool, and the size test still passes.

To try it, call the iterations tool with { "owner": "ada", "name": "game" } against /mcp.

The check failed because none of my commit messages had a Why now: line or a Try: line. I added both in a new empty commit and pushed it. bun scripts/gate.ts printed nothing locally, which I take as a pass. I did not run the tests again, since no code changed, and the forge's check on this push hasn't reported yet.

The pull still adds an iterations MCP tool. It takes owner and name and returns the same { forks, lanes } as GET /api/v1/repos/:owner/:name/iterations. It reads the family through the same core/iterations.ts functions as the API route and the Iterations page. A private repository the caller can't read answers not_found, and a family with no pins answers empty lists. test/mcp-iterations.test.ts covers those cases.

To try it, call the iterations tool on the preview's /mcp with {"owner":"ada","name":"game"} and compare the result with GET /api/v1/repos/ada/game/iterations.

I did not add an action or kind to an existing tool. The issue asks for a registered iterations tool, and test/mcp-size.test.ts still passes.

I fixed two of the three failures and pushed, but I think the third is flaky and I didn't change it.

• OpenAPI route index: src/contract/openapi/routes/index.ts was stale, probably because the iterations API route (a4606c6f) landed on main without regenerating it. I regenerated it with bun scripts/openapi-routes.ts. test/openapi-routes.test.ts now passes.
• MCP protocol test: the expected tool list in test/mcp.test.ts didn't include iterations, so I added it. The test passes.
• ETag test: "the list carries an ETag: a repeat is 304 until a pull's verdict changes" in test/api-pulls-check-preview.test.ts failed on my first run. On three reruns it failed twice and passed once, with nothing changed between them. My change doesn't touch the pulls list, so I think it's timing-dependent, and I left it alone. If the forge's check fails on it again, that points at the test, not this pull.

I didn't run the full suite here. The forge's check on this push will run it.

I added the missing documentation and pushed. docs/features/iterations.md now has an "Over MCP" section after the API paragraph. It names the iterations tool with { owner, name } and says it answers the same { forks, lanes } as the route. It also gives not_found for a private repository the caller can't read and empty lists for a family with no pin. It says the tool is read-only.

bun scripts/gate.ts printed nothing, which I take as a pass. I didn't re-run the tests, since only the doc changed.

I agree with the review and have nothing to push back on.