MCP SERVER · TYPED GIT
nxm-git
Typed, structured Git for agents — and the Git backend of the future NXM TUI.
Built to run entirely locally. Open source under the MIT license.
Why I built it
Most harnesses let an agent drive Git through the shell. With many features in flight at once — often across isolated worktrees at the same time — I needed a governance tool to be sure the work happened in the right place, and that a careless operation never broke what was already working.
I built nxm-git so a coding agent handles Git the way it should: by reading structured data, not by scraping terminal text.
A normal agent runs git in a shell and parses back the human-formatted output — brittle, token-hungry, and one format change away from a bug. It also has nothing stopping a distracted force-push onto main or a private trace slipping into a public push. nxm-git fixes both. Every read returns native, typed data (status, diff, log, blame) with no parsing. Every write passes two gates first — a repository-path perimeter and a per-repo policy — so the dangerous edge needs an explicit, deliberate flag.
The result: an agent that reads Git as structured JSON, never force-pushes by accident, and never ships content that was supposed to stay private. The same core runs in-process behind the NXM TUI, so the human gets identical guards.
What it is
nxm-git is a small, security-first MCP server over a typed Rust core. It exposes fourteen Git operations as typed tools returning structured JSON, reads with git2 (no text parsing) and writes by shelling out with strict argument arrays. Every write is confined to an allow-listed repository and checked against a committed per-repo policy before a single git command runs. It is not a full Git port and makes no guarantee of security — it removes the distracted mistake and complements the shell-blocking guardrails hook.
Typed, not log text
Reads return native git2 data — status, diff, log, blame — as structured JSON an agent acts on directly. No screen-scraping, no log-parsing bugs, fewer tokens.
Two gates before any write
A command touches nothing until it clears both: ResolvedRepo::open confines it to an allow-listed repository, then check_policy blocks protected-branch, force, and forbidden-content writes. Guards are friction, not a cage — an intentional op passes with an explicit flag.
One core, two consumers
The agent calls it over MCP; the future NXM TUI calls the same Rust core in-process. Both inherit identical behaviour and identical safety — the core never knows who called it.
How it works
Architecture — one core, two consumers, two gates before any write
Tool catalogue — fourteen typed tools, read vs write
The workflow — work rises through isolated worktrees; main is guarded
The fourteen tools
Read — structured, native (no output parsing)
git_status
staged / unstaged / untracked paths
git_diff
per-file additions/deletions between refs or worktree
git_log
commits in a range: SHA, author, date, subject
git_branches
local/remote branches with ahead/behind vs upstream
git_show
file at a ref, or commit info
git_blame
per-line commit, author and content
git_scan_forbidden
forbidden-pattern scan — hits or CLEAN
Write — policy-gated
git_commit
commits staged changes; protected branch needs confirm
git_create_branch
branch from an explicit base, never current HEAD
git_create_integration_branch
integration/<workstream> from develop
git_worktree_add
.worktrees/<workstream> isolated worktree
git_switch
switch to an existing branch
git_push
blocks force without flags, and any forbidden content
git_pr_create
opens a PR, never merges
git_scan_forbidden is the flagship: the public-safety check once done by hand every session. git_pr_create never auto-merges; git_push refuses an unflagged force.
Created by Daniele Oddo — AI Engineering Architect
Project: nxm-git · github.com/dangranaz/nxm-mcp-git
View on GitHub →
Tech details
Structure
Rust workspace — nxm-git (typed core) + nxm-git-mcp (thin server)
git2
native reads (status, diff, log, blame) — no text parsing
Writes
strict argument arrays — no shell string interpolation
rmcp
official Rust MCP SDK
tokio
async runtime
axum
Streamable HTTP transport (plus stdio)
clap
CLI
toml
per-repo policy
serde / thiserror
serialization & typed errors
One core, two consumers: the agent over MCP, the future NXM TUI in-process. The same typed core and the same two gates (path confinement + per-repo policy) serve both — the core never knows who called it.