# agent-handoff-mcp

Centralized multi-project state & handoff **MCP server** (Streamable HTTP).
AI agents (Claude Code, Codex, Cursor, …) save checkpoints in one session and
resume in another with under 500 tokens of input overhead. The full specification
is captured across the guides in the [Documentation](#documentation) section.

## Quickstart

```bash
cd agent-handoff
./dev.sh                 # bootstraps .venv, installs dev deps, starts the server
# with the web dashboard:  http://127.0.0.1:8766/
# MCP endpoint:            http://127.0.0.1:8765/mcp
```

`dev.sh` uses repo-local defaults (`./state.db`, loopback, dashboard on) and
supports `--fresh`, `--no-dashboard`, `--port`, `--dash-port`, `--token`,
`--log`, and `--check` (run lint+tests). See `./dev.sh --help`. To run
manually instead:

```bash
python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
DATABASE_PATH=./state.db .venv/bin/python main.py
```

The server listens for MCP at `http://127.0.0.1:8765/mcp` and exposes a
`GET /health` endpoint (`{"status":"ok","db":"writable"}`).

## Features

- **12 tools · 2 resources · 1 prompt** — every command explained in
  [`docs/mcp-usage.md`](docs/mcp-usage.md)
- **Handoff context < 500 tokens** — deterministic `ceil(len/4)` metric with a
  documented truncation order
- **Seed context** — drop `.md`/`.json` files in a repo's `.agent-handoff/`
  folder (glossary, API contracts, business flows) and the server folds them
  into the handoff summary + serves them on demand
- **Git snapshots** — `save_checkpoint` captures `git diff HEAD --stat` plus
  untracked files (capped at 200 lines / 4 KB)
- **SQLite WAL** with a single async writer connection (no `database is locked`)
- **Fail-closed auth** — `Authorization: Bearer <token>` required when
  `MCP_AUTH_TOKEN` is set; refuses to bind non-loopback without a token
- **Code-graph integration** — queries `code-review-graph` + `graphify`, and can
  store per-project graphs **inside the MCP database** instead of each repo
- **Auto-start** — the server can spawn and supervise graph-server subprocesses

## Documentation

| Guide | What it covers |
|---|---|
| [`docs/getting-started.md`](docs/getting-started.md) | Install, run, connect MCP clients, first-run walkthrough |
| [`docs/mcp-usage.md`](docs/mcp-usage.md) | **The command reference**: every tool, resource and prompt, with parameters, examples, responses and error codes |
| [`docs/configuration.md`](docs/configuration.md) | All environment variables, the auth model, and the data layout |
| [`docs/code-graph-integration.md`](docs/code-graph-integration.md) | Graph servers, manual start, auto-start, DB-backed per-project graphs, stale-artifact cleanup |
| [`docs/deployment.md`](docs/deployment.md) | Docker, systemd service, backups, Tailscale/SSH exposure, hardening |
| [`docs/ROADMAP.md`](docs/ROADMAP.md) | Done vs. planned work, PRD acceptance-criteria coverage matrix |
| [`CHANGELOG.md`](CHANGELOG.md) | Feature milestones, fixes, and known limitations |

## Tests

```bash
.venv/bin/python -m pytest -q
```

Covers the PRD acceptance criteria: migrations/WAL, path validation, git
capture, the 500-token budget, retention pruning, fail-closed auth (401s),
`/health`, 20 parallel mixed requests, code-graph capture, DB-backed graph
storage, and auto-start supervision.