CodeGraphContext: Análisis de código con grafos

CodeGraphContext es un servidor MCP + herramienta CLI que convierte tu codebase en una base de datos de grafos, permitiéndote analizar código con precisión estructural mediante Tree-Sitter y consultas Cypher. Creado por Shashank Singh en febrero de 2026, ya alcanzó 2.7k stars en GitHub y se integra nativamente con Claude Desktop para debugging y refactoring inteligente.

Qué es CodeGraphContext y por qué cambió el análisis de código

CodeGraphContext es un servidor MCP que transforma tu codebase en un grafo de conocimiento consultable. Une tres tecnologías: Tree-Sitter para parseo de código con 100% de precisión estructural, bases de datos de grafos para almacenamiento eficiente de relaciones, y MCP para integración directa con Claude y otros agentes IA.

Lo que lo diferencia de herramientas anteriores: en vez de analizar código como texto (regex, AST parsing lineal), CodeGraphContext lo ve como una red. Las funciones son nodos, las llamadas son aristas. Eso significa que preguntas que antes tardaban horas, ahora tardan segundos (ponele que necesitás saber quién llama a una función en 47 archivos diferentes, con qué parámetros, y quién a su vez llama a esos llamadores).

Shashank Singh lo lanzó el 25 de febrero de 2026 con código abierto en GitHub. Hoy está en PyPI con versión 0.2.x, es mantenido activamente, y ya hay una comunidad de devs usando esto en producción (spoiler: funciona).

Cómo funciona: del código al grafo de conocimiento

El flujo es simple de entender. Vos le decís a CodeGraphContext “indexá este repo”, y en segundo plano pasan tres cosas.

Primero, Tree-Sitter lo parsea. Tree-Sitter no es un evaluador de código, es un parser incremental que genera un árbol sintáctico 100% preciso sin ejecutar nada. Entiende Python, Go, JavaScript, Rust, Java, C++, todo. El parsing es lo difícil, y Tree-Sitter lo resuelve mejor que cualquier otra herramienta pública.

Segundo, se construye un grafo. Cada función, clase, módulo, import se convierte en un nodo. Las relaciones se mapean como aristas etiquetadas: “function_x calls function_y”, “class_a extends class_b”, “module_p imports module_q”. El grafo vive en una base de datos optimizada para consultas de relaciones (ojo: no es una SQL database, eso sería lento; es una graph database con índices de aristas nativos).

Tercero, consultás. Usás Cypher (el lenguaje estándar de query de grafos) para preguntar cosas que en código lineal serían imposibles sin un macrospider: “dame todas las funciones que llaman directa o indirectamente a auth.login()”, “qué funciones no las llama nadie” (código muerto), “qué función es más compleja por número de llamadas”. Claude puede hacer estas queries en tiempo real.

La ventaja sobre análisis textual es brutal. Si buscás “login” en grep, te salen 4000 matches con falsos positivos. Con CodeGraphContext, preguntás estructuralmente y obtenés 3 resultados verdaderos.

Instalación en 3 pasos y configuración inicial

Paso 1: Instalar el paquete.

Abrís la terminal y ejecutás pip install codegraphcontext. Toma 2-3 minutos porque incluye dependencias de grafos. Soporta Python 3.9+. Sobre eso hablamos en mejores prácticas de seguridad.

Paso 2: Ejecutar el wizard de setup.

Corrés cgc mcp setup. El wizard es interactivo. Te pregunta: ¿Dónde está Claude Desktop? (detecta automáticamente en Windows/Mac/Linux). ¿Qué backend de grafo querés? (KùzuDB embebida es default, recomendado). ¿Qué directorios indexar? (podés agregar múltiples repos).

Si la pregunta es “¿qué es KùzuDB?”, la respuesta es: es una base de datos de grafos embebida (no requiere servidor externo), corre en tu máquina, no necesita configuración, y es lo bastante rápida para repos de hasta 500k líneas.

Paso 3: Verificar la integración.

Reabrís Claude Desktop. Si el setup fue correcto, CodeGraphContext aparece automáticamente en la sección “Tools” bajo codebase. Probás con algo simple: escribís “show me the call graph for function X” y Claude debería poder acceder al grafo.

CLI: comandos clave para analizar tu código

La CLI de CodeGraphContext tiene 6-7 comandos principales. No necesitás aprenderte todos, pero estos resuelven 90% de los problemas reales.

cgc index . indexa el directorio actual. Corre una sola vez (o cuando agregás código nuevo). Genera el grafo y lo guarda en .cgc_graph. Tarda según tamaño del repo: 10 segundos para 50k líneas, 2 minutos para 500k.

cgc watch . monitora cambios en tiempo real. Cada vez que guardás un archivo, updatea el grafo. Útil si estás refactoreando y necesitás feedback instant.

