# Intent-Diff MCP

> Catch **context drift** — the scope an AI coding agent quietly adds beyond what you actually asked for.

An [MCP](https://modelcontextprotocol.io) server with two tools. You lock in your original request; the agent, before it declares "done", diffs the actual code changes against that request and reports anything it added on its own — an unrequested library, a metrics layer, a new abstraction — so you can **Keep** it or **Roll it back**.

The *diff* is deterministic ground truth (git doesn't lie). The *judgment* is a fresh Claude call that didn't write the code, so it has no stake in rationalizing the additions.

```
🤖 Intent Diff Report

Requested: Add a Postgres connection pool in db.ts — ✅ done

[+] Added on my own (drift candidates):
- New metrics.ts with Prometheus instrumentation — you never asked for
  observability or a new dependency (prom-client).

[?] Worth confirming:
- Should metrics.ts stay, or be removed?

→ Keep or Rollback?
```

## Tools

| Tool | When | What it does |
|------|------|--------------|
| `start_task` | A non-trivial feature/refactor is requested | Records your request + snapshots the current git HEAD. Cheap (one SHA). |
| `get_intent_diff` | Before saying "done" on substantial changes | Diffs everything since the snapshot, runs the judge, returns a drift report. |

## Install

Requires **Node ≥ 18** and either a logged-in **Claude Code** session *or* an `ANTHROPIC_API_KEY` (see [Auth](#auth)).

Add to your MCP client config (Claude Code `.mcp.json`, `mcporter.json`, etc.):

```json
{
  "mcpServers": {
    "intent-diff": {
      "command": "npx",
      "args": ["-y", "@ssh00n/intent-diff-mcp"]
    }
  }
}
```

That's the whole setup — `npx` fetches and runs it.

## Recommended workflow (hybrid)

Intent-Diff is **not** meant to gate every edit — that just taxes trivial work. The sweet spot: **always snapshot (cheap), judge on demand (costly)**. Drop this into your project's `CLAUDE.md` (a ready copy is in [`examples/CLAUDE.md`](examples/CLAUDE.md)):

```markdown
# Intent-Diff workflow (hybrid)
- When starting a non-trivial feature or refactor, call `start_task` with the
  user's request verbatim. (It's cheap — just a git snapshot.)
- Before declaring a substantial change "done" — new feature, or edits spanning
  multiple files — run `get_intent_diff` and show the report.
- Treat the report as advisory: surface drift to the user and ask Keep/Rollback.
  Skip it for one-line fixes and pure exploration.
```

Prefer softer or stricter? See [Tuning the rules](#tuning-the-rules).

## Auth

The judge needs to call Claude. Two ways, checked in this order:

1. **`ANTHROPIC_API_KEY`** (recommended for CI and contributors) — normal API billing.
2. **Local Claude Code subscription** — if no API key is set, the server reuses the
   OAuth token your Claude Code login already stores (macOS Keychain or
   `~/.claude/.credentials.json`), refreshing it when near expiry. No extra setup if
   you're already logged into Claude Code.

Pick the judge model with `INTENT_DIFF_MODEL` (default `claude-sonnet-4-6`).

## Tuning the rules

The workflow above is the **hybrid** default. Adjust to taste:

- **Softer** — drop the `get_intent_diff` line; call it only when *you* ask "check drift". The agent self-checks the rest of the time.
- **Stricter** — make both calls mandatory ("always `start_task` first; never say done without `get_intent_diff`") and require an explicit Keep/Rollback answer. Good for team enforcement; higher overhead.

Note: a heavy-handed rule can bias an agent toward *under*-implementing (skipping necessary error handling for fear of "drift"). The judge is told to ignore refactors and necessary error handling, but keep the rule proportional to the stakes.

## How it works

`start_task` writes `<repo>/.mcp/intent_state.json`, keyed by git branch, with your
request and the HEAD SHA. `get_intent_diff` collects `git diff <baseSha>` plus any
untracked files (skipping binaries, lockfiles, and `.mcp/`), caps it, and sends
`{ original intent, actual diff }` to the judge, which returns structured JSON that's
rendered into the report.

## Development

```bash
npm install
npm run typecheck    # tsc --noEmit
npm test             # Tier-1 unit tests (no network)
npm run test:smoke   # end-to-end via MCP client, stub judge (no network)
npm run eval         # judge accuracy over labeled fixtures (needs auth — real calls)
```

## Contributing

Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). Good first areas:
more judge fixtures, additional credential sources, non-git VCS support.

## License

[MIT](LICENSE) © ssh00n