{"_id":"@diegonogueiradev_/mcp-graph","_rev":"5-bfc68a46058397ff7b477565199d0a71","name":"@diegonogueiradev_/mcp-graph","dist-tags":{"latest":"2.0.1"},"versions":{"1.0.0":{"name":"@diegonogueiradev_/mcp-graph","version":"1.0.0","keywords":["mcp","prd","task-graph","local-first","agent-tooling"],"license":"MIT","_id":"@diegonogueiradev_/mcp-graph@1.0.0","maintainers":[{"name":"diegonogueiradev_","email":"diegonogueiradev@gmail.com"}],"bin":{"mcp-graph":"dist/mcp/stdio.js","mcp-graph-server":"dist/mcp/server.js"},"dist":{"shasum":"6b3396c7faed4a4d9f067dad44af0e490bc93b0c","tarball":"https://registry.npmjs.org/@diegonogueiradev_/mcp-graph/-/mcp-graph-1.0.0.tgz","fileCount":233,"integrity":"sha512-MS0QMmlpctPdPeOfZi4/zMQ+nwY2/QWVgEdZPN0J1Pd+mOl7Y0BLa8IgcsqgVYW02mBqSyxc7CU/o7ReNxF6qQ==","signatures":[{"sig":"MEUCIFhhofHawf4igJZVKRRCNDs7sbTWC1P1hOa0MnuXGOonAiEAi5rjDBDEdc5XtIx+WS3FmwtcvAAqKPHG3kcCLtkeZ2Q=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":310338},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"ca3324da9230e6e8491acf7cf009bb63b4bbb51c","scripts":{"dev":"tsx src/mcp/server.ts","lint":"tsc --noEmit","test":"vitest run","build":"tsc","start":"node dist/mcp/server.js","dev:stdio":"tsx src/mcp/stdio.ts","setup:mcp":"bash scripts/setup-mcp.sh","typecheck":"tsc --noEmit","test:watch":"vitest","prepublishOnly":"npm run build && npm test"},"_npmUser":{"name":"diegonogueiradev_","email":"diegonogueiradev@gmail.com"},"_npmVersion":"10.9.4","description":"MCP local-first PRD to task graph — transforms text into executable structure","directories":{},"_nodeVersion":"22.22.0","dependencies":{"zod":"^4.3.6","yaml":"^2.8.2","express":"^5.2.1","better-sqlite3":"^12.6.2","@modelcontextprotocol/sdk":"^1.27.1"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.21.0","vitest":"^4.0.18","typescript":"^5.9.3","@types/node":"^25.3.3","@types/express":"^5.0.6","@types/better-sqlite3":"^7.6.13"},"_npmOperationalInternal":{"tmp":"tmp/mcp-graph_1.0.0_1772717517665_0.21522549883369746","host":"s3://npm-registry-packages-npm-production"}},"2.0.0":{"name":"@diegonogueiradev_/mcp-graph","version":"2.0.0","keywords":["mcp","prd","task-graph","local-first","agent-tooling"],"license":"MIT","_id":"@diegonogueiradev_/mcp-graph@2.0.0","maintainers":[{"name":"diegonogueiradev_","email":"diegonogueiradev@gmail.com"}],"bin":{"mcp-graph":"dist/cli/index.js","mcp-graph-stdio":"dist/mcp/stdio.js","mcp-graph-server":"dist/mcp/server.js"},"dist":{"shasum":"db2875c61247c5f0e62b78242bb854d6299c8930","tarball":"https://registry.npmjs.org/@diegonogueiradev_/mcp-graph/-/mcp-graph-2.0.0.tgz","fileCount":422,"integrity":"sha512-Fj7DaJHNZiogGTqFx3PdoOE2La8s33zUoxgF0i0hGXS/dJrupcVLD3qceQLQNpLZZDsu7KnbHNSD0h6VaQUecw==","signatures":[{"sig":"MEUCIQC7Y98GPHrA5AepVqdHyv8y3HpeHoSXMzgGuDM6DLgeLgIgVpQFsoSznMJIaYtXWOyTJitXWJ9IIjw/xDLKGHbrgyA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":4173612},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"9aa53f786a5271f73efeb2dcd468db881c342c2d","scripts":{"dev":"tsx src/mcp/server.ts","lint":"tsc --noEmit","test":"vitest run","build":"tsc && npm run dashboard:build && npm run copy-dashboard","start":"node dist/mcp/server.js","test:all":"vitest run && playwright test","test:e2e":"playwright test","dev:stdio":"tsx src/mcp/stdio.ts","setup:mcp":"bash scripts/setup-mcp.sh","typecheck":"tsc --noEmit","test:bench":"vitest bench","test:watch":"vitest","dashboard:dev":"cd src/web/dashboard && npm run dev","test:coverage":"vitest run --coverage","copy-dashboard":"mkdir -p dist/web/dashboard && cp -r src/web/dashboard/dist dist/web/dashboard/","prepublishOnly":"npm run build && npm test","dashboard:build":"cd src/web/dashboard && npm run build","dashboard:install":"cd src/web/dashboard && npm install"},"_npmUser":{"name":"diegonogueiradev_","email":"diegonogueiradev@gmail.com"},"_npmVersion":"11.11.0","description":"MCP local-first PRD to task graph — transforms text into executable structure","directories":{},"_nodeVersion":"25.8.0","dependencies":{"zod":"^4.3.6","yaml":"^2.8.2","multer":"^2.1.1","cheerio":"^1.2.0","express":"^5.2.1","commander":"^14.0.3","pdf-parse":"^2.4.5","playwright":"^1.58.2","better-sqlite3":"^12.6.2","@modelcontextprotocol/sdk":"^1.27.1"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.21.0","vitest":"^4.0.18","supertest":"^7.2.2","typescript":"^5.9.3","@types/node":"^25.3.3","@types/multer":"^2.1.0","@types/express":"^5.0.6","@playwright/test":"^1.58.2","@types/supertest":"^7.2.0","@vitest/coverage-v8":"^4.0.0","@types/better-sqlite3":"^7.6.13"},"_npmOperationalInternal":{"tmp":"tmp/mcp-graph_2.0.0_1773023607932_0.8202193153078425","host":"s3://npm-registry-packages-npm-production"}},"2.0.1":{"name":"@diegonogueiradev_/mcp-graph","version":"2.0.1","keywords":["mcp","prd","task-graph","local-first","agent-tooling"],"license":"MIT","_id":"@diegonogueiradev_/mcp-graph@2.0.1","maintainers":[{"name":"diegonogueiradev_","email":"diegonogueiradev@gmail.com"}],"bin":{"mcp-graph":"dist/cli/index.js","mcp-graph-stdio":"dist/mcp/stdio.js","mcp-graph-server":"dist/mcp/server.js"},"dist":{"shasum":"23fd527798e2ae17849fcaaeebce77fcd928429a","tarball":"https://registry.npmjs.org/@diegonogueiradev_/mcp-graph/-/mcp-graph-2.0.1.tgz","fileCount":422,"integrity":"sha512-xTn0EP6M6aJPVRMEaBS9Mcyisp1xtf8kZIRTNDu4YT6TPxMyHocHDFy/XICk6hEj9YayhJNH8/gjI+PUmh409A==","signatures":[{"sig":"MEUCIAZ+yLsmOyHjoWAjq/KULBzXNsZFYqWNBe4P+dKaFwbmAiEAs7Pfi3iyygQ5q+KzsmZQbWIbAps3wNnUnsaK6GW3iQI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":4173653},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"2aca217de2171f61b6cd2e8d78d731883622efec","scripts":{"dev":"tsx src/mcp/server.ts","lint":"tsc --noEmit","test":"vitest run","build":"tsc && npm run dashboard:build && npm run copy-dashboard","start":"node dist/mcp/server.js","test:all":"vitest run && playwright test","test:e2e":"playwright test","dev:stdio":"tsx src/mcp/stdio.ts","setup:mcp":"bash scripts/setup-mcp.sh","typecheck":"tsc --noEmit","test:bench":"vitest bench","test:watch":"vitest","dashboard:dev":"cd src/web/dashboard && npm run dev","test:coverage":"vitest run --coverage","copy-dashboard":"mkdir -p dist/web/dashboard && cp -r src/web/dashboard/dist dist/web/dashboard/","prepublishOnly":"npm run build && npm test","dashboard:build":"cd src/web/dashboard && npm run build","dashboard:install":"cd src/web/dashboard && npm install"},"_npmUser":{"name":"diegonogueiradev_","email":"diegonogueiradev@gmail.com"},"_npmVersion":"11.11.0","description":"MCP local-first PRD to task graph — transforms text into executable structure","directories":{},"_nodeVersion":"25.8.0","dependencies":{"zod":"^4.3.6","yaml":"^2.8.2","multer":"^2.1.1","cheerio":"^1.2.0","express":"^5.2.1","commander":"^14.0.3","pdf-parse":"^2.4.5","playwright":"^1.58.2","better-sqlite3":"^12.6.2","@modelcontextprotocol/sdk":"^1.27.1"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.21.0","vitest":"^4.0.18","supertest":"^7.2.2","typescript":"^5.9.3","@types/node":"^25.3.3","@types/multer":"^2.1.0","@types/express":"^5.0.6","@playwright/test":"^1.58.2","@types/supertest":"^7.2.0","@vitest/coverage-v8":"^4.0.0","@types/better-sqlite3":"^7.6.13"},"_npmOperationalInternal":{"tmp":"tmp/mcp-graph_2.0.1_1773024575847_0.7340835228946785","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2026-03-05T13:31:57.551Z","modified":"2026-08-24T05:29:22.982Z","1.0.0":"2026-03-05T13:31:57.825Z","2.0.0":"2026-03-09T02:33:28.223Z","2.0.1":"2026-03-09T02:49:36.073Z"},"license":"MIT","keywords":["mcp","prd","task-graph","local-first","agent-tooling"],"description":"MCP local-first PRD to task graph — transforms text into executable structure","maintainers":[{"email":"diegonogueiradev@gmail.com","name":"devnogueira_"}],"readme":"# @diegonogueiradev_/mcp-graph\n\nA local-first CLI tool (TypeScript) that converts PRD text files into persistent execution graphs (SQLite), enabling structured, token-efficient agentic workflows.\n\n## Features\n\n- **PRD to Graph** — Parse PRD text files into structured task graphs with nodes and edges\n- **Local-first** — SQLite persistence, zero external dependencies, no Docker\n- **Smart Routing** — `next` command suggests the best task based on priority, dependencies, and blockers\n- **Context Compression** — Reduce LLM context payload by 70-85% via structural summarization\n- **MCP Protocol** — 26 tools accessible via HTTP or Stdio transport\n- **Web Dashboard** — Real-time browser UI with Mermaid diagrams, backlog management, and insights\n- **REST API** — Full CRUD + search + import + insights via Express\n- **Cross-platform** — Windows, macOS, and Linux compatible\n\n## Quick Start\n\n### As MCP Server (recommended)\n\nAdd to your Claude Code `.mcp.json` or Cursor MCP config:\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-graph\": {\n      \"command\": \"npx\",\n      \"args\": [\"@diegonogueiradev_/mcp-graph\"]\n    }\n  }\n}\n```\n\nThen use the tools via your MCP client:\n\n```\ninit → import_prd → list → next → update_status → stats\n```\n\n### From source\n\n```bash\ngit clone <repo-url>\ncd mcp-graph-workflow\nnpm install\nnpm run build\nnpm run dev          # Start HTTP server + dashboard\nnpm run dev:stdio    # Start MCP Stdio server\n```\n\n### CLI\n\n```bash\nmcp-graph init                    # Initialize project\nmcp-graph import docs/my-prd.md  # Import PRD file\nmcp-graph stats                  # Show graph statistics\nmcp-graph stats --json           # JSON output\nmcp-graph serve --port 3000      # Start dashboard\n```\n\n## Architecture\n\n```mermaid\ngraph TD\n    CLI[CLI — Commander.js] --> Core\n    MCP[MCP Server — HTTP/Stdio] --> Core\n    API[REST API — Express] --> Core\n    Web[Web Dashboard — Vanilla JS] --> API\n\n    Core --> Store[SQLite Store — WAL + FTS5]\n    Core --> Parser[Parser — classify, extract, segment]\n    Core --> Planner[Planner — next-task selection]\n    Core --> Context[Context Builder — 70-85% reduction]\n    Core --> Insights[Insights — bottlenecks, metrics]\n    Core --> Search[Search — FTS5 + TF-IDF reranking]\n```\n\n```\nsrc/\n  cli/             # Commander.js commands (thin orchestration)\n  core/\n    graph/         # SQLite persistence + queries + Mermaid export\n    importer/      # PRD import pipeline\n    parser/        # classify, extract, normalize, segment\n    planner/       # next-task selection logic\n    context/       # compact context builder\n    insights/      # bottleneck detection, metrics\n    search/        # FTS5 + TF-IDF search\n    events/        # SSE event bus\n    store/         # SQLite store, migrations\n    config/        # Configuration loader\n    docs/          # Docs cache syncer\n    utils/         # errors, fs, id, logger, time\n  api/             # Express REST API routes + middleware\n  mcp/             # MCP server (HTTP + Stdio) + tool wrappers\n  schemas/         # Zod v4 schemas\n  web/public/      # Dashboard (HTML, CSS, vanilla JS)\n  tests/           # Vitest unit/integration + Playwright E2E\n```\n\n## MCP Tools\n\n| Tool | Description |\n|---|---|\n| `init` | Initialize project and SQLite database |\n| `import_prd` | Parse PRD file and generate task graph |\n| `list` | List nodes filtered by type/status/sprint |\n| `show` | Show node details with edges and children |\n| `next` | Suggest next task based on priority and dependencies |\n| `update_status` | Update node status (backlog/ready/in_progress/blocked/done) |\n| `update_node` | Edit node fields (title, description, priority, tags, etc.) |\n| `stats` | Show graph statistics and context reduction metrics |\n| `context` | Build compact context payload for a specific task |\n| `search` | Full-text search across nodes |\n| `rag_context` | RAG-based contextual search via FTS5+TF-IDF |\n| `add_node` | Add a new node to the graph |\n| `add_edge` | Add an edge between nodes |\n| `delete_node` | Delete node with cascade edge cleanup |\n| `delete_edge` | Delete an edge |\n| `list_edges` | List edges filtered by node or type |\n| `move_node` | Move node to a different parent |\n| `clone_node` | Clone a node (optionally with children) |\n| `bulk_update_status` | Update status of multiple nodes at once |\n| `decompose` | Detect large tasks and suggest breakdown |\n| `velocity` | Calculate team velocity and sprint metrics |\n| `dependencies` | Analyze dependency chains, critical path, blockers |\n| `export_graph` | Export the complete graph as JSON |\n| `export_mermaid` | Export the graph as a Mermaid diagram (flowchart or mindmap) |\n| `create_snapshot` | Create a named snapshot of the current graph state |\n| `restore_snapshot` | Restore graph from a snapshot |\n| `list_snapshots` | List available snapshots |\n\n## REST API\n\nAll endpoints under `/api/v1/`:\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | `/project/init` | Initialize project |\n| GET | `/nodes` | List all nodes |\n| POST | `/nodes` | Create node |\n| GET | `/edges` | List edges |\n| POST | `/edges` | Create edge |\n| GET | `/stats` | Graph statistics |\n| GET | `/search?q=term` | Full-text search |\n| POST | `/import` | Import PRD file (multipart) |\n| GET | `/graph/document` | Full graph document |\n| GET | `/graph/mermaid` | Mermaid diagram |\n| GET | `/insights/bottlenecks` | Bottleneck report |\n| GET | `/context/preview?nodeId=x` | Compact context for node |\n| GET | `/docs` | Docs cache entries |\n| GET | `/events` | SSE real-time events |\n| GET | `/integrations/status` | Integration status (Serena, GitNexus) |\n| GET | `/skills` | Available skills |\n\n## Web Dashboard\n\nThe dashboard runs at `http://localhost:3000` via `mcp-graph serve` and provides 5 tabs:\n\n1. **Graph** — Interactive Mermaid diagram with filters (status, type, direction, format), node table with search/sort, and detail panel\n2. **PRD & Backlog** — PRD source view, backlog list, next task badge, progress bars per epic\n3. **Code Graph** — Integration with GitNexus/Serena code analysis\n4. **Knowledge** — Docs cache and context preview\n5. **Insights** — Bottleneck detection, metrics, and reports\n\nReal-time updates via Server-Sent Events (SSE). Dark/light theme toggle.\n\n## Testing\n\n```bash\nnpm test               # Unit + integration tests (Vitest)\nnpm run test:watch     # Watch mode\nnpm run test:e2e       # Browser E2E tests (Playwright)\nnpm run test:coverage  # Coverage report (V8)\nnpm run test:bench     # Benchmark tests\nnpm run test:all       # All tests (unit + E2E)\n```\n\nSee [docs/TEST-GUIDE.md](docs/TEST-GUIDE.md) for the full testing guide.\n\n## How It Works\n\n1. **Parse** — Read PRD text, normalize, segment by headings, classify blocks heuristically\n2. **Transform** — Convert blocks to nodes (epic, task, subtask, requirement, constraint, risk) with edges (depends_on, parent_of, blocks, related_to)\n3. **Persist** — Store graph in local SQLite with WAL mode, FTS5 indexes, and snapshots\n4. **Execute** — Route tasks by priority, dependency resolution, and blocker analysis\n5. **Compress** — Generate minimal context payloads for LLM consumption (70-85% token reduction)\n\n## Node Types\n\n`epic` | `task` | `subtask` | `requirement` | `constraint` | `milestone` | `acceptance_criteria` | `risk` | `decision`\n\n## Status Flow\n\n```\nbacklog → ready → in_progress → done\n                → blocked\n```\n\n## XP Anti-Vibe-Coding Workflow\n\nThe project follows an anti-vibe-coding methodology based on Extreme Programming (XP). Discipline over intuition. Every line of code has a tested purpose, and the execution graph ensures no progress is lost between sessions.\n\n### Why a Graph?\n\n| Problem | List/Kanban | Graph (mcp-graph) |\n|---------|------------|-------------------|\n| Task dependencies | Invisible or manual | Explicit edges: `blocks`, `depends_on`, `parent_of` |\n| Execution order | Decided by dev each time | `next` auto-resolves based on priority + dependencies |\n| AI context | Dev explains everything | `context` generates compact payload (70-85% fewer tokens) |\n| Session continuity | Lost — \"where was I?\" | `stats` + `list` show exact state |\n| Hierarchical decomposition | Flat | Tree: PRD → Feature → Story → Task → Subtask |\n\n### Key Skills\n\n| Skill | Purpose |\n|-------|---------|\n| `/xp-bootstrap` | Sequential workflow: Isolation → Foundation → TDD → Implementation → Optimization → Interface → Deploy |\n| `/project-scaffold` | Auto-setup: `.mcp.json` + `CLAUDE.md` template + `.claude/rules/` + mcp-graph init |\n| `/dev-flow-orchestrator` | Continuous XP cycle: ANALYZE → DESIGN → PLAN → IMPLEMENT → VALIDATE → REVIEW → HANDOFF → LISTENING |\n| `/track-with-mcp-graph` | Keep graph in sync with real work state |\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/my-feature`\n3. Follow TDD: write failing test first, then implement\n4. Ensure all checks pass: `npm run build && npm test && npm run test:e2e`\n5. Submit a PR with clear description\n\n## Documentation\n\n| Document | Description |\n|---|---|\n| [CLAUDE.md](CLAUDE.md) | AI agent instructions, conventions, and rules |\n| [docs/ARCHITECTURE-GUIDE.md](docs/ARCHITECTURE-GUIDE.md) | Complete architecture guide |\n| [docs/TEST-GUIDE.md](docs/TEST-GUIDE.md) | Testing guide and best practices |\n\n## License\n\n[MIT](LICENSE)\n","readmeFilename":"README.md"}