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

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, with phase-aware MCP suggestions
• Environment Doctor — mcp-graph doctor validates Node.js, SQLite, permissions, integrations, and suggests fixes
• 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 serve --port 3000    # or: npm run dev

Tools & API

| | Count | Reference | |---|---|---| | MCP Tools | 45 + 6 deprecated | MCP-TOOLS-REFERENCE.md | | REST Endpoints | 135 (26 routers) | REST-API-REFERENCE.md |

| CLI Commands | 6 | init, import, index, stats, serve, doctor |

Integrations

| Integration | Role | |-------------|------| | Code Intelligence | Native LSP-based code analysis, symbol navigation, multi-language | | Context7 | Up-to-date library documentation fetching | | Playwright | Browser-based task validation and A/B testing |

Native systems: Code Intelligence (code analysis), Native Memories (project knowledge). See INTEGRATIONS-GUIDE.md.

Testing

4200+ tests across 390 Vitest files + 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 | 46 tools + 6 deprecated, full parameters | | REST API Reference | 19 routers, 59 endpoints | | Knowledge Pipeline | RAG, embeddings, context assembly | | Integrations | Code Intelligence, Context7, Playwright | | Test Guide | Test pyramid and best practices | | PRD Writing Guide | How to write PRDs that import correctly | | 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