Code-Index-MCP (Indexador de código local-first)

Indexador de código local-first modular y extensible, diseñado para mejorar Claude Code y otros LLMs con capacidades de comprensión profunda del código. Construido sobre el Protocolo de Contexto de Modelos (MCP) para una integración fluida con asistentes de IA.

Estado de la implementación

Versión: 1.0.0 (Lanzamiento MVP) Características principales: Estable - Indexación local, búsqueda de símbolos/texto, soporte para 48 lenguajes Características opcionales: Búsqueda semántica (requiere Voyage AI), sincronización de índices (beta) Rendimiento: Consultas por debajo de 100ms, indexación <10s para repositorios en caché (evaluado en esta base de código; los resultados varían según el tamaño del repositorio y la mezcla de lenguajes)

¿Eres nuevo en Code-Index-MCP? Consulta nuestra Guía de inicio para un recorrido rápido.

🎯 Características clave

• 🚀 Arquitectura Local-First: Toda la indexación ocurre localmente para mayor velocidad y privacidad

• 📂 Almacenamiento de índice local: Todos los índices se almacenan en .indexes/ (relativo al servidor MCP)

• 🔌 Diseño basado en plugins: Fácilmente extensible con plugins específicos para cada lenguaje

• 🔍 Soporte para 48 lenguajes: Integración completa con tree-sitter con búsqueda semántica

• ⚡ Actualizaciones en tiempo real: Monitoreo del sistema de archivos para actualizaciones de índice instantáneas

• 🧠 Búsqueda semántica: Búsqueda de código impulsada por IA con embeddings de Voyage AI

• 📊 Inteligencia de código enriquecida: Resolución de símbolos, inferencia de tipos, seguimiento de dependencias

• 🚀 Rendimiento mejorado: Consultas por debajo de 100ms con protección de tiempo de espera y omisión de BM25

• 🔄 Sincronización con Git: Actualizaciones automáticas de índice que rastrean los cambios en el repositorio

• 📦 Gestión de índices portátil: Intercambio de índices sin costo a través de GitHub Artifacts

• 🔄 Sincronización automática de índices: Extraer índices al clonar, enviar al realizar cambios

• 🎯 Reordenamiento inteligente de resultados: Reordenamiento con múltiples estrategias para mejorar la relevancia

• 🎯 Enrutamiento de intención de consulta: Las consultas de patrones de símbolos (class Foo, def bar, CamelCase) omiten BM25 y acceden directamente a la tabla de símbolos para búsquedas por debajo de 5ms

• 🔒 Exportación consciente de la seguridad: Filtrado automático de archivos sensibles de los índices compartidos

• 🔍 Búsqueda híbrida: BM25 + búsqueda semántica con fusión configurable

• 🔐 Indexa todo localmente: Busca archivos .env y secretos en tu máquina

• 🚫 Filtrado inteligente al compartir: Patrones de .gitignore y .mcp-index-ignore aplicados solo durante la exportación

• 🌐 Indexación multilingüe: Indexa repositorios completos con lenguajes mixtos

🏗️ Arquitectura

Code-Index-MCP sigue una arquitectura modular basada en plugins diseñada para la extensibilidad y el rendimiento:

Capas del sistema

1. 🌐 Contexto del sistema (Nivel 1)

   • El desarrollador interactúa con Claude Code u otros LLMs

   • El protocolo MCP proporciona una interfaz de herramientas estandarizada

   • Procesamiento local-first con características de nube opcionales

   • SLAs de rendimiento: <100ms para búsqueda de símbolos, <500ms para búsqueda

2. 📦 Arquitectura de contenedores (Nivel 2)

   ┌─────────────────┐     ┌──────────────┐     ┌─────────────┐
   │   API Gateway   │────▶│  Dispatcher  │────▶│   Plugins   │
   │   (FastAPI)     │     │              │     │ (Language)  │
   └─────────────────┘     └──────────────┘     └─────────────┘
          │                        │                     │
          ▼                        ▼                     ▼
   ┌─────────────────┐     ┌──────────────┐     ┌─────────────┐
   │  Local Index    │     │ File Watcher │     │  Embedding  │
   │  (SQLite+FTS5)  │     │  (Watchdog)  │     │   Service   │
   └─────────────────┘     └──────────────┘     └─────────────┘

3. 🔧 Detalles de los componentes (Nivel 3)

   • Gateway Controller: Endpoints de API RESTful

   • Dispatcher Core: Enrutamiento y ciclo de vida de plugins

   • Plugin Base: Interfaz estándar para todos los plugins

   • Language Plugins: Analizadores y analizadores especializados

   • Index Manager: SQLite con FTS5 para búsquedas rápidas

   • Watcher Service: Monitoreo de archivos en tiempo real

