polycodegraph

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.