cgc list muestra todos los repos indexados localmente. Sirve para confirmar qué está guardado.

cgc analyze callers nombre_funcion te dice exactamente quién llama a esa función. Output es una lista con rutas de archivo y números de línea. Ojo: si la función no existe o hay typo, te devuelve error claro (no silencio como grep).

cgc analyze dead-code detecta funciones que nadie llama. Extremadamente útil antes de refactorear o antes de limpiar un repo legacy. Filtra automaticamente constructores, decoradores y funciones de entrada. Te puede servir nuestra cobertura de integración con chatgpt.

cgc analyze complexity rankea funciones por número de llamadas salientes (complejidad estructural). Si una función llama a 50 otras, sale primero en el listado. Son candidatos obvios para simplificar.

Todos los comandos aceptan --format json para parseo programático. Útil si querés piping a otros tools.

Conectar CodeGraphContext a Claude: cómo funciona MCP

MCP significa Model Context Protocol. Es el estándar de Anthropic (desde septiembre 2024) para que modelos IA accedan a recursos externos. CodeGraphContext implementa MCP, lo que significa que Claude puede hacer tres cosas sin salir del chat.

Primero, tools: Claude puede ejecutar comandos del CLI. Vos escribís “dame todos los callers de la función handle_auth_token” y Claude detrás de escenas corre cgc analyze callers handle_auth_token y te devuelve el resultado con contexto.

Segundo, resources: Claude accede a lecturas en tiempo real del grafo. El modelo puede preguntar “dame el código de la función X” y recibe no solo el código, sino también sus dependencias y dependientes. Es como tener un map completo en tu contexto sin cargarlo manualmente.

Tercero, prompts precargados: vienen algunos defaults como “analiza este código para bugs” o “refactor suggestion”, pero vos podés agregar los tuyos propios.

La ventaja sobre copiar-pastear código en el chat: el grafo se actualiza automáticamente cuando cambias el código. Claude siempre analiza con información fresca, no con un snapshot de hace 3 días. Además, no hay límite de contexto: aunque tu repo sea 5MB, Claude solo carga lo relevante a cada pregunta.

Casos de uso reales: de debugging a refactor inteligente

Debugging surgical. Producción explota. Tenés un TypeError en production que solo ocurre con cierto input. Ese input entra por la API, pasa por 20 funciones intermedias, y explota en la #21. ¿Dónde exactamente se corrompen los datos? Normalmente esto te toma 4 horas de grep + log reading. Con CodeGraphContext, le pedís a Claude “trace el flujo desde validate_input hasta database_write” y recibís un mapa exacto con una línea que probablemente sea el culpable. Comprobás, arreglás, desplegás. 20 minutos vs 4 horas. Para más detalles técnicos, mirá modelos gpt disponibles.

Onboarding de nuevos devs. Junior llega a tu equipo. Necesita entender cómo interactúan auth.py, models.py y api.py. En vez de mandarle la carpeta src/ y que se pierda, le decís “pasá por aquí, Claude te muestra el grafo de dependencias”. Junior consulta directamente las relaciones: quién importa qué, en qué orden se ejecutan las cosas, qué es crítico.

Identificación de código muerto. Heredás un repo de 300k líneas. Hay scaffolding viejo, funciones que alguien escribió hace 4 años para un test que ya no existe, imports circulares. Correr cgc analyze dead-code te da una lista de 120 candidatos. Revisás los que parecen obvios, abrís un PR, los borrás. Es catártico.

Detección de dependencias circulares y objetos dios. Un archivo tiene 2000 líneas, toca 5 módulos, importa 40 funciones. Es un código god object candidato a refactor. CodeGraphContext lo identifica automáticamente: si una clase tiene 30+ llamadas salientes, sale en el reportaje de complejidad.

Impact analysis. Querés borrar una función. ¿Qué se rompe? Sin CodeGraphContext, rezás, borrás, corres tests, ves qué falló. Con CodeGraphContext, le pedís a Claude “qué se rompe si elimino utils.parse_config()” y recibís una lista exacta de 7 funciones en 3 archivos que lo requieren.

Estos casos pasan en la mayoría de repos, todos los días. CodeGraphContext automatiza lo que antes era manual y lento.

Bases de datos de grafos soportadas: cuál elegir

Base de datos	Tipo	Setup	Velocidad	Máximo recomendado	Ideal para
KùzuDB	Embebida	Cero configuración	Muy rápida	500k líneas	Proyectos pequeños a medianos, desarrollo local
FalkorDB Lite	Embebida	Cero configuración (solo Linux/Mac)	Extremadamente rápida	1M líneas	Alto rendimiento en equipos, CI/CD
FalkorDB Remote	Cliente-servidor	Requiere servidor	Rápida (depende de red)	5M+ líneas	Equipos distribuidos, análisis compartido
Neo4j	Cliente-servidor	Requiere Docker + config	Rápida	10M+ líneas	Empresas grandes, análisis complejos, ecosistema maduro

