Contexto de Inteligencia MCP

Un servidor MCP de Inteligencia de Repositorio que indexa los archivos, símbolos, importaciones y el grafo de dependencias de un código base, y entrega a Copilot/agentes un paquete de contexto pequeño y enfocado en lugar de hacer que escaneen todo el repositorio.

Por qué

Cuando un agente recibe una pregunta ambigua sobre un repositorio grande, a menudo tiene que listar directorios repetidamente, abrir archivos no relacionados y volver a derivar la estructura antes de encontrar el código relevante — quemando tokens y tiempo. Este proyecto construye un índice persistente y actualizado incrementalmente del repositorio (archivos, símbolos, importaciones, dependencias inversas) y expone herramientas MCP que devuelven solo el contexto relevante para una consulta, con un presupuesto aproximado de tokens.

Related MCP server: lens

Cómo funciona

1. index_repository recorre el repositorio (respetando .gitignore), analiza archivos Python (mediante ast) y JS/TS (mediante heurísticas ligeras de regex) en busca de funciones/clases/métodos/importaciones/exportaciones, y construye un grafo de dependencias inversas. El índice se almacena en caché en .mcp_intel_cache/index.json y se actualiza incrementalmente (solo se vuelven a analizar los archivos modificados, según mtime/tamaño).

2. search_code / get_relevant_context clasifican archivos por nombre de símbolo, nombre de archivo, docstring/resumen y coincidencias de importación (búsqueda léxica/de símbolos — sin embeddings en este MVP) y devuelven un paquete de contexto con presupuesto de tokens: tablas de símbolos + pequeños extractos de código, no archivos completos. get_relevant_context también informa una comparación de token_savings frente a una línea base ingenua de escaneo completo del repositorio, para que los ahorros sean visibles en la propia respuesta de la herramienta.

3. get_file_summary / get_dependencies permiten a un agente profundizar en los símbolos de un archivo específico o en el radio de impacto (importadores/importaciones) sin leer el archivo completo.

4. Las herramientas informan una advertencia de obsolescencia si el índice en caché tiene más de 5 minutos y no hay un observador en vivo activo. En la práctica, la primera llamada a una herramienta para un repositorio inicia un observador de archivos en segundo plano (mediante watchdog) que aplica eventos de creación/modificación/eliminación al índice en memoria inmediatamente, por lo que el índice se mantiene continuamente actualizado a medida que el código cambia — sin necesidad de reindexar manualmente durante una sesión. La caché en disco se vacía con un debounce (~2s) para que los guardados rápidos no provoquen una escritura por pulsación de tecla.

Estructura del repositorio

src/mcp_intelligence_context/   Python MCP server package
  walker.py                     gitignore-aware file walker
  parsers/                      Python (ast) and JS/TS (regex) symbol extraction
  indexer.py                    builds/caches the RepoIndex, resolves imports
  watcher.py                    background file watcher that keeps the index live
  search.py                     lexical/symbol search + reverse-dep lookups
  context_builder.py            token-budgeted context package assembly
  server.py                     MCP tool definitions (stdio server)
vscode-extension/                VS Code extension wrapper (setup/reindex/status commands)
scripts/                         one-command bootstrap for new users

Inicio rápido (Nuevos usuarios)

Si eres nuevo en MCP y solo quieres que esto funcione rápidamente en VS Code:

git clone https://github.com/LeoChimal09/MCP-INTELLIGENCE-CONTEXT.git
cd MCP-INTELLIGENCE-CONTEXT
bash scripts/setup_mcp_workspace.sh

Lo que hace este script:

1. Instala (o actualiza) mcp-intelligence-context con pipx.

2. Escribe .vscode/mcp.json para este espacio de trabajo.

3. Restringe la indexación a la carpeta del espacio de trabajo actual estableciendo MCP_INTEL_ALLOWED_ROOTS=${workspaceFolder}.

Luego en VS Code:

1. Paleta de comandos -> MCP: List Servers.

2. Inicia/Reinicia mcp-intelligence-context.

3. En el selector de herramientas de Copilot Chat, habilita mcp-intelligence-context.

Si el script dice que falta pipx, instálalo una vez:

brew install pipx
pipx ensurepath

Ejecutar el servidor MCP de forma independiente

python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/mcp-intelligence-context        # or: python -m mcp_intelligence_context.server

Apunta el repositorio a indexar estableciendo MCP_INTEL_REPO_ROOT, o pasa repo_root explícitamente a cualquier llamada de herramienta (por defecto, el directorio de trabajo actual del servidor).

Instalación sin clonar este repositorio

Otros usuarios no necesitan una copia local — instala directamente desde el repositorio git (o desde PyPI, una vez publicado allí):

python3 -m venv .venv
.venv/bin/pip install "git+https://github.com/LeoChimal09/MCP-INTELLIGENCE-CONTEXT.git"
# once published: .venv/bin/pip install mcp-intelligence-context

El script de consola mcp-intelligence-context y la variable de entorno MCP_INTEL_REPO_ROOT funcionan exactamente igual en ambos casos — solo difiere la fuente de pip install.

Registrar con un cliente MCP (por ejemplo, VS Code)

Añade a .vscode/mcp.json en el espacio de trabajo de destino:

{
  "servers": {
    "mcp-intelligence-context": {
      "type": "stdio",
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["-m", "mcp_intelligence_context.server"],
      "env": { "MCP_INTEL_REPO_ROOT": "${workspaceFolder}" }
    }
  }
}

Extensión de VS Code

vscode-extension/ incluye un envoltorio ligero con tres comandos:

• MCP Intelligence: Setup Server — crea un venv e instala el paquete de Python, luego escribe la entrada .vscode/mcp.json anterior.

• MCP Intelligence: Reindex Repository — fuerza una reindexación del espacio de trabajo abierto.

• MCP Intelligence: Show Status — imprime el recuento de archivos del índice en caché, el commit de git y la antigüedad.

Por defecto, "Setup Server" instala el paquete desde el repositorio git de este proyecto en un venv bajo el almacenamiento privado de la extensión — sin necesidad de clon local. Dos ajustes controlan esto:

• mcpIntelligenceContext.serverPath — apunta a una copia editable local (utilizada para el desarrollo en este monorepo); déjalo vacío en caso contrario.

• mcpIntelligenceContext.pythonPackageSource — anula el destino de instalación de pip (por ejemplo, un nombre de paquete de PyPI) cuando serverPath está vacío.

Para compilarlo:

cd vscode-extension
npm install
npm run compile

Luego presiona F5 en VS Code (con vscode-extension/ abierto) para lanzar un Host de Desarrollo de Extensiones.

Herramientas MCP disponibles

Evaluar si esto realmente ayuda

eval/ contiene un benchmark pequeño y honesto contra el propio código de este repositorio (sin llamadas a LLM, sin números inventados): 10 consultas escritas a mano con archivos de verdad conocida, comparando nuestra herramienta indexada contra una línea base ingenua (listar el árbol, grep, leer archivos completos coincidentes).

.venv/bin/python eval/run_eval.py

Informa hit@1/hit@3 (¿apunta el resultado principal al archivo correcto?), reducción promedio de tokens y latencia. Esto solo mide la mecánica de recuperación/tokens — no mide si una respuesta real de Copilot es realmente mejor, ya que eso requiere llamadas a modelos en vivo.

Limitaciones actuales (MVP)

• El análisis JS/TS se basa en regex (no en un AST completo), por lo que una sintaxis inusual puede pasarse por alto. El análisis de Python utiliza el módulo estándar ast y es exacto.

• La búsqueda es solo léxica/de símbolos (con filtrado de palabras vacías y puntuación acumulada de múltiples señales); aún no hay embeddings/búsqueda semántica.

• El observador de archivos aplica cambios por archivo pero no vuelve a recorrer los cambios de .gitignore en sí mismos en tiempo de ejecución — si se edita .gitignore, ejecuta index_repository con refresh=true una vez para recoger las nuevas reglas.

Consideraciones de seguridad antes de un uso más amplio/de producción

Ya corregido:

• Inyección de shell — la extensión de VS Code anteriormente interpolaba ajustes del espacio de trabajo en cadenas de comandos de shell; ahora usa execFile con matrices de argumentos (sin shell) y se niega a ejecutar "Setup Server" en espacios de trabajo no confiables.

• Escape de enlaces simbólicos — el recorredor omite enlaces simbólicos que se resuelven fuera de la raíz del repositorio (bloquea un enlace simbólico plantado para exponer archivos como /etc/passwd).

• Fuga de secretos — los nombres de archivo que coinciden con patrones comunes de credenciales (.env, *.pem, id_rsa, credentials.json, etc., consulta SENSITIVE_FILENAME_PATTERNS en config.py) se omiten incluso si no están en gitignore, para que su contenido no pueda terminar en la salida de la herramienta.

• Bloqueo por caché corrupta — un .mcp_intel_cache/index.json malformado/alterado ahora desencadena una reconstrucción limpia en lugar de bloquear el servidor al iniciarse.

• ReDoS — el analizador regex JS/TS omite líneas individuales patológicamente largas (archivos minificados) para evitar DoS por retroceso catastrófico.

• repo_root sin restricciones — establece MCP_INTEL_ALLOWED_ROOTS (una lista separada por : de rutas absolutas) para restringir qué directorios indexará el servidor; sin establecer por defecto para preservar el comportamiento flexible actual de un solo usuario.

Aún arquitectónico, no completamente resuelto — lee antes de implementar más allá de un solo usuario local:

• No es seguro como servicio de red compartido/multiusuario. Esto está diseñado como un servidor stdio local de un proceso por usuario. Las cachés del índice/observador en memoria no tienen aislamiento por usuario ni autenticación. No expongas esto como un endpoint HTTP/SSE compartido sin añadir sandboxing y autenticación por llamador.

• Las dependencias no están fijadas (solo >=) — fija versiones exactas o usa un archivo de bloqueo para instalaciones de producción reproducibles y verificadas (esto ya nos mordió una vez con un cambio de API incompatible de mcp 1.x → 2.0).

• No hay pruebas de regresión automatizadas para este código base todavía — los cambios se verifican actualmente mediante el arnés manual eval/ y ejecuciones ad hoc, no una suite de pruebas controlada por CI.