From 8d843e94ee911553faabce9b434c90d24a1454b7 Mon Sep 17 00:00:00 2001 From: joaovictor91123 Date: Sun, 12 Jul 2026 21:57:44 +0400 Subject: [PATCH] docs(miner): cross-reference the MCP tool surface from coding-agent-driver.md The README's MCP server section already documents every landed gittensory-miner-mcp tool, including the excluded-columns safety note for the ledger/governor tools, but nothing pointed a coding-agent-driver.md reader at it, and there was no automated check keeping the docs in sync with the actual tool registry. Adds the cross-reference, strengthens the paragraph relating AMS's local tools to ORB's hosted ones (naming convention, local SQLite vs. hosted backing store), and adds a parity test that fails if a registered tool goes undocumented or vice versa. Closes #5162 --- packages/gittensory-miner/README.md | 2 +- .../docs/coding-agent-driver.md | 1 + test/unit/miner-mcp-tool-docs-parity.test.ts | 55 +++++++++++++++++++ 3 files changed, 57 insertions(+), 1 deletion(-) create mode 100644 test/unit/miner-mcp-tool-docs-parity.test.ts diff --git a/packages/gittensory-miner/README.md b/packages/gittensory-miner/README.md index 37fffb9954..4a47f76f8e 100644 --- a/packages/gittensory-miner/README.md +++ b/packages/gittensory-miner/README.md @@ -172,7 +172,7 @@ This completes the read-only AMS MCP tool surface (status, portfolio, claims, ev } ``` -`gittensory` exposes ORB's hosted contributor-workflow tools (issue ranking, PR packet prep, decision packs). `gittensory-miner` exposes AMS's own local state-visibility tools listed above (portfolio dashboard, claims, audit feed, run state, plans) — a fully separate, 100% local tool surface with no shared code or network calls between the two. +`gittensory` exposes ORB's hosted contributor-workflow tools (issue ranking, PR packet prep, decision packs). `gittensory-miner` exposes AMS's own local state-visibility tools listed above (portfolio dashboard, claims, audit feed, run state, plans) — a fully separate, 100% local tool surface with no shared code or network calls between the two. Both follow the same `gittensory_*` tool-naming convention (`gittensory_...` vs. `gittensory_miner_...`), but back onto different stores: ORB's tools read the hosted gittensory backend, AMS's tools read this machine's own local SQLite files (see [Local storage](#local-storage)) — a handful of AMS tools even name the ORB tool they mirror (e.g. `gittensory_miner_get_run_state` is the read-only analog of `gittensory_get_automation_state`) so the relationship is explicit at the point of use, not just here. ## Version check diff --git a/packages/gittensory-miner/docs/coding-agent-driver.md b/packages/gittensory-miner/docs/coding-agent-driver.md index 7cd26c1420..a378ce6c00 100644 --- a/packages/gittensory-miner/docs/coding-agent-driver.md +++ b/packages/gittensory-miner/docs/coding-agent-driver.md @@ -129,3 +129,4 @@ between loop cycles -- an after-the-fact, cross-cycle total, not the per-iterati - [`env-reference.md`](env-reference.md) — env vars including ledger path overrides. - [`../DEPLOYMENT.md`](../DEPLOYMENT.md) — laptop vs fleet deployment and state directory layout. - [`miner-goal-spec.md`](miner-goal-spec.md) — per-repo `.gittensory-miner.yml` targeting policy. +- [`../README.md#mcp-server`](../README.md#mcp-server) — the `gittensory-miner-mcp` read-only tool surface for querying this driver's resolved status (provider, model env-var name, CLI presence) and the rest of AMS's local state over MCP. diff --git a/test/unit/miner-mcp-tool-docs-parity.test.ts b/test/unit/miner-mcp-tool-docs-parity.test.ts new file mode 100644 index 0000000000..5cc9f4a1c5 --- /dev/null +++ b/test/unit/miner-mcp-tool-docs-parity.test.ts @@ -0,0 +1,55 @@ +import { readFileSync } from "node:fs"; +import { join } from "node:path"; +import { describe, expect, it } from "vitest"; + +const MCP_BIN_PATH = join(process.cwd(), "packages/gittensory-miner/bin/gittensory-miner-mcp.js"); +const README_PATH = join(process.cwd(), "packages/gittensory-miner/README.md"); +const CODING_AGENT_DRIVER_DOC_PATH = join(process.cwd(), "packages/gittensory-miner/docs/coding-agent-driver.md"); + +/** Every `server.registerTool("gittensory_miner_...", ...)` name in the real MCP bin -- the source of truth + * this test pins the README's "MCP server" section against, so the two can never silently drift (#5162). */ +function registeredMinerMcpToolNames(): string[] { + const source = readFileSync(MCP_BIN_PATH, "utf8"); + const names = [...source.matchAll(/server\.registerTool\(\s*\n?\s*"(gittensory_miner_\w+)"/g)] + .map((m) => m[1]) + .filter((name): name is string => name !== undefined); + expect(names.length).toBeGreaterThan(0); + return names; +} + +describe("miner MCP tool documentation parity (#5162)", () => { + it("documents every registered tool in the README, and documents nothing else", () => { + const registered = registeredMinerMcpToolNames(); + const readme = readFileSync(README_PATH, "utf8"); + const mcpSection = readme.slice(readme.indexOf("## MCP server"), readme.indexOf("## Version check")); + + for (const name of registered) { + expect(mcpSection).toContain(`\`${name}\``); + } + + const documented = [...mcpSection.matchAll(/`(gittensory_miner_\w+)`/g)] + .map((m) => m[1]) + .filter((name): name is string => name !== undefined); + for (const name of documented) { + expect(registered).toContain(name); + } + }); + + it("documents the excluded-column safety property for the ledger/governor tools", () => { + const readme = readFileSync(README_PATH, "utf8"); + const mcpSection = readme.slice(readme.indexOf("## MCP server"), readme.indexOf("## Version check")); + expect(mcpSection).toContain("payload_json"); + }); + + it("relates AMS's local MCP tools to the hosted gittensory-mcp tools", () => { + const readme = readFileSync(README_PATH, "utf8"); + const mcpSection = readme.slice(readme.indexOf("## MCP server"), readme.indexOf("## Version check")); + expect(mcpSection).toContain("local SQLite"); + expect(mcpSection).toContain("hosted"); + }); + + it("is cross-referenced from the coding-agent-driver doc", () => { + const doc = readFileSync(CODING_AGENT_DRIVER_DOC_PATH, "utf8"); + expect(doc).toContain("../README.md#mcp-server"); + }); +});