Code Index MCP

Code Index MCP

Resumen

Code Index MCP es un servidor de Model Context Protocol que cierra la brecha entre los modelos de IA y las bases de código complejas. Proporciona indexación inteligente, capacidades de búsqueda avanzada y análisis de código detallado para ayudar a los asistentes de IA a comprender y navegar por tus proyectos de manera efectiva.

Perfecto para: revisión de código, refactorización, generación de documentación, asistencia de depuración y análisis arquitectónico.

Inicio rápido

🚀 Configuración recomendada (para la mayoría de usuarios)

La forma más fácil de comenzar con cualquier aplicación compatible con MCP:

Requisitos previos: Python 3.10+ y uv

1. Agrega a tu configuración de MCP (por ejemplo, claude_desktop_config.json o ~/.claude.json):

   {
     "mcpServers": {
       "code-index": {
         "command": "uvx",
         "args": ["code-index-mcp"]
       }
     }
   }
   

   Opcional: agrega --project-path /absolute/path/to/repo al arreglo args para que el servidor se inicialice automáticamente con ese repositorio (equivalente a llamar a set_project_path después del inicio).

2. Reinicia tu aplicación – uvx maneja automáticamente la instalación y ejecución

3. Comienza a usarlo (dale estas indicaciones a tu asistente de IA):

   Set the project path to /Users/dev/my-react-app
   Find all TypeScript files in this project  
   Search for "authentication" functions
   Analyze the main App.tsx file
   

   Si inicias con --project-path, puedes omitir el primer comando anterior: el servidor ya conoce la ubicación del proyecto.

Configuración de Codex CLI

Si estás usando el Codex CLI de Anthropic, agrega el servidor a ~/.codex/config.toml. En Windows, el archivo se encuentra en C:\Users\<you>\.codex\config.toml:

[mcp_servers.code-index]
type = "stdio"
command = "uvx"
args = ["code-index-mcp"]

Puedes agregar --project-path C:/absolute/path/to/repo a la lista args para configurar el proyecto automáticamente al inicio (mismo efecto que ejecutar la herramienta set_project_path).

En Windows, uvx necesita que los directorios de perfil estándar estén presentes. Mantén la anulación de entorno en el mismo bloque para que el MCP se inicie de manera confiable:

env = {
  HOME = "C:\\Users\\<you>",
  APPDATA = "C:\\Users\\<you>\\AppData\\Roaming",
  LOCALAPPDATA = "C:\\Users\\<you>\\AppData\\Local",
  SystemRoot = "C:\\Windows"
}

Linux y macOS ya exponen las rutas XDG requeridas y HOME, por lo que generalmente puedes omitir la tabla env allí. Agrega anulaciones solo si ejecutas el CLI dentro de un contenedor restringido.

Manifiestos de FastMCP y descubrimiento

• Ejecuta fastmcp run fastmcp.json para lanzar el servidor mediante FastMCP con el punto de entrada de origen correcto y los metadatos de dependencia. Pasa --project-path (o llama a la herramienta set_project_path después del inicio) para que el índice se inicie con el repositorio correcto.
• Sirve o copia .well-known/mcp.json para compartir un manifiesto MCP compatible con estándares. Los clientes que admiten la convención .well-known (por ejemplo, Claude Desktop, Codex CLI) pueden importar este archivo directamente en lugar de crear configuraciones manualmente.
• Publica .well-known/mcp.llmfeed.json cuando quieras exponer los metadatos más ricos de LLM Feed. Hace referencia a la misma definición de servidor code-index más enlaces de documentación/fuente, lo que ayuda a los registros a presentar descripciones, etiquetas y capacidades automáticamente.

Al compartir los manifiestos, recuerda a los consumidores que proporcionen --project-path (o que llamen a set_project_path) para que el servidor indexe el repositorio deseado.

Casos de uso típicos

Revisión de código: "Encuentra todos los lugares que usan la API antigua"
Ayuda de refactorización: "¿Dónde se llama a esta función?"
Proyectos de aprendizaje: "Muéstrame los componentes principales de este proyecto React"
Depuración: "Busca todo el código relacionado con el manejo de errores"

Características clave

🔍 Búsqueda y análisis inteligente

• Arquitectura de doble estrategia: análisis especializado con tree-sitter para 10 lenguajes principales, estrategia de respaldo para más de 50 tipos de archivos
• Integración directa con Tree-sitter: sin respaldos de regex para lenguajes especializados: falla rápidamente con errores claros
• Búsqueda avanzada: detecta y usa automáticamente la mejor herramienta disponible (ugrep, ripgrep, ag o grep)
• Soporte universal de archivos: cobertura integral desde análisis AST avanzado hasta indexación básica de archivos
• Análisis de archivos: información profunda sobre estructura, importaciones, clases, métodos y métricas de complejidad después de ejecutar build_deep_index

🗂️ Soporte multilingüe

