Fluxgit MCP Server

fluxgit-mcp-sidecar

mcp-name: io.github.fluxgit-hq/fluxgit-mcp-server

Safety-first Model Context Protocol (MCP) server for Git.

AI agents inspect. FluxGit keeps control.

A Rust MCP server with 38 contracts for AI code agents: 25 read-only tools and 13 human-gated operation tools (12 proposals plus cancellation of a pending proposal). The sidecar never executes a Git write; it bridges approved proposals to the FluxGit desktop application.

For context-budget comparisons, see the public Git context token benchmark. It publishes the fixture, raw outputs, scripts and checksums, including both the broad CLI sweep and a smaller hand-tuned counterexample.

---

Why this exists

AI coding agents are increasingly asked to navigate real repositories: explain branch state, summarize diffs, find lost commits, recommend safe next steps. To do this well, an agent needs Git context that is richer than git status and structured enough to reason over. To do this safely, an agent must never be able to silently mutate refs, force-push, discard work, or apply patches without a human approving the consequence.

Other MCP Git servers face a choice: stay strictly read-only (limited utility) or expose write tools directly (dangerous — agents hallucinate, prompts can be poisoned, mistakes are destructive). This sidecar chooses neither. Inspection is schema-validated and bounded; operations go through a write-with-UI-handshake: the agent proposes, FluxGit shows the preview, the user approves in the app, and FluxGit executes through its safety pipeline with restore points and audit.

---

What's exposed

25 read-only tools

13 write-with-UI-handshake tools

All 12 operation.preview.* proposals dispatch through the FluxGit gateway when configured. The sidecar POSTs the proposal, performs one bounded status read, and normally returns immediately with accepted: true, the canonical previewId, current status and nextAction.tool: "operation.status". The FluxGit app renders a “Requested by AI agent” approval card while human review continues asynchronously. Code 10003 is reserved for a bridge that is absent, invalid or unreachable; it is not a human-approval timeout.

All 12 preview schemas accept an optional bounded idempotencyKey. Reuse it only when retrying the same logical intent; the sidecar scopes it to the operation type so that retry resolves to the existing gateway proposal. Omit it for a new intent—even when the other arguments match—and the sidecar sends a fresh UUID-backed key. Preview tools therefore continue to advertise idempotentHint: false.

All write proposals require a free-text reason so the user sees the agent's justification in the approval modal. All reuse the same durable gateway lifecycle (pending → approved → executing → completed|failed, with rejection/cancellation/expiry branches) and the same Tauri bridge in the UI. Six shims cover pending, recoverable, approve, claim, reject and complete. After restart, Approved proposals may resume only after repo/ref revalidation and claim; Executing proposals are shown for explicit reconciliation and are never blindly re-executed. When an approved operation captures a restore point, the completion result exposes that recovery metadata so the agent can report it without guessing.

The boundary is deliberately fail-closed at approval time. FluxGit resolves the proposal's repoPath to its canonical open-repository id and requires it to match the repository the human is reviewing; an unresolved path, mismatch, or repository switch blocks execution. Tool arguments are validated before dispatch and again by the gateway. An optional declarative agent policy can deny proposals before a card opens. Its rules match the agentId the sidecar forwards (the sanitized, self-declared clientInfo.name, such as claude-code) a