Code-Index-MCP

Un indexador de código local que mejora los LLMs con una comprensión profunda del código. Se integra con asistentes de IA a través del Model Context Protocol (MCP) y admite búsqueda semántica impulsada por IA.

GitHub

Prueba este MCPPatrocinado

Documentación

Code-Index-MCP

Dale a tu asistente de codificación con IA acceso instantáneo y preciso a todo tu código base — para que encuentre el código exacto que necesita en milisegundos en lugar de gastar tiempo y tokens leyendo archivos completos.

Code-Index-MCP es un índice de búsqueda rápido y local-first para tu código. Se integra con Claude Code y otros asistentes de IA (a través del Protocolo de Contexto de Modelos, "MCP") y les permite buscar cualquier símbolo o texto en tu repositorio casi instantáneamente — sin que tu código salga nunca de tu máquina.

¿Nuevo en Code-Index-MCP? Comienza con la Guía de Inicio.

Estado: Superficie estable v1.4.0 preparada — las herramientas MCP (search_code, symbol_lookup) son la interfaz principal; una puerta de enlace administrativa FastAPI está disponible para diagnósticos.

Estado de preparación de la superficie estable: Esta guía apunta al candidato de lanzamiento de endurecimiento 1.4.0 propiedad del repositorio. MCP STDIO sigue siendo la superficie principal para LLM y FastAPI sigue siendo una superficie administrativa secundaria. Una verificación de colisiones del 10 de julio de 2026 no encontró index-it-mcp==1.4.0 en vivo, por lo que esta guía usa fuente y prueba de rueda local en lugar de afirmar que la superficie 1.4.0 preparada está publicada.

Estado del Proyecto

Versión: 1.4.0 (superficie preparada propiedad del repositorio; no publicada al 10 de julio de 2026) Distribución de Python: index-it-mcp Imagen de contenedor: ghcr.io/consiliency/code-index-mcp Superficie principal: Herramientas MCP (search_code, symbol_lookup) a través del ejecutor STDIO cuando la preparación del repositorio es ready Superficie secundaria: Puerta de enlace REST administrativa FastAPI para diagnósticos y scripting — ver "Interfaz REST Administrativa (secundaria)" más abajo Características principales: indexación local, búsqueda de símbolos/texto, cobertura de lenguajes basada en registro; ver docs/SUPPORT_MATRIX.md Características opcionales: búsqueda semántica (requiere Voyage AI o un endpoint vLLM local), sincronización de índices de GitHub Artifacts Rendimiento: búsqueda de símbolos en menos de 100 ms y búsqueda en menos de 500 ms en repositorios indexados (evaluado en este código base; los resultados varían según el tamaño del repositorio y la mezcla de lenguajes) Decisión de GA: ver docs/validation/ga-final-decision.md; la decisión actual del producto es ship GA, mientras que las afirmaciones de la superficie de instalación permanecen limitadas por docs/status/public-package-identity.md. Contrato de preparación para GA: ver docs/validation/ga-readiness-checklist.md para el límite de lanzamiento congelado, etiquetas de nivel de soporte, propiedad de evidencia y expectativas de reversión que aplican antes del despacho. Despacho de lanzamiento: el registro histórico de gobernanza nombra este límite GADISP; el flujo de trabajo actual lo implementa como un modo publish separado restringido a main protegido. Modelo de repositorio: un servidor puede servir muchos repositorios no relacionados, con un árbol de trabajo registrado por directorio común de git. Solo la rama rastreada/por defecto se indexa automáticamente. Los resultados MCP indexados son autoritativos solo cuando la preparación es ready; los índices no disponibles devuelven index_unavailable con safe_fallback: "native_search".

MCP_CLIENT_SECRET es un guardián de protocolo de enlace STDIO local para mcp-index stdio. La puerta de enlace FastAPI usa autenticación separada de token portador admin/debug, y no se implementa autorización MCP remota mientras el transporte MCP remoto permanezca diferido.

Por qué existe

Cuando un asistente de IA trabaja en un código base grande, a menudo lee grandes fragmentos de archivos solo para encontrar lo que necesita. Eso es lento, y cada archivo que lee cuesta tokens (dinero). Code-Index-MCP construye un índice local para que el asistente pueda saltar directamente a la función, clase o línea correcta — reduciendo el costo de tokens y haciendo las respuestas más rápidas y precisas.

Para quién es

Desarrolladores y equipos que usan asistentes de codificación con IA en código base real y considerable que quieren resultados más rápidos, más baratos y más precisos — y que quieren que su código permanezca privado, en su propia máquina.

Lo que obtienes

⚡ Búsquedas instantáneas — búsqueda de símbolos en menos de 100 ms, búsqueda en menos de 500 ms en repositorios indexados.
🔒 Local-first y privado — la indexación se ejecuta en tu máquina; tu código no se envía a la nube.
💸 Menor costo de tokens — el asistente busca en lugar de leer archivos completos (ver los gráficos abajo).
🧠 Búsqueda semántica (opcional) — búsqueda de código en lenguaje natural mediante embeddings.
🌐 Muchos lenguajes, muchos repositorios — un servidor puede indexar múltiples repositorios con lenguajes mixtos.
🔌 Basado en plugins y extensible — agrega soporte de lenguajes sin tocar el núcleo.

Vélo en acción

Los benchmarks en este repositorio muestran grandes reducciones de tokens/costos cuando un asistente busca con Code-Index-MCP en lugar de leer archivos directamente:

Token and cost savings — summary

Cost savings

Token reduction by language

(Gráficos generados a partir de los benchmarks en reports/; los números varían según el tamaño del repositorio y la mezcla de lenguajes.)

🎯 Características Clave