• 10 lenguajes con análisis AST de Tree-sitter: Python, JavaScript, TypeScript, Java, Kotlin, C#, Go, Objective-C, Zig, Rust
• Más de 50 tipos de archivos con estrategia de respaldo: C/C++, Ruby, PHP y todos los demás lenguajes de programación
• Archivos de documentación y configuración: Markdown, JSON, YAML, XML con manejo adecuado
• Frontend web: Vue, React, Svelte, HTML, CSS, SCSS
• Java Web y compilación: archivos JSP/Tag (.jsp, .jspx, .jspf, .tag, .tagx), Grails/GSP (.gsp), compilaciones de Gradle y Groovy (.gradle, .groovy), .properties y Protocol Buffers (.proto)
• Base de datos: variantes de SQL, NoSQL, procedimientos almacenados, migraciones
• Configuración: JSON, YAML, XML, Markdown
• Ver lista completa

⚡ Monitoreo en tiempo real y actualización automática

• Observador de archivos: actualizaciones automáticas del índice cuando los archivos cambian
• Multiplataforma: monitoreo nativo del sistema de archivos del SO
• Procesamiento inteligente: agrupa cambios rápidos para evitar reconstrucciones excesivas
• Actualización de índice superficial: observa los cambios de archivos y mantiene la lista de archivos actualizada; ejecuta una reconstrucción profunda cuando necesites metadatos de símbolos

⚡ Rendimiento y eficiencia

• Análisis AST de Tree-sitter: análisis de sintaxis nativo para extracción precisa de símbolos
• Caché persistente: almacena índices para un acceso posterior ultrarrápido
• Filtrado inteligente: exclusión inteligente de directorios de compilación y archivos temporales
• Eficiente en memoria: optimizado para bases de código grandes
• Dependencias directas: sin mecanismos de respaldo: falla rápidamente con mensajes de error claros

Tipos de archivos compatibles

🛠️ Configuración de desarrollo

Para contribuir o desarrollo local:

1. Clona e instala:

   git clone https://github.com/johnhuang316/code-index-mcp.git
   cd code-index-mcp
   uv sync
   

2. Configura para desarrollo local:

   {
     "mcpServers": {
       "code-index": {
         "command": "uv",
         "args": ["run", "code-index-mcp"]
       }
     }
   }
   

3. Depura con MCP Inspector:

   npx @modelcontextprotocol/inspector uv run code-index-mcp
   

pip install code-index-mcp

{
  "mcpServers": {
    "code-index": {
      "command": "code-index-mcp",
      "args": []
    }
  }
}

Herramientas disponibles

🏗️ Gestión de proyectos

Ejecuta build_deep_index cuando necesites datos a nivel de símbolos; el índice superficial predeterminado permite un descubrimiento rápido de archivos.

🔍 Búsqueda y descubrimiento

🔄 Monitoreo y actualización automática

🛠️ Sistema y mantenimiento

Ejemplos de uso

🎯 Flujo de trabajo de inicio rápido

1. Inicializa tu proyecto

Set the project path to /Users/dev/my-react-app

Indexa automáticamente tu base de código y crea un caché de búsqueda 2. Explorar la estructura del proyecto

Find all TypeScript component files in src/components

Usa: find_files con el patrón src/components/**/*.tsx

3. Analizar archivos clave

Give me a summary of src/api/userService.ts

Usa: get_file_summary para mostrar funciones, importaciones y complejidad Consejo: ejecuta build_deep_index primero si obtienes una respuesta de needs_deep_index.

🔍 Ejemplos de búsqueda avanzada

Search for all function calls matching "get.*Data" using `regex=True`

Find authentication-related functions with fuzzy search for 'authUser'

Search for "API_ENDPOINT" only in Python files

Configure automatic index updates when files change

I added new components, please refresh the project index

Solución de problemas

🔄 La actualización automática no funciona

Si las actualizaciones automáticas del índice no funcionan cuando los archivos cambian, prueba:

• pip install watchdog (puede resolver problemas de aislamiento del entorno)
• Usa la actualización manual: llama a la herramienta refresh_index después de realizar cambios en los archivos
• Verifica el estado del observador de archivos: usa get_file_watcher_status para confirmar que la supervisión está activa

Opciones del observador de archivos en macOS

El observador FSEvents predeterminado funciona bien para la mayoría de los proyectos. Si experimentas problemas, puedes cambiar a un observador alternativo mediante configure_file_watcher:

• "auto" (predeterminado): Valor predeterminado de la plataforma (FSEvents en macOS)
• "kqueue": Observador Kqueue (macOS/BSD)
• "fsevents": Forzar FSEvents (solo macOS)
• "polling": Alternativa de sondeo multiplataforma

Nota: Kqueue abre un descriptor de archivo por cada archivo supervisado. Para proyectos grandes que usan kqueue, es posible que debas aumentar el límite: ulimit -n 10240

Desarrollo y contribuciones

🔧 Compilar desde el código fuente

git clone https://github.com/johnhuang316/code-index-mcp.git
cd code-index-mcp
uv sync
uv run code-index-mcp

🐛 Depuración

npx @modelcontextprotocol/inspector uvx code-index-mcp

🤝 Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar un Pull Request.

📜 Licencia

Licencia MIT

🌐 Traducciones

• 繁體中文
• 日本語