codeindex

Inteligencia estructural de código sobre MCP: encuentra dónde se define un símbolo, lee una función, mira qué la llama, rastrea importaciones y evalúa qué rompe un cambio, en más de 40 lenguajes, sin leer archivos completos.

GitHub

Prueba este MCPPatrocinado

Documentación

Un motor de inteligencia estructural de código que se ejecuta como servidor MCP para agentes de codificación con IA.

Indexa tu base de código con tree-sitter (más de 40 lenguajes), construye un índice de texto completo por trigramas, un índice de palabras invertido y un grafo de dependencias — y los expone a través de 16 herramientas MCP.

 ┌─────────────┐      MCP (stdio)       ┌──────────────┐
 │  AI Agent   │ ◄─────────────────────► │   codeindex  │
 │ (Claude,    │   16 tools, JSON-RPC    │  (Zig binary) │
 │  Cursor…)   │                         │              │
 └─────────────┘                         └──────┬───────┘
                                                │
                                   tree-sitter parse (40+ langs)
                                         trigram + word index
                                         dependency graph
                                         snapshot persistence

Por qué

Los agentes de codificación con IA gastan tokens leyendo archivos completos. codeindex responde preguntas estructurales — esquemas de símbolos, definiciones, llamadores, radio de impacto, cadenas de dependencias — en unos pocos cientos de tokens en lugar de miles.

Una sola llamada a plan_change devuelve: dónde se define un símbolo, cada sitio de llamada, el rol arquitectónico del archivo (módulo dios / núcleo estable / isla / controlador), literales codificados para revisar y el radio de impacto transitivo completo si el archivo cambia.

Inicio rápido

El camino más corto, si tienes Node 18+. Nada más que instalar, sin clave, sin configuración — el paquete es un envoltorio de 4 KB que descarga el binario para tu plataforma y lo verifica contra las sumas de verificación publicadas:

claude mcp add codeindex -- npx -y @munhq/codeindex

Sin Node, o quieres también la habilidad y el hook:

# Prebuilt binary + skill + MCP registration, in one command
curl -fsSL https://raw.githubusercontent.com/munhq/codeindex/main/install.sh | bash

# Or build from source:
cd zig && ./fetch-vendor.sh && zig build -Doptimize=ReleaseFast

Docker, para hosts que instalan servidores MCP como imágenes. El espacio de trabajo se monta de solo lectura; codeindex nunca escribe en él:

docker run -i --rm -v "$PWD:/workspace:ro" munhq/codeindex

Regístrate con tu agente de IA:

# Claude Code — the plugin is the one-step path. It ships the skill, the hook
# and the MCP server together, and its launcher finds or fetches the binary.
claude plugin marketplace add munhq/codeindex
claude plugin install codeindex@codeindex

# Without the plugin (or for a different MCP client), register the binary
# directly. Do not do both: two registrations mean two servers, two copies of
# every tool schema, and two writers on one snapshot. install.sh detects the
# plugin and skips this step when it is present.
claude mcp add -s user codeindex -- ~/.local/bin/codeindex --mcp

# Cursor / Claude Desktop / other MCP clients: add to your config
{
  "mcpServers": {
    "codeindex": {
      "command": "npx",
      "args": ["-y", "@munhq/codeindex"]
    }
  }
}

Cada listado apunta al mismo servidor: npm @munhq/codeindex, el registro oficial de MCP como io.github.munhq/codeindex y Smithery como munhq/codeindex.

La próxima vez que tu agente se inicie, codeindex indexa tu proyecto en segundo plano y sirve consultas estructurales.

Herramientas MCP

