MCP Codebase Search Server

Servidor Model Context Protocol que reutiliza el índice semántico existente de Roo Code y expone los tools superior_codebase_search y superior_codebase_rerank vía transporte stdio.

Requisitos

• Node.js 18+
• Acceso a la carpeta del workspace ya indexado por Roo Code
• Qdrant accesible con la colección creada por la extensión
• API key para el proveedor de embeddings compatible con OpenAI
• API key para el proveedor del Judge (LLM) compatible con OpenAI

Instalación

En esta carpeta (tiene su propio repositorio Git):

pnpm install

Si tu pnpm ya tiene un store con @modelcontextprotocol/sdk, el flag --offline también funciona.

Configuración

Variables de entorno soportadas:

Variable	Descripción
MCP_CODEBASE_WORKSPACE / WORKSPACE_PATH	Opcional: ruta por defecto del workspace indexado.
MCP_CODEBASE_QDRANT_URL / QDRANT_URL	URL del servidor Qdrant (por ejemplo http://localhost:6333).
MCP_CODEBASE_QDRANT_API_KEY / QDRANT_API_KEY	API key de Qdrant si aplica.
MCP_CODEBASE_EMBEDDER_PROVIDER / EMBEDDER_PROVIDER	openai (default) u openai-compatible.
MCP_CODEBASE_EMBEDDER_API_KEY / EMBEDDER_API_KEY	API key para el servicio de embeddings.
MCP_CODEBASE_EMBEDDER_BASE_URL / EMBEDDER_BASE_URL	Base URL cuando se usa openai-compatible.
MCP_CODEBASE_EMBEDDER_MODEL_ID / EMBEDDER_MODEL_ID	Modelo de embeddings (default text-embedding-3-small).
MCP_CODEBASE_SEARCH_MIN_SCORE / SEARCH_MIN_SCORE	Umbral mínimo de score (default 0.4).
MCP_CODEBASE_SEARCH_MAX_RESULTS / SEARCH_MAX_RESULTS	Número máximo de resultados (default 20).
MCP_CODEBASE_JUDGE_PROVIDER / JUDGE_PROVIDER	Proveedor para el Judge: openai (default), openai-compatible o mcp-internal.
MCP_CODEBASE_JUDGE_API_KEY / JUDGE_API_KEY	API key para el servicio Judge (LLM).
MCP_CODEBASE_JUDGE_BASE_URL / JUDGE_BASE_URL	Base URL cuando se usa openai-compatible o mcp-internal.
MCP_CODEBASE_JUDGE_MODEL_ID / JUDGE_MODEL_ID	Modelo LLM para el Judge (default gpt-4o).
MCP_CODEBASE_JUDGE_MAX_TOKENS / JUDGE_MAX_TOKENS	Tokens máximos para respuesta (default 1024).
MCP_CODEBASE_JUDGE_TEMPERATURE / JUDGE_TEMPERATURE	Temperatura para el Judge (default 0).
MCP_CODEBASE_JUDGE_SYSTEM_PROMPT / JUDGE_SYSTEM_PROMPT	Prompt del sistema personalizado para el Judge.
MCP_CODEBASE_RERANKING_MAX_RESULTS / RERANKING_MAX_RESULTS	Máximo de resultados tras reordenar (default 10).
MCP_CODEBASE_RERANKING_INCLUDE_REASON / RERANKING_INCLUDE_REASON	Incluir explicación del reordenamiento (default true).
MCP_CODEBASE_RERANKING_SUMMARIZE / RERANKING_SUMMARIZE	Generar resumen por defecto (default false).

Puedes definirlas en un fichero .env en esta carpeta; el servidor la carga automáticamente con dotenv.

Ejecución

pnpm start

Esto levanta el servidor MCP por stdio. Para integrarlo con Roo Code o Claude Code:

{
  "mcpServers": {
    "codebase-search": {
      "command": "pnpm",
      "args": ["start"],
      "cwd": "/ruta/al/proyecto/mcp-codebase-search",
      "alwaysAllow": ["superior_codebase_search", "superior_codebase_rerank"]
    }
  }
}

Tools disponibles

• superior_codebase_search

  • Parámetros: query (obligatorio), workspacePath (ruta absoluta del proyecto), path (prefijo opcional).
  • Respuesta: texto con lista de coincidencias, score y fragmentos de código.

• superior_codebase_rerank

  • Parámetros: query (obligatorio), workspacePath (ruta absoluta del proyecto), path (prefijo opcional), mode (opcional, valores: rerank o summary).
  • Respuesta: texto con lista de coincidencias reordenadas por relevancia según el LLM Judge, con puntuación de relevancia, razones de la selección, y opcionalmente un resumen.
  • Modos:
    • rerank (predeterminado): solo reordena los resultados por relevancia.
    • summary: reordena los resultados y genera un resumen consolidado del código relevante.

Prueba de conectividad (embeddings OpenAI-compatible)

El archivo data.txt contiene un endpoint de pruebas compatible con OpenAI que devuelve embeddings como strings. Para validar la conectividad y ver cómo los convierte el servidor:

pnpm test:embedding

• Lee data.txt, extrae Base URL, API key y modelo.
• Envía una petición /embeddings.
• Muestra dimensión del embedding y los primeros valores obtenidos.

Prueba end-to-end con búsqueda usando la ruta de data.txt:

pnpm test:search

Para probar el reranking:

pnpm test:rerank

Notas

• El servidor no indexa archivos; depende de que Roo Code mantenga Qdrant al día.
• El nombre de la colección coincide con la lógica original (ws-<hash16(workspacePath)>).
• El reranking utiliza un modelo LLM para evaluar la relevancia semántica de los resultados.
• Puedes ampliar services.ts para añadir otros proveedores de embeddings o más formatos de respuesta.