# git-surgeon-mcp

![License](https://img.shields.io/badge/license-MIT-blue.svg)
![Node](https://img.shields.io/badge/node-%3E%3D18-339933?logo=node.js&logoColor=white)
![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178C6?logo=typescript&logoColor=white)
![MCP](https://img.shields.io/badge/MCP-server-8A2BE2)

An MCP server that gives AI agents safe, non-interactive Git history editing — squashing, rewording, and reflog rescue — without ever hanging on a Vim buffer.

## Why

Agents shell out to Git fine for everyday commands, but `git rebase -i` and `git commit --amend` (without `-m`) open an interactive editor and hang forever waiting for input that never comes. Agents then resort to risky fallbacks like `git reset --hard`. `git-surgeon-mcp` wraps these operations in clean, programmatic tools instead.

## How it's safe

- **No shell execution** — every Git call uses `execFile` with an argument array, so command injection is structurally impossible.
- **No `-m` quoting issues** — messages are written to a temp file and applied via `git commit -F`.
- **Non-interactive rebase shim** — rewording a non-HEAD commit normally needs two interactive editors; the server points `GIT_SEQUENCE_EDITOR`/`GIT_EDITOR` at generated scripts that do it programmatically.
- **Clean-tree checks** — every operation requires a clean `git status` and auto-aborts (`git rebase --abort`) on failure.

## Tools

| Tool | Description |
|---|---|
| `git_get_history` | Structured `git log` output. |
| `git_quick_squash` | Squash the last N commits with a new message. |
| `git_reword_commit` | Reword any commit (HEAD or buried in history). |
| `git_rescue_reflog` | Find dangling/unreachable commits via reflog + fsck. |

## Setup

```bash
git clone https://github.com/mustafatekiinn/git-surgeon-mcp.git
cd git-surgeon-mcp
npm install && npm run build
```

Add to your client's MCP config (Claude Desktop's `claude_desktop_config.json`, Cursor's `.cursor/mcp.json`, etc.), using the absolute path to `dist/index.js`:

```json
{
  "mcpServers": {
    "git-surgeon": {
      "command": "node",
      "args": ["/absolute/path/to/git-surgeon-mcp/dist/index.js"]
    }
  }
}
```

Restart the client — the four tools are now available whenever the agent works inside a Git repo.

## Requirements

- Node.js 18+, Git on `PATH`, a local Git repository

## Safety Notes

- Squashing/rewording rewrites history — force-push (`--force-with-lease`) if already pushed, and coordinate with collaborators first.
- All operations abort cleanly, leaving no partial state, if the working tree is dirty or a step fails.

## License

MIT