Codebase Context is an MCP server that lets coding agents inspect a local repository before editing by searching code, navigating symbols, checking patterns, managing project memory, and monitoring index health.
Search indexed code (search_codebase) with natural-language queries, compact/full responses, filters, optional snippets, and edit/refactor/migrate preflight intent.
Get project metadata, dependencies, architecture patterns, and statistics (get_codebase_metadata).
Check indexing status or refresh/re-index (get_indexing_status, refresh_index), including incremental indexing.
Query style guide rules and team patterns (get_style_guide, get_team_patterns).
Find concrete symbol references (get_symbol_references) and detect circular dependencies (detect_circular_dependencies).
Store and retrieve conventions, decisions, gotchas, and failures (remember, get_memory).
Inspect codebase health signals and high-risk files (get_codebase_health).
Route automatically to the active project or accept explicit project paths/URIs, with a deprecated project-directory alias.
Analyzes Angular framework patterns, including signals and standalone components, to provide AI agents with context on team-specific architectural conventions.
Identifies and tracks the usage of Jest testing conventions to help AI assistants follow the project's established testing patterns.
Integrates with OpenAI's API to generate cloud-based vector embeddings for semantic code search and indexing.
Monitors the usage frequency of PrimeNG components to ensure AI agents suggest the correct library wrappers or components based on codebase history.
Parses TypeScript codebases to extract pattern frequencies, library usage statistics, and golden file examples for AI-driven development.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Codebase Context what's our team's pattern for dependency injection in Angular components?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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.
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 statusReplace 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.
Related MCP server: Carto MCP Server
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 --yesThe 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-contextThe 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.
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: remember and get_memory store and retrieve project conventions, decisions, gotchas and failures.
Review context: codebase-context-review builds 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.
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.jsonThe 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.maxChunks can 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.
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.
Routes to the active/current project automatically when known. Analyze the import graph to detect circular dependencies between files. Circular dependencies can cause initialization issues, tight coupling, and maintenance problems. Returns all detected cycles sorted by length (shorter cycles are often more problematic).
Inputs: scope, project, project_directory.
Routes to the active/current project automatically when known. Get actionable codebase health signals from the latest index. Returns the highest-risk files and their reasons, or a single file when requested.
Inputs: file, limit, level, project, +1 more.
Routes to the active/current project automatically when known. Get codebase metadata including framework information, dependencies, architecture patterns, and project statistics.
Inputs: project, project_directory.
Routes to the active/current project automatically when known. Get current indexing status: state, statistics, and progress. Use refresh_index to manually trigger re-indexing when needed.
Inputs: project, project_directory.
Routes to the active/current project automatically when known. Retrieves team conventions, architectural decisions, and known gotchas. CALL BEFORE suggesting patterns, libraries, or architecture.
Filters: category (tooling/architecture/testing/dependencies/conventions), type (convention/decision/gotcha), query (keyword search).
Inputs: category, type, query, project, +1 more.
Routes to the active/current project automatically when known. Query style guide rules and architectural patterns from project documentation.
Inputs: query, category, project, project_directory.
Routes to the active/current project automatically when known. Find concrete references to a symbol in indexed chunks. Returns total usageCount and top usage snippets.
Inputs: symbol (required), limit, project, project_directory.
Routes to the active/current project automatically when known. Get actionable team pattern recommendations based on codebase analysis. Returns consensus patterns for DI, state management, testing, library wrappers, etc.
Inputs: category, project, project_directory.
Routes to the active/current project automatically when known. Re-index the codebase. Supports full re-index or incremental mode. Use incrementalOnly=true to only process files changed since last index.
Inputs: reason, incrementalOnly, project, project_directory.
Routes to the active/current project automatically when known. CALL IMMEDIATELY when user explicitly asks to remember/record something.
USER TRIGGERS:
"Remember this: [X]"
"Record this: [Y]"
"Save this for next time: [Z]"
DO NOT call unless user explicitly requests it.
HOW TO WRITE:
ONE convention per memory (if user lists 5 things, call this 5 times)
memory: 5-10 words (the specific rule)
reason: 1 sentence (why it matters)
Skip: one-time features, code examples, essays
Inputs: type (required), category (required), memory (required), reason (required), +3 more.
Routes to the active/current project automatically when known. Search the indexed codebase. Default compact mode returns at most 6 ranked results with light graph context (importedByCount, topExports, layer), a patternSummary, bestExample, nextHops, and response-budget metadata. Use mode="full" for today's richer response with full hints arrays and all memories — identical shape as before this parameter existed. IMPORTANT: Pass the intent="edit"|"refactor"|"migrate" to get preflight: edit readiness check with evidence gating.
Inputs: query (required), mode, intent, limit, +4 more.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 11 tools
Each tool targets a distinct aspect of codebase context: detection, health, metadata, indexing, memory, style guide, references, patterns, refresh, remember, and search. No two tools have overlapping purposes; descriptions clearly differentiate them.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., get_codebase_health, detect_circular_dependencies). The only exception is 'remember' which is a single verb but remains clear and fits the pattern.
11 tools is well-scoped for a codebase context server. It covers indexing, querying, analysis, and memory without being overwhelming. Each tool earns its place.
The tool set covers reading and writing codebase knowledge, analysis (dependencies, health, references), and search. Minor gaps exist, such as no direct file content retrieval or code review integration, but the domain of 'context' is well-served.
Your team's shipping standards, org map and delivery metrics, inside your coding agent.
Codebase intelligence for AI agents — dead code, blast radius, ownership.
Serves your design system and coding standards to coding agents, so they stop guessing.
Give your AI agent a persistent map of your project's structure, dependencies, and bugs.
