polycodegraph

polycodegraph

Analiza cualquier repositorio y conviértelo en un grafo de código consultable. Traza un parámetro desde un fetch del frontend a través de cada capa hasta la consulta SQL. Potencia Claude Code, Cursor y Windsurf mediante MCP, para que tu asistente de IA lea contexto enfocado en lugar de todo el código base.

Mismo Claude Sonnet 4.6. Mismas 10 preguntas sobre dos repos reales (el propio codegraph + FastAPI). Solo cambia el servidor MCP registrado. Reproduce con codegraph bench agent, datos crudos en bench/RESULTS_AGENT_LATEST.md.

Inicio rápido

pip install polycodegraph     # the PyPI distribution name
codegraph init                # the CLI binary + Python module + MCP server are all `codegraph` (see footnote ↓)
codegraph build               # parse repo → .codegraph/graph.db
codegraph serve               # web dashboard at http://127.0.0.1:8765

Eso es todo. Tres comandos y tienes un grafo consultable, un panel 3D y un servidor MCP con el que tu IDE puede hablar.

Idiomas + frameworks (hoy)

Añadir un nuevo idioma es un único módulo de parser tree-sitter + archivo de fixture (~3 horas — ver codegraph/parsers/go.py para la plantilla v1). Pull requests bienvenidos.

El MOAT — un grafo, todo encima

polycodegraph tiene exactamente una opinión: construye el grafo correcto, y todas las funciones interesantes salen gratis.

Las entradas que alimentan el grafo van más allá de imports y aristas de llamadas. polycodegraph lee parses de tree-sitter para Python, TypeScript, JavaScript y Go; captura los argumentos de cada call-site como texto; reconoce 24 decoradores de frameworks para que los handlers de FastAPI / Flask / Celery / pytest / Click / MCP / Django / SQLAlchemy nunca se confundan con código muerto; detecta rutas (@app.get("/x")) y fetches de frontend (fetch, axios, useSWR, useQuery); y une URLs a través de la pila (/{id} ↔ ${id} ↔ :id) para poder trazar un fetch hasta su handler.

Las salidas que salen gratis una vez que el grafo está bien:

Código muerto con conciencia de decoradores, clasificación de roles (HANDLER / SERVICE / COMPONENT / REPO), radio de impacto, ciclos, detección de funciones sin testear, un trace extremo a extremo entre capas con anotaciones de renombrado, un panel 3D con modo de enfoque, un modal de ciclo de vida en Learn Mode, embeddings locales para búsqueda semántica + híbrida, un servidor MCP de 18 herramientas y un CI de revisión de PRs que compara el grafo de la rama contra main.

Un único archivo SQLite. Sin demonio. Sin red. Viaja con tu rama de git.

Cómo funciona

  ┌─────────────────────────────────────────────────────┐
  │  tree-sitter parsing                                │
  │  (Python, TS/JS, TSX, JSX, Go)                      │
  └─────────────────────────────────────────────────────┘
                        ↓
  ┌─────────────────────────────────────────────────────┐
  │  Cross-file resolution (R1, R2, R3)                 │
  │  ✓ per-name imports  ✓ relative imports             │
  │  ✓ constructor calls ✓ decorators                   │
  │  ✓ self.X.Y chains  ✓ fresh instances               │
  └─────────────────────────────────────────────────────┘
                        ↓
  ┌─────────────────────────────────────────────────────┐
  │  SQLite graph (nodes + edges)                       │
  │  DF0: call-site arguments                           │
  │  DF1: routes (FastAPI, Flask, aiohttp)              │
  │  DF2: fetches (fetch, axios, SWR, useQuery)         │
  │  DF3: URL stitching (/{id} ↔ ${id} ↔ :id)          │
  │  DF4: end-to-end trace (fetch→handler→service→DB)   │
  └─────────────────────────────────────────────────────┘
                   ↙            ↓            ↘
            CLI tools       Web dashboard      MCP server
         (graph, roles,    (3D focus view,  (18 tools for
         cycles, dead      architecture,     Claude Code,
         code, untested)   learn mode)       Cursor, etc.)

Lo que puedes hacer