🚀 Arquitectura Local-First: Toda la indexación ocurre localmente para 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 de lenguaje
🔍 Soporte de lenguajes: El soporte de lenguajes/runtimes por niveles está documentado en docs/SUPPORT_MATRIX.md
⚡ Actualizaciones en Tiempo Real: Monitoreo del sistema de archivos para actualizaciones instantáneas del índice
🧠 Búsqueda Semántica: Búsqueda de código impulsada por IA con embeddings de Voyage AI
📊 Inteligencia de Código Rica: Resolución de símbolos, inferencia de tipos, seguimiento de dependencias
🚀 Rendimiento Mejorado: Consultas en menos de 100 ms con protección de tiempo de espera y bypass de BM25
🔄 Sincronización de Git: Actualizaciones automáticas del índice que rastrean cambios del repositorio
📦 Gestión de Índice Portátil: Compartición de índices sin costo mediante GitHub Artifacts
🔄 Sincronización Automática de Índices: Extrae índices al clonar, envía al hacer cambios
🎯 Reordenamiento Inteligente de Resultados: Reordenamiento multi-estrategia para relevancia mejorada
🎯 Enrutamiento de Intención de Consulta: 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 en menos de 5 ms
🔒 Exportación Consciente de Seguridad: Filtrado automático de archivos sensibles de í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: Los patrones .gitignore y .mcp-index-ignore se aplican solo durante la exportación
🌐 Indexación Multi-Lenguaje: Indexa repositorios completos con lenguajes mixtos

🏗️ Arquitectura

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

Capas del Sistema

🌐 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
- SLA de rendimiento: <100 ms búsqueda de símbolos, <500 ms búsqueda

📦 Arquitectura de Contenedores (Nivel 2)

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

🔧 Detalles de Componentes (Nivel 3)
- Controlador de Puerta de Enlace: Endpoints de API RESTful
- Núcleo de Despacho: Enrutamiento de plugins y ciclo de vida
- Base de Plugins: Interfaz estándar para todos los plugins
- Plugins de Lenguaje: Analizadores y parsers especializados
- Gestor de Índices: SQLite con FTS5 para búsquedas rápidas
- Servicio de Vigilancia: Monitoreo de archivos en tiempo real

🔐 Seguridad

Code-Index-MCP implementa endurecimiento de seguridad en profundidad (Fase 15):

Aislamiento de Plugins: Los plugins se ejecutan en procesos de trabajo aislados con restricciones basadas en capacidades. Ver docs/security/sandbox.md.
Atestación de Artefactos: Los índices publicados están firmados con atestaciones SLSA de GitHub y verificados en la descarga. Ver docs/security/attestation.md.
Protección contra Traversal de Rutas: Los resultados de búsqueda se validan para evitar escapar de las raíces de repositorio configuradas. Ver docs/security/path-guard.md.
Validación de Tokens: Los tokens de GitHub se validan para los alcances requeridos al inicio (contents:read, metadata:read, actions:read, actions:write, attestations:write). Ver docs/security/token-scopes.md.
Autenticación de Métricas: El endpoint /metrics requiere autenticación de token portador.

MCP_CLIENT_SECRET es solo un guardián de protocolo de enlace STDIO local. No es la autenticación de token portador admin/debug de la puerta de enlace, y no se implementa autorización MCP remota mientras el repositorio continúa difiriendo el transporte MCP remoto.

Para un runbook de operador completo, ver docs/operations/user-action-runbook.md.

📁 Estructura del Proyecto

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

Directorios clave:

mcp_server/ - Implementación del servidor MCP principal
scripts/ - Scripts de desarrollo y utilidades
tests/ - Suite de pruebas completa con fixtures
docs/ - Documentación y guías
architecture/ - Diseño del sistema y diagramas
docker/ - Configuraciones de Docker y archivos compose
mcp-index-kit/ - Kit de herramientas de indexación MCP compartido y ejemplos
docs/status/ - Notas de evidencia duraderas bajo control de versiones

🛠️ Soporte de Lenguajes

El contrato de soporte de superficie estable actual está centralizado en docs/SUPPORT_MATRIX.md. Distingue plugins especializados, cobertura genérica del registro Tree-sitter, soporte de sandbox por defecto, extras opcionales, configuración semántica/reordenamiento, y limitaciones alfa conocidas. No asumas que cada lenguaje del registro tiene la misma calidad de símbolos o comportamiento de sandbox por defecto.

🚀 Inicio Rápido

Las rutas de instalación soportadas son la imagen de contenedor publicada ghcr.io/consiliency/code-index-mcp:v1.4.0 (o :latest), Python/STDIO nativo con uv sync --locked, y una rueda index-it-mcp construida localmente. La imagen ghcr.io/consiliency/code-index-mcp:local-smoke sigue siendo una ruta de desarrollo opcional construida desde este checkout con make release-smoke-container. La cobertura de lenguajes está limitada por docs/SUPPORT_MATRIX.md, la propiedad de evidencia de endurecimiento GA está congelada en docs/validation/ga-readiness-checklist.md, y los procedimientos de reversión viven en docs/operations/deployment-runbook.md. No trates esta superficie estable publicada como una afirmación universal de soporte de lenguajes; los niveles de soporte por fila aún viven en la matriz de soporte.

🎯 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 apropiada.

🐳 Configuración con Docker

Extrae la imagen v1.4.0 publicada de GHCR. El instalador usa por defecto esta imagen publicada; la etiqueta local-smoke sigue siendo una imagen de desarrollo opcional que puedes construir desde este checkout con make release-smoke-container.

Opción 1: Búsqueda Básica (Sin Claves de API) - 2 Minutos

# Index your current directory with the published image
docker run -it -v $(pwd):/workspace ghcr.io/consiliency/code-index-mcp:v1.4.0

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 enabled explicitly
docker run -it -v $(pwd):/workspace -e SEMANTIC_SEARCH_ENABLED=true -e VOYAGE_API_KEY ghcr.io/consiliency/code-index-mcp:v1.4.0

💻 Configuración Específica por Entorno

🪟 Windows (Nativo)

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

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

🍎 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
uv sync --locked

📦 Contenedores Anidados (Contenedores de Desarrollo)

# 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

Respaldo de Longitud de Ruta en Windows

Las rutas de repositorio rastreadas se mantienen en o por debajo del límite de 160 caracteres de ruta rastreada, y la auditoría REPOCLEAN también verifica la profundidad de rutas del contenido de la rueda para miembros site-packages instalados. Si un checkout de Windows aún encuentra un caso límite de longitud de ruta debido a una ubicación de clon profundamente anidada o herramientas de terceros, usa git config --global core.longpaths true como respaldo en lugar de como mitigación principal.

📋 Ejemplos de Configuración MCP.json

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

Python Nativo (Contenedor de Desarrollo/Local)

{
  "mcpServers": {
    "code-index-native": {
      "command": "python",
      "args": ["-m", "mcp_server.cli.stdio_runner"],
      "cwd": "${workspace}"
    }
  }
}

