# Instalar Graph Indexer

> Instala Graph Indexer con npx graph-indexer init: requiere Node.js 22.5+, conecta el servidor MCP a tus agentes de IA y crea un índice de código local.

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](https://www.npmjs.com/package/graph-indexer).

## ¿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.

```bash
node --version   # v22.5.0 o superior
```

## ¿Cómo instalo Graph Indexer?

Desde la raíz del repositorio que quieres indexar:

```bash
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](/es/tools/). Si usas Claude Code, también puedes instalarlo con el [plugin de Claude Code](/es/claude-code-plugin/).

## ¿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:

| Agente | Archivo que escribe | Clave principal |
|---|---|---|
| [Claude Code](/es/agents/claude-code/) | `.mcp.json` | `mcpServers` |
| [Cursor](/es/agents/cursor/) | `.cursor/mcp.json` | `mcpServers` |
| [VS Code (Copilot)](/es/agents/vscode-copilot/) | `.vscode/mcp.json` | `servers` |
| [Gemini CLI](/es/agents/gemini-cli/) | `.gemini/settings.json` | `mcpServers` |
| [OpenCode y Kilo Code](/es/agents/opencode/) | `opencode.json` (o un `kilo.json`, `.kilo/kilo.json` existente) | `mcp` |
| [Junie](/es/agents/junie/) | `.junie/mcp/mcp.json` | `mcpServers` |
| [Zed](/es/agents/zed/) | `.zed/settings.json` | `context_servers` |
| [Codex CLI](/es/agents/codex/) | no escribe nada; imprime el TOML para `~/.codex/config.toml` | `mcp_servers` |
| [Devin](/es/agents/devin/) | no escribe nada; imprime la entrada del servidor para los ajustes MCP de Devin | n/a |

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`?

| Flag | Efecto |
|---|---|
| `--agents claude,cursor,vscode,gemini,codex,opencode,junie,zed,devin` | Configura solo los agentes indicados |
| `--all` | Configura todos los agentes soportados |
| `--hooks` | Añade los hooks de Claude Code a `.claude/settings.json` y el plugin de OpenCode / Kilo Code |
| `--local` | Usa este checkout de Graph Indexer en lugar de `npx` |
| `--dry-run` | Muestra qué cambiaría sin escribir nada |
| `--no-instructions` | Omite el bloque de `CLAUDE.md` / `AGENTS.md` |
| `--no-helper` | Omite el sub-agente `code-structure` de Claude Code |
| `--repo DIR` | Apunta a un repositorio distinto del actual |

## ¿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:

```json
{
  "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`:

```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](/es/claude-code-plugin/) 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](/es/faq/) y la [política de seguridad](https://github.com/MaquinaTech/graph-indexer/blob/main/SECURITY.md) para más detalle.

## Preguntas frecuentes

### ¿Graph Indexer necesita compilar algo o un servidor de base de datos?

No. Graph Indexer no tiene dependencias, ni compilaciones nativas, ni descarga de modelos. El runtime de tree-sitter y las gramáticas viajan como WebAssembly dentro del paquete npm, y el índice es un archivo SQLite local en .graph-indexer/.

### ¿Puedo instalar Graph Indexer solo para un agente?

Sí. Pasa --agents con una lista separada por comas, por ejemplo npx graph-indexer init --agents claude,cursor. Sin flags, init configura los agentes que detecta en el repositorio y, si no hay ninguno, Claude Code.

### ¿Es seguro subir la carpeta .graph-indexer a git?

No. El índice contiene fragmentos de tu código, así que trátalo como el propio repositorio. init añade .graph-indexer/ al .gitignore, y borrar la carpeta es seguro: se reconstruye en el siguiente arranque.

---

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