Captura	Caso de uso
	Vista 3D de enfoque — Elige cualquier función, traza su árbol de llamadas descendente real, expande o colapsa ancestros y descendientes en línea. Se muestra: build_dashboard_payload con sus 15 llamadas directas — find_dead_code, find_cycles, build_hld, find_hotspots, compute_metrics y el resto de la pila de análisis.
	Mapa de arquitectura — Handlers agrupados por rol (HANDLER, SERVICE, COMPONENT, REPO), componentes de infraestructura (BD, caché, cola) y sus conexiones de un vistazo. Haz clic en un handler → Learn Mode abre un modal de ciclo de vida de petición: TCP → TLS → HTTP → consulta → respuesta.
	Trace entre capas DF4 — Haz clic en cualquier handler en la vista de Arquitectura y Learn Mode anima el ciclo de vida completo de la petición: DNS → TCP → TLS → HTTP → middleware → handler → servicio → SQL → 200 OK. El parámetro user_id se resalta en cada salto con anotaciones de renombrado (userId → user_id → id). Una consulta al grafo, sin bucear en logs.
	Herramientas MCP que tu asistente de IA llama directamente — Una respuesta real de find_symbol("get_user") del servidor MCP de polycodegraph. Tres resultados en ~50 tokens, clasificados por rol como HANDLER vs SERVICE, sin lecturas de archivos. Añádelo junto al grep de Claude Code y el asistente dejará de volcar archivos completos en su ventana de contexto — ver el benchmark abajo.

Benchmark — mismo Claude, variando el grafo MCP

Cuatro configuraciones. Mismo Claude Sonnet 4.6. Mismas 10 preguntas en dos códigos base reales (el propio polycodegraph + FastAPI). Las cuatro configuraciones incluyen las herramientas nativas de grep y lectura de archivos de Claude — lo que todo desarrollador obtiene por defecto en Claude Code o Cursor. Lo único que cambia es si también se registra además un grafo MCP.

codegraph-self

fastapi

La lectura honesta en ambos repos:

• claude+grep solo es el más correcto (8/10) — Claude puede responder a la mayoría de preguntas sobre el código buscando con grep y leyendo archivos completos. Pero paga el precio: 336k tokens, $1.17, latencia media de 78s.
• + polycodegraph alcanza eso dentro de una pregunta (7/10) a 3× menos coste y 4× menos latencia (90k tokens, $0.37, 20s). Porque polycodegraph devuelve subgrafos pequeños y enfocados (~20-50 tokens por llamada) en lugar de volcar archivos completos con grep en el contexto de Claude.
• Los otros grafos MCP son estrictamente peores que solo usar grep. code-review-graph: 3/10 a $0.68. graphify: 5/10 a $0.50. Añaden sobrecoste de herramientas sin compensar en corrección.

Reproduce: codegraph bench agent --only claude+grep,claude+grep+polycodegraph,claude+grep+code-review-graph,claude+grep+graphify. JSONL crudo por ejecución en bench/agent_raw_latest.jsonl. Metodología completa en bench/README.md.

Instalación y uso

Desde PyPI

pip install polycodegraph
codegraph init
codegraph build

Regístrate como servidor MCP

codegraph init escribe un .mcp.json a nivel de proyecto en el repo — Claude Code y Cursor lo detectan automáticamente en cuanto abres el proyecto. Para otros clientes, de momento necesitas añadir el servidor manualmente a su configuración global (v0.2 lo hará por ti).

// Claude Code (global)  →  ~/.claude.json
// Cursor (global)       →  ~/.cursor/mcp.json   (or .cursor/mcp.json per workspace)
// Windsurf              →  ~/.windsurf/mcp.json
// OpenAI Codex CLI      →  ~/.codex/mcp.json
// GitHub Copilot CLI    →  ~/.config/copilot/mcp.json
// Zed                   →  ~/.config/zed/settings.json under "context_servers"
// Continue              →  ~/.continue/config.json under "experimental.modelContextProtocolServers"

{
  "mcpServers": {
    "codegraph": {
      "command": "codegraph",
      "args": ["mcp", "serve"]
    }
  }
}

El mismo fragmento JSON de cinco líneas funciona para todos los clientes — solo cambia la ruta del archivo.

Luego pregúntale a tu asistente cosas como:

"¿Qué nodos HANDLER no tienen cobertura de tests?" "Muéstrame todos los llamadores de UserService.login con sus argumentos." "Traza GET /api/users/{id} desde el fetch del frontend hasta la base de datos." "¿Cuál es el radio de impacto de cambiar esta función?"

Las 18 herramientas devuelven subgrafos pequeños y enfocados — sin inundar la ventana de contexto.

Opcional: embeddings locales

pip install 'polycodegraph[embed]'
codegraph embed     # chunks the repo, embeds with nomic-ai/CodeRankEmbed

Desbloquea las herramientas MCP semantic_search y hybrid_search. Descarga de modelo de ~140 MB, se ejecuta localmente, sin claves de API.

Demo en vivo

Un fixture pequeño de FastAPI + SQLAlchemy + React vive en examples/cross-stack-demo/. Ejecuta polycodegraph sobre él para ver cómo se iluminan DF0, DF1, DF1.5, DF2, DF3 y DF4:

codegraph build --no-incremental --root examples/cross-stack-demo
codegraph dataflow trace "GET /api/users/{user_id}"

Ver el README de la demo para la salida esperada.

Limitaciones (lista honesta)

Lo que polycodegraph todavía no hace. Se listan aquí para que el benchmark y las afirmaciones del README sigan siendo limpias.

• Inferencia de tipos (Mypy / Pyright). DF0 captura el texto de los argumentos, no los tipos. Hoja de ruta v0.3.
• Identidad de valor de argumentos entre saltos. DF4 emite saltos ordenados con anotaciones de renombrado; la propagación completa de un único valor desde el cuerpo del fetch → parámetro de ruta → argumento de servicio → columna de BD se difiere (v0.3).
• Los docstrings se almacenan en cada nodo pero aún no se consumen en el análisis. Los embeddings los usan como texto de respaldo del cuerpo; el código muerto, la clasificación de roles y el flujo de datos los ignoran. Hoja de ruta v0.3.
• Minería de historial de git (semántica de mensajes de commit, señales de autor/frecuencia de modificación). No implementado. Git se usa solo para el SHA actual de HEAD y el diff de revisión de PRs. Hoja de ruta v0.4.
• Paridad de resolvers por idioma (v0.1.2). Python incluye todas las correcciones R1/R2/R3. Los patrones R2 de TypeScript (alias de ruta, binding de instancia nueva, aristas de llamada por decorador) se difieren.
• Los símbolos CLI de Typer no se etiquetan como HANDLER (v0.1.x). DF1.5 solo clasifica decoradores de frameworks HTTP.
• Visualización de async / await (v0.4). DF4 recorre solo el grafo de llamadas síncronas.
• Renderizado de ramas de camino de error (v0.4). Learn Mode muestra el camino feliz.
• Middleware de autenticación como fase distinta (v0.4). Hoy la autenticación aparece como un nodo CALL normal.
• Resaltado simultáneo de múltiples parámetros (v0.4). Solo selección de un parámetro.
• Traces entre procesos (v0.4). Todavía no puede enlazar múltiples archivos .codegraph/graph.db.

Hoja de ruta

Sobre el auto-grafo: de 451 hallazgos de código muerto a 0

Ejecutamos polycodegraph sobre su propio código fuente como objetivo de regresión. Los hallazgos de código muerto bajaron de 451 → 24+ → 15 → 0 a medida que el resolver se endurecía, la detección de puntos de entrada con conciencia de decoradores aterrizaba y los métodos intencionales de API pública se marcaban con # pragma: codegraph-public-api.

Estadísticas actuales del auto-grafo:

• 3,320 nodos (archivos, clases, funciones, imports)
• 7,557 aristas (5,245 CALLS, 1,357 DEFINED_IN, 886 IMPORTS, 28 INHERITS, 12 ROUTE, 27 FETCH_CALL, 1 READS_FROM, 1 WRITES_TO)
• 3 ciclos, todos documentados y aceptados (redibujado del panel, auto-recursión del parser, falso positivo del resolver MCP serve/run)
• 0 hallazgos de código muerto (con exenciones por pragma para métodos de API pública)
• 637 tests pasando (537 pytest de Python + 100 tests de Node)

Dónde encaja