Docker (Windows/Mac/Linux)

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

Prueba de Humo de Lanzamiento

make release-smoke
make release-smoke-container

Uso con Muchos Repositorios

Indexa muchos repositorios no relacionados desde una sola instancia de servidor en ejecución. Requisitos previos: establece MCP_ALLOWED_ROOTS como una lista de rutas de directorio absolutas separadas por el separador de rutas del sistema operativo (: en Unix, ; en Windows) que el servidor puede indexar antes de iniciarlo:

export MCP_ALLOWED_ROOTS=/abs/a:/abs/b

Inicia el servidor (con secretos mediante op run o mcp-index stdio simple):

op run --env-file=.mcp.env -- mcp-index stdio

Registra cada repositorio: registra un worktree por directorio común de git. El repo_id estable proviene del git rev-parse --git-common-dir de Nivel 1, por lo que los worktrees hermanos del mismo repositorio comparten identidad y no se indexan de forma independiente en v3:

mcp-index repository register /abs/a
mcp-index repository register /abs/b

Limita las consultas por repositorio: pasa repository=<name> (nombre registrado o ruta) a search_code / symbol_lookup:

search_code(query="def parse", repository="my-repo")
symbol_lookup(symbol="Parser", repository="my-repo")

Cliente Python (API local beta): para scripts y aplicaciones locales en la misma máquina que el repositorio registrado, usa mcp_server.client en lugar de iniciar STDIO o llamar a FastAPI. Las herramientas MCP siguen siendo la superficie LLM preferida.

from mcp_server.client import open_client
from mcp_server.client_types import ClientSearchOptions

with open_client(workspace_root="/path/to/repo") as client:
    result = client.search_code(
        ClientSearchOptions(
            query="TODO",
            source_type="friction",
            friction_categories=("todo",),
            include_source_metadata=True,
        )
    )
    if result.index_unavailable:
        print(result.index_unavailable.safe_fallback)
    else:
        print(result.results[0].file)

La superficie del cliente Python compatible es solo local: search_code, symbol_lookup, reindex y get_status comparten el mismo servicio consciente de disponibilidad que la herramienta MCP search_code. Es una API programática local, no un cliente de servicio remoto.

Los metadatos de patrones de fricción están disponibles como filtro aditivo en search_code. Usa source_type="friction" con friction_categories=["todo", "fixme", "hack", "workaround", "wish", "extraction_hint"] opcional. Establece include_source_metadata=true para adjuntar el sobre search_source_metadata.v1 almacenado a los resultados devueltos. Las llamadas léxicas ordinarias sin filtro mantienen la forma de resultado heredada; las categorías de fricción no válidas devuelven un error de validación solo de metadatos en lugar de un resultado vacío silencioso.

El contexto histórico de issues de GitHub usa el mismo sobre de metadatos y la misma superficie de búsqueda. Ejecuta mcp-index history ingest --repo owner/repo para ingerir documentos de issues solo de metadatos, luego fíltralos con source_type="history" más history_labels=["reflection"] o history_repos=["owner/repo"] opcionales. El contrato HISTORY está respaldado por fixtures en las pruebas, no requiere credenciales de GitHub en vivo y no persiste los cuerpos de issues sin procesar de forma predeterminada.

Seguimiento de índice: la rama rastreada/predeterminada de cada repositorio es seguida por MultiRepositoryWatcher (RefPoller cada 30 s). Los múltiples worktrees del mismo repositorio y las consultas de ramas no predeterminadas no son compatibles con el enrutamiento v3: devuelven index_unavailable con safe_fallback: "native_search" y remediación de disponibilidad en lugar de reutilizar el índice de otro checkout. Verifica get_status o mcp-index repository list -v y confía en los resultados MCP indexados solo cuando la disponibilidad sea ready.

Zona de pruebas de rutas: las herramientas search_code, symbol_lookup, summarize_sample y reindex rechazan rutas fuera de MCP_ALLOWED_ROOTS con el código de error path_outside_allowed_roots. Los nombres de repositorios registrados omiten la verificación.

Opciones:

Establece MCP_AUTO_INDEX=false en el entorno del servidor para omitir la autoindexación en segundo plano y llama manualmente a la herramienta MCP reindex (recomendado para repositorios muy grandes).
Agrega {"enabled": false} a .mcp-index.json en el repositorio de destino para deshabilitar la indexación de ese repositorio por completo.
Después de un reindexado completo 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 en cada repositorio. Para sobrescribir con un archivo de perfil personalizado, establece MCP_PROFILES_PATH=/abs/path/to/your-profiles.yaml en el entorno del servidor. Para sobrescribir URL 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).

⚡ Habilita la Búsqueda Semántica

La búsqueda por palabras clave BM25 funciona con configuración cero. Para agregar búsqueda vectorial (semántica), elige una opción:

Opción A — Voyage AI (recomendada):

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, sin necesidad de 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

Ambos perfiles y sus nombres de colección están definidos en code-index-mcp.profiles.yaml y se pueden personalizar.

code-index-mcp.profiles.yaml es un nombre de archivo de perfil incluido en el repositorio, no un objetivo de instalación de pip.

Costos y Funciones Opcionales

El paquete de contenedor documentado es ghcr.io/consiliency/code-index-mcp. La búsqueda de código BM25 funciona sin credenciales de proveedor. La búsqueda semántica, el reordenamiento, la sincronización de artefactos y la supervisión dependen de extras, variables de entorno y configuración de servicios. Consulta docs/SUPPORT_MATRIX.md para obtener detalles de compatibilidad de lenguajes/entornos de ejecución.

🚀 Inicio Rápido (Python)

Requisitos Previos

Python 3.12+
Git

Instalación

Opción 1: Usa la instalación desde el código fuente del repositorio (Recomendada)

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

# Install locked project dependencies
uv sync --locked

# Verify the canonical CLI entrypoint
uv run mcp-index --version

Opción 2: Compila la rueda local

# From the repo root
uv run --extra dev python -m build --wheel
python -m pip install dist/index_it_mcp-1.4.0-py3-none-any.whl
index-it-mcp --version

El nombre de distribución canónico de Python sigue siendo index-it-mcp, pero el PyPI en vivo actualmente no tiene un artefacto publicado para la superficie 1.4.0 preparada de este repositorio. Usa la rueda local o la instalación desde el código fuente anterior hasta que una fase posterior de evidencia de lanzamiento vuelva a demostrar la paridad del paquete en vivo.

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 MCP STDIO runner (primary surface used by LLMs via .mcp.json)
mcp-index stdio

