# Graph Indexer para Claude Code

> Añade Graph Indexer a Claude Code con npx graph-indexer init: escribe .mcp.json, un bloque en CLAUDE.md y un subagente de modelo pequeño. Hooks opcionales.

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.

```bash
npx graph-indexer init
npx graph-indexer index   # opcional: construye el índice ahora
```

Claude 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](/es/claude-code-plugin/) 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:

```json
{
  "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](https://github.com/MaquinaTech/graph-indexer/blob/main/docs/AGENTIC-BENCHMARK.md).

## ¿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_references` lista cada uso de un símbolo ligado a la definición a la que apunta e indica si la lista está completa.
- `call_graph` rastrea llamadores y llamados entre archivos.
- `change_impact` da el radio de impacto de un cambio y los tests que ejecutar.
- `check_changes` verifica las ediciones sin confirmar sin compilar.
- `read_code`, `search_text`, `search_code` y `outline` leen 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](/es/benchmarks/) y la [referencia de herramientas](/es/tools/).

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.

---

Actualizado: 2026-10-08 · Graph Indexer 3.0.0 · https://graph-indexer.vercel.app/es/agents/claude-code/