The MCP server

The local MCP server lets an agent read repository context and check a proposed change while it is still writing it. Findings and coverage give the agent a concrete next step before review.

This page is the server. For the whole loop an agent runs — the envelope it reads, the pre-push hook, garboard init per harness, the plugin, and what the Check Run gives it afterwards — see Deltz for coding agents.

Use the matching reviewed build supplied during setup. The application-change input and optional verification observation below require that build; the older private v0.2.10 release does not include those MCP extensions. The commands assume garboard is already installed on PATH.

Read-only by contract

The MCP tools are read-only. They inspect supplied changes and local context; they do not edit the repository, execute application tests, merge a pull request or write to your cloud. There is no write tool to enable.

The tools

check_diff returns the shared {status, clean, findings[], coverage{}, meta{}} envelope used by garboard gate --format json. Inspect findings and coverage: unsupported input or a failed read is not successful verification. A clean local result describes the supported checks that ran, not complete application behavior. See the status table.

For supported candidate files, supply their full contents and the actual local base ref:

{
  "files": {"src/example.ts": "export const value: any = 1;\n"},
  "base_ref": "origin/main"
}

Run the MCP process in the repository whose Git history is being compared. base_ref resolves to the merge-base with HEAD, and meta.base identifies the comparison actually used. Supported infrastructure inputs use their existing checks; .ts, .tsx, .js and .jsx changes use advisory integrity checks. Application checks do not parse/type-check TypeScript or execute tests.

Application deletions and explicit before/after inputs use changes, with base and head sides declared present (with content) or confirmed absent. An empty existing file differs from absence; a missing, unreadable or truncated side cannot become an empty baseline. Represent renames as delete plus add. When base_ref is supplied alongside explicit baseline bytes, they must agree. See the agent guide for the input bounds and scope.

Optional verification: true adds a local observation of supplied bytes and actual coverage. Its profile retains unresolved protected requirements and never returns complete. It does not authenticate customer CI or claim full repository scope. Omitting the flag preserves the ordinary envelope.

Recorded episode history is context, not proof of acceptance, CI success or deployment. Missing or unreadable local history must not be interpreted as proof that the repository has no history.

Running it

garboard mcp                        # stdio, the default
# --transport http is not implemented: the server speaks stdio only, and the
# binary refuses any other value. The agent runs it as a local process.
garboard mcp --rcd .garboard/rcd.json

It loads the RCD written by garboard scan and local episode context at startup. Rescan and restart the local server when that context changes. Local checks run offline without a model key or cloud credentials. garboard init --harness claude-code merges {"command": "garboard", "args": ["mcp"]} into .mcp.json; Cursor also uses .cursor/mcp.json. Codex requires the additional codex mcp add garboard -- garboard mcp step. Follow the per-harness setup, then confirm the installed agent can list and call the tools.

The static alternative

If you would rather hand an agent a file than run a server:

garboard export --format claude-md      # CLAUDE.md
garboard export --format agents-md      # AGENTS.md
garboard export --format cursor-rules   # cursor rules
garboard export --format all

The exported file and the running MCP server both depend on the context they loaded. Regenerate exported instructions after a rescan, or restart MCP to load the updated local RCD. Neither automatically becomes current with a hosted workspace.

Why this is the distribution channel

We ship an MCP server so that coding agents can read this material. That is also why our documentation does not block AI crawlers — agents reading our docs is the point, not a leak.