# Or start the FastAPI admin REST gateway (secondary, for diagnostics only;
# this is not the repo's MCP Streamable HTTP transport)
mcp-index serve
mcp-index serve --port 9123   # alternate port

Desde un LLM (Claude Code, Cursor, …) registra el ejecutor STDIO en .mcp.json e invoca el indexador como llamadas a herramientas MCP. Las dos herramientas principales son search_code (búsqueda de patrones / palabras clave / semántica, <500 ms) y symbol_lookup (búsqueda exacta de clase/función, <100 ms). Llama a get_status para confirmar que la disponibilidad del repositorio es ready, o maneja una respuesta de consulta con code: "index_unavailable" y safe_fallback: "native_search" usando la búsqueda nativa mientras sigues la remediación devuelta, como reindex:

{
  "tool": "search_code",
  "arguments": {
    "query": "def parse",
    "limit": 20,
    "semantic": false
  }
}

{
  "tool": "symbol_lookup",
  "arguments": {
    "symbol": "parse_file"
  }
}

Ambas herramientas aceptan un argumento "repository" opcional (nombre de repositorio registrado o una ruta absoluta dentro de MCP_ALLOWED_ROOTS) para el alcance de múltiples repositorios. Consulta la sección "Uso con Muchos Repositorios" anterior. Un índice listo sin coincidencias devuelve cargas útiles ordinarias sin coincidencias (results: [] para search_code o result: "not_found" para symbol_lookup) con metadatos de disponibilidad; los índices no disponibles devuelven index_unavailable en su lugar.

La superficie STDIO tools/list es determinista y ahora anuncia metadatos MCP más ricos para cada herramienta pública: valores title estables, contratos de entrada JSON Schema explícitos (required, valores predeterminados y postura additionalProperties), anotaciones para comportamiento de solo lectura frente a mutación, y borradores outputSchema propiedad de la implementación. La superficie STDIO tools/call ahora devuelve objetos CallToolResult nativos del SDK con structuredContent con forma de objeto, contenido de respaldo de texto JSON conservado en content para clientes más antiguos, y isError en ramas de rechazo y error. Las cargas útiles heredadas similares a arreglos, como los resultados de búsqueda léxica simple, se envuelven bajo structuredContent.results, mientras que las fallas de disponibilidad aún llevan index_unavailable con safe_fallback: "native_search" donde ese contrato ya se aplicaba.

reindex y write_summaries también admiten ejecución aumentada por tareas a través de la superficie de tareas MCP nativa del SDK. Ambas herramientas anuncian execution.taskSupport = "optional", por lo que los clientes pueden mantener la ruta síncrona actual o incluir un objeto task en tools/call y luego usar tasks/get, tasks/list, tasks/result y tasks/cancel para progreso, recuperación de carga útil terminal y cancelación de mejor esfuerzo. Los rechazos de disponibilidad, las fallas de la zona de pruebas de rutas, los errores de alcance en conflicto y las verificaciones previas de resumidor no disponible aún fallan de forma síncrona antes de que se cree cualquier tarea.

La postura actual verificada del cliente MCP se resume en la matriz de compatibilidad MCP. La prueba de humo directa propiedad de la fase es el SDK oficial de Python sobre STDIO; Claude Code y otros lanzadores STDIO están documentados contra ese mismo contrato de servidor, mientras que el MCP remoto Streamable HTTP sigue diferido.

🔧 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-mode Qdrant: QDRANT_URL, plus QDRANT_API_KEY when the server sets
# QDRANT__SERVICE__API_KEY (leave unset for an unauthenticated server)
# QDRANT_URL=http://localhost:6333
# QDRANT_API_KEY=your_qdrant_api_key

# 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 incluyen 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 Qdrant separadas dentro del artefacto para que los consumidores puedan extraer una línea base y usar cualquiera de los perfiles 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 incrustación 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 de 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 compilarlos/publicarlos; los artefactos de GitHub distribuyen la línea base de ejecución real que MCP restaura localmente.

Gestión del Espacio de Trabajo Local

# Inspect all registered repositories and their readiness
mcp-index repository list -v

# Check all registered repos 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

MRREADY congela la interpretación orientada al lanzamiento de esos comandos:

mcp-index repository list -v, mcp-index repository status y mcp-index artifact workspace-status ahora muestran un estado de lanzamiento por repositorio: ready, local_only, publish_failed, wrong_branch, stale_commit, missing_index o partial_index_failure.
Las herramientas de consulta siguen siendo una superficie separada de cierre ante fallas. Si la disponibilidad no es ready, la búsqueda MCP devuelve index_unavailable con safe_fallback: "native_search" en lugar de tratar una fila de estado como un éxito de consulta.
El veredicto actual de múltiples repositorios sigue siendo controlled rollout only mientras las superficies de múltiples repositorios y STDIO aún están en beta.

