# polycodegraph

> A language-agnostic code graph builder and MCP server that parses any repo into a queryable SQLite graph, enabling AI assistants like Claude Code and Cursor to trace parameters across the full stack with focused context.

polycodegraph is an open-source CLI tool and MCP server that parses codebases into a queryable code graph stored in a single SQLite file. Built by mochan and available on PyPI as `polycodegraph`, it powers AI coding assistants like Claude Code, Cursor, and Windsurf by returning small, focused subgraphs instead of flooding the context window with entire files. The project is MIT-licensed and currently at v0.1.2.

## What It Is

polycodegraph is a code intelligence tool that uses tree-sitter to parse Python, TypeScript, JavaScript, TSX, JSX, and Go into a graph of nodes (files, classes, functions, imports) and edges (calls, imports, routes, fetches, data-flow). The graph lives in a single `.codegraph/graph.db` SQLite file — no daemon, no network, no external database server required. On top of that graph, it exposes a 3D web dashboard, a rich CLI, and an 18-tool MCP server that AI assistants can query directly.

## How the Graph and Data-Flow Layers Work

The core architecture is a multi-stage pipeline:

- **R1/R2/R3 resolver stages** handle per-name imports, relative imports, constructor calls, decorator stacks, `self.X.Y` chains, and fresh-instance binding across file boundaries.
- **DF0** captures call-site argument text at parse time (no type inference), powering edge labels and signature tooltips.
- **DF1** extracts HTTP route edges from FastAPI, Flask, and aiohttp, creating synthetic `route::METHOD::/path` nodes.
- **DF1.5** classifies functions by role: HANDLER, SERVICE, COMPONENT, or REPO, using 24 recognized framework decorators.
- **DF2** extracts frontend fetches (`fetch`, `axios`, `useSWR`, `useQuery`, `apiClient.*`) with method, URL, and body-key shape.
- **DF3** stitches URLs across the stack by normalizing placeholders (`/{id}` ↔ `${id}` ↔ `:id`).
- **DF4** walks the full call graph plus DF1/DF2 edges to emit an ordered hop trace from a frontend fetch all the way to the SQL query, with per-hop argument rename annotations.

## The MCP Server and AI Assistant Integration

The 18-tool MCP server is the primary integration surface. Running `codegraph init` writes a `.mcp.json` file that Claude Code and Cursor auto-detect when the project is opened. The same five-line JSON snippet works for Windsurf, OpenAI Codex CLI, GitHub Copilot CLI, Zed, and Continue — only the config file path changes.

Key MCP tools include:
- `find_symbol`, `callers`, `callees`, `blast_radius`, `subgraph` — structural graph queries
- `dead_code`, `cycles`, `untested`, `hotspots`, `metrics` — code health analysis
- `semantic_search`, `hybrid_search` — embedding-based retrieval (requires `codegraph embed`)
- `dataflow_routes`, `dataflow_fetches`, `dataflow_trace` — cross-stack tracing
- `workspace_state`, `workspace_diff_since`, `workspace_blast_radius` — multi-repo workspace queries

The README's benchmark compares four configurations of Claude Sonnet 4.6 answering 10 questions across two real codebases. According to the vendor-published results, adding the polycodegraph MCP alongside Claude's native grep tools matched the correctness of grep-only at roughly 3× lower token cost and 4× lower latency, because the MCP returns 20–50 token subgraphs instead of whole file dumps.

## Local Embeddings and Semantic Search

Installing the optional `[embed]` extra and running `codegraph embed` chunks the repository and embeds it using `nomic-ai/CodeRankEmbed` (Apache 2.0, approximately 140 MB), running entirely locally with no API keys required. This unlocks `semantic_search` and `hybrid_search` in the MCP server, where hybrid search combines 0.6 × cosine similarity with 0.4 × graph-distance for reranking around a focal function.

## Update: v0.1.2

The latest release is v0.1.2, published May 31, 2026, following the initial v0.1.0 PyPI launch. The roadmap lists v0.1.2 as targeting TypeScript R2 resolver patterns (path aliases, fresh-instance binding, decorator edges) and CLI HANDLER classification for Typer/Click. Planned v0.2 will rename the CLI binary from `codegraph` to `polycodegraph` (keeping `codegraph` as a deprecated alias) and extend `codegraph init` to write to every detected client's global MCP config automatically. The project currently has 13 stars and 2 forks on GitHub, with 637 tests passing (537 Python pytest + 100 Node tests) and 0 dead-code findings on its own self-graph.

## Features
- Parse any repo into a queryable SQLite code graph
- 18-tool MCP server for Claude Code, Cursor, and Windsurf
- Cross-stack end-to-end trace from frontend fetch to SQL query (DF4)
- Decorator-aware dead code detection (24 framework decorators)
- Role classification: HANDLER, SERVICE, COMPONENT, REPO
- 3D focus-mode web dashboard
- Architecture view with Learn Mode request lifecycle animation
- Local embeddings with nomic-ai/CodeRankEmbed (no API key)
- Semantic and hybrid search MCP tools
- PR-review CI with graph-diff against main branch
- Call/import cycle detection
- Hotspot and untested function detection
- Cross-repo workspace mode
- Support for Python, TypeScript, JavaScript, TSX, JSX, and Go
- Single SQLite file, no daemon, no network required
- Argument-level data flow text capture (DF0)

## Integrations
Claude Code, Cursor, Windsurf, OpenAI Codex CLI, GitHub Copilot CLI, Zed, Continue, FastAPI, Flask, aiohttp, Express, NestJS, SQLAlchemy, Prisma, Celery, pytest, tree-sitter, nomic-ai/CodeRankEmbed, GitHub Actions

## Platforms
WINDOWS, WEB, API, CLI

## Pricing
Open Source

## Version
v0.1.2

## Links
- Website: https://github.com/smochan/polycodegraph
- Documentation: https://github.com/smochan/polycodegraph/blob/main/docs/GETTING_STARTED.md
- Repository: https://github.com/smochan/polycodegraph
- EveryDev.ai: https://www.everydev.ai/tools/polycodegraph