Git Tools

Git Version Control

The git tool provides filesystem-aware Git operations, fully integrated with the MCP server’s security model (allowed paths), hook system, and audit logging.

Requires: Git CLI installed and accessible in PATH. All actions except init must run inside a git repository (the repo root is auto-detected from path).

---

git

Actions (9): status, diff, log, show, add, commit, restore, branch, init

Annotations:

Annotation	Value
readOnly	false
destructive	true (restore, branch delete)
idempotent	false

Parameters:

Parameter	Required	Type	Description
action	Yes	string	One of the 9 actions above
path	No	string	Working directory or file path (default: auto-detect repo root). A file path acts as implicit pathspec for diff/log/status
paths	No	array of strings	Pathspec limiting diff/log/status/add/restore. Native array, equivalent to git <cmd> -- <paths>
output	No	string	Output format. diff/show: stat (default) | name-only | full. status: name-only (default) | full. log: oneline (default) | full
max_lines	No	number	Max output lines before truncation with hint footer (default: 200)
limit	No	number	log: max commits (default: 10)
rev	No	string	Revision or range (HEAD~3, abc123..def456, main). For diff/log/show/restore
staged	No	bool	diff: compare index vs HEAD (--cached). restore: unstage-only variant
message	Yes (commit)	string	Commit message
name	No	string	branch: branch name to create/delete
checkout	No	bool	branch: with name, also switch to the new branch (git switch -c)
force	No	bool	restore (working-tree): required. branch delete: escalate -d → -D

Removed in v4.5.25: commit_range and source (use rev), max_count (use limit), branch_action/branch_name (use name), all, auto_message, dry_run. paths changed from JSON string to native array.

---

Actions

status — Repository Status

git({ action: "status" })
git({ action: "status", paths: ["src/"], output: "full" })

• output:"name-only" (default): git status --porcelain=v1 -b
• output:"full": porcelain v2 with branch tracking info
• Compact server mode: one-liner repo (branch) | +staged ~unstaged ?untracked | clean|dirty

---

diff — Show Changes

git({ action: "diff" })                                        // stat of unstaged
git({ action: "diff", staged: true })                          // stat of staged
git({ action: "diff", rev: "HEAD~3..HEAD" })                   // range
git({ action: "diff", paths: ["src/main.go"], output: "full" }) // full patch, scoped

4-layer guardrail (prevents context blow-up on huge diffs):

1. Default output is stat, never full patch
2. output:"full" without paths and more than 20 changed files → downgraded to stat with a banner (not an error)
3. output:"full" with explicit paths is always honored
4. max_lines (default 200) truncates all output with a footer

---

log — Commit History

git({ action: "log" })                                  // last 10, oneline+decorate
git({ action: "log", limit: 5, rev: "main" })
git({ action: "log", paths: ["src/"], output: "full" }) // hash|subject|author|relative-date

---

show — Show a Commit

rev is required.

git({ action: "show", rev: "HEAD" })                 // commit metadata + stat
git({ action: "show", rev: "abc1234", output: "full" })
git({ action: "show", rev: "HEAD~1", paths: ["core/"], output: "name-only" })

---

add — Stage Files

paths is required — there is no implicit add . / -A fallback (refused by design since v4.5.20).

git({ action: "add", paths: ["src/main.go", "core/engine.go"] })

A -- separator is always inserted before paths, so a file named -A cannot be parsed as an option.

Hooks: HookPreWrite / HookPostWrite.

---

commit — Commit Staged Changes

message is required. Optional paths commits only a subset of staged changes.

git({ action: "commit", message: "fix: resolve null pointer in handler" })
git({ action: "commit", message: "wip", paths: ["src/"] })

Risk assessment (reported in the response, never blocks):

Level	Condition
LOW	≤15 files and ≤800 insertions
MEDIUM	>15 files or >800 insertions
HIGH	>40 files, >3000 insertions, or >500 deletions

Nothing staged → usage error with an add example. Hooks: HookPreWrite / HookPostWrite (hook can deny the commit).

---

restore — Restore Files

paths is required — no implicit whole-tree restore.

git({ action: "restore", paths: ["src/main.go"], staged: true })              // unstage only (safe)
git({ action: "restore", paths: ["src/main.go"], force: true })               // discard working-tree changes
git({ action: "restore", paths: ["src/main.go"], rev: "HEAD~1", force: true }) // from a prior commit

• staged:true — unstage-only (equivalent to git reset HEAD <path>), non-destructive, no force needed
• Working-tree restore or restore-with-rev discards changes → requires force:true
• rev is passed as --source=<rev>

Hooks: HookPreDelete / HookPostDelete.

---

branch — List, Create, Delete

Behavior is driven by name and whether the branch exists:

Call	Result
no name	List all branches (git branch -a)
name (doesn’t exist)	Create branch; with checkout:true → git switch -c
name (exists)	Delete with -d; force:true escalates to -D

git({ action: "branch" })
git({ action: "branch", name: "feature/new-ui", checkout: true })
git({ action: "branch", name: "feature/old" })                 // -d: git refuses unmerged
git({ action: "branch", name: "feature/old", force: true })    // -D

Plain -d is not gated behind force — git itself refuses to delete unmerged branches.

---

init — Initialize Repository

git({ action: "init", path: "C:/path/to/new-project" })

The only action that works outside a repository. Respects --allowed-paths. Hooks: HookPreCreate / HookPostCreate.

---

Security

• No shell interpretation: arguments go straight to the git process via exec.Command — never through cmd.exe/sh — so metacharacters (& | % ^ ") in messages, branch names or paths are inert. The old cmd /c Windows fallback was removed (v4.5.29).
• Option-injection guard: rev and name values starting with - are rejected before reaching git (rejectOptionLike), closing the --output=<file> injection vector.
• -- separator before every user pathspec in add/diff/log/status/restore.

Error Handling

Errors include a usage: example with the correct call shape. Common cases:

Error	Resolution
path is not inside a git repository	Run git(action:"init", path:...) or use a path inside a repo
git add requires explicit 'paths'	Pass paths:["file"] — no implicit add .
nothing staged to commit	Run git(action:"add", ...) first
destructive git operation 'restore' requires force:true	Add force:true, or use staged:true for the safe unstage variant
invalid rev "-x": value must not start with '-'	Option-injection guard — pass a real revision

For the full parameter schema with examples, call help(tool:"git") from any MCP client.

---

Hardening History

• v4.5.20 — git add requires explicit paths; -- separator before user paths
• v4.5.21 — Windows stderr propagation fixed
• v4.5.22 — restore validation order; --staged no longer requires force
• v4.5.23 — restore command construction; branch -d/-D safety inversion corrected
• v4.5.25 — agent-usable refactor: show action (9 total), rev replaces commit_range/source, paths becomes native array, output enum, 4-layer diff guardrail, usage:-example errors, help(tool:"git")
• v4.5.29 — cmd.exe fallback removed (command-injection surface); govulncheck hardening

The audit trail is in CHANGELOG.md.

---

See Also

• Core Tools — All 20 MCP tools
• Backup Tools — Persistent backup and recovery
• Tool Selection Guide — Which tool for your task