La recomendación corta: si tu repo cabe en memoria (500k líneas o menos), KùzuDB. Si necesitás extrema velocidad y usás Linux/Mac, FalkorDB Lite. Si el equipo es disperso y varios devs necesitan acceder al grafo simultáneamente, FalkorDB Remote. Neo4j solo si ya lo usás en producción o necesitás escala enterprise.

Cambiar de backend no es difícil: borrás el archivo de config y corres cgc mcp setup de nuevo, seleccionás otro. El grafo se regenera automáticamente en el nuevo backend.

Errores comunes (y cómo evitarlos)

Error 1: Indexar código con compilación requerida. CodeGraphContext parsea sin ejecutar. Eso es ventaja. Pero si tu código no puede parsearse sin compilación previa (C/C++ con headers que requieren make, por ejemplo), el parser falla silenciosamente en esos archivos. Solución: compilá primero o excluí archivos no parseables con --ignore. Ya lo cubrimos antes en alternativas como gemini.

Error 2: Olvidar re-indexar después de cambios grandes. Agregaste 50 archivos nuevos. El grafo sigue viejo. Consultás y no ves los callees nuevos. Solución: cgc index . después de cambios estructurales, o activá cgc watch si estás refactoreando.

Error 3: Asumir que “dead code” es 100% muerto. cgc analyze dead-code a veces reporta falsos positivos: funciones que se llaman mediante reflection, decoradores dinámicos, o plugins. Revisá antes de eliminar. Lee el código primero, no solo confíes en el reporte.

Preguntas Frecuentes

¿Qué lenguajes de programación soporta CodeGraphContext?

Python, JavaScript/Node, Go, Rust, Java, C++, C, Kotlin, Bash, YAML, y algunos más. Si lo soporta Tree-Sitter (y lo soporta), CodeGraphContext lo parsea. El repo oficial lista la versión completa. No soporta lenguajes esoté, pero cubre 99% de lo que se usa en producción.

¿Puedo usar CodeGraphContext en equipos distribuidos si el código es privado?

Sí. Si usás FalkorDB Remote o Neo4j, el grafo corre en tu servidor privado. El grafo nunca sale de tu red. Si usás KùzuDB embebida, cada dev indexa localmente. En ambos casos, cero datos van a Anthropic ni a terceros. El MCP server se conecta a Claude Desktop localmente.

¿CodeGraphContext reemplaza linters y type checkers como mypy o eslint?

No, son complementarios. Linters detectan estilo y errores tipo. CodeGraphContext analiza relaciones estructurales. Corrés ambos. Un linter te dice “esta variable no está tiped”, CodeGraphContext te dice “esta función la llaman 8 lugares y 6 usan un tipo incorrecto”.

¿Cuánta memoria necesita CodeGraphContext?

Depende del tamaño del repo y el backend. KùzuDB usa Rule of Thumb: aproximadamente 2-3GB por cada millón de líneas de código. Para 50k líneas típicas, menos de 200MB. Si tu máquina tiene 8GB de RAM, no es problema incluso con repos medianos.

¿CodeGraphContext funciona con monorepos?

Sí. Indexá la raíz del monorepo y CodeGraphContext incluye todas las relaciones cross-workspace. Obtenés un grafo unificado donde ves que workspace-a importa workspace-b e identifica dependencias circulares entre workspaces.

Conclusión

CodeGraphContext es una herramienta que lleva el análisis de código de “búsqueda textual + intuición humana” a “grafos estructurales + inteligencia automatizada”. Lo cambió el hecho de que integra MCP y funciona con Claude en tiempo real: antes tenías que exportar resultados y procesarlos manualmente. Ahora Claude lee el grafo directamente y responde preguntas complejas.

¿Cuándo lo usarías? Cuando tenés un bug que tarda horas en rastrear, cuando heredás un repo grande, cuando necesitás refactorear sin romper nada, o simplemente cuando querés entender mejor cómo funciona tu código. Instalación y setup tardan 5 minutos. ROI (en tiempo ahorrado) se recupera en la primera semana de uso.

Si trabajás con Python, Node o Go en un repo de tamaño mediano, probá CodeGraphContext. Si lo probás, muy probablemente no vuelvas atrás.

Fuentes

• CodeGraphContext en GitHub – repositorio oficial, documentación completa, ejemplos
• CodeGraphContext en PyPI – paquete Python, instrucciones de instalación
• CodeGraphContext Documentación Oficial – guía de setup, CLI reference, backends soportados
• MCP Anniversary – Anthropic Blog – contexto sobre protocolo MCP y servidores integrados
• Por qué se creó CodeGraphContext – Medium – artículo del autor explicando motivación y diseño