codegraph-mcp

Servidor MCP local que le da a Claude Code (CLI y la extensión de VS Code) un modelo consultable de tu código: dónde están definidas las cosas, quién llama a qué, qué depende de qué, y qué se decidió en sesiones anteriores. Sin él, el agente redescubre tu arquitectura en cada sesión mediante grep y lectura archivo por archivo; con él, las preguntas estructurales obtienen respuestas estructurales:

• Cambios más seguros — antes de tocar una función, el agente ve su radio de impacto (analyze_impact), cada punto de llamada (find_callers), cada mención (find_references) y cada módulo dependiente (who_imports), en lugar de editar lo que grep haya sacado a la superficie.

• Orientación más rápida — una llamada a repo_map mapea el proyecto por centralidad de imports; find_symbol y semantic_search ("¿dónde se valida el token de autenticación?") aterrizan directamente en el código correcto.

• Continuidad — save_note / recall_notes llevan decisiones y advertencias entre sesiones, por repositorio.

• Exploración más barata — como consecuencia de lo anterior, el agente lee firmas en lugar de archivos completos (file_skeleton, read_symbol), y un proxy transparente comprime el historial de conversación a nivel de red. usage_stats informa de los ahorros medidos.

100% portátil: JavaScript puro + gramáticas WASM. Sin node-gyp, sin compilación nativa. npm install funciona igual en Windows, macOS y Linux.

Herramientas expuestas al agente

Comprensión y navegación

Seguridad ante cambios

Lectura enfocada

Memoria y operaciones

Lenguajes soportados: JavaScript, TypeScript, TSX, Python, Go, Rust, Java, Ruby, C, C++, C#, PHP, GDScript. Los archivos que el indexador no puede extraer se cuentan y se informan mediante repo_map, por lo que la cobertura parcial siempre es visible.

Related MCP server: MCP Context Manager

Instalación

Requiere Node.js ≥ 20 y Claude Code. Idéntico en Windows / macOS / Linux:

git clone https://github.com/denzharkov/codegraph-mcp
cd codegraph-mcp && npm install
node bin/codegraph-mcp.js install     # registers in Claude Code (user scope)

Eso es todo: el comando install ejecuta claude mcp add por ti, y el servidor funciona en la CLI y en la extensión de VS Code (comparten la configuración de MCP). Verifícalo con claude mcp list o /mcp dentro de Claude Code.

El servidor indexa el directorio en el que se inicia (Claude Code inicia los servidores MCP en el directorio del proyecto), o la ruta dada mediante --root / CODEGRAPH_ROOT. Para limitarlo a un solo proyecto en lugar del ámbito de usuario, añade .mcp.json a ese proyecto:

{
  "mcpServers": {
    "codegraph": {
      "command": "node",
      "args": ["/absolute/path/to/codegraph-mcp/bin/codegraph-mcp.js"]
    }
  }
}

Para eliminarlo: node bin/codegraph-mcp.js uninstall.

Configuración cero

No se necesitan ediciones de CLAUDE.md ni ajustes de prompt: el servidor envía sus guías de uso ("ejecuta analyze_impact antes de cambiar una función, find_symbol en lugar de grep, file_skeleton antes de leer un archivo, …") a través del campo instructions de MCP, que Claude Code inyecta en el contexto del agente automáticamente al conectarse. Instala, registra, listo.

Proxy transparente (ahorros garantizados)

Las herramientas MCP anteriores ahorran tokens solo cuando el agente decide usarlas. La capa de proxy funciona al revés: como ContextForge, se sitúa entre Claude Code y la API de Anthropic y comprime el tráfico independientemente del comportamiento del agente:

• Deduplicación de historial: cuando la conversación contiene resultados de herramienta idénticos (la misma lectura de archivo dos veces, salida de comando repetida), cada ocurrencia después de la primera se reemplaza con un stub corto antes de que la solicitud salga de tu máquina. La primera ocurrencia permanece verbatim, por lo que el modelo no pierde nada que realmente pueda usar — y se preserva el prefijo de caché de prompt (solo se reescribe la nueva cola, por lo que la deduplicación nunca causa fallos de caché en turnos antiguos).

• Esqueletización de lecturas obsoletas: cuando un archivo se leyó, editó y volvió a leer, la copia completa más antigua en el historial se reemplaza por su esqueleto de firmas de tree-sitter (imports + declaraciones con rangos de línea); la lectura más reciente siempre permanece verbatim. Los archivos que no son código recurren a truncamiento de cabeza+cola. Las transformaciones son funciones puras del contenido, por lo que las solicitudes repetidas producen bytes idénticos y la caché de prompt se re-estabiliza después de una sola reescritura.

