# ShadowGit MCP server

Gives Claude Code, Cursor and Claude Desktop access to [ShadowGit](https://shadowgit.com): the automatic snapshots
ShadowGit takes of your projects every few minutes, kept apart from your own git history. Your assistant can see what
changed and when, and can save its own edits as one named checkpoint instead of many partial snapshots.

## Requirements

- Node.js 20 or later
- The ShadowGit app (0.3.4 or later for checkpoints, a release after 0.3.5 for the Lens, after 0.3.7 for its linked
  words, after 0.3.9 for the map, after 0.3.10 for the Lens's dependency facts, 0.3.11 or later for the project's
  rules, 0.3.13 or later for a session's unsaved edits in a snapshot as it ends and for the check of a checkpoint
  that finds nothing new), tracking at least one project.
  Reading history works while the app is closed;
  sessions, checkpoints, the Lens and the map need it running.
- Git on your PATH

## Setup

**Claude Code** (one install for every project):

```bash
claude mcp add --scope user shadowgit -- npx -y shadowgit-mcp-server
```

**Cursor**: in `~/.cursor/mcp.json`:

```json
{ "mcpServers": { "shadowgit": { "command": "npx", "args": ["-y", "shadowgit-mcp-server"] } } }
```

**Claude Desktop**: the same entry in `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or
`%APPDATA%\Claude\claude_desktop_config.json` (Windows).

In Claude Code the server knows which project you are in. In Cursor and Claude Desktop, name the project ("in
webshop") when ShadowGit tracks more than one.

## What to ask

- "What changed in the last hour?"
- "When did the login page break?"
- "Show me the history of Header.tsx"
- "How is this project organised?"
- "What depends on chargeCard?"
- "Start a ShadowGit session for this refactor", then "Create a checkpoint: Fixed login redirect", then "End the
  ShadowGit session"
- "Write the Lens words for this session"
- "What does the billing area do?"
- "Document this project in ShadowGit"

## Tools

| Tool | Does |
|---|---|
| `list_repos` | Lists tracked projects, the current one, their last snapshot and any active session |
| `git_command` | Runs a read-only git command (`log`, `diff`, `show`, `blame`, …) on the snapshot history |
| `get_map` | Gives how the project is organised: its areas, layers and the links between them, or one area, the project's rules and its docs pages' summaries |
| `get_code_context` | Gives where files and symbols sit, what depends on them, where a change to them lands, the project's rules for them and their areas' docs pages' summaries |
| `start_session` | Pauses automatic snapshots while the assistant edits |
| `checkpoint` | Saves the current changes as one named checkpoint, following `.shadowgit-ignore`, then checks it against the project's `.shadowgit-rules` |
| `end_session` | Resumes automatic snapshots |
| `get_lens` | Reads ShadowGit's Lens of a range, by default the latest AI session, with what it makes depend on what and the links a rule names |
| `write_lens_words` | Writes the Lens's words for that range, kept in the history, with links, a why and an excerpt |
| `get_docs` | Reads the project's docs pages, one per map area plus an Overview: by default those the latest AI session changed that need words, each with its facts, its words so far and what changed since them |
| `write_docs` | Writes pages' words, with links to symbols and areas, or keeps words that still hold; kept in the history, never in the project's files |

The other tools work on the current project unless given `repo`.

## Security

`git_command` runs only read-only subcommands, without a shell, and refuses the options that would read or write files
outside the snapshot history (`--output`, `--no-index`, `blame --contents` and others, including abbreviated and bundled
forms), the ones that run helper commands from git's configuration (`--ext-diff`, `--textconv`, `--filters`), and paths
outside the project. Checkpoints are made by the ShadowGit app, only in projects you added to it. The
server itself only talks to the ShadowGit app on localhost; what it returns goes to your assistant like any tool result.

The server trusts the project's `.shadowgit.git` history, which the ShadowGit app creates. Git honours that history's
configuration, so a planted one can make git run programs, through the app's own snapshots as much as through this
server. Don't add a project to ShadowGit that arrived with a `.shadowgit.git` folder you didn't create.

## Configuration

| Variable | Default | Purpose |
|---|---|---|
| `SHADOWGIT_TIMEOUT` | `10000` | Milliseconds a git command may run |
| `SHADOWGIT_SESSION_API` | `http://localhost:45289/api` | The ShadowGit app's local API |
| `SHADOWGIT_STORAGE_DIR` | platform default | Where ShadowGit keeps `repos.json` |

## Development

```bash
npm install
npm test        # builds, then runs the unit, integration and end-to-end tests
npm run eval    # runs the phrases from docs.shadowgit.com through Claude Code (spends tokens)
```

## License

MIT