📁 Estructura del proyecto

El proyecto sigue una estructura limpia y organizada. Consulta docs/PROJECT_STRUCTURE.md para ver el diseño detallado.

Directorios clave:

• mcp_server/ - Implementación principal del servidor MCP

• scripts/ - Scripts de desarrollo y utilidad

• tests/ - Suite de pruebas integral con fixtures

• docs/ - Documentación y guías

• architecture/ - Diseño del sistema y diagramas

• docker/ - Configuraciones de Docker y archivos compose

• data/ - Archivos de base de datos e índices

• logs/ - Registros de la aplicación y pruebas

• reports/ - Informes de rendimiento y análisis generados

• analysis_archive/ - Análisis histórico e investigación archivada

🛠️ Soporte de lenguajes

✅ Lenguajes totalmente soportados (46+ en total)

Características listas para producción:

• Carga dinámica de plugins: Los lenguajes se cargan bajo demanda para un rendimiento óptimo

• Análisis con Tree-sitter: Extracción precisa de símbolos basada en AST con consultas específicas del lenguaje

• Caché de consultas: Rendimiento mejorado con consultas de tree-sitter en caché

• Búsqueda semántica: Búsqueda de código opcional impulsada por IA (cuando Qdrant está disponible)

• Búsqueda entre lenguajes: Encuentra símbolos y patrones en todos los lenguajes soportados

Categorías de lenguajes:

Estado de la implementación: Listo para producción - Todos los lenguajes soportados a través del despachador mejorado con:

• ✅ Carga dinámica de plugins (inicialización perezosa)

• ✅ Manejo robusto de errores y mecanismos de respaldo

• ✅ Resolución de rutas para estructuras de proyectos complejas

• ✅ Degradación elegante cuando los servicios externos no están disponibles

🚀 Inicio rápido

🎯 Configuración automática para Claude Code/Desktop (Recomendado)

# Auto-configures MCP for your environment
./scripts/setup-mcp-json.sh

# Or interactive mode
./scripts/setup-mcp-json.sh --interactive

Esto detecta automáticamente tu entorno y crea la configuración .mcp.json adecuada.

🐳 Configuración de Docker por entorno

Opción 1: Búsqueda básica (Sin claves API) - 2 minutos

# Install MCP Index with Docker
curl -sSL https://raw.githubusercontent.com/ViperJuice/Code-Index-MCP/main/scripts/install-mcp-docker.sh | bash

# Index your current directory
docker run -it -v $(pwd):/workspace ghcr.io/code-index-mcp/mcp-index:minimal

Opción 2: Búsqueda impulsada por IA

# Set your API key (get one at https://www.voyageai.com — free tier available)
export VOYAGE_API_KEY=your-key

# Run with semantic search
docker run -it -v $(pwd):/workspace -e VOYAGE_API_KEY ghcr.io/code-index-mcp/mcp-index:standard

💻 Configuración específica del entorno

🪟 Windows (Nativo)

# PowerShell
.\scripts\setup-mcp-json.ps1

# Or manually with Docker Desktop
docker run -it -v ${PWD}:/workspace ghcr.io/code-index-mcp/mcp-index:minimal

🍎 macOS

# Install Docker Desktop or use Homebrew
brew install --cask docker

# Run setup
./scripts/setup-mcp-json.sh

🐧 Linux

# Install Docker (no Desktop needed)
curl -fsSL https://get.docker.com | sh

# Run setup
./scripts/setup-mcp-json.sh

🔄 WSL2 (Subsistema de Windows para Linux)

# With Docker Desktop integration
./scripts/setup-mcp-json.sh  # Auto-detects WSL+Docker

# Without Docker Desktop
cp .mcp.json.templates/native.json .mcp.json
pip install -e .

📦 Contenedores anidados (Dev Containers)

# For VS Code/Cursor dev containers
# Option 1: Use native Python (already in container)
cp .mcp.json.templates/native.json .mcp.json

# Option 2: Use Docker sidecar (avoids dependency conflicts)
docker-compose -f docker/compose/development/docker-compose.mcp-sidecar.yml up -d
cp .mcp.json.templates/docker-sidecar.json .mcp.json

📋 Ejemplos de configuración de MCP.json

El script de configuración crea el .mcp.json adecuado para tu entorno. Ejemplos manuales:

Python nativo (Dev Container/Local)

{
  "mcpServers": {
    "code-index-native": {
      "command": "python",
      "args": ["scripts/cli/mcp_server_cli.py"],
      "cwd": "${workspace}"
    }
  }
}

Docker (Windows/Mac/Linux)

{
  "mcpServers": {
    "code-index-docker": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "${workspace}:/workspace",
        "ghcr.io/code-index-mcp/mcp-index:minimal"
      ]
    }
  }
}

