Las 8 herramientas MCP de Graph Indexer

Graph Indexer expone ocho herramientas MCP de solo lectura: search_code, search_text, read_code, find_references, call_graph, change_impact, check_changes y outline. Cada una responde a una pregunta que se hace un agente de IA mientras modifica código, devuelve una respuesta compacta en texto plano de entre 400 y 1.500 tokens y termina con una pista para el siguiente paso. El agente sigue usando sus propias herramientas para leer y hacer grep; estas sirven para lo que la búsqueda de texto no puede responder con exactitud.

Las ocho herramientas son de solo lectura. Cada respuesta está acotada, pone el mejor resultado primero e indica lo que el índice no puede ver, por ejemplo llamadas con el mismo nombre que no pudo enlazar a una definición. El índice se resincroniza con los archivos del disco antes de cada respuesta, así que incluye ediciones que el agente hizo hace un segundo. Cómo funciona, en Cómo funciona Graph Indexer.

Los nombres de abajo son los de las herramientas MCP. Los ejemplos usan nombres genéricos y muestran la forma de la salida, no los bytes exactos.

search_code: ¿dónde vive este comportamiento?

search_code encuentra funciones, clases y tipos a partir de una descripción en palabras (“dónde se validan los tokens”) o de identificadores, y devuelve símbolos ordenados con ubicación, firma, primera línea de documentación y líneas coincidentes. Combina coincidencia en nombre, firma, documentación y cuerpo con centralidad en el grafo; no usa embeddings ni ningún modelo.

Parámetros clave:

• query (obligatorio): una descripción del comportamiento o identificadores.
• path: solo resultados bajo este prefijo de ruta, por ejemplo src/auth/.
• kind: solo este tipo de símbolo (function, method, class, interface, struct, enum, type, field).
• limit: de 1 a 30, por defecto 8.

> search_code("where are tokens validated")
3 results for "where are tokens validated" (of 41 candidates):
1. AuthService.verifyToken — method · src/auth/auth.service.ts:58-83
   verifyToken(raw: string): Claims
   Verify the signature and expiry of a bearer token.
   62: const claims = this.jwt.verify(raw);
2. authGuard — function · src/auth/guard.ts:12-30
…
Next: read_code with the names you want (several at once); find_references / call_graph for usages.

El agente debe usar search_code cuando sabe qué hace el código pero no cómo se llama. Para cadenas literales y claves de configuración, search_text es mejor.

search_text: ¿dónde aparece este texto?

search_text es un grep sobre todos los archivos del repositorio (código, configuración y documentación) que además dice qué es cada coincidencia. Una coincidencia en código lleva su función contenedora y, si es un identificador, indica si es la definición, una referencia enlazada a un símbolo, una referencia sin enlazar o solo un comentario o cadena.

Parámetros clave:

• pattern (obligatorio): una expresión regular de JavaScript, o texto plano con literal: true.
• path: solo archivos bajo este prefijo, como src/ o config/app.yaml.
• literal e ignore_case: booleanos, ambos false por defecto.
• limit: de 1 a 300 líneas mostradas, por defecto 60; los totales siempre son completos.

