mcp-graph is an MCP server — a persistent context layer that plugs into the AI coding tool you already use and gives it structured memory, task tracking, and engineering discipline.

The AI does the work. The server keeps it on track.

The problem

Every AI coding session has the same failure modes:

• The agent forgets — each new chat starts from zero, the plan gets reinvented
• PRDs become walls of text — nobody re-reads them, the agent improvises
• No traceability — you can't tell what was done, what's blocked, or why

How it works

mcp-graph runs as an MCP server that your AI coding tool connects to automatically. Once connected, the AI gains access to 54 MCP tools — persistent task graph, compressed context, lifecycle phases, and structured engineering.

You write a PRD. The AI implements it.

PRD → import_prd (MCP) → task graph → start_task → [TDD] → finish_task → done

The AI calls the MCP tools directly. No manual commands needed.

Setup — once per project

npm install -g @mcp-graph-workflow/mcp-graph
mcp-graph init

mcp-graph init generates the connection config for every supported AI tool automatically:

| AI Tool | Config file generated | |---|---| | Claude Code | .mcp.json | | OpenCode | opencode.json | | GitHub Copilot (VS Code) | .vscode/mcp.json | | Cursor | .mcp.json |

Open your AI tool. It connects to the MCP server automatically. No further configuration needed.

Prerequisites: Node.js ≥ 18. No Docker. No LLM API key.

Tell the AI what to do

Once connected, give your AI tool a PRD and a skill:

"Read PRD.md and implement it using /graph-implement"

The AI will:

1. Call import_prd (MCP) — parses the PRD, creates tasks with acceptance criteria in the graph
2. Call start_task (MCP) — picks the next task with compressed context (73% fewer tokens)
3. Follow TDD: write failing test → implement → make it pass
4. Call finish_task (MCP) — validates 9 Definition-of-Done checks, marks done, suggests next
5. Repeat until the backlog is empty

Skills — your interface to the AI

Skills are slash commands that trigger the right MCP workflow for each phase:

| You want to... | Skill | |---|---| | Implement the next task | /graph-implement | | Validate what was built | /graph-validate | | Plan a sprint | /graph-plan | | Review before PR | /graph-review | | Import a PRD | /graph-prd |

Skills are installed by mcp-graph init and appear in the autocomplete of your AI tool (type / in Claude Code, OpenCode, or Copilot).

What the AI gains via MCP

| Capability | What it does | |---|---| | Persistent task graph | SQLite local — survives across sessions, never in the cloud | | Compressed context | 73% token reduction per task — RAG (FTS5 + BM25), no external LLM | | 9-phase lifecycle | ANALYZE → DESIGN → PLAN → IMPLEMENT → VALIDATE → REVIEW → HANDOFF → DEPLOY → LISTENING | | DoD automation | 9 checks per task before marking done (AC quality, TDD, no blockers) | | Knowledge store | Captures decisions, patterns, and context for future sessions |

Privacy

Zero telemetry. Zero phone-home. Runs offline after installation.

All data lives in workflow-graph/graph.db — local SQLite, gitignored, never in the cloud.

Documentation

• Quickstart — connect and run in 60 seconds
• AI tools setup — Claude Code, OpenCode, Copilot, Cursor
• Full guide — MCP server, skills, lifecycle phases
• End-to-end tutorial — PRD to delivery
• Cheatsheet — all commands and skills

License

AGPL-3.0-or-later — open source with strong copyleft. Proprietary commercial use: commercial license available.