Herramienta	Qué hace
`status`	Estadísticas del índice: número de archivos, número de símbolos, estado de indexación, % de ahorro de tokens
`search`	Búsqueda de texto completo acelerada por trigramas en todos los archivos indexados
`find_symbol`	Encuentra definiciones de símbolos (funciones, structs, clases…) por nombre
`find_word`	Búsqueda exacta de palabras/identificadores en el índice de palabras invertido
`find_callers`	Llamadores aproximados de un símbolo (heurístico, sin resolución completa de nombres)
`get_outline`	Esquema estructural de un archivo (símbolos, recuentos de líneas)
`get_tree`	Árbol de directorios con metadatos de archivos
`get_imports`	Qué archivos importa/depende un archivo dado
`get_imported_by`	Dependencias inversas — quién importa este archivo
`get_change_impact`	Radio de impacto transitivo: qué se rompe si un archivo cambia
`plan_change`	Plan completo de refactorización para un símbolo o archivo — definiciones, llamadores, rol del archivo, literales, radio de impacto
`get_hot_files`	Archivos modificados recientemente ordenados por actualidad
`read_file`	Lee el contenido de un archivo con rango de líneas opcional
`read_symbol`	Lee solo el código fuente de un símbolo (con líneas de contexto opcionales)
`index_workspace`	Indexa o re-indexa un directorio de trabajo
`analyze`	Ejecuta uno de los 16 análisis de código (ver abajo)

Análisis (herramienta `analyze`)

Análisis	Qué encuentra
`security`	Secretos codificados, patrones de inyección SQL, bloques inseguros, uso de eval
`dead_code`	Archivos y símbolos sin referencias
`unwrap_audit`	Manejo de errores propenso a `.unwrap()` / pánico (Rust)
`test_coverage`	Archivos sin cobertura de pruebas
`architecture`	Olores arquitectónicos — módulos dios, dependencias circulares, islas
`crossref`	Referencias de símbolos entre archivos
`type_drift`	Desajustes de firmas de tipos entre módulos
`db_schema`	Deriva del esquema de base de datos entre migraciones y código
`migration_parity`	Migraciones faltantes para cambios de esquema
`manifest_compliance`	Problemas de cumplimiento en package.json / Cargo.toml / go.mod
`literal_scan`	URLs, IPs, puertos, rutas absolutas y TODOs codificados
`coupling`	Métricas de acoplamiento de módulos
`cycles`	Detección de dependencias circulares
`duplication`	Funciones libres reinventadas — el mismo trabajo escrito dos veces
`clones`	Cuerpos de funciones copiados y pegados, ignorando nombres y espacios en blanco
`health`	Resumen de los análisis anteriores en un informe de salud del índice

Lenguajes soportados

Más de 40 lenguajes vía tree-sitter: Rust, Python, TypeScript/TSX, Go, Zig, C, C++, Java, Ruby, Bash, C#, Kotlin, Lua, Scala, Elixir, R, Swift, Dart, Haskell, TOML, JSON, YAML, HTML, CSS, SCSS, SQL, HCL, Dockerfile, Markdown, Nix, Make y más.

Configuración

codeindex --mcp                          # Run as MCP server (stdio)
codeindex --workspace ./my-project       # Index a specific directory
codeindex --project-id my-project        # Project identifier
codeindex -v                             # Print version
codeindex -h                             # Print help

# Environment variables
CODEINDEX_WORKSPACE=/path/to/project     # Same as --workspace
CODEINDEX_PROJECT_ID=my-project          # Same as --project-id

codeindex detecta automáticamente la raíz del proyecto subiendo desde el directorio de trabajo buscando .git, package.json, Cargo.toml, go.mod, build.zig, pyproject.toml, etc.

Se niega a indexar todo tu directorio personal o la raíz del sistema de archivos — pasa --workspace para ser explícito.

Arquitectura