> search_text("parseConfig", literal: true)
7 matches in 4 files for "parseConfig":
src/config/loader.ts
    14 def │ export function parseConfig(raw: string): Config {
src/app.ts
    22 → parseConfig (src/config/loader.ts) (bootstrap) │ const cfg = parseConfig(text);
docs/setup.md
    40 comment │ Call parseConfig before starting the server.

Si la búsqueda no encuentra la definición del nombre buscado, la respuesta indica dónde está, de modo que la siguiente llamada es una lectura y no otra búsqueda. Usa search_text para cadenas literales, mensajes de error, claves de configuración y todo lo que no sea un símbolo.

read_code: ¿qué dice este código?

read_code lee funciones, métodos, clases, rangos de líneas o archivos completos, varios por llamada, con números de línea. Bajo cada resultado lista dónde está definido cada nombre que usa el código (archivo, línea, firma, primera línea de documentación). Para un símbolo muestra además sus sobrescrituras, quién lo usa y qué tests lo referencian.

Parámetros clave:

• targets (obligatorio): hasta 12 elementos, cada uno un símbolo (myFunc, UserService.find, path:Name), un rango (src/app.py:120-180) o un archivo.
• full: devuelve archivos completos aunque sean largos, hasta 2.000 líneas. Sin él, un archivo de más de 300 líneas llega como esquema.
• max_lines: de 5 a 1.000, por defecto 200; las definiciones más largas se truncan tras ese número de líneas.

> read_code(["UserService.find"])
UserService.find — method · src/users/user.service.ts:31-47
  31  async find(id: string): Promise<User> {
  …
Defined elsewhere (used above):
  UserRepository.byId  src/users/user.repository.ts:19  byId(id: string): Promise<User | null>
Used by: 4 callers in 3 files · tests: user.service.spec.ts

El agente debe usar read_code cuando conoce el nombre o la ubicación. Sustituye el bucle de leer y luego buscar por una sola llamada.

find_references: ¿quién usa este símbolo?

find_references lista cada uso de un símbolo (llamadas, instanciaciones, usos como tipo, herencia, decoradores y usos como valor), agrupados por archivo con la función contenedora y la línea. Las referencias se enlazan mediante ámbitos, imports y tipos de receptor inferidos, de modo que una llamada a UserService.find no se confunde con cualquier otro método llamado find. Las llamadas hechas a través de un tipo padre se marcan, y se incluyen los miembros referidos por cadena (como jest.spyOn o getattr de Python).

Parámetros clave:

• symbol (obligatorio): un nombre, Class.member, path:Name o path:line.
• kind: all (por defecto), call, type, inherit, new, value o decorator.
• path: solo referencias en archivos bajo esta ruta.
• include_tests: true por defecto.
• limit: de 1 a 500, por defecto 80.

> find_references("UserService.find")
6 references to UserService.find (src/users/user.service.ts:31) in 4 files:
src/users/user.controller.ts
  44 UserController.show   call  exact
src/admin/admin.service.ts
  17 AdminService.lookup   call  exact   (via base type)
Complete: all indexed references listed. Unbound: 2 other "find(…)" calls with receivers of unknown type; none is in a file that mentions UserService.

Cada referencia lleva una etiqueta de confianza: exact o high significa que se enlazó por ámbito, import o tipo de receptor inferido; likely o possible significa que solo coincidió el nombre. El pie indica si la lista está completa y si son plausibles las llamadas sin enlazar con el mismo nombre, para que el agente sepa cuándo comprobar de nuevo. Es la herramienta que hay que llamar antes de renombrar un símbolo o cambiar su firma. En 400 símbolos de nestjs comparados con el compilador de TypeScript, alcanzó una precisión del 99,7 % y una exhaustividad del 96,2 %; grep, una precisión del 12,8 %. Mira los benchmarks.

call_graph: ¿quién llama a esto y a qué llama?

call_graph devuelve los llamadores (transitivos, hasta una profundidad) y los llamados de una función o método como un árbol con ubicaciones y confianza, y muestra cómo fluye una petición o un dato entre archivos.

Parámetros clave:

• symbol (obligatorio): las mismas formas que en find_references.
• direction: callers, callees o both (por defecto).
• depth: de 1 a 4, por defecto 2.
• limit: de 5 a 200 nodos por dirección, por defecto 40.
• include_tests: true por defecto.

> call_graph("parseConfig", direction: "callers", depth: 2)
parseConfig — src/config/loader.ts:14
callers:
  bootstrap  src/app.ts:20  [exact]
    main  src/main.ts:5  [exact]
  loadTestConfig  test/helpers.ts:9  [exact]

Usa call_graph para entender el flujo entre archivos antes de tocar una función en mitad de una cadena.

change_impact: ¿qué afecta este cambio?

change_impact informa del radio de impacto de un cambio: dependientes transitivos ordenados por distancia, sobrescrituras y subclases que heredan el símbolo, los tests a ejecutar, los archivos que cambian juntos en el historial de git, un nivel de riesgo y lo que el índice no puede ver. Cuando el grafo no puede saberlo, el riesgo dice “unknown” en lugar de adivinar.

Parámetros clave:

• symbols: símbolos que vas a cambiar.
• files: archivos que vas a cambiar (todos sus símbolos).
• diff: con true usa tus cambios de git sin confirmar como conjunto de cambios.
• depth: de 1 a 5, por defecto 3.

> change_impact(symbols: ["UserService.find"], depth: 2)
Impact of changing UserService.find
dependents: 7 symbols in 3 files (non-test)
  distance 1 (3):
    UserController.show  src/users/user.controller.ts:40-52
    AdminService.lookup  src/admin/admin.service.ts:14-25
  distance 2 (4):
    …
tests to run (1 file):
    user.service.spec.ts
often changed together (git): user.controller.ts (9/31), …
risk: medium (7 dependents, 1 test files)

El agente debe llamar a change_impact antes de cambiar una firma o hacer una refactorización, y con diff: true para revisar qué alcanza un cambio sin terminar.

check_changes: ¿qué ha roto mi edición?

check_changes verifica las ediciones sin confirmar sin compilar el proyecto. Informa de errores de sintaxis introducidos por la edición, llamadas cuyo número de argumentos ya no encaja con una firma cambiada, nombres eliminados o renombrados que siguen en uso, llamadores en archivos que el agente no tocó, subclases que heredan métodos cambiados y los tests más cercanos con el comando para ejecutarlos (reconoce jest, vitest, mocha, pytest, unittest, Django, go test, cargo, Maven y Gradle). Tarda alrededor de 1 segundo en nestjs.

Parámetros clave:

• files: comprobar solo estos archivos o directorios modificados (por defecto, todos los cambios).
• base: revisión de git con la que comparar, HEAD por defecto.

> check_changes()
2 files changed. Problems:
  src/users/user.controller.ts:44  UserService.find(id, opts) — 2 arguments, signature now takes 1
  src/admin/admin.service.ts:17    untouched caller of UserService.find
tests to run: npx vitest run src/users/user.service.spec.ts

check_changes no es un comprobador de tipos, así que complementa al compilador en lugar de sustituirlo. Su valor es la velocidad: señala las llamadas que una edición dejó atrás antes de que el agente lance una compilación lenta. En tareas de resolución de incidencias reales, el benchmark con agentes no mostró un ahorro medible; las cifras, en Benchmarks.

outline: ¿qué hay en este archivo o repositorio?

outline muestra las definiciones sin cuerpos. Para un archivo devuelve firmas con rangos de líneas. Para un directorio o el repositorio entero (ruta vacía) devuelve los símbolos más centrales ordenados por PageRank dentro de un presupuesto de tokens, opcionalmente centrado en la descripción de una tarea.

Parámetros clave:

• path: un archivo o directorio; vacío significa todo el repositorio.
• focus: una tarea o consulta sobre la que centrar el mapa.
• max_tokens: de 200 a 8.000, por defecto 1.500.

> outline(path: "src/", focus: "token validation", max_tokens: 800)
src/auth/auth.service.ts
  class AuthService  :12
    verifyToken(raw: string): Claims  :58-83
src/auth/guard.ts
  function authGuard(req, res, next)  :12-30
…

El agente debe usar outline al llegar a un repositorio desconocido o para decidir qué archivo abrir. El mapa del repositorio aplica la idea de ordenar por importancia de un repo map a símbolos en lugar de archivos.

¿Cómo se relacionan la CLI y los hooks con las herramientas?

La línea de comandos ejecuta las mismas herramientas, útil para scripts y para comprobar lo que ve un agente:

npx graph-indexer search "where are tokens validated" --path src/ --limit 5
npx graph-indexer read UserService.find src/app.py:120-180
npx graph-indexer grep "parseConfig"
npx graph-indexer refs UserService.find --kind call --no-tests
npx graph-indexer callgraph parseConfig --direction callers --depth 3
npx graph-indexer impact --diff
npx graph-indexer check
npx graph-indexer outline src/ --focus "token validation" --max-tokens 800

La CLI también tiene files <texto|glob> para buscar archivos por ruta, algo que los clientes MCP ya hacen con su propio buscador de archivos, además de init, serve, index, status, hook y daemon.

Los hooks hacen que las herramientas funcionen sin que el agente tenga que pedirlas. Ejecutar npx graph-indexer init --hooks añade a .claude/settings.json hooks de Claude Code que llaman a graph-indexer hook en PostToolUse (tras Edit, Write, MultiEdit, Grep, Bash o Read), SessionStart y SubagentStart:

• Tras una edición, el hook ejecuta la comprobación de edición sobre ese archivo.
• Tras una búsqueda que no encontró una definición, indica dónde está.
• Cuando el agente va dando vueltas (tres búsquedas o lecturas desde la última edición), una lectura recibe dónde están definidos sus nombres.
• Un subagente arranca con las reglas de consulta.
• En cualquier otro caso guarda silencio, y, si se agota su plazo, termina sin error para no bloquear nunca al agente.

También se leen las entradas de hooks de Cursor, Codex, Gemini CLI y Copilot CLI, y OpenCode y Kilo Code reciben un plugin equivalente. Un proceso residente mantiene el índice abierto, así que las llamadas de hooks y CLI responden en unos 0,1 s. Los detalles de instalación, en Instalar Graph Indexer y en la página del plugin de Claude Code.