Grafo de Dependencias + MCP: Reduce Tokens en Claude Code

Claude Code lleva un año en producción. Lo que empezó como un proyecto de hackathon interno en Anthropic se convirtió en la herramienta de desarrollo asistido por IA más usada en entornos profesionales. El aniversario, celebrado en febrero de 2026 con un hackathon global y el lanzamiento de Opus 4.6, coincidió con una conversación que lleva meses activa en la comunidad: el consumo de tokens es el talón de Aquiles del agente cuando trabajas en proyectos reales.

TL;DR: Claude no tiene memoria entre sesiones. En cada conversación nueva, explora el proyecto desde cero ejecutando grep, find y leyendo archivos completos, lo que puede consumir miles de tokens antes de llegar al problema real. Un grafo de dependencias construido con Tree-sitter, almacenado en SQLite y servido vía MCP cambia eso radicalmente: Claude consulta un índice semántico en lugar de explorar a ciegas. Las reducciones documentadas van del 40% en consultas generales hasta 50 veces menos tokens por búsqueda de símbolo. Este artículo explica la arquitectura y cómo configurarla.

El problema que los tutoriales no mencionan

Hay un patrón que aparece en todos los proyectos medianos con Claude Code: las primeras sesiones van bien, pero a medida que el proyecto crece, la calidad de las respuestas se degrada. Claude pierde el hilo, sugiere código que ya existe en otro módulo, o pide leer archivos que ya leyó diez minutos antes.

La causa es mecánica: sin memoria persistente, Claude empieza cada sesión desde cero. Si le pides que refactorice una clase, puede ejecutar 15 o 20 llamadas a herramientas buscando dependencias antes de tener el contexto necesario. En un proyecto con 300 archivos, buscar dónde está definida una función con grep devuelve 200 coincidencias, incluye falsos positivos como comentarios y cadenas de texto, y puede costar 2.000 tokens y cinco llamadas a herramientas para una sola búsqueda.

He visto esto directamente al migrar un pipeline de embeddings de Java a Python: Claude leía el mismo archivo de configuración tres o cuatro veces por sesión porque no recordaba haberlo consultado. Tokens desperdiciados, contexto saturado a mitad de sesión, respuestas que perdían coherencia cuando el espacio disponible caía por debajo del umbral crítico.

Conectar varios MCP servers sin gestión agrava el problema. Un equipo documentó que cuatro servidores MCP activos consumían entre 50.000 y 67.000 tokens solo en definiciones de herramientas, antes de escribir una sola línea de código.

¿Qué es un grafo de dependencias de código?

Un grafo de dependencias de código es una estructura de datos que mapea las relaciones entre los símbolos de un proyecto: qué función llama a qué, qué clase hereda de qué, qué módulo importa qué. En lugar de buscar en texto plano, el agente consulta este grafo y obtiene la respuesta exacta con metadatos precisos.

La diferencia práctica es grande: buscar log con grep devuelve 200 coincidencias incluyendo catalog, blog y comentarios. Consultar el grafo devuelve exactamente los símbolos llamados log con su ubicación, firma de función y lista de callers. Son aproximadamente 50 tokens frente a 2.000 para la misma pregunta.

¿Qué es Tree-sitter y por qué es la pieza clave?

Tree-sitter es un parser incremental que construye un árbol sintáctico abstracto (AST) de código fuente en milisegundos. Entiende la estructura del lenguaje, no solo el texto. Puede distinguir entre una función llamada process y la palabra "process" apareciendo en un comentario o en un nombre de variable.

Es la base de todo el sistema: Tree-sitter parsea el código, extrae los símbolos (funciones, clases, métodos, imports, dependencias entre módulos) y con esa información se construye el índice semántico. Ese índice se almacena en SQLite para consultas rápidas y se expone vía MCP para que Claude pueda consultarlo sin necesidad de leer archivos completos.

La arquitectura: tres piezas que encajan

El sistema tiene tres componentes independientes que trabajan juntos:

1. Indexación con Tree-sitter: Parsea todo el proyecto y extrae símbolos con metadatos: tipo (función, clase, método), archivo, número de línea, firma completa, y relaciones de dependencia. Se ejecuta una vez al inicio y se actualiza incrementalmente cuando cambias archivos.
2. Almacenamiento en SQLite: El índice se guarda en una base de datos local, sin cloud, sin latencia de red, sin coste adicional. Un archivo .codeindex/index.db en la raíz del proyecto, portable y sin dependencias externas.
3. Servidor MCP: Expone herramientas de consulta sobre ese índice. Claude llama a herramientas como find_symbol o get_callers y recibe la respuesta exacta en tokens mínimos, sin explorar archivos completos.