Analizador: tree-sitter con más de 40 gramáticas, compilado en un solo binario
Índice: índice de trigramas para búsqueda de texto difusa + índice de palabras invertido para búsqueda exacta de identificadores
Grafo de dependencias: resolución de importaciones a nivel de archivo con aristas directas e inversas
Almacén de versiones: rastrea cambios de archivos con números de secuencia para actualizaciones incrementales
Observador en vivo: re-indexa al crear/modificar/eliminar archivos (hilo en segundo plano en modo MCP). inotify en Linux; un recorrido de sondeo en macOS y Windows, que compara mtime y tamaño cada un par de segundos. status informa qué backend está activo como watcher_backend.
Instantánea: persiste el índice completo en .codeindex.json, de modo que un reinicio carga la instantánea en lugar de re-indexar
Servidor MCP: JSON-RPC sobre stdio, implementa el protocolo MCP 2024-11-05

Soporte de plataformas

Cada fila es construida por CI y sus pruebas se ejecutan en esa plataforma, excepto donde se indique. status informa el backend del observador en vivo para que nunca sea una suposición.

	binario	pruebas en CI	observador	install.sh	plugin
Linux x86_64	Sí	Sí	inotify	Sí	Sí
Linux aarch64	Sí	compilación cruzada	inotify	Sí	Sí
macOS aarch64	Sí	Sí	sondeo	Sí	Sí
macOS x86_64	Sí	compilación cruzada	sondeo	Sí	Sí
Windows x86_64	Sí	Sí	sondeo	necesita un shell	ver abajo
Windows aarch64	Sí	compilación cruzada	sondeo	necesita un shell	ver abajo

En Windows, install.sh y el lanzador del plugin son scripts de shell, por lo que necesitan Git Bash, MSYS2 o Cygwin — los detectan y resuelven el recurso .exe correcto. El plugin registra su servidor a través de ese lanzador, por lo que un Claude Code nativo de Windows sin shell debería registrar el binario directamente:

claude mcp add -s user codeindex -- C:\path\to\codeindex.exe --mcp

Nada aquí está firmado o notarizado. En macOS, un binario descargado con curl se ejecuta sin un aviso de Gatekeeper; uno descargado a través de un navegador está en cuarentena, y xattr -d com.apple.quarantine codeindex lo limpia.

Compilación desde el código fuente

Requiere Zig 0.16.0.

cd zig
./fetch-vendor.sh    # Clone tree-sitter + 40 grammar repos
zig build -Doptimize=ReleaseFast
# Binary: zig/zig-out/bin/codeindex

Ejecuta las pruebas:

cd zig && zig build test-bin && ./zig-out/bin/test

zig build test enruta los resultados a través del protocolo IPC del runner de compilación en stdout, que las fuentes C de tree-sitter vinculadas corrompen mediante sus rutas de depuración printf. Compilar el binario de prueba y ejecutarlo directamente son las mismas pruebas sin ese protocolo en el camino.

Cómo se compara

	codeindex	ast-grep	ctags	LSIF	Sourcegraph
Nativo MCP	Sí	No	No	No	No
Eficiente en tokens	Sí (esquemas, no archivos completos)	No	Parcial	Sí	Sí
Binario único	Sí	Sí	Sí	No	No (servidor)
Observador en vivo	Sí (inotify / sondeo)	No	No	No	No
Grafo de dependencias	Sí	No	No	Sí	Sí
Radio de impacto	Sí (transitivo)	No	No	No	Parcial
Planificador de refactorización	Sí (`plan_change`)	No	No	No	No
Lenguajes	40+	20+	50+	Varía	Varía

Se combina con chat-recall

codeindex responde preguntas sobre el código frente a ti. chat-recall responde preguntas sobre el trabajo que ya hiciste — indexa tus sesiones de Claude Code, Gemini CLI, Codex, OpenCode y Antigravity en un historial buscable y lo expone también a través de MCP.

Juntos cubren ambas mitades de lo que un agente olvida: codeindex evita que vuelva a leer archivos que podría haber esquematizado, y chat-recall evita que rehaga trabajo que ya terminó. chat-recall detecta un binario de codeindex en tu PATH y registra cuatro herramientas adicionales de inteligencia de código cuando lo encuentra — ninguno requiere del otro.

Licencia

MIT. Ver LICENSE.