🌍 Uso en otro repositorio

Para indexar un repositorio diferente, apunta el cwd del servidor a ese repositorio en tu configuración de Claude Code MCP (~/.claude/settings.json o .mcp.json):

{
  "mcpServers": {
    "code-index-mcp": {
      "command": "/abs/path/to/Code-Index-MCP/.venv/bin/python",
      "args": ["/abs/path/to/Code-Index-MCP/scripts/cli/mcp_server_cli.py"],
      "cwd": "/abs/path/to/your-repo"
    }
  }
}

El campo cwd controla qué repositorio se indexa. En el primer uso, el servidor construye automáticamente el índice en un hilo en segundo plano; el servidor responde inmediatamente mientras la indexación progresa, y las respuestas de search_code incluyen "indexing_in_progress": true hasta que se completa la construcción inicial.

Opciones:

• Establece MCP_AUTO_INDEX=false en el entorno del servidor para omitir la auto-indexación en segundo plano y llamar a la herramienta MCP reindex manualmente (recomendado para repositorios muy grandes).

• Agrega {"enabled": false} a .mcp-index.json en el repositorio de destino para deshabilitar la indexación para ese repositorio por completo.

• Después de una reindexación completa o cambios de código, llama a la herramienta MCP reindex para reconstruir el índice bajo demanda.

Perfiles semánticos: La búsqueda BM25 no requiere configuración adicional. Para la búsqueda semántica (vectorial), el servidor carga automáticamente code-index-mcp.profiles.yaml desde su propio directorio de instalación; no es necesario copiarlo a cada repositorio. Para anular con un archivo de perfil personalizado, establece MCP_PROFILES_PATH=/abs/path/to/your-profiles.yaml en el entorno del servidor. Para anular URLs de endpoints individuales sin editar el YAML, usa las variables de entorno referenciadas en el archivo (p. ej., VLLM_EMBEDDING_BASE_URL, VLLM_SUMMARIZATION_BASE_URL).

⚡ Habilitar búsqueda semántica

La búsqueda por palabras clave BM25 funciona sin configuración. Para agregar búsqueda vectorial (semántica), elige un camino:

Opción A — Voyage AI (recomendado):

export VOYAGE_API_KEY=your-key   # free tier available at voyageai.com

El perfil commercial_high se activa automáticamente. Reinicia el servidor MCP; el registro de inicio confirmará que la búsqueda semántica está activa.

Opción B — OSS local (Qwen3-Embedding-8B vía vLLM, no se necesita clave API):

export VLLM_EMBEDDING_BASE_URL=http://localhost:8000/v1
# Start vLLM (requires ~20GB VRAM or shared CPU with --dtype float32):
docker run -p 8000:8000 vllm/vllm-openai --model Qwen/Qwen3-Embedding-8B

Tanto los perfiles como sus nombres de colección están definidos en code-index-mcp.profiles.yaml y pueden personalizarse.

💰 Costos y características

🚀 Inicio rápido (Python)

Requisitos previos

• Python 3.12+

• Git

Instalación

Opción 1: Instalar vía pip (Recomendado)

# Install the package
pip install index-it-mcp

# Or install with dev tools for testing
pip install index-it-mcp[dev]

Opción 2: Instalar desde el código fuente

# Clone the repository
git clone https://github.com/ViperJuice/Code-Index-MCP.git
cd Code-Index-MCP

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in editable mode
pip install -e .

Inicio rápido después de la instalación

# Authenticate GitHub artifact access once
gh auth login

# Check repo/artifact readiness before starting work
mcp-index preflight

# Pull the latest published index baseline for this repo
mcp-index artifact pull --latest

# Reconcile only your local drift after restore
mcp-index artifact sync

# The restored files live locally for MCP runtime use:
# - code_index.db
# - .index_metadata.json
# - vector_index.qdrant/

# Check index status
mcp-index index status

# Start the API server
mcp-index serve

# Or choose a custom port explicitly
mcp-index serve --port 9123

# Test the API
curl http://localhost:8000/status
curl -X POST http://localhost:8000/search \
  -H "Content-Type: application/json" \
  -d '{"query": "def parse"}'

🔧 Configuración

Crea un archivo .env para la configuración:

# Semantic profile setup — set VOYAGE_API_KEY (free tier at voyageai.com) to enable vector search
VOYAGE_API_KEY=your_api_key_here
# Use 127.0.0.1 for local inference, or a Tailscale/SSH tunnel IP for remote GPUs
OPENAI_API_BASE=http://127.0.0.1:8001/v1
QDRANT_PATH=vector_index.qdrant

# Server settings
MCP_SERVER_HOST=0.0.0.0
MCP_SERVER_PORT=8000
MCP_LOG_LEVEL=INFO

# Workspace settings
MCP_WORKSPACE_ROOT=.
MCP_MAX_FILE_SIZE=10485760  # 10MB

# GitHub Artifact Sync (privacy settings)
MCP_ARTIFACT_SYNC=false  # Set to true to enable
AUTO_UPLOAD=false        # Auto-upload on changes
AUTO_DOWNLOAD=true       # Auto-download on clone

Los artefactos publicados ahora llevan la línea base léxica completa más dos perfiles semánticos:

• commercial_high usando voyage-code-3

• oss_high usando Qwen/Qwen3-Embedding-8B

Esos perfiles se almacenan en colecciones de Qdrant separadas dentro del artefacto para que los consumidores puedan extraer una línea base y usar cualquier perfil localmente.

Consejo profesional: Inferencia remota para el perfil de código abierto Si tu máquina local carece de la potencia de GPU para ejecutar el modelo de embedding oss_high localmente (p. ej., vía vLLM u Ollama), puedes ejecutar la inferencia en una máquina remota y apuntar el servidor MCP hacia ella:

• Tailscale/VPN: Establece OPENAI_API_BASE=http://<tailnet-ip>:8001/v1

• Túnel SSH: Ejecuta ssh -L 8001:localhost:8001 user@remote-gpu-machine, y la configuración predeterminada 127.0.0.1:8001 se tunelizará directamente a tu servidor de inferencia.

Los archivos de índice generados no están destinados a vivir en el historial de git. El repositorio rastrea el código, el flujo de trabajo y la configuración necesarios para construirlos/publicarlos; los artefactos de GitHub distribuyen la línea base de tiempo de ejecución real que MCP restaura localmente.

Flujo de trabajo multi-repositorio en la misma máquina

Para usuarios de código abierto, el modelo multi-repositorio recomendado es local-first en una máquina:

# Register each local repository once
mcp-index repository register /path/to/repo-a
mcp-index repository register /path/to/repo-b

# Inspect repository-level readiness details
mcp-index repository list -v

# Inspect all registered repositories and their local artifact/runtime readiness
mcp-index artifact workspace-status

# Refresh readiness after restoring or rebuilding local indexes
mcp-index artifact reconcile-workspace

# Prepare per-repo local artifact payloads without requiring remote publication
mcp-index artifact publish-workspace

Patrón recomendado:

1. registra cada checkout de repositorio una vez con mcp-index repository register <path>

2. mantén cada checkout de repositorio autocontenido

3. restaura o reconstruye los archivos de tiempo de ejecución locales por repositorio según sea necesario

4. usa mcp-index repository list -v y el estado/reconciliación del espacio de trabajo para ver qué repositorios están listos o obsoletos

5. solo usa la publicación de artefactos de GitHub cuando realmente quieras compartir una línea base de repositorio

🔐 Privacidad y sincronización de artefactos de GitHub

Controla cómo se comparte tu índice de código:

// .mcp-index.json
{
  "github_artifacts": {
    "enabled": false,        // Disable sync entirely
    "auto_upload": false,    // Manual upload only
    "auto_download": true,   // Still get team indexes
    "exclude_patterns": [    // Additional exclusions
      "internal/*",
      "proprietary/*"
    ]
  }
}

Características de privacidad:

• Índices filtrados automáticamente por .gitignore

• Patrones adicionales vía .mcp-index-ignore

• Los registros de auditoría muestran lo que se excluyó

• Sincronización deshabilitada por defecto en la versión mínima de Docker

🆕 Características avanzadas

Reordenamiento de resultados de búsqueda

Hay tres reordenadores disponibles, configurados a través de la variable de entorno RERANKER_TYPE:

export RERANKER_TYPE=flashrank   # or cross-encoder, voyage, none

El reordenamiento se aplica solo a la ruta de recuperación semántica. Los resultados de BM25/FTS no se reordenan. Implementación: mcp_server/dispatcher/reranker.py.

Resumen de fragmentos de LLM

Los fragmentos semánticos pueden aumentarse con resúmenes generados por LLM antes de la incrustación, mejorando la recuperación de consultas basadas en la intención. Configurado por perfil en code-index-mcp.profiles.yaml:

summarization:
  enabled: true
  mode: lazy           # lazy (on first query) | comprehensive (at index time)
  provider: openai_compatible
  model_name: gpt-4o-mini
  base_url: "https://api.openai.com/v1"
  api_key_env: OPENAI_API_KEY
  prompt_template: "Describe this code chunk's inputs, outputs, and purpose in 2 concise sentences."

⚠️ Seguridad: No resumas código no confiable con LLMs