Codebase RAG MCP

Un servidor MCP de recuperación de código local, sin necesidad de clave API. Escanea repositorios específicos, divide en fragmentos por ventanas de código y realiza una clasificación híbrida mediante BM25, nombres de símbolos, rutas de archivo y coincidencias exactas. Se puede conectar directamente a Codex y también proporciona herramientas estándar search / fetch para escenarios de recuperación de conocimiento en ChatGPT.

Funcionalidades

• Utiliza preferentemente git ls-files, respetando los .gitignore anidados del repositorio; los directorios que no son Git utilizan escaneo del sistema de archivos.

• Soporta formatos de código de texto comunes como TypeScript, JavaScript, Python, Go, Rust, Java, C/C++, C#, Ruby, Shell, SQL, Markdown, Vue, Svelte, etc.

• Divide automáticamente camelCase, snake_case y palabras de ruta, y admite expansión de consultas de código en chino común, por ejemplo, "用户登录认证" (autenticación de inicio de sesión de usuario).

• Devuelve rutas de archivo exactas, números de línea, fragmentos de código con números de línea, motivo de coincidencia e ID estable para lectura continua.

• La lectura de rutas se limita al directorio raíz del repositorio configurado; por defecto omite enlaces simbólicos, binarios, claves, archivos de variables de entorno, código comprimido y archivos grandes.

• Soporta tanto stdio local como HTTP Streamable sin estado /mcp.

Inicio rápido

Requiere Node.js 20 o superior.

Obtén el proyecto desde GitHub:

git clone https://github.com/sudoriaa/codebase-rag-mcp.git
cd codebase-rag-mcp

Instala las dependencias y construye:

npm install
npm run build
node dist/cli.js --root C:/path/to/your-repository

El último comando inicia el servidor MCP stdio, que espera la conexión del cliente MCP, por lo que es normal que el terminal permanezca en ejecución.

Conectar a Codex

Coloca lo siguiente en el archivo de configuración de usuario %USERPROFILE%/.codex/config.toml, o en .codex/config.toml del repositorio de confianza:

[mcp_servers.codebase-rag]
command = "C:/Program Files/nodejs/node.exe"
args = [
  "C:/absolute/path/codebase-rag-mcp/dist/cli.js",
  "--root",
  "C:/absolute/path/your-repository"
]
cwd = "C:/absolute/path/codebase-rag-mcp"
startup_timeout_sec = 60
tool_timeout_sec = 120

Se recomienda usar / en las rutas TOML de Windows. command solo debe contener el ejecutable; los demás parámetros se colocan por separado en args. El PATH heredado por las aplicaciones de escritorio puede diferir del de PowerShell, por lo que para uso a largo plazo se recomienda especificar la ruta absoluta de node.exe.

También se puede registrar mediante CLI:

codex mcp add codebase-rag -- "C:\Program Files\nodejs\node.exe" "C:\absolute\path\codebase-rag-mcp\dist\cli.js" --root "C:\absolute\path\your-repository"
codex mcp get codebase-rag --json

Después de la configuración, reinicia la aplicación de escritorio de Codex o la extensión del IDE. Consulta la configuración de ejemplo en examples/codex-config.toml.

Iniciar HTTP MCP

node dist/cli.js --root C:/path/to/your-repository --transport http --host 127.0.0.1 --port 3000

Puntos finales:

• MCP: http://127.0.0.1:3000/mcp

• Health check: http://127.0.0.1:3000/health

• Archivo fuente de referencia: http://127.0.0.1:3000/source/:documentId

Por defecto solo escucha en localhost. Al implementar en otras máquinas, se debe agregar TLS, autenticación y control de acceso en la capa de proxy inverso, y usar --public-base-url para establecer la dirección canónica accesible por el modelo.

Al escuchar directamente en 0.0.0.0 u otras direcciones que no sean localhost, el servicio requerirá un Bearer Token:

$env:CODEBASE_MCP_TOKEN = "replace-with-a-long-random-token"
node dist/cli.js --root C:/path/to/your-repository --transport http --host 0.0.0.0 --port 3000

El cliente deberá enviar Authorization: Bearer <token> para /mcp y /health. La dirección de referencia devuelta por el servicio incluirá automáticamente una firma HMAC, por lo que el usuario puede abrir directamente el enlace /source correspondiente; el acceso manual a direcciones /source sin firmar aún requiere el Bearer Token. Al publicar a través de un proxy inverso local, el servicio puede seguir escuchando en 127.0.0.1 y el proxy se encargará de la autenticación externa.

Herramientas MCP

Orden de llamada recomendado:

1. Usa search_code para buscar implementaciones y fragmentos relacionados.

2. Usa get_code_context para expandir fragmentos de alta puntuación.

3. Usa find_symbol para localizar definiciones con precisión.

4. Usa fetch solo cuando realmente necesites el archivo completo.

Método de recuperación

El índice se ejecuta completamente en la memoria local:

1. Los archivos de código se dividen en fragmentos de hasta 120 líneas, con superposición de 20 líneas.

2. Se extraen símbolos como class, interface, type, enum, function, method de declaraciones de lenguajes comunes.

3. El cuerpo del texto se recupera con BM25, y los símbolos y rutas se clasifican por separado.

4. Se utiliza fusión de rango recíproco para combinar las puntuaciones del cuerpo, símbolos, rutas y coincidencias exactas.

5. Por defecto, cada archivo devuelve como máximo dos fragmentos para evitar que el código repetitivo llene los resultados.

Esta versión no tiene base de datos vectorial externa ni carga el código fuente. Para recuperación semántica multilingüe y de múltiples repositorios a gran escala, se puede agregar recuperación por embeddings o reranker antes y después del CodebaseIndex.search existente, sin necesidad de cambiar el contrato de las herramientas MCP.

Configuración

--root PATH
--transport stdio|http
--host HOST
--port PORT
--public-base-url URL
--max-file-bytes N
--max-files N

Las variables de entorno correspondientes son:

CODEBASE_ROOT
CODEBASE_TRANSPORT
CODEBASE_HOST
CODEBASE_PORT
CODEBASE_PUBLIC_BASE_URL
CODEBASE_MCP_TOKEN
CODEBASE_MAX_FILE_BYTES
CODEBASE_MAX_FILES

El límite predeterminado por archivo es de 1 MiB, y el límite de número de archivos es de 20,000.

Desarrollo y verificación

npm run build
npm test

Las pruebas cubren construcción de índices, .gitignore, expansión de consultas en chino, filtrado de símbolos y rutas, desbordamiento de rutas, search/fetch estándar, MCP en memoria, subprocesos stdio reales y HTTP Streamable.

MCP Inspector también puede verificar directamente el servicio HTTP:

npx @modelcontextprotocol/inspector

Luego selecciona Streamable HTTP y completa http://127.0.0.1:3000/mcp.

La implementación sigue la Guía oficial de servidores MCP de OpenAI y la forma de datos estándar de search / fetch.

Límites actuales

• El índice se reconstruye después de reiniciar el proceso, sin caché persistente.

• Los repositorios Git cumplen completamente con las reglas de ignorar de Git; los directorios que no son Git actualmente leen el .gitignore raíz.

• La extracción de símbolos utiliza análisis ligero de declaraciones, no equivale a un AST completo del compilador.

• Después de cambios en archivos, se llama a refresh_index; la versión actual no tiene monitoreo de archivos habilitado.

Licencia

MIT