ContextTree MCP 🌳

Búsqueda semántica profunda de código para asistentes de IA — impulsada por análisis de AST y embeddings locales. 100 % offline.

ContextTree MCP es un servidor local de Model Context Protocol que proporciona a tu asistente de codificación una comprensión estructural de la base de código. Combina dos mundos:

• tree-sitter analiza los archivos fuente en un AST y extrae bloques lógicos —funciones, métodos, firmas de clases con docstrings—.

• sentence-transformers (all-MiniLM-L6-v2) incrusta cada bloque —enriquecido con la ruta del archivo, la clase contenedora, el nombre del método y el docstring— en un almacén vectorial local de ChromaDB.

El resultado: tu asistente encuentra código por significado, no solo por palabras clave, y cada resultado de búsqueda llega con la ruta exacta del archivo y los números de línea.

🔒 La privacidad es lo primero. Todo se ejecuta en tu máquina: análisis sintáctico, modelo de embeddings e índice vectorial. Sin llamadas a la nube, sin telemetría; el código nunca sale del disco en el que reside.

¿Por qué no usar una búsqueda de texto plano?

grep y la búsqueda de texto completo buscan cadenas coincidentes. Fallan justo donde más se necesita ayuda:

Related MCP server: CodeGrok MCP

Características

• 🌲 Fragmentación consciente del AST — indexa funciones, métodos y firmas de clases mediante tree-sitter, no a través de ventanas arbitrarias de texto.

• 🧩 Bloques lógicos enriquecidos con contexto — cada documento indexado contiene su ruta de archivo, clase propietaria, nombre de método, docstring y cuerpo, de modo que consultas como "lógica de reintento de pago" den con el método correcto.

• ⚡ Indexación incremental — hashes SHA-256 de contenido por archivo; solo se reprocesan los archivos modificados, nuevos o eliminados.

• 🔍 Búsqueda semántica — consulta de lengua natural → fragmentos de código clasificados con intervalos de línea exactos.

• 📞 Localización de usos AST — encuentra los lugares reales de llamada o instanciación de una función o clase, filtrando falsos positivos como cadenas explicativas o comentarios.

• 🗄️ Índice local persistente — ChromaDB guarda en .chroma/, sobrevive a reinicios y nunca se envía al repositorio Git.

• 🔌 Transporto MCP de stdio — compatible con Claude Desktop, OpenCode, Cursor, Cline o cualquier cliente a aceptar MCP.

Pila tecnológica

Instalación

Se requiere Python 3.12+. Se recomienda uv como gestor de paquetes rápido y moderno:

git clone https://github.com/<your-org>/mcp-context-tree.git
cd mcp-context-tree

# Option A — uv (recommended): resolves dependencies from pyproject.toml, locks uv.lock
uv sync

# Option B — classic pip + venv
python -m venv venv && source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -r requirements.txt

💡 La primera vez en ejecución descarga el modelo de embeddings (~90 MB). PyTorch se instala como dependencia de sentence-transformers; la versión CPU es suficiente — no se necesita GPU.

Alta en un cliente MCP

Ejemplo de configuración (Claude Desktop / cualquier cliente compatible con servidores stdio):

{
  "mcpServers": {
    "context-tree": {
      "command": "<path-to-venv>/bin/python",
      "args": ["-m", "context_tree"],
      "env": {}
    }
  }
}

(En Windows usa <ruta-al-venv>\Scripts\python.exe).

Herramientas expuestas a la IA

Proceso de uso típico:

1. index_workspace("D:/projects/my-app")
2. semantic_search("where do we handle payment retries", limit=8)
3. find_ast_usages("PaymentGateway.retry")

Lenguajes compatibles

Documentación

• 🏛️ ARCHITECTURE.md — estructura del proyecto, esquema de datos de ChromaDB, lógica de extracción de AST y diseño de indexación incremental.

• 🇷🇺 README.ru.md — documentación en ruso.

Hoja de ruta

• Modo watch: reindexado automático al cambiar archivos (fs watcher)

• Más lenguajes mediante enlaces tree-sitter

• Búsqueda híbrida (BM25 + rerank de vectores)

• Clasificación con grafo de llamadas (“¿quién llama esto?”)

• Publicación en PyPI (context-tree-mcp)

Contribuciones

Las incidencias y las PRs son bienvenidas. Por favor, mantén los cambios coherentes con ARCHITECTURE.md.

Licencia

MIT — consulta LICENSE.