Instalar Graph Indexer

Graph Indexer se instala con un solo comando: ejecuta npx graph-indexer init desde la raíz de tu repositorio con Node.js 22.5 o superior. Escribe la configuración MCP a nivel de proyecto para los agentes de IA que detecta, añade un bloque corto de instrucciones a CLAUDE.md o AGENTS.md, deja .graph-indexer/ fuera de git, y el índice se construye la primera vez que arranca el servidor. Graph Indexer tiene licencia MIT y está publicado en npm.

¿Qué requisitos tiene?

Graph Indexer requiere Node.js 22.5 o superior, porque usa el módulo integrado node:sqlite. No hace falta nada más: ni compilador, ni compilación nativa, ni descarga de modelos, ni servicio que mantener. El runtime de tree-sitter y las 16 gramáticas de lenguaje viajan como WebAssembly dentro del paquete.

node --version   # v22.5.0 o superior

¿Cómo instalo Graph Indexer?

Desde la raíz del repositorio que quieres indexar:

cd tu-repo
npx graph-indexer init      # conecta el servidor MCP a los agentes que detecta
npx graph-indexer index     # opcional: construye el índice ya

El paso index es opcional. El servidor MCP construye el índice en el primer arranque y lo sincroniza con los archivos del disco antes de cada respuesta, así que las ediciones de hace un segundo ya cuentan. Tras init, reinicia tu agente para que cargue el servidor y comprueba que aparecen las ocho herramientas. Si usas Claude Code, también puedes instalarlo con el plugin de Claude Code.

¿Qué cambia npx graph-indexer init?

graph-indexer init solo escribe archivos a nivel de proyecto, fusiona con la configuración existente en lugar de pisar otros servidores y es idempotente. Esto es lo que escribe para cada agente:

Si un archivo JSON tiene comentarios o no es JSON plano, init lo deja intacto e imprime la entrada que debes añadir a mano.

Además de la entrada MCP, init hace lo siguiente:

• Añade un bloque gestionado a CLAUDE.md (Claude Code) o a AGENTS.md (el resto de agentes).
• Para Claude Code, escribe el sub-agente code-structure en .claude/agents/code-structure.md.
• Añade .graph-indexer/ al .gitignore si todavía no está.

¿Qué flags acepta init?

¿Qué añade --hooks?

npx graph-indexer init --hooks añade tres hooks de Claude Code a .claude/settings.json: PostToolUse (con matcher Edit|Write|MultiEdit|Grep|Bash|Read), SessionStart y SubagentStart. Tras una edición, la comprobación posterior avisa de errores de sintaxis introducidos, llamadas que ya no encajan con una firma cambiada y nombres eliminados que siguen en uso. Cuando el agente lleva un rato buscando y leyendo sin editar, indica además dónde están definidos los nombres de las líneas leídas y, tras un grep de un nombre compartido, cuál definición es cuál. En el resto de casos se queda en silencio. Devin, Copilot CLI y Cursor también ejecutan los hooks de Claude Code, y para OpenCode y Kilo Code --hooks escribe un plugin en .opencode/plugins/graph-indexer.js o .kilo/plugin/graph-indexer.js.

¿Cómo configuro Graph Indexer a mano en cualquier cliente MCP?

Cualquier cliente MCP puede ejecutar el servidor de Graph Indexer por stdio. Usa este comando y estos argumentos, cambiando la ruta por la de tu repositorio:

{
  "mcpServers": {
    "graph-indexer": {
      "command": "npx",
      "args": ["-y", "graph-indexer@3", "serve", "--repo", "/ruta/al/repo"]
    }
  }
}

VS Code usa "servers" en lugar de "mcpServers" y añade "type": "stdio". Para Codex CLI, añade esto a ~/.codex/config.toml:

[mcp_servers.graph-indexer]
command = "npx"
args = ["-y", "graph-indexer@3", "serve", "--repo", "/ruta/al/repo"]

Sin --repo, el servidor indexa el repositorio git que contiene su directorio de trabajo; la variable de entorno GRAPH_INDEXER_REPO también funciona. Para Claude Desktop, JetBrains AI Assistant y Cline, añade un servidor MCP con el comando npx y los mismos argumentos.

¿Qué es el bloque de CLAUDE.md / AGENTS.md?

Graph Indexer escribe un bloque corto, delimitado por <!-- graph-indexer:start --> y <!-- graph-indexer:end -->, que le dice al agente cuándo usar el índice. Son pocas líneas a propósito: los archivos de contexto largos generados automáticamente perjudican a los agentes de forma medible. El bloque da cuatro reglas de consulta (explorar de una pasada, leer las líneas necesarias y no archivos enteros, buscar la línea de definición, ejecutar una vez los tests que cubren el cambio) y nombra las herramientas para lo que una búsqueda de texto no responde con exactitud: find_references para los usos de un nombre compartido, call_graph para los llamadores de los llamadores, change_impact antes de cambiar una firma y check_changes después. Si vuelves a ejecutar init, actualiza el bloque entre los marcadores y no toca el resto del archivo.

¿Qué es el sub-agente code-structure?

Para Claude Code, init escribe .claude/agents/code-structure.md: un sub-agente de solo lectura que corre sobre el modelo pequeño haiku, no puede editar archivos y responde desde el índice a preguntas sobre llamadas, llamadores, subclases e impacto de un cambio. El agente principal le delega estas preguntas y recibe solo una lista de entradas path:line más si la lista está completa. Un archivo con ese nombre que hayas escrito tú se deja como está, y --no-helper lo omite. El plugin de Claude Code incluye el mismo sub-agente.

¿Cómo resuelvo los problemas habituales?

El servidor no arranca o falta node:sqlite

Ejecuta node --version. Cualquier versión anterior a 22.5 no tiene el módulo integrado node:sqlite que necesita Graph Indexer. Actualiza Node.js y reinicia tu agente.

El agente no muestra las herramientas

Reinicia o recarga el agente después de init. Luego comprueba que el archivo de configuración de la tabla anterior contiene una entrada graph-indexer; si init avisó de que un archivo tiene comentarios, añade a mano la entrada que imprimió.

Quiero reconstruir el índice desde cero

Borra la carpeta .graph-indexer/ del repositorio. Solo contiene el índice derivado, así que es seguro eliminarla, y el siguiente arranque la reconstruye. El índice también se reconstruye solo cuando la versión instalada de Graph Indexer cambia la forma de extraer los datos. Consulta su estado con npx graph-indexer status.

¿Dónde se guarda el índice y es privado?

El índice vive en <repo>/.graph-indexer/. Graph Indexer no hace llamadas de red ni envía telemetría; el agente sigue enviando lo que lee a su proveedor de modelo. Mira las preguntas frecuentes y la política de seguridad para más detalle.