Implementación con AiDex paso a paso

AiDex es la implementación más completa de este patrón disponible a febrero de 2026. Soporta 11 lenguajes (Python, TypeScript, JavaScript, Rust, Go, Java, C/C++, C#, PHP, Ruby), tiene tiempos de consulta de 1-10ms en proyectos de 500 archivos, y se integra directamente con Claude Code como servidor MCP. Todo corre en local, sin telemetría.

Paso 1: Instalación

# Instalar el servidor MCP de AiDex globalmente
npm install -g @aidex/mcp-server

# Verificar que el binario está disponible
aidex --version
# Output: aidex 1.4.2

Paso 2: Indexar el proyecto

# Desde la raíz del proyecto
aidex index .

# Output esperado:
# Detectando lenguajes: Python, TypeScript
# Indexando 347 archivos...
# Extrayendo símbolos con Tree-sitter...
# Índice creado en .codeindex/index.db (2.3 MB)
# Tiempo total: 4.2s

Paso 3: Registrar en Claude Code

Edita el archivo .claude/settings.json en la raíz del proyecto para añadir el servidor MCP:

{
  "mcpServers": {
    "aidex": {
      "command": "aidex",
      "args": ["serve", "--db", ".codeindex/index.db"]
    }
  }
}

Paso 4: Verificar la integración

# Iniciar Claude Code en el proyecto
claude

# Dentro de la sesión, listar MCP servers activos:
# /mcp
#
# Deberías ver:
# aidex (connected)
#   - find_symbol
#   - get_callers
#   - get_dependencies
#   - search_by_type

Desde ese momento, cuando Claude necesita localizar una función o rastrear dependencias, consulta el índice en lugar de explorar el proyecto con grep.

Paso 5: Mantener el índice actualizado

# Actualización incremental después de cambios
aidex index . --incremental

# Modo watcher durante sesiones activas de desarrollo
aidex watch .

# Hook post-commit en Git para sincronización automática
# Añade esto a .git/hooks/post-commit:
#!/bin/bash
aidex index . --incremental --quiet

Caso real: refactorización de un pipeline de embeddings

En un proyecto de refactorización de un pipeline de embeddings con ~400 archivos Python entre código de producción, tests y configuración, el impacto fue claro desde la primera sesión. Sin índice, Claude ejecutaba entre 15 y 20 llamadas a herramientas para mapear todas las dependencias de una clase central antes de poder proponer cambios. Con AiDex configurado, la misma operación requería 2 o 3 llamadas.

El ahorro no es solo de tokens: es de coherencia. Cuando Claude tiene el contexto correcto desde el principio, hay menos ciclos de corrección y menos riesgo de que el agente proponga soluciones que ya existen en otro módulo. En la práctica, eso se traduce en sesiones más cortas y menor gasto total en la API de Anthropic.

Un patrón que combina bien con este enfoque: activar también el Tool Search nativo de Anthropic, que hace lazy loading de las definiciones de herramientas MCP. Según datos internos de Anthropic, esta feature reduce el overhead de contexto de los servidores MCP en un 46,9% (de 51.000 a 8.500 tokens en pruebas reales). La combinación de AiDex para búsqueda semántica de código más Tool Search para gestión de herramientas da los mejores resultados en proyectos con múltiples MCP servers activos.

En Producción

Antes de asumir que este sistema funciona sin fricciones en cualquier proyecto, hay que conocer sus límites reales.

Coste de setup inicial. Indexar 400 archivos tarda 3-5 segundos con AiDex. Un monorepo con 10.000 archivos puede tardar minutos en la indexación completa. La actualización incremental es sub-segundo para cambios puntuales, pero el primer índice requiere planificación si quieres integrarlo en un pipeline CI/CD.

Precisión en lenguajes dinámicos. Tree-sitter entiende la sintaxis estática. En Python, las llamadas dinámicas mediante getattr, decoradores complejos o metaprogramación no aparecen en el grafo. El índice es una aproximación del grafo real. Para la mayoría del código empresarial estándar esto no es un problema, pero en código muy dinámico puede haber huecos.

Reducciones reales de tokens. Las cifras varían según el caso de uso: AiDex reporta ~50 tokens frente a 2.000 por búsqueda de símbolo (50x), el Tool Search de Anthropic muestra 46,9% de reducción en overhead de MCP, y enfoques vectoriales como Claude Context logran ~40% de reducción end-to-end. El ahorro total en una sesión depende del tipo de tarea. Para exploración y refactorización, el impacto es mayor. Para generar código nuevo desde cero, el beneficio es menor porque Claude necesita contexto amplio de todas formas.

Sincronía del índice. Si editas archivos fuera de la sesión de Claude sin actualizar el índice, el agente consultará información desactualizada. En equipos con varios desarrolladores, el índice puede desfasarse. La solución más simple es el hook post-commit en Git mostrado en el paso 5.

Privacidad. Todo el índice es local. Ningún dato sale de tu máquina. Esto importa en proyectos con código propietario o requisitos de compliance estrictos.

Errores comunes y cómo resolverlos

Error: las herramientas de AiDex no aparecen en Claude Code. Causa: el servidor MCP no está registrado correctamente o el path al binario es incorrecto en el shell que usa Claude Code. Solución: ejecuta which aidex para obtener el path absoluto y úsalo en el campo command del settings.json en lugar del comando bare.

Error: Claude sugiere código de versiones anteriores del proyecto. Causa: se añadieron o modificaron archivos sin regenerar el índice. Solución: añadir aidex index . --incremental como hook post-commit, o activar el modo watcher (aidex watch .) durante sesiones activas de desarrollo.

Error: el lenguaje del proyecto no está soportado por AiDex. Causa: el lenguaje no está entre los 11 soportados (por ejemplo, Kotlin o Swift). Solución: Code-Index-MCP es una alternativa que permite plugins de lenguaje personalizados. Para proyectos mixtos, puedes combinar AiDex para los lenguajes que soporta con búsqueda convencional para el resto.

Preguntas frecuentes

¿Vale la pena configurar esto en proyectos pequeños?

Para proyectos de menos de 50 archivos, el overhead de configuración no justifica el beneficio. Claude puede explorar ese tamaño sin problemas graves de contexto. El punto de inflexión está en proyectos de 100-200 archivos en adelante, especialmente si hay muchas dependencias cruzadas o trabajas en la misma base de código durante varios días seguidos.

¿Es compatible con otros MCP servers que ya tengo activos?

Sí, AiDex convive con otros servidores MCP (GitHub, Linear, Postgres, etc.). Si tienes varios activos, combínalo con el Tool Search nativo de Anthropic para hacer lazy loading de las definiciones de herramientas. La combinación de ambos da los mejores resultados en términos de eficiencia de contexto total.

¿Necesito entender Tree-sitter para usarlo?

No. AiDex abstrae completamente la capa de parsing. Interactúas solo con la CLI y el servidor MCP. Si quieres construir tu propio servidor con lógica personalizada, sí necesitas familiarizarte con la API de Tree-sitter, pero para el uso habitual no hace falta.

Un año después, el contexto sigue siendo el cuello de botella

Claude Code cumplió un año con Opus 4.6, una ventana de contexto de un millón de tokens y una comunidad de cientos de miles de desarrolladores. La herramienta es mucho más capaz que hace doce meses. Pero la limitación fundamental no ha cambiado: entre sesiones, el agente no recuerda nada, y dentro de una sesión, cada token gastado explorando código a ciegas es un token que no puede usarse para razonar sobre el problema real.

La combinación de Tree-sitter, SQLite y MCP no es perfecta. Tiene limitaciones en código dinámico, requiere mantener el índice sincronizado y no elimina la necesidad de gestionar el contexto activamente. Pero es la solución más pragmática disponible hoy para proyectos medianos: sin cloud, sin coste adicional de API, con setup en menos de diez minutos.

Si llevas tiempo usando Claude Code en proyectos de más de cien archivos y notas que las sesiones se degradan después de varias interacciones, este es el problema y esta es la solución más directa. Configúralo una vez, añade la actualización incremental como hook de Git, y deja que trabaje en segundo plano mientras tú te centras en el código.

¿Has probado algún enfoque parecido en tu flujo de trabajo con Claude Code? Cuéntamelo en los comentarios o en Twitter @sergiomarquezp_. El siguiente artículo va sobre memoria persistente en agentes más complejos: cómo hacer que lo que aprende en una sesión sobreviva a la siguiente.