La diferencia no es un algoritmo de grafo más sofisticado: es que polycodegraph trata trazar este argumento a través del stack como una operación de primera clase, no como un grep posterior. Las herramientas de recuperación basadas en embeddings (code-review-graph, Cursor, Cody) manejan bien prosa/docstrings; la arquitectura correcta es grafo + embeddings en el mismo bucle MCP, y v0.1.0 incluye ambos.

# Graph building
codegraph init      # interactive setup: detect languages, configure ignore globs, register MCP
codegraph build     # parse repo with tree-sitter, write/update .codegraph/graph.db
codegraph status    # graph freshness, last build time, drift indicators

# Analysis
codegraph analyze                # whole-project audit: dead code, cycles, untested, hotspots, metrics
codegraph query callers <symbol> # reverse-BFS: who calls this?
codegraph query callees <symbol> # forward traversal: what does this call?
codegraph query subgraph <symbol>
codegraph query deadcode
codegraph query untested
codegraph query cycles
codegraph query hotspots
codegraph query metrics

# Visualization
codegraph serve                       # web dashboard at http://127.0.0.1:8765
codegraph viz                         # Mermaid / interactive HTML / SVG
codegraph explore                     # static subgraph explorer pages (good for sharing)
codegraph dataflow trace "<M> <path>" # walk DF1→DF4 to trace endpoint frontend→DB

# PR review + baselines
codegraph review              # graph-diff current branch vs baseline; CSV or Markdown
codegraph baseline save       # snapshot current graph as the local baseline
codegraph baseline status
codegraph baseline push       # optional S3 remote
codegraph hook install        # pre-push git hook running codegraph review
codegraph hook uninstall

# MCP + embeddings
codegraph mcp serve           # MCP stdio server: 18 tools for Claude Code / Cursor / Windsurf
codegraph embed               # chunk + embed (nomic-ai/CodeRankEmbed); enables semantic + hybrid search

# Cross-repo workspace mode
codegraph workspace init      # ~/.codegraph/workspace.yml
codegraph workspace add <path>
codegraph workspace remove <path>
codegraph workspace list
codegraph workspace status
codegraph workspace sync [--only <name>]

gh auth refresh -h github.com -s workflow
cp .github/ci-templates/pr-review.workflow.yml .github/workflows/pr-review.yml
git add .github/workflows/pr-review.yml
git commit -m "ci: activate codegraph PR review"
git push

./scripts/test-pr-review-locally.sh

Desarrollo

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

ruff check .                    # lint
mypy --strict codegraph         # type-check
pytest -q                       # 537 Python tests
node --test tests/*.js          # 100 Node tests
./scripts/test-pr-review-locally.sh  # dry-run the PR review workflow

Los chequeos de CI están definidos en .github/workflows/ci.yml. ¿Nuevo en el repo? Empieza con docs/GETTING_STARTED.md. Para convenciones de commits y el proceso de PR, consulta CONTRIBUTING.md.

Nota sobre los nombres

Este proyecto se instala desde PyPI como polycodegraph porque el nombre simple codegraph ya estaba tomado cuando se publicó v0.1.0. Todo lo demás — el paquete de Python que importas, el binario CLI que ejecutas y la clave de servidor MCP que registras — es codegraph, el nombre original del proyecto. Planeamos unificar en polycodegraph en todas partes en v0.2 (renombrado de CLI con un alias codegraph durante una versión). Por ahora: dos nombres, una herramienta.

Agradecimientos

polycodegraph se basa en tree-sitter (análisis sintáctico), vasturiano/3d-force-graph (renderizado 3D), networkx (algoritmos de grafo), pydantic (esquema tipado), typer (CLI), rich (salida de consola), nomic-ai/CodeRankEmbed (embeddings), y el Model Context Protocol Python SDK.

Licencia

MIT © mochan

Soporte comercial, despliegues y forks con licencia personalizada disponibles — contacta smochan07@gmail.com. polycodegraph en sí es y seguirá siendo MIT; la línea de contacto existe para equipos que quieran soporte empresarial o acuerdos de licencia específicos adicionales.

Se aceptan pull requests. Consulta CONTRIBUTING.md para la configuración local, chequeos de CI, convenciones de commits y el Acuerdo de Licencia para Contribuyentes de un clic que se te pedirá firmar en tu primer PR.