mcp-deepcontext

Servidor MCP que permite la búsqueda semántica consciente de símbolos en Claude Code

motivación

La mayoría de las herramientas de búsqueda de código tratan el código como texto, ignorando la estructura semántica que hace que el código sea significativo. Cuando trabajas en una base de código grande, no solo quieres encontrar dónde aparece una cadena. Quieres encontrar dónde se llama a una función, dónde se implementa un tipo o qué módulos dependen de un símbolo en particular.

Este servidor MCP cierra esa brecha al exponer capacidades de análisis de código semántico a Claude. En lugar de buscar texto mediante grep, Claude puede hacer preguntas como "¿dónde se implementa esta interfaz?" o "¿cuáles son todas las llamadas a esta función?" y obtener resultados precisos y conscientes de los símbolos. Esto hace posible tener conversaciones realmente útiles sobre bases de código desconocidas.

arquitectura

graph TD
    A[Claude Desktop] -->|MCP Protocol| B[mcp-deepcontext Server]
    B -->|Parse & Index| C[Symbol Database]
    B -->|AST Analysis| D[TypeScript Compiler API]
    B -->|Semantic Search| E[Vector Embeddings]
    
    C -->|Symbol Locations| B
    D -->|Type Information| B
    E -->|Similarity Scores| B
    
    F[Your Codebase] -->|Watch & Reindex| B

primeros pasos

instalación

npm install -g mcp-deepcontext

inicio rápido

Añádelo a la configuración de Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "deepcontext": {
      "command": "mcp-deepcontext",
      "args": ["--workspace", "/path/to/your/project"]
    }
  }
}

Luego reinicia Claude Desktop. El servidor indexará tu base de código al iniciarse.

cómo funciona

El servidor utiliza la API del compilador de TypeScript para construir un grafo de símbolos completo de tu base de código. Esto incluye definiciones de tipos, firmas de funciones, jerarquías de clases y relaciones de importación. Cuando Claude solicita información, el servidor puede responder con ubicaciones precisas y contexto.

Para la búsqueda semántica, el servidor genera embeddings para los símbolos de código y su contexto circundante. Esto permite una coincidencia difusa basada en la intención en lugar de texto exacto. La base de datos de símbolos se mantiene sincronizada con los cambios de archivo a través de un observador de archivos que activa una reindexación incremental.

El protocolo MCP expone esto a través de herramientas como search_symbols, find_references, get_definition y find_implementations. Claude puede encadenarlas para responder preguntas complejas sobre la estructura y las relaciones del código.

configuración

El servidor acepta estos argumentos de línea de comandos:

• --workspace <path>: Directorio raíz del proyecto a indexar (obligatorio)

• --languages <list>: Lista separada por comas de los lenguajes a indexar (predeterminado: typescript,javascript)

• --exclude <patterns>: Patrones glob a excluir (predeterminado: node_modules,dist,build,.git)

• --max-file-size <bytes>: Omitir archivos más grandes que este tamaño (predeterminado: 1MB)

• --embedding-model <name>: Modelo a utilizar para los embeddings (predeterminado: text-embedding-3-small)

Variables de entorno:

• OPENAI_API_KEY: Obligatorio para la generación de embeddings

• DEEPCONTEXT_LOG_LEVEL: Establecer en debug para un registro detallado

preguntas frecuentes

P: ¿Qué lenguajes son compatibles?

Actualmente TypeScript y JavaScript con plena conciencia de tipos. El soporte para Python y Go está planificado.

P: ¿Funciona esto con bases de código grandes?

Sí, la indexación es incremental y la base de datos de símbolos utiliza una estructura de grafo eficiente. Probado en bases de código de hasta 500k líneas sin problemas.

P: ¿Cuánto cuesta la generación de embeddings?

Para una base de código típica de 100k líneas, la indexación inicial genera alrededor de 10k embeddings, costando aproximadamente $0.02 con text-embedding-3-small. Las actualizaciones incrementales son mucho más baratas.

P: ¿Puedo usar esto sin embeddings?

Sí, pasa --no-embeddings para deshabilitar la búsqueda semántica. Seguirás obteniendo todas las herramientas conscientes de símbolos como buscar referencias e ir a la definición.

P: ¿Esto envía mi código a servicios externos?

Solo los nombres de símbolos extraídos y su contexto inmediato se envían a OpenAI para la generación de embeddings. Puedes deshabilitar esto con --no-embeddings para una operación completamente local.

licencia

MIT