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 section.

Quickstart

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:

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

Tests

.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.