• Anclaje de prompt: tu mensaje se transforma antes de llegar al modelo — de la forma segura. Las palabras nunca se reescriben; en su lugar, el proxy añade un bloque claramente etiquetado de hechos verificables sobre los identificadores que el mensaje menciona (tipo, file:lines, doc de una línea del grafo de símbolos). El modelo comienza orientado en lugar de gastar idas y vueltas de herramientas descubriendo los mismos hechos. Solo se anclan coincidencias exactas de mayúsculas/minúsculas, solo el mensaje más reciente recibe un bloque nuevo, y los bloques se memoizan para que el historial permanezca estable en bytes para la caché de prompt.

• Los encabezados de autenticación pasan sin cambios (clave API u OAuth). Cualquier cosa que el proxy no pueda analizar se reenvía verbatim. El streaming (SSE) se canaliza.

codegraph-mcp wrap                 # like 'cf wrap claude': proxy + claude in one command
codegraph-mcp proxy --port 3210    # or run the proxy standalone

Para la extensión de VS Code, ejecuta el proxy y apunta la extensión hacia él mediante la configuración de proyecto o global:

{ "env": { "ANTHROPIC_BASE_URL": "http://127.0.0.1:3210" } }

Los ahorros acumulados se registran en ~/.codegraph/proxy-stats.json y se imprimen al iniciar el proxy.

Uso desde CLI

node bin/codegraph-mcp.js index                # index cwd, print stats
node bin/codegraph-mcp.js index --root ~/proj  # index another directory
node bin/codegraph-mcp.js dashboard            # HTML report, opens in browser
node bin/codegraph-mcp.js map                  # interactive architecture map
node bin/codegraph-mcp.js                      # start stdio MCP server (cwd)

El mapa de arquitectura (.codegraph/map.html) es una vista en capas, estilo C4, del repositorio, completamente derivada del índice:

• Resumen — tarjetas de subsistemas (directorios de nivel superior) con aristas de import ponderadas entre ellos, más puntos de partida derivados automáticamente (hub, punto de entrada, módulo más grande);

• Subsistema — los archivos de un directorio con sus aristas de import y subsistemas vecinos colapsados; haz clic en un archivo para rastrear dependientes y dependencias, haz clic de nuevo para profundizar;

• Archivo — sus símbolos con flechas de llamada intra-archivo, importadores e imports como columnas navegables.

Cada nivel narra propósito, no solo estructura: las descripciones se extraen de la propia documentación del código — docstrings de módulos y comentarios de cabecera para archivos y símbolos, READMEs / __init__.py / index.* para carpetas y el propio repositorio — y se muestran en las tarjetas de carpetas, en tooltips y en el panel lateral.

Los niveles son enlazables en profundidad (#d=src, #f=src/proxy.js), búsqueda con /, Esc sube un nivel, arrastrar desplaza, rueda hace zoom. HTML autocontenido, sin conexión.

El dashboard (--no-open para solo escribir el archivo) aterriza en .codegraph/dashboard.html: ahorro de tokens, uso por herramienta, lenguajes indexados y los archivos más importados. HTML estático, sin servidor, con modo claro/oscuro. El agente también puede generarlo a petición mediante usage_stats con dashboard=true.

Cómo funciona

• Los archivos se analizan con gramáticas tree-sitter WASM (paquete tree-sitter-wasms) mediante web-tree-sitter — sin binarios específicos de plataforma.

• El extractor recorre cada AST una vez, recopilando definiciones, aristas de llamada e imports según la especificación de cada lenguaje (src/languages.js).

• El grafo persiste en .codegraph/index.json dentro del repositorio objetivo; las actualizaciones son incrementales (mtime+tamaño) y limitadas, por lo que las consultas siguen siendo rápidas.

• Se omiten node_modules, salidas de compilación, archivos vendored y minificados; se respetan los patrones simples de .gitignore de la raíz.

• semantic_search usa un modelo de embeddings local (all-MiniLM-L6-v2 vía transformers.js, una dependencia opcional). En el primer uso descarga ~25 MB en ~/.codegraph/models y cachea los vectores de símbolos por repositorio en .codegraph/vectors.bin. Sin conexión o sin la dependencia, cae silenciosamente a búsqueda por palabras clave — todo lo demás funciona independientemente.

Añade .codegraph/ al .gitignore de tu proyecto (es una caché más tus notas privadas).

Licencia

MIT