Graph Indexer para Claude Code es un servidor MCP local más un subagente auxiliar de solo lectura que da a Claude Code referencias exactas, grafos de llamadas e impacto de cambios a partir de un índice tree-sitter de tu repositorio. Ejecuta npx graph-indexer init en la raíz del proyecto; escribe .mcp.json, un bloque gestionado en CLAUDE.md y .claude/agents/code-structure.md.
¿Cómo añado Graph Indexer a Claude Code?
Ejecútalo desde la raíz del repositorio. Hace falta Node.js 22.5 o superior.
npx graph-indexer init
npx graph-indexer index # opcional: construye el índice ahoraClaude Code es la opción por defecto: si init no encuentra carpetas de ningún agente, configura Claude Code. Para elegirlo explícitamente usa npx graph-indexer init --agents claude.
¿Prefieres el plugin? Dentro de Claude Code ejecuta /plugin marketplace add MaquinaTech/graph-indexer y luego /plugin install graph-indexer@graph-indexer. La página del plugin de Claude Code explica qué incluye y cuándo conviene frente a init.
¿Qué escribe npx graph-indexer init para Claude Code?
Para Claude Code, init hace estos cambios, todos idempotentes:
| Archivo | Contenido |
|---|---|
.mcp.json | Una entrada graph-indexer bajo mcpServers, fusionada con los servidores que ya haya |
CLAUDE.md | Un bloque corto entre <!-- graph-indexer:start --> y <!-- graph-indexer:end --> con las reglas de búsqueda |
.claude/agents/code-structure.md | El subagente auxiliar estructural; se omite con --no-helper |
.gitignore | .graph-indexer/ para que el índice no entre en el control de versiones |
Si ya tienes un .claude/agents/code-structure.md escrito por ti, init no lo toca.
¿Cómo es la configuración manual?
La entrada que init añade a .mcp.json es un servidor stdio normal:
{
"mcpServers": {
"graph-indexer": {
"command": "npx",
"args": ["-y", "graph-indexer@3", "serve"]
}
}
}Sin --repo, el servidor indexa el repositorio git que contiene su directorio de trabajo. Claude Code lo arranca dentro del proyecto, así que no hace falta ruta.
¿Qué es el helper code-structure?
El helper code-structure de Claude Code es un subagente de solo lectura que corre con el modelo haiku y tiene prohibidos Edit, Write, MultiEdit y NotebookEdit. El agente principal le delega preguntas estructurales: todos los puntos de llamada de un método, llamadores de llamadores, clases que implementan una interfaz, qué afecta un cambio. Responde con find_references, call_graph y change_impact y devuelve solo una lista path:line, así la búsqueda no ensucia el contexto principal.
En el benchmark del proyecto, 24 preguntas delegadas así se respondieron con exactitud en 20 de 24, igual que un subagente general con grep, con un 76 % menos de coste y un 72 % menos de tiempo. Los detalles están en el benchmark con agentes.
¿Qué hooks añade Graph Indexer a Claude Code?
npx graph-indexer init --hooks fusiona tres hooks en .claude/settings.json sin quitar los tuyos:
| Hook | Qué hace |
|---|---|
PostToolUse en Edit, Write, MultiEdit, Grep, Bash, Read | Tras una edición, ejecuta el verificador sobre ese archivo; tras un grep de un nombre compartido, distingue las definiciones; en lo demás calla |
SessionStart | Añade una línea diciendo que el índice existe y lo construye en segundo plano si falta |
SubagentStart | Da a los subagentes la misma línea y las reglas, porque no leen CLAUDE.md |
Los hooks fallan en abierto: ante cualquier error, timeout o entrada irrelevante no imprimen nada. El plugin incluye los mismos tres hooks.
¿Qué gana Claude Code?
Claude Code gana ocho herramientas de solo lectura. find_references está marcada como siempre cargada, así que sigue visible aunque Claude Code difiera las herramientas MCP tras la búsqueda de herramientas. Esto responde cada una:
find_referenceslista cada uso de un símbolo ligado a la definición a la que apunta e indica si la lista está completa.call_graphrastrea llamadores y llamados entre archivos.change_impactda el radio de impacto de un cambio y los tests que ejecutar.check_changesverifica las ediciones sin confirmar sin compilar.read_code,search_text,search_codeyoutlineleen y localizan código con números de línea.
Sobre 400 símbolos de nestjs comprobados contra el compilador de TypeScript, find_references devolvió un 99,7 % de referencias reales con un 96,2 % de recall; grep llegó al 12,8 % de precisión. Mira los benchmarks y la referencia de herramientas.
El límite, con honestidad: arreglar incidencias reales no mostró un ahorro medible en el benchmark, porque en ellas el agente a menudo no llegó a llamar al índice.
Preguntas frecuentes
¿Necesito el plugin de Claude Code o me basta con init?
Sirven los dos. init escribe archivos de proyecto que puedes revisar y commitear. El plugin se instala con /plugin e incluye el servidor MCP, el helper y los hooks. Los hooks de init son opcionales.
¿Graph Indexer añade contexto a Claude Code?
Un poco. La huella medida es de unos 1.200 tokens por sesión de Claude Code, porque solo find_references se carga de entrada y el resto de herramientas quedan diferidas. Las respuestas típicas ocupan entre 400 y 1.500 tokens.
¿init sobrescribe mi .mcp.json?
No. Fusiona su entrada graph-indexer dentro del objeto mcpServers existente y respeta tus otros servidores. Si el archivo tiene comentarios o no es JSON plano, init lo deja como está e imprime la entrada para añadirla a mano.
¿Graph Indexer envía mi código a algún sitio?
Graph Indexer no hace llamadas de red ni envía telemetría. Claude Code sigue enviando lo que lee, incluidas las respuestas de las herramientas, a su proveedor de modelo, como hace siempre.