🔐 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/*"
    ]
  }
}

Funciones de Privacidad:

Los índices se filtran automáticamente por .gitignore
Patrones adicionales mediante .mcp-index-ignore
Los registros de auditoría muestran lo que se excluyó
La sincronización está deshabilitada de forma predeterminada en la versión mínima de Docker

🆕 Funciones Avanzadas

Reordenamiento de Resultados de Búsqueda

Hay tres reordenadores disponibles, configurados mediante la variable de entorno RERANKER_TYPE:

Valor	Reordenador	Notas
`flashrank`	FlashRank	OSS, local, rápido (~1–5 ms de sobrecarga)
`cross-encoder`	Cross-Encoder	OSS, local, mayor calidad
`voyage`	Voyage Reranker	API en la nube, requiere `VOYAGE_API_KEY`
`none`	Deshabilitado	Predeterminado

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

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

Resumen de Fragmentos LLM

Los fragmentos semánticos se pueden aumentar con resúmenes generados por LLM antes de la incrustación, mejorando la recuperación de consultas basadas en 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 LLM en la nube. Las instrucciones ocultas en comentarios pueden ser ejecutadas por el resumidor. Consulta la sección Notas de Seguridad.

Implementación: mcp_server/indexing/summarization.py

Intercambio de Índices con Conciencia de Seguridad

Evita el intercambio accidental de archivos sensibles:

# Analyze current index for security issues
python scripts/utilities/analyze_gitignore_security.py

# Create secure index export (filters gitignored files)
python scripts/utilities/secure_index_export.py

# The secure export will:
# - Exclude all gitignored files
# - Remove sensitive patterns (*.env, *.key, etc.)
# - Create audit logs of excluded files

Búsqueda Híbrida BM25

Combina la búsqueda de texto completo tradicional con la búsqueda semántica:

# The system automatically uses hybrid search when available
# Configure weights in settings:
HYBRID_SEARCH_BM25_WEIGHT=0.3
HYBRID_SEARCH_SEMANTIC_WEIGHT=0.5
HYBRID_SEARCH_FUZZY_WEIGHT=0.2

🔧 Configuración del Despachador

Despachador Mejorado (Predeterminado)

El despachador mejorado incluye protección de tiempo de espera y respaldo automático:

from mcp_server.dispatcher.dispatcher_enhanced import EnhancedDispatcher
from mcp_server.storage.sqlite_store import SQLiteStore

store = SQLiteStore(".indexes/YOUR_REPO_ID/current.db")
dispatcher = EnhancedDispatcher(
    sqlite_store=store,
    semantic_search_enabled=True,  # Enable if Qdrant available
    lazy_load=True,               # Load plugins on-demand
    use_plugin_factory=True       # Use dynamic plugin loading
)

# Search with automatic optimization
results = list(dispatcher.search("your query", limit=10))

Despachador Simple (Alternativa Ligera)

Para máximo rendimiento con búsqueda solo BM25:

from mcp_server.dispatcher.simple_dispatcher import create_simple_dispatcher

# Ultra-fast BM25 search without plugin overhead
dispatcher = create_simple_dispatcher(".indexes/YOUR_REPO_ID/current.db")
results = list(dispatcher.search("your query", limit=10))

Opciones de Configuración

Configura el comportamiento del despachador mediante variables de entorno:

# Dispatcher settings
MCP_DISPATCHER_TIMEOUT=5          # Plugin loading timeout (seconds)
MCP_USE_SIMPLE_DISPATCHER=false   # Use simple dispatcher
MCP_PLUGIN_LAZY_LOAD=true        # Load plugins on-demand

# Performance tuning
MCP_BM25_BYPASS_ENABLED=true     # Enable direct BM25 bypass
MCP_MAX_PLUGIN_MEMORY=1024       # Max memory for plugins (MB)

# Auto-indexing (cross-repo use)
MCP_AUTO_INDEX=true               # Set false to skip background auto-index on first run
MCP_AUTO_INDEX_MAX_FILES=100000   # Skip auto-index if repo exceeds this file count
MCP_PROFILES_PATH=                # Absolute path to a custom profiles YAML (overrides built-in)

# Endpoint overrides (no need to edit profiles.yaml)
VLLM_EMBEDDING_BASE_URL=          # Override vLLM embedding endpoint (default: http://ai:8001/v1)
VLLM_SUMMARIZATION_BASE_URL=      # Override summarization endpoint (default: http://win:8002/v1)

🗂️ Gestión de Índices

Almacenamiento Centralizado de Índices

Todos los índices ahora se almacenan centralmente en .indexes/ (relativo al proyecto MCP) para una mejor organización y para evitar confirmaciones accidentales:

.indexes/
├── {repo_hash}/              # Unique hash for each repository
│   ├── main_abc123.db        # Index for main branch at commit abc123
│   ├── main_abc123.metadata.json
│   └── current.db -> main_abc123.db  # Symlink to active index
├── qdrant/                   # Semantic search embeddings
│   └── main.qdrant/          # Centralized Qdrant database

Beneficios:

Los índices nunca se confirman accidentalmente en git
Reutilizables en múltiples clones del mismo repositorio
Separación clara entre código e índices
Descubrimiento automático basado en el remoto de git Migración: Para repositorios existentes con índices locales:

python scripts/move_indexes_to_central.py

Para Este Repositorio

Este proyecto utiliza GitHub Actions Artifacts para compartir índices de manera eficiente, por lo que la mayoría de los usuarios comienzan desde una línea base de índice publicada en lugar de reconstruir localmente.

# First time setup - pull latest indexes
mcp-index artifact pull --latest

# After pull, reconcile only your branch/worktree drift
mcp-index artifact sync

# Share your indexes with the team
mcp-index artifact push

# Check sync status
mcp-index artifact sync

# Optional: Install git hooks for automatic sync
mcp-index hooks install
# Now indexes upload automatically on git push
# and download automatically on git pull

Para CUALQUIER Repositorio (MCP Index Kit)

Habilita la gestión de índices portátil en cualquier repositorio con cero costos de cómputo de GitHub:

Instalación Rápida

npm install -g mcp-index-kit
mcp-index init

Cómo Funciona

Arquitectura de Cero Costos:
- Todo el indexado ocurre en las máquinas de los desarrolladores
- Los índices se almacenan como GitHub Artifacts (gratis para repositorios públicos)
- Descarga automática al clonar, carga automática al hacer push
- No se requiere cómputo de GitHub Actions
Diseño Portátil:
- Configuración con un solo comando para cualquier repositorio
- Auto-detectado por servidores MCP y herramientas
- El comportamiento de lenguaje/tiempo de ejecución sigue los niveles de soporte explícitos en docs/SUPPORT_MATRIX.md
- Habilitar/deshabilitar por repositorio

Uso:

# Initialize in your repo
cd your-repo
mcp-index init

# Build index locally
mcp-index build

# Push to GitHub Artifacts
mcp-index push

# Pull latest index
mcp-index pull

# Auto sync
mcp-index sync

Configuración

Configuración de Búsqueda Semántica

Para habilitar capacidades de búsqueda semántica, necesitas una clave API de Voyage AI. Obtén una en https://www.voyageai.com/.

Método 1: Configuración de Claude Code (Recomendado)

Crea o edita .mcp.json en la raíz de tu proyecto:

{
  "mcpServers": {
    "code-index-mcp": {
      "command": "mcp-index",
      "args": ["stdio"],
      "env": {
        "VOYAGE_API_KEY": "your-voyage-ai-api-key-here",
        "SEMANTIC_SEARCH_ENABLED": "true"
      }
    }
  }
}

La etiqueta de servidor code-index-mcp en estos ejemplos es un ID de servidor MCP local del cliente, no el nombre de distribución de Python.

Método 2: CLI de Claude Code

claude mcp add code-index-mcp -e VOYAGE_API_KEY=your_key -e SEMANTIC_SEARCH_ENABLED=true -- mcp-index stdio

Método 3: Variables de Entorno

export VOYAGE_API_KEY=your_key
export SEMANTIC_SEARCH_ENABLED=true

Método 4: Archivo .env

Crea un archivo .env en la raíz de tu proyecto:

VOYAGE_API_KEY=your_key
SEMANTIC_SEARCH_ENABLED=true

Verificar Configuración

Verifica tu configuración de búsqueda semántica:

mcp-index index check-semantic

Configuración de Índice

Edita .mcp-index.json en tu repositorio:

{
  "enabled": true,
  "auto_download": true,
  "artifact_retention_days": 30,
  "github_artifacts": {
    "enabled": true,
    "max_size_mb": 100
  }
}

Consulta mcp-index-kit para documentación completa

Ver detalles del artefacto

mcp-index artifact info 12345


#### Index Management
```bash
# Check index status
mcp-index index status

# Check compatibility
mcp-index index check-compatibility

# Rebuild indexes locally only if artifact sync cannot catch up
mcp-index index rebuild

# Create backup
mcp-index index backup my_backup

# Restore from backup
mcp-index index restore my_backup

Integración con GitHub Actions

Pull Requests: Valida índices proporcionados por desarrolladores (sin reconstrucción)
Fusiones a Main: Promueve índices validados a artefactos
Eficiente en Costos: Usa almacenamiento gratuito de GitHub Actions Artifacts
Limpieza Automática: Los artefactos antiguos se limpian después de 30 días

Almacenamiento y Costos

GitHub Actions Artifacts: GRATIS para repositorios públicos, incluido en las cuotas de repositorios privados
Retención: 7 días para artefactos de PR, 30 días para la rama principal
Límites de Tamaño: 500MB por artefacto (comprimido)
Compresión Automática: ~70% de reducción de tamaño con tar.gz

Flujo de Trabajo del Desarrollador

Clonar Repositorio

git clone https://github.com/yourusername/Code-Index-MCP.git
cd Code-Index-MCP

Obtener Índices Más Recientes
```
 gh auth login
 mcp-index artifact pull --latest
```
- Esto descarga la instantánea completa del artefacto de GitHub actual.
- mcp-index artifact sync luego reconcilia solo la desviación de tu rama/área de trabajo local cuando la actualización incremental es apropiada.
Haz Tus Cambios
- Edita el código como de costumbre
- Los índices se actualizan automáticamente mediante el observador de archivos

Compartir Actualizaciones

# Your indexes are already updated locally
 mcp-index artifact push

Compatibilidad del Modelo de Embeddings

El sistema rastrea las versiones de los modelos de embeddings para garantizar la compatibilidad:

commercial_high: voyage-code-3 — 2048 dimensiones, producto punto, float32
oss_high: Qwen/Qwen3-Embedding-8B — 4096 dimensiones, producto punto, l2-normalizado
Auto-detección: El sistema verifica la compatibilidad del perfil antes de la descarga

La configuración semántica de múltiples perfiles se puede proporcionar en:

SEMANTIC_PROFILES_JSON (variable de entorno), o
code-index-mcp.profiles.yaml (raíz del repositorio).

Estrategia de Artefactos

Las descargas de artefactos de GitHub son instantáneas completas, no recuperaciones parciales de parches remotos.
El artefacto comprimido actual es lo suficientemente modesto como para que las descargas completas sigan siendo más simples que un protocolo de delta remoto.
La eficiencia proviene del indexado incremental local después de la restauración:
- descargar el último artefacto completo
- comparar el commit del artefacto restaurado con el HEAD local
- dejar que el observador o el reindexado incremental local reconcilien archivos añadidos, modificados, eliminados y renombrados
Los artefactos remotos específicos de rama son opcionales. La estrategia predeterminada es usar el último artefacto main como base y reconciliar la desviación de la rama localmente.

Configuración Semántica Fácil (Docker-Primero)

Ejecuta la incorporación con inicio automático de Qdrant local:

mcp-index setup semantic

Precedencia de configuración (de mayor a menor):

Banderas de CLI (para una ejecución de comando)
Variables de entorno / .env
code-index-mcp.profiles.yaml
SEMANTIC_PROFILES_JSON
Valores predeterminados integrados

Controles comunes:

# Preflight checks only
mcp-index setup semantic --dry-run

# Strict mode: fail command if semantic stack isn't ready
mcp-index setup semantic --strict

# Override local embedding endpoint
mcp-index setup semantic --openai-api-base http://127.0.0.1:8001/v1

La carga de plugins se auto-optimiza por defecto utilizando detección rápida de lenguaje del repositorio:

MCP_AUTO_DETECT_LANGUAGES=true
MCP_LANGUAGE_DETECT_MAX_FILES=5000
MCP_LANGUAGE_DETECT_MIN_FILES=2

Para entornos sensibles al inicio, habilita:

MCP_FAST_STARTUP=true (utiliza carga diferida de plugins y omite el inicio del observador de archivos)

Cuando MCP_AUTO_DETECT_LANGUAGES=true, la auto-detección tiene prioridad sobre plugins.yaml. Establece MCP_AUTO_DETECT_LANGUAGES=false para forzar la selección de lenguaje plugins.yaml.

Para una configuración de doble perfil (Voyage + vLLM/Qwen local), establece:

VOYAGE_API_KEY
OPENAI_API_BASE (por ejemplo http://127.0.0.1:8000/v1)
OPENAI_API_KEY (marcador de posición aceptado para configuraciones vLLM locales)

Si usas un modelo de embeddings diferente, el sistema detectará la incompatibilidad y reconstruirá localmente con tu configuración.

💻 Desarrollo

Creando un Nuevo Plugin de Lenguaje

Crear la estructura del plugin

mkdir -p mcp_server/plugins/my_language_plugin
cd mcp_server/plugins/my_language_plugin
touch __init__.py plugin.py

Implementar la interfaz del plugin

from mcp_server.plugin_base import PluginBase

class MyLanguagePlugin(PluginBase):
    def __init__(self):
        self.tree_sitter_language = "my_language"
    
    def index(self, file_path: str) -> Dict:
        # Parse and index the file
        pass
    
    def getDefinition(self, symbol: str, context: Dict) -> Dict:
        # Find symbol definition
        pass
    
    def getReferences(self, symbol: str, context: Dict) -> List[Dict]:
        # Find symbol references
        pass

Registrar el plugin

# In dispatcher.py
from .plugins.my_language_plugin import MyLanguagePlugin

self.plugins['my_language'] = MyLanguagePlugin()

Ejecutando Pruebas

# Run all tests
pytest

# Run specific test
pytest test_python_plugin.py

# Measure the current local/offloaded coverage baseline
make coverage-baseline

# Generate the local/offloaded coverage report
make coverage

# Reject tracked or staged generated coverage outputs
make coverage-artifact-guard

El contrato de COBERTURA es local/descargado primero: make coverage emite salida terminal de líneas faltantes más coverage.xml, y make agent-full posee la generación de cobertura rutinaria. La insignia del README permanece diferida hasta que un evento confiable produzca evidencia real cargada.

Visualización de Arquitectura

# View C4 architecture diagrams
docker run --rm -p 8080:8080 \
  -v "$(pwd)/architecture":/usr/local/structurizr \
  structurizr/lite

# Open http://localhost:8080 in your browser

Interfaz REST de Administración (secundaria)

La superficie canónica son las llamadas a herramientas MCP (search_code, symbol_lookup, etc.) a través del ejecutor STDIO — consulta las secciones "Inicio Rápido" anteriores. La puerta de enlace REST FastAPI documentada aquí es una interfaz de administración secundaria para diagnósticos, scripting y clientes que no pueden hablar MCP. Sus endpoints no son la ruta recomendada para flujos de trabajo impulsados por LLM.

Endpoints REST de Administración

`GET /symbol`

Obtener definición de símbolo (superficie de administración/depuración — prefiere la herramienta MCP symbol_lookup):

GET /symbol?symbol_name=parseFile&file_path=/path/to/file.py

Parámetros de consulta:

symbol_name (obligatorio): Nombre del símbolo a encontrar
file_path (opcional): Archivo específico para buscar

`GET /search`

Buscar patrones de código (superficie de administración/depuración — prefiere la herramienta MCP search_code):

GET /search?query=async+def.*parse&file_extensions=.py,.js

Parámetros de consulta:

query (obligatorio): Patrón de búsqueda (regex compatible)
file_extensions (opcional): Lista de extensiones separadas por comas
source_type (opcional): friction o history
friction_categories (opcional): categorías de fricción separadas por comas
history_labels (opcional): etiquetas de problemas de historial separadas por comas
history_repos (opcional): filtros de propietario/repositorio separados por comas para documentos de problemas de historial
include_source_metadata (opcional): incluir registros search_source_metadata.v1 en resultados coincidentes

API de Cliente Python (API local beta)

Usa el cliente Python cuando necesites acceso programático local desde la misma máquina y checkout registrado. Usa herramientas MCP cuando un asistente necesite la superficie de herramientas LLM principal.

from mcp_server.client import open_client
from mcp_server.client_types import ClientSearchOptions

with open_client(workspace_root="/path/to/repo") as client:
    search = client.search_code(ClientSearchOptions(query="Reflection issue"))
    symbol = client.symbol_lookup("IndexItClient")
    status = client.get_status()

La preparación permanece con cierre ante fallos. Los repositorios no preparados devuelven datos index_unavailable tipados con safe_fallback="native_search" en lugar de despachar contra un índice obsoleto. El cliente Python beta intencionalmente no tiene cliente de servicio remoto.

Formato de Respuesta

Todas las respuestas de la API siguen una estructura JSON consistente:

Respuesta de Éxito:

{
  "status": "success",
  "data": { ... },
  "timestamp": "2024-01-01T00:00:00Z"
}

Respuesta de Error:

{
  "status": "error",
  "error": "Error message",
  "code": "ERROR_CODE",
  "timestamp": "2024-01-01T00:00:00Z"
}

🚢 Despliegue

Opciones de Despliegue Docker

El proyecto incluye múltiples configuraciones de Docker para diferentes entornos:

Desarrollo (Predeterminado):

# Uses docker-compose.yml + Dockerfile
docker-compose up -d
# - SQLite database
# - Uvicorn development server  
# - Volume mounts for code changes
# - Debug logging enabled

Producción:

# Uses docker-compose.production.yml + Dockerfile.production
docker-compose -f docker-compose.production.yml up -d
# - PostgreSQL database
# - Gunicorn + Uvicorn workers
# - Multi-stage optimized builds
# - Security hardening (non-root user)
# - Production logging

Desarrollo Mejorado:

# Uses both compose files with development overrides
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up -d
# - Development base + enhanced debugging
# - Source code volume mounting
# - Read-write code access

Comportamiento de Reinicio del Contenedor

Importante: Por defecto, docker-compose restart usa la configuración de DESARROLLO:

docker-compose restart → Usa docker-compose.yml (Desarrollo)
docker-compose -f docker-compose.production.yml restart → Usa Producción

Despliegue en Producción

Para entornos de producción, proporcionamos:

Construcciones Docker de múltiples etapas con endurecimiento de seguridad
Base de datos PostgreSQL con soporte asíncrono
Caché Redis para optimización del rendimiento
Base de datos vectorial Qdrant para búsqueda semántica
Stack de monitoreo Prometheus + Grafana
Manifiestos de Kubernetes en el directorio k8s/
Configuración de proxy inverso nginx

Consulta nuestra Guía de Despliegue para instrucciones detalladas que incluyen:

Configuraciones de despliegue de Kubernetes
Configuración de auto-escalado
Optimización de base de datos
Mejores prácticas de seguridad
Monitoreo y observabilidad

Requisitos del Sistema

Mínimo: 2GB RAM, 2 núcleos de CPU, 10GB de almacenamiento
Recomendado: 8GB RAM, 4 núcleos de CPU, 50GB de almacenamiento SSD
Bases de código grandes: 16GB+ RAM, 8+ núcleos de CPU, 100GB+ de almacenamiento SSD

📦 Lanzamientos e Índices Pre-construidos

Usando Índices Pre-construidos

Para una configuración rápida, descarga índices pre-construidos desde nuestros lanzamientos de GitHub:

# List available releases
python scripts/download-release.py --list

# Download the current pre-built index artifact
python scripts/download-release.py --latest

# Download specific version
python scripts/download-release.py --tag v2024.01.15 --output ./my-index

Creando Lanzamientos

Los mantenedores pueden crear nuevos lanzamientos con índices pre-construidos:

# Prepare or update the release PR from the feature branch
gh workflow run "Release Automation" --ref <release-branch> -f mode=prepare -f version=v1.4.0 -f auto_merge=false

# After that PR merges, publish only from protected main
gh workflow run "Release Automation" --ref main -f mode=publish -f version=v1.4.0 -f auto_merge=false

Sincronización Automática de Índices

El proyecto incluye hooks de Git para la sincronización automática de índices:

Pre-push: Sube cambios de índice a artefactos de GitHub
Post-merge: Descarga índices compatibles después de hacer pull

Instala los hooks con: mcp-index hooks install

🤝 Contribuciones

¡Agradecemos las contribuciones! Consulta nuestra Guía de Contribución para más detalles.

Proceso de Desarrollo

Haz un fork del repositorio
Crea una rama de características (git checkout -b feature/amazing-feature)
Haz tus cambios
Agrega pruebas (apunta a 90%+ de cobertura)
Actualiza la documentación
Envía un pull request

Estilo de Código

Sigue PEP 8 para código Python
Usa sugerencias de tipo para todas las funciones
Escribe docstrings descriptivos
Mantén las funciones pequeñas y enfocadas

📈 Rendimiento

Benchmarks

Operación	Objetivo de Rendimiento	Estado Actual
Búsqueda de Símbolos	<100ms (p95)	✅ Logrado - Todas las consultas < 100ms
Búsqueda de Código	<500ms (p95)	✅ Logrado - Búsqueda BM25 < 50ms
Indexado de Archivos	10K archivos/min	✅ Logrado - 152K archivos indexados

Benchmark de Matriz (2026-04-01)

Métrica	Solo BM25	voyage-code-3	Qwen3-Embedding-8B
Top-1 (sin reranker)	12/17 (70.6%)	17/17 (100%)	17/17 (100%)
Top-1 (flashrank)	13/17 (76.5%)	17/17 (100%)	17/17 (100%)
Top-1 (cross-encoder)	—	17/17 (100%)	17/17 (100%)
Top-1 (voyage-reranker)	—	15/17 (88.2%)	—
Consulta de símbolo BM25 p50	~1–5 ms	—	—
Consulta semántica p50 (híbrida)	—	~50–400 ms	~50–280 ms

Resultados completos: docs/benchmarks/matrix_benchmark.md / .json

🏗️ Resumen de Arquitectura

El sistema sigue patrones de arquitectura del modelo C4:

Definición del Espacio de Trabajo: definido en architecture/workspace.dsl y validado con CLI de Structurizr
Contexto del Sistema (L1): Claude Code se integra a través de sub-agentes MCP contra la superficie primaria STDIO
Nivel de Contenedor (L2): 8 contenedores principales que incluyen servidor MCP mejorado y documentación de usuario
Nivel de Componente (L3): Sistema de plugins, gestión de memoria y coordinación entre repositorios
Nivel de Código (L4): 43 diagramas PlantUML que documentan todos los componentes y flujos del sistema

Para documentación arquitectónica detallada, consulta el directorio architecture/.

🗺️ Hoja de Ruta de Desarrollo

Consulta ROADMAP.md para planes de desarrollo detallados y progreso actual. Estado actual: Superficie de endurecimiento 1.4.0 preparada; la publicación principal protegida aún está pendiente

✅ Indexación principal: SQLite + FTS5 para búsqueda local rápida
✅ Multilenguaje: Cobertura de lenguajes especializada y respaldada por registros; consulte docs/SUPPORT_MATRIX.md
✅ Protocolo MCP: Compatibilidad verificada con el SDK oficial de Python a través de STDIO; consulte docs/status/MCP_COMPATIBILITY_EVALUATION.md para la postura del cliente nombrado
✅ Rendimiento: Consultas en menos de 100 ms con optimización BM25
🔄 Sincronización de índice: Soporte beta mediante GitHub Artifacts
🔄 Búsqueda semántica: Funcionalidad opcional que requiere la API de Voyage AI

Mejoras recientes:

⚡ Optimización del despachador: Protección de tiempo de espera y omisión de BM25 para mayor fiabilidad
🔄 Búsqueda híbrida: BM25 + búsqueda semántica con degradación gradual
📊 Clasificación de resultados: Relevancia mejorada con normalización de puntuaciones
🔧 Herramientas CLI: Comando mcp-index con todas las funciones para la gestión de índices

Consejos de optimización

Las funciones de optimización del rendimiento están implementadas y disponibles:

Habilitar caché: El caché de Redis está implementado y es configurable mediante variables de entorno
Ajustar el tamaño del lote: Configurable mediante la variable de entorno INDEXING_BATCH_SIZE
Usar almacenamiento SSD: Mejora significativamente la velocidad de indexación
Limitar el tamaño de archivo: Configurable mediante la variable de entorno INDEXING_MAX_FILE_SIZE
Procesamiento paralelo: Indexación con múltiples trabajadores configurable mediante INDEXING_MAX_WORKERS

🔒 Seguridad

Local primero: Todo el procesamiento ocurre localmente por defecto
Validación de rutas: Previene ataques de traversal de directorios
Saneamiento de entradas: Todas las consultas se sanean
Detección de secretos: Redacción automática de secretos detectados
Aislamiento de complementos: Los complementos se ejecutan en entornos restringidos
⚠️ Riesgos del resumen semántico: Si habilita resúmenes semánticos generados por LLM (perezosos o completos), tenga en cuenta las vulnerabilidades de inyección de prompts. Actores malintencionados podrían colocar instrucciones ocultas en comentarios de código (por ejemplo, en una dependencia de código abierto) que el LLM resumidor podría ejecutar. Siempre revise los metadatos de índice generados si resume código no confiable.

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT; consulte el archivo LICENSE para más detalles.

🙏 Agradecimientos

Tree-sitter para el análisis de lenguajes
Jedi para el análisis de Python
FastAPI para el marco de la API
Voyage AI para los embeddings
Anthropic para el protocolo MCP

📬 Contacto

Problemas: GitHub Issues
Discusiones: GitHub Discussions

Hecho con ❤️ para la comunidad de desarrolladores