git-surface-mcp

An agent-ergonomic MCP git service — the wrapper the evolutionary tournament (../new_repo/packages/git_surface) converged toward, materialised as a real, dependency-free MCP stdio server.

Traditional git output is written for humans; an LLM agent burns context parsing noisy strings and hallucinates flags. This service inverts that with deep empathy for the containerised agent.

Tools

| tool | returns | |---|---| | inspect_git_surface(repo) | branch · short commit · categorised changed paths (counts-only when large) — no raw status/log noise | | pull_atomic_file(repo, path, start?, end?, max_tokens?) | metadata header (lines/range/est_tokens) then content; missing path → ranked fuzzy suggestions; over max_tokens → content withheld + paging hint (never a silent context blow-up) | | query_file_blame(repo, path, n?) | commit count + last n touches (sha/date/subject), not the whole log |

Design principles (evolved, evidence-backed)

- Minimal token overhead — files are atomic targets; metadata precedes content so the agent can page or abort. - High atomic precision — self-correcting error payloads (did_you_mean) let the agent self-heal without losing momentum. - Structured, low-noise — every response is a compact JSON object, not a wall of text.

Run

python -m git_surface_mcp            # MCP stdio server (JSON-RPC 2.0, newline-delimited)
python tests/test_tools.py           # self-verifying tests (real git fixture)

Stdlib only — no mcp/FastMCP dependency; handle_message is a pure function for testing.

Provenance

Distilled from the git-surface tournament: structured/summary surface, ranged reads with a token header, and ranked fuzzy error self-heal were the traits the fitness function selected for. See RFC-0028 (experimental) for the tournament method.