Permite que los agentes de codificación con IA inspeccionen la estructura de los repositorios, busquen código y recuerden las convenciones del proyecto mediante MCP y CLI.
También conocido como PatrickSys/codebase-context
- Stars
- 68
- Herramientas
- —
- Descargas, 30 días
- —
- Última versión
- —
- Último commit
- 7 nov 2026
- Licencia
- —
¿Qué es Codebase Context MCP?
Codebase Context es un MCP server. Permite que los agentes de codificación con IA inspeccionen la estructura de los repositorios, busquen código y recuerden las convenciones del proyecto mediante MCP y CLI.
Resumen generado a partir del README del proyecto
Acerca del MCP server de Codebase Context
Lo que permite codebase-context es ayudar a los agentes de codificación con IA a comprender repositorios complejos mediante herramientas especializadas de indexación y recuperación. Los desarrolladores utilizan esta herramienta para proporcionar a los agentes un mapa de alto nivel del repositorio, referencias de símbolos y relaciones entre archivos, lo que permite a una IA inspeccionar la estructura de un proyecto antes de intentar realizar cualquier edición. Funciona localmente a través de stdio o mediante una configuración avanzada de HTTP, y puede inicializarse para clientes específicos como Claude Code, Cursor, Codex y OpenCode.
Los usuarios pueden elegir entre un índice predeterminado basado en palabras clave que no requiere API keys ni GPU, o un modo de indexación semántica opcional que utiliza proveedores de embeddings. El sistema incluye funciones únicas como la memoria del proyecto para almacenar convenciones y una herramienta de contexto de revisión que crea un paquete delimitado a partir de los diffs de Git. Aunque el índice de palabras clave está limitado por defecto a 5,000 fragmentos buscables, los usuarios pueden ajustar estos límites mediante la configuración. Proporciona analizadores específicos para frameworks como React, Next.js, Angular y NestJS para mejorar la forma en que los agentes navegan por las bases de código.
Qué puedes hacer con él
- 1Mapear la estructura del repositorioPide a un agente de IA que genere una visión general de alto nivel de la organización y los patrones del proyecto antes de comenzar una tarea.
- 2Buscar código específicoDirige a una IA para que encuentre símbolos o funciones específicas dentro de la base de código utilizando resultados de búsqueda clasificados.
- 3Recordar las convenciones del proyectoInstruye a un agente para que recupere decisiones o reglas arquitectónicas almacenadas previamente utilizando las herramientas de memoria.
- 4Analizar cambios recientesProporciona a una IA el contexto necesario de un commit reciente para realizar una revisión de código enfocada.
Escrito a partir del README del proyecto. Cada caso de uso se verifica con una cita del mismo.
Cómo instalar Codebase Context MCP
Formatos verificados el 10 nov 2026Añadir a CursorAñadir a GooseInstalar Codebase Context MCP en Claude Code
$ claude mcp add codebase-context -- npx -y codebase-contextInstalar Codebase Context MCP en Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"codebase-context": {
"command": "npx",
"args": [
"-y",
"codebase-context"
]
}
}
}Instalar Codebase Context MCP en VS Code
.vscode/mcp.json
{
"servers": {
"codebase-context": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"codebase-context"
]
}
}
}Instalar Codebase Context MCP en VS Code CLI
$ code --add-mcp '{"name":"codebase-context","type":"stdio","command":"npx","args":["-y","codebase-context"]}'Instalar Codebase Context MCP en Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"codebase-context": {
"command": "npx",
"args": [
"-y",
"codebase-context"
]
}
}
}Instalar Codebase Context MCP en Codex
$ codex mcp add codebase-context -- npx -y codebase-contextInstalar Codebase Context MCP en Codex config.toml
~/.codex/config.toml
[mcp_servers.codebase-context] command = "npx" args = ["-y", "codebase-context"]
Instalar Codebase Context MCP en Gemini CLI
$ gemini mcp add -s user codebase-context npx -- -y codebase-contextInstalar Codebase Context MCP en Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"codebase-context": {
"command": "npx",
"args": [
"-y",
"codebase-context"
]
}
}
}Verificaciones automáticas
Ejecutado 13 nov 2026Informe completo →Pasó nuestras verificaciones automáticas. Esto no es una auditoría de seguridad: lee el código y dale al servidor el acceso más limitado que necesite. Cómo funcionan las verificaciones · Qué corregir para obtener más puntos
- Repositorio de origen vinculado y accesiblepatricksys/codebase-context is public and reachablegithub.com/patricksys/codebase-context ↗Aprobado
- El paquete indica este repositorio como su origencodebase-context names patricksys/codebase-context as sourcenpmjs.com/package/codebase-context ↗Aprobado
- Procedencia de la compilación (atestación de Sigstore)Sigstore attestation for codebase-contextnpmjs.com/package/codebase-context/v/2.2.0#provenance ↗Aprobado
- Licencia de código abierto (OSI)No licenseHallazgo
- Commit o lanzamiento en el último añoLast commit or release 2026-11-07github.com/patricksys/codebase-context ↗Aprobado
- OpenSSF ScorecardNo verificado
- El nombre del paquete no es similar a un paquete popularNo popular package one edit away from codebase-contextAprobado
- No hay avisos críticos en el paquete ni en sus dependenciasNo verificado
- Sin instrucciones ocultas para el modelo0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersAprobado
- Las herramientas destructivas están etiquetadasNo verificado
- El endpoint remoto responde al handshake de MCPNo verificado
README
Ver en GitHubCodebase Context
Local repository maps, code search and symbol references for coding agents. Codebase Context exposes these through MCP and a CLI so an agent can inspect the repository before editing it.
Published beta: 2.3.1-beta.0 (stable: 2.2.0)
As checked on 4 November 2026, npm beta points to 2.3.1-beta.0, while npm latest remains 2.2.0. The beta requires Node.js 22 or newer. An unpinned npx -y codebase-context may use an already installed local version; without one, it resolves npm latest (currently the stable 2.2.0). To select the published beta explicitly, use npx -y codebase-context@2.3.1-beta.0 --version. A source checkout or a local tarball is separate from a verified registry release.
Fresh beta indexes use keyword search without downloading an embedding or reranker model. Existing indexes keep their recorded mode. Semantic indexing is an explicit option; its optional runtimes and model downloads are separate from the default path.
Try the beta or a local build from the terminal
Use an explicitly installed 2.3.1-beta.0, a built checkout (pnpm install, then pnpm build in the CBC checkout) or an installed local tarball. From the repository you want to inspect, point Node at that installation's actual entrypoint:
node /path/to/codebase-context/dist/index.js --version
node /path/to/codebase-context/dist/index.js map
node /path/to/codebase-context/dist/index.js search --query "a symbol or feature in this repository" --limit 5
node /path/to/codebase-context/dist/index.js status
Replace the paths and query with your own. For a tarball installed under /path/to/cbc-local, the entrypoint is /path/to/cbc-local/node_modules/codebase-context/dist/index.js. Quote paths containing spaces.
map builds an index when the folder has no previous index. It then returns a bounded repository map. Search returns ranked source locations; open the returned code before relying on it. Low confidence means weak matching evidence, not that an implementation is absent.
To refresh the index, use reindex. Omitting mode flags preserves the recorded mode; reindex --no-embeddings explicitly selects keyword-only indexing. reindex --embeddings selects the configured embedding provider and requires optional LanceDB storage. The default local provider also requires Transformers and may download models; an explicitly configured remote provider has its own connection requirements. Changing modes requires a full rebuild, including when --incremental is supplied.
Set up your AI client
From the target repository, the installed beta or built source can write project registrations for selected detected clients:
node /path/to/codebase-context/dist/index.js init
# Or select one client explicitly:
node /path/to/codebase-context/dist/index.js init --client codex --root /path/to/project --yes
The wizard recognizes Claude Code, Codex, Cursor and OpenCode. It saves the Node binary and package entrypoint that ran setup. If that installation or its npx cache is moved or removed, rerun setup. Writing a config does not prove that a native client connected or completed a coding task.
After registration, restart the client and ask:
Use Codebase Context to find [feature] in this repository. Pass this repository's absolute path as project, wait for indexing if needed, and open the relevant source files.
The client setup guide contains beta setup instructions and dated checks for the older stable package. Historical manual recipes, including Windsurf, retain their dated verification limits. For example, the following manual registration leaves the package version unpinned; it may use an already installed local version or fall back to npm latest, so it does not reliably select the beta:
claude mcp add --scope user --transport stdio codebase-context -- npx -y codebase-context
The default transport is stdio: the client starts the server. HTTP is an advanced option with client-specific setup. Explicit project selection is the portable default. A successful selection becomes active for later calls in that server process; select again after restarting or changing repositories.
What your agent can inspect
- Repository map: structure, detected patterns and example files before narrowing to a task.
- Code search: bounded, ranked results with source locations and search-quality information. The default compact response contains at most six results.
- Symbol references: static identifier occurrences. They are not a runtime call graph.
- File relationships: TypeScript/JavaScript imports and re-exports, with unresolved or stale edges reported. Python and Go import navigation are not supported.
- Team patterns: file-level frequencies and example files. These are observations about the repository, not prescriptions about code quality.
- Project memory:
rememberandget_memorystore and retrieve project conventions, decisions, gotchas and failures. - Review context:
codebase-context-reviewbuilds a bounded packet from a committed Git diff. It does not review code or establish reviewer quality. The review-context guide retains a separate historical version preview; it is not evidence of this candidate's publication.
Dedicated analyzers in the source cover Angular, React, Next.js and NestJS. Other files use the generic analyzer and available parsers. See the capabilities reference for scope and limitations.
Privacy and storage
The default keyword index is built locally. Docker, a GPU and an API key are not required. Optional local embeddings also run on the machine. If you explicitly configure a remote embedding provider, code chunks are sent to that provider.
Your AI client may send returned code to its own model provider; CBC does not control that connection. Project memory also travels with the repository if you commit and push it.
Generated index data should stay out of version control. To share project memory while ignoring the generated index:
.codebase-context/*
!.codebase-context/memory.json
Evidence and limits
The benchmark report and prior report archive describe separate historical experiments. These are retrieval observations, not a winner or a coding-quality claim. This historical evidence does not establish patch correctness or end-to-end coding quality. Versions, fixtures and failure records matter; these reports do not certify this candidate. This draft makes no claim that CBC beats text search, improves coding outcomes, or reduces time or tokens.
The default keyword path can miss natural-language questions when their vocabulary differs from the code. A returned file and a high score are not proof that an answer is correct. Inspect the cited implementation. Optional semantic search has not established a retrieval-quality advantage for this candidate.
Other practical limits:
- The default keyword index holds at most 5,000 searchable chunks per project.
projects[].parsing.maxChunkscan raise that limit. - Search has bounded candidate inspection. Narrow a query when the candidate budget is exhausted; refresh when source files changed or became unavailable.
- Existing formats or incomplete generations can require an explicit rebuild or recovery choice. A failed operation is not a successful recovery.
- Setup evidence differs by client. Config writing, protocol connectivity and native-client task completion are separate checks.
- Stdio routing checks do not establish concurrent HTTP client isolation.
Reference
- Client setup — candidate registration, dated checks and limits
- Capabilities — tools, routing, configuration and optional modes
- CLI — local-candidate commands and historical illustrations
- Benchmark — historical methods, observations and failures
- Contributing — local development and evaluation commands
- Changelog — candidate changes and historical entries
Elastic-2.0. See LICENSE.
Preguntas sobre Codebase Context MCP
¿Cómo agrego Codebase Context MCP a Claude Code?
Ejecuta claude mcp add codebase-context -- npx -y codebase-context en tu terminal. Añade --scope user para que esté disponible en todos los proyectos.
¿Cómo agrego Codebase Context MCP a Cursor?
Abre ~/.cursor/mcp.json y añade el servidor en mcpServers, usando la configuración de Cursor que se muestra en la sección de instalación de arriba.
¿Qué puede inspeccionar un agente de IA con Codebase Context?
El agente puede ver un mapa del repositorio, ejecutar búsquedas de código clasificadas, consultar referencias de símbolos y relaciones entre archivos, observar patrones del equipo y almacenar o recuperar la memoria del proyecto.
¿Requiere Codebase Context Docker, una GPU o una API key?
No. El índice de palabras clave predeterminado se construye localmente sin necesidad de Docker, una GPU o una API key. Los embeddings opcionales también se ejecutan localmente, a menos que configures explícitamente un proveedor remoto.
¿Qué clientes de IA puede configurar automáticamente Codebase Context?
El asistente de inicialización reconoce Claude Code, Codex, Cursor y OpenCode, y escribe los registros de proyecto para ellos.
¿Cuántos resultados devuelve una búsqueda de código por defecto?
La respuesta de búsqueda compacta predeterminada contiene como máximo seis resultados clasificados.
¿Se debe incluir el índice generado en el control de versiones?
No. Debes mantener los datos del índice generado fuera del control de versiones y, opcionalmente, puedes incluir únicamente el archivo de memoria del proyecto.