contextshrinker

contextshrinker es un servidor de Protocolo de Contexto de Modelo (MCP) sin dependencias y sin interfaz gráfica, escrito en Go. Indexa bases de código locales en una base de datos de grafos Kùzu integrada para reducir drásticamente el exceso de tokens de LLM para agentes de IA autónomos (como Claude Code, Cursor, Antigravity IDE, Aider y Claude Desktop).

En lugar de obligar a los agentes de IA a leer archivos fuente sin procesar o ejecutar búsquedas torpes basadas en grep, contextshrinker permite a los agentes consultar un grafo semántico de las dependencias arquitectónicas de tu proyecto, cadenas de llamadas a funciones y estructuras de herencia de clases, reduciendo el consumo de contexto de entrada entre un 90% y un 98%.

🚀 Características principales

• Compatibilidad universal con agentes: Se integra sin problemas con cualquier herramienta de codificación o IDE compatible con MCP a través de E/S estándar (stdio).

• Cero bases de datos externas: Totalmente autónomo. Ejecuta una base de datos de grafos en proceso (Kùzu) dentro del directorio local .contextshrinker/ de tu proyecto.

• Demonios LSP autogestionados: Detecta automáticamente los lenguajes del proyecto, aprovisiona programáticamente servidores de lenguaje en espacio aislado (como gopls para Go o pyright para Python) si faltan, y consulta sus interfaces RPC en segundo plano para construir grafos de llamadas.

• Soporte multilenguaje: Análisis sintáctico AST completo e indexación semántica para Go, Python, JavaScript, TypeScript y Java.

• Aislamiento limpio del proyecto: Cada espacio de trabajo mantiene su propio directorio .contextshrinker/ que contiene reglas de configuración aisladas (.contextshrinker/ignore) y archivos de base de datos de grafos (.contextshrinker/db/).

• Sincronización de estado en vivo: Utiliza fsnotify para vigilar tus archivos de forma recursiva. Al guardar, una actualización delta con debounce elimina los nodos antiguos y reindexa los archivos modificados en tiempo real.

• Visualización interactiva de grafos: Genera una impresionante visualización HTML de la base de código en modo oscuro impulsada por Vis.js (.contextshrinker/contextshrinker_graph.html) bajo demanda.

Related MCP server: code-graph-mcp

🛠️ Arquitectura: la ingesta de dos pasadas

Para indexar tu código limpiamente, contextshrinker ejecuta una secuencia de ingesta de dos pasadas:

graph TD
    A[Walk Workspace] -->|Filter via .contextshrinker/ignore| B[Pass 1: Tree-sitter Syntax]
    B -->|Create Nodes| C[(Kùzu Graph DB)]
    C --> D[Pass 2: LSP Semantic Cross-References]
    D -->|Create CALLS / IMPLEMENTS Edges| C

1. Pasada 1 (Extracción AST con Tree-sitter): Escanea rápidamente los archivos fuente para extraer entidades (funciones/métodos, clases/estructuras, variables) y sus cadenas de documentación asociadas, insertándolas como nodos.

2. Pasada 2 (Resolución semántica LSP): Consulta demonios del Protocolo de Servidor de Lenguaje (LSP) en segundo plano para referencias cruzadas, identificando y conectando invocaciones (CALLS), importaciones (IMPORTS) y herencias de clases (IMPLEMENTS / EXTENDS).

📥 Instalación

Opción 1: Binarios precompilados (lo más rápido)

Si no quieres instalar Go, puedes descargar un paquete portátil precompilado para tu plataforma:

1. Ve a la página de Releases.

2. Descarga el archivo comprimido para tu sistema operativo (.tar.gz o .zip).

3. Extrae el archivo. Mantén el ejecutable (contextshrinker) y su biblioteca dinámica (libkuzu / kuzu_shared) en la misma carpeta.

4. Ejecuta el ejecutable desde ese directorio:

macOS / Linux:

chmod +x contextshrinker
./contextshrinker --help

Windows:

contextshrinker.exe --help

Opción 2: Compilar desde el código fuente (requiere Go)

Requisitos previos

• Go (1.21 o posterior)

• Node.js y npm (para instalar automáticamente los LSP de JS/TS y Python)

Compilar

Clona el repositorio y ejecuta:

go build -o contextshrinker

Para instalarlo directamente en el PATH de tu sistema:

go install

🔌 Integración en agentes de codificación

contextshrinker se ejecuta bajo demanda como un proceso hijo de tu agente de codificación. Registra la ruta absoluta al binario compilado en tu cliente:

1. Antigravity IDE (panel del agente Gemini)

1. Abre Antigravity IDE.

2. Haz clic en el menú ... (Más opciones) del panel del agente.

3. Selecciona "Administrar servidores MCP" $\rightarrow$ "Ver configuración sin procesar".

4. Registra el servidor en tu mcp_config.json:

   {
     "mcpServers": {
       "contextshrinker": {
         "command": "/absolute/path/to/contextshrinker"
       }
     }
   }

2. Claude Code (CLI)

Añade el servidor automáticamente:

claude mcp add contextshrinker /absolute/path/to/contextshrinker

3. Cursor IDE

1. Navega a Configuración $\rightarrow$ Funciones $\rightarrow$ MCP.

2. Haz clic en + Añadir nuevo servidor MCP.

3. Establece la configuración:

   • Nombre: contextshrinker

   • Tipo: command

   • Comando: /absolute/path/to/contextshrinker

4. Claude Desktop

Añádelo a tu ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "contextshrinker": {
      "command": "/absolute/path/to/contextshrinker"
    }
  }
}

🧰 Herramientas expuestas

Una vez configurado, las siguientes herramientas estarán automáticamente disponibles para tus agentes de IA:

1. search_codebase

   • Argumentos: query (cadena)

   • Descripción: Ejecuta búsquedas de texto completo y consultas Cypher para emparejar estructuras y cadenas de documentación en clases, funciones y variables.

2. get_call_chain

   • Argumentos: target_function (cadena), depth (entero, máx. 5)

   • Descripción: Resuelve cadenas de llamadas ascendentes mediante consultas Cypher de longitud variable para mapear dependencias de llamadas.

3. get_file_structure

   • Argumentos: file_path (cadena)

   • Descripción: Recupera la estructura completa de nodos abstractos (clases, interfaces, métodos, variables) contenida en un solo archivo sin enviar el contenido de texto sin procesar a la ventana de contexto.

4. visualize_codebase

   • Descripción: Activa una exportación HTML bajo demanda, guardando contextshrinker_graph.html dentro de tu directorio .contextshrinker/.

5. get_architecture_report

   • Descripción: Recupera el informe completo de salud arquitectónica de la base de código que contiene métricas sobre objetos Dios, puntos calientes de acoplamiento, ciclos, funciones no exportadas muertas, métricas de IA (SCR, DCR, BVI, AOI, índice de profundidad de cadena de llamadas - CDI) y pautas prácticas de calidad de código (principios de Jeff Dean) con directivas de prompt de sistema de IA.

🏛️ Optimización de la base de código y la arquitectura

Puedes usar contextshrinker para auditar sistemáticamente el acoplamiento, analizar los límites del dominio (DDD) y guiar la reestructuración del código (por ejemplo, dividir un monolito en módulos) mediante LLM.

Flujo de trabajo de optimización

1. Genera las métricas y pautas arquitectónicas: Ejecuta el comando de análisis en tu terminal para inspeccionar el grafo de la base de código y generar un informe:

   ./contextshrinker analyze

   Esto genera contextshrinker-report.md que contiene métricas de objetos Dios (alto acoplamiento saliente), agujeros negros (alto número de llamadas entrantes), rutas de importación cíclicas, código muerto (funciones privadas no utilizadas), métricas de IA (incluido el índice de profundidad de cadena de llamadas - CDI) y pautas prácticas de calidad de código y arquitectura de LLM (principios de Jeff Dean).

2. Obtención del prompt de sistema: Recupera el prompt del arquitecto principal de sistemas desde la CLI:

   ./contextshrinker prompt architect

3. Análisis con LLM:

   • Establece la salida del comando prompt architect como prompt de sistema para tu LLM.

   • Proporciona el contenido del contextshrinker-report.md generado como contexto / entrada.

   • Pide al LLM que proponga divisiones de contexto acotado o límites de interfaz.

4. Flujos de trabajo agénticos / de uso de herramientas: Si usas un agente compatible con MCP (como Antigravity IDE, Claude Code o Cursor), puedes pedirle directamente:

   "Ejecuta el informe de análisis de contextshrinker, lee el markdown generado y actúa como arquitecto de sistemas para auditar nuestros puntos críticos de diseño. Usa las herramientas get_call_chain y get_file_structure para inspeccionar el acoplamiento antes de sugerir extracciones de módulos concretas."

⚙️ Configuración e ignorados

Para evitar la hinchazón del grafo del espacio de trabajo, la biblioteca estándar y las carpetas de dependencias (node_modules/, vendor/, .git/, etc.) se ignoran de forma predeterminada.

Para añadir ignorados personalizados, inicializa el proyecto y genera un archivo .csignore en la raíz de tu espacio de trabajo ejecutando:

contextshrinker init

Cada línea de .csignore se compara de forma recursiva:

# Custom project ignores
*.log
tmp-output/
dist/
.vitepress

💡 Prácticas recomendadas para proyectos grandes

Si estás usando contextshrinker en un proyecto de mediana a gran envergadura (por ejemplo, cientos o miles de archivos), ejecutar la ingesta inicial de la base de código directamente desde un prompt de LLM/agente (como Claude Code o Cursor) puede provocar problemas de tiempo de espera del agente. Esto ocurre porque el agente tiene un límite de tiempo de espera estricto (normalmente 60 segundos) mientras espera que se complete el análisis inicial del espacio de trabajo y la resolución de referencias LSP.

Para evitarlo, sigue este flujo de trabajo optimizado en tu terminal antes de iniciar el agente:

1. Inicializa el espacio de trabajo: Ejecuta el comando de inicialización para crear el directorio de configuración y la lista de ignorados predeterminada:

   contextshrinker init

2. Configura tus ignorados: Abre el archivo .csignore generado en la raíz de tu espacio de trabajo y añade los directorios grandes que quieras excluir (por ejemplo, sitios de documentación, recursos de prueba, carpetas de compilación generadas).

3. Construye la base de datos sin conexión: Ejecuta el comando de análisis una vez desde tu terminal para construir la base de datos de grafos inicial:

   contextshrinker analyze

   Esto realiza el trabajo pesado del análisis de Tree-sitter y la referenciación cruzada semántica LSP sin conexión. Una vez que la base de datos está poblada, las solicitudes posteriores del agente y las sincronizaciones de estado en vivo se ejecutarán de forma incremental en segundos, ¡evitando futuros tiempos de espera!

📊 Modo de interfaz de línea de comandos (CLI)

Puedes consultar el grafo de la base de código, iniciar el demonio del servidor MCP explícitamente, recuperar prompts de arquitecto de sistemas o generar informes de análisis de salud directamente desde tu terminal.

1. Iniciar el servidor MCP

De forma predeterminada, ejecutar ./contextshrinker sin argumentos inicia el demonio del servidor MCP. También puedes activarlo explícitamente:

./contextshrinker start

2. Ejecutar análisis arquitectónico de la base de código

Analiza la estructura de la base de código (objetos Dios, puntos calientes de llamadas entrantes, importaciones cíclicas, código muerto, índice de profundidad de cadena de llamadas - CDI y pautas de calidad de código para LLM) y escribe un informe en contextshrinker-report.md:

./contextshrinker analyze

3. Imprimir el prompt del arquitecto principal de sistemas

Imprime el prompt de sistema del arquitecto principal de sistemas de Diseño Dirigido por el Dominio (DDD) en la salida estándar:

./contextshrinker prompt architect

4. Buscar en la base de código

Encuentra funciones, clases o variables que coincidan con una consulta:

./contextshrinker search "IngestWorkspace"

5. Trazar cadenas de llamadas

Traza los llamadores ascendentes de un nombre de función objetivo (la profundidad predeterminada es 3, la máxima es 5):

./contextshrinker call-chain "IngestWorkspace" --depth 3

6. Recuperar la estructura de un archivo

Obtén la estructura de un archivo sin leer su contenido de texto completo:

./contextshrinker structure "main.go"

7. Generar visualización interactiva

Genera una representación de grafo de la base de código con Vis.js:

./contextshrinker visualize

Abre el archivo .contextshrinker/contextshrinker_graph.html generado en cualquier navegador para explorar la arquitectura de tu proyecto de forma interactiva.

Opciones (indicadores globales)

• --workspace <ruta>: Especifica el directorio del proyecto (por defecto, .).

• --db <ruta>: Especifica el directorio de almacenamiento de la base de datos (por defecto, .contextshrinker/db).

• --reindex: Fuerza un escaneo completo de ingesta del espacio de trabajo (reanalizando el código y mapeando las relaciones LSP) antes de ejecutar la consulta. Si la base de datos está vacía, la ingesta se ejecuta automáticamente.

• Nota: Debido a que la base de datos de Kuzu establece un bloqueo exclusivo a nivel de archivo, asegúrate de que el cliente MCP de tu IDE esté en pausa o detenido al ejecutar comandos CLI en la base de datos activa, o usa un directorio de espacio de trabajo/base de datos diferente con los indicadores de la CLI.

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT.