@mcp-graph-workflow/mcp-graph

Automate project planning from PRD to execution. Local-first CLI that converts product requirement documents into structured task graphs with AI-powered context, semantic search, and multi-agent orchestration.

mcp-graph dashboard — task graph view

Quick Start

GitHub Copilot (VS Code)

Create .vscode/mcp.json in your project:

{
  "servers": {
    "mcp-graph": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@mcp-graph-workflow/mcp-graph"]
    }
  }
}

Enable Agent Mode in Copilot Chat, then use the tools: init → import_prd → next → context → update_status

Claude Code / Cursor / IntelliJ

Add to .mcp.json:

{
  "mcpServers": {
    "mcp-graph": {
      "command": "npx",
      "args": ["-y", "@mcp-graph-workflow/mcp-graph"]
    }
  }
}

Windsurf / Zed / Other MCP Clients

Use stdio transport with:

npx -y @mcp-graph-workflow/mcp-graph

From Source

git clone <repo-url> && cd mcp-graph-workflow
npm install && npm run build
npm run dev        # HTTP + dashboard at localhost:3000

For detailed setup, see Getting Started.

Features

PRD → Task Graph — Import .md, .txt, .pdf, or .html documents and auto-generate hierarchical task trees
AI-Optimized Context — 70-85% token reduction with tiered compression (summary/standard/deep)
Smart Task Routing — next suggests the best task based on priority, dependencies, and blockers
Semantic Search + RAG — Full-text BM25 search + TF-IDF embeddings, 100% local
Sprint Planning — Velocity metrics, capacity-based planning, risk assessment
Web Dashboard — Interactive graph visualization, backlog tracking, code intelligence, insights
Multi-Agent Mesh — Serena + GitNexus + Context7 + Playwright coordinated via event bus
Local-First — SQLite persistence, zero external dependencies, cross-platform

Who is this for?

Persona	Use Case
AI Engineers	Structured agentic workflows with token-efficient context
Tech Leads	PRD decomposition into trackable, dependency-aware task graphs
Solo Developers	Project planning with AI-powered suggestions and progress tracking
Teams using Copilot/Claude/Cursor	MCP-native tool integration for AI-assisted development

Dashboard

6 tabs: Graph (interactive diagram + filters) · PRD & Backlog (progress tracking) · GitNexus (code intelligence) · Serena (code memories) · Insights (bottlenecks + metrics) · Benchmark (token economy)

mcp-graph dashboard — PRD & Backlog view

mcp-graph dashboard — Insights view

mcp-graph dashboard — Benchmark token economy

mcp-graph serve --port 3000    # or: npm run dev

Tools & API

	Count	Reference
MCP Tools	26	MCP-TOOLS-REFERENCE.md
REST Endpoints	44 (17 routers)	REST-API-REFERENCE.md
CLI Commands	5	`init`, `import`, `index`, `stats`, `serve`

Integrations

Integration	Role
Serena	Code analysis, memory, symbol navigation
GitNexus	Git graph, impact analysis, dependency visualization
Context7	Up-to-date library documentation fetching
Playwright	Browser-based task validation and A/B testing

All coordinated by an event-driven IntegrationOrchestrator. See INTEGRATIONS-GUIDE.md.

Testing

910+ tests across 101 Vitest files + 11 Playwright E2E specs.

npm test            # Unit + integration
npm run test:e2e    # Browser E2E (Playwright)
npm run test:all    # Everything

Documentation

Document	Description
Getting Started	Step-by-step guide for new users
Architecture	System layers, modules, data flows
MCP Tools Reference	26 tools with full parameters
REST API Reference	17 routers, 44 endpoints
Knowledge Pipeline	RAG, embeddings, context assembly
Integrations	Serena, GitNexus, Context7, Playwright
Test Guide	Test pyramid and best practices
Lifecycle	8-phase dev methodology

Support the Project

If this tool is useful to you, consider supporting its development:

Star this repo — it helps others discover the project
Share — tell your team, post on X/LinkedIn, write about it
Contribute — see CONTRIBUTING.md. TDD is mandatory — write the failing test first
Sponsor — GitHub Sponsors

License

MIT

mcp-graph-workflow