The codebase-context server is an MCP server that helps AI agents understand and navigate codebases by providing structured context, convention analysis, and targeted information retrieval.
Search codebase (search_codebase): Natural language searches with filters for architectural layer, framework, language, component type, and tags — returns ranked results with file summaries, scores, pattern trends, and a preflight decision card for edit intent.
Get team patterns (get_team_patterns): Detect active team conventions for DI, state management, testing, and library usage, including adoption percentages, trend directions (rising/stable/declining), golden file examples, and conflict detection.
Manage team memory (remember / get_memory): Record and retrieve conventions, architectural decisions, and known gotchas with confidence decay; these automatically surface in search results and preflight cards.
Get codebase metadata (get_codebase_metadata): Retrieve detected frameworks, dependencies, architecture patterns, and project statistics.
Get style guide (get_style_guide): Query style rules and architectural patterns from project docs, filterable by category.
Find component usage (get_component_usage): Discover all files importing a specific package or module.
Detect circular dependencies (detect_circular_dependencies): Analyze the import graph for cycles, optionally scoped to a path prefix.
Indexing (get_indexing_status / refresh_index): Monitor index state and trigger full or incremental re-indexing (incremental processes only changed files).
Multi-project support: Route requests across multiple repositories from a single server instance.
Broad language support: Full symbol extraction for 10 languages (TypeScript, JavaScript, Python, Java, Kotlin, C, C++, C#, Go, Rust) and indexing/retrieval for 30+ languages.
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.
Coding agents can read files, but they still have to discover how your repository is organized, which patterns your team follows, and which examples are worth copying.
Codebase Context gives an agent a local view of that information through code search, team patterns, strong examples, and project memory. It runs as an MCP server - a local tool that your editor or command-line agent can call while it works - and keeps the index on your machine by default.
Related MCP server: Carto MCP Server
Choose your coding tool and run its command once. Use Node.js 22 or newer. These commands use published npm 2.2.0 and do not require a project folder in your configuration:
# Claude Code
claude mcp add --scope user --transport stdio codebase-context -- npx -y codebase-context@2.2.0
# Codex CLI
codex mcp add codebase-context -- npx -y codebase-context@2.2.0
# OpenCode 1.x (keep the quoted separator on Windows)
opencode mcp add codebase-context '--' npx -y codebase-context@2.2.0Start a new agent session in your project, then ask:
Use Codebase Context to find [feature] in this repository. Pass this repository's absolute path as project when checking get_indexing_status and searching. Wait for indexing if needed, read codebase://context, then search_codebase and open a returned source file. Show me the relevant files.
Replace [feature] with something you want to find. The agent supplies the repository path in its tool calls, so the registration can serve different projects. Initial indexing may need a local model download. The October 6 isolated checks proved these client registrations and published-package project selection/search; they did not establish a full native agent investigation.
For Codex Desktop, create or merge .codex/config.toml in the project you want to search:
[mcp_servers.codebase-context]
command = "npx"
args = ["-y", "codebase-context@2.2.0"]
startup_timeout_sec = 120Trust the project if asked, restart Codex, and start a new task there. Use the prompt above. Config placement alone does not establish successful first use; this no-folder recipe has not been accepted in a fresh native Desktop task.
Other clients use their own setup commands:
Client | Shortest current setup |
Gemini CLI |
|
Cursor | Add |
VS Code with GitHub Copilot | Add |
GitHub Copilot CLI |
|
Windsurf | Add |
Check an existing same-name entry before replacing it. To give the server a default folder, append that folder's absolute path to the npx arguments. The client setup guide covers scopes, optional fixed-folder configuration, verification limits and the unreleased installer. Published 2.2.0's interactive init has registration bugs; use the commands above.
The client setup guide has the exact commands and config for every client, plus what was checked locally and what still relies on official instructions.
The default connection is stdio (standard input/output): your client starts the server when it needs it. HTTP is an advanced, client-dependent option; verify the setup guide and client support before relying on it.
search_codebase ranks files and symbols for the task instead of returning an unstructured dump. The agent can ask for a compact result first, then read the code it needs.
get_team_patterns shows the approaches used in the repository and points to representative files. Published 2.2.0 includes dedicated analyzers for Angular, React and Next.js, with a generic analyzer for other stacks. NestJS support belongs to the newer source candidate.
remember stores a convention, decision, gotcha, or past failure for the project. get_memory retrieves relevant entries in later sessions, including when the agent or editor changes.
Index locally. Codebase Context scans the project, builds a keyword index, and creates local semantic embeddings - numeric representations used to match code by meaning as well as exact words.
Understand the repository. The agent can request a compact codebase map with structure, patterns, and representative files.
Find the code for the task. Search returns ranked files and symbols; the agent reads the selected files before editing.
The same information is available from the terminal. Run these commands from your project root. The first index can take a while because it scans the project and creates local embeddings; once it is ready, inspect the map and search for the code you need:
# Build or refresh the local index
npx -y codebase-context@2.2.0 reindex
# Repository structure, patterns, and representative files
npx -y codebase-context@2.2.0 map
# Ranked code search
npx -y codebase-context@2.2.0 search --query "auth middleware"
# Current team patterns
npx -y codebase-context@2.2.0 patternsOne stdio server can route across several repositories. Supply project in tool calls to select the intended repository; a successful selection becomes the default for later calls in that process. Some clients also announce workspace roots: one root can auto-select, while an ambiguous selection asks for a project instead of guessing. MCP deprecated Roots in its July 2026 revision, so explicit project selection is the documented default rather than a dependency on client discovery.
These are real CLI results from the open-source angular-spotify repository.
Patterns and representative files
The map shows the patterns found in the project, how common they are, and files that demonstrate them.
Search before an edit
The search result shows ranked files, relevant project patterns, and what the agent should read before it changes code.
More examples are available in the CLI gallery and walkthrough.
Code and indexes stay on the machine with the default local embedding provider. Docker, a GPU, and an API key are not required.
Cloud embeddings are optional. If you select a cloud provider, code chunks are sent to that provider to create the search index. The provider, model, project root, and local HTTP port can be changed through environment variables or the project config; see the capabilities reference.
This is the privacy boundary of Codebase Context itself. Your AI client may send search results or file contents to the model provider configured in that client. Codebase Context does not control that connection. If you commit and push .codebase-context/memory.json, the recorded project memory also travels with the repository.
Generated indexes belong in .gitignore. Project memory can be kept in version control when the team wants to share it:
.codebase-context/*
!.codebase-context/memory.jsonCodebase Context runs locally through the Model Context Protocol (MCP), with indexed code kept on your machine by default.
Its ranked code search combines Match words, Search by meaning, and Rank results to give the agent ranked files, a best example, project patterns, relationships, and relevant memory before they edit.
The benchmark reports a corrected 100-attempt retrieval family across five local code-context tools: 99 completed attempts and 1 failed attempt. Codebase Context recovered 25.7% of expected gold files with 11.5% file precision in that fixed adapter run; jCodeMunch recovered 27.1% with 11.0% file precision. Raw-native is a deterministic lexical adapter here, not a full normal coding-agent baseline. These are retrieval observations, not a winner or a coding-quality claim. The sanitized evidence extract records the exact values and source hashes.
The same report retains a separate 300-attempt repeatability history, a 30-run two-task full-agent pilot, and a metered replay whose tool-use validity remains unresolved. A historical Codebase Context indexing observation with embeddings enabled took about 12 minutes 31 seconds, but it does not establish warm-use speed, query latency, install cost, or a cross-tool index-speed ranking. The report does not combine these families into a pooled score and does not establish patch correctness or end-to-end coding quality. Earlier public reports are preserved separately in the benchmark archive.
The method and failures are documented so the measurements can be inspected with their limits.
Local semantic indexing does more work than a plain text index, especially on a fresh checkout and CPU-only machine.
Retrieval measurements describe expected-file coverage, file precision, and reported peakPrivateGb, not patch correctness or end-to-end coding quality.
The paired token observation covers two frozen investigation tasks and records observed agent behavior; it is not a universal token or time guarantee.
Setup checks differ by client. The detailed guide distinguishes a written config, a config recognized by the client, a local connection, and instructions checked only against official docs.
Published 2.2.0 has dedicated Angular, React and Next.js analyzers; NestJS support is in the newer source candidate. Other projects use the generic analyzer and the language parsers available for that stack.
The default searchable-chunk limit is 5,000 per project. Larger repositories can raise it in .codebase-context/config.json.
The agent must identify its repository in tool calls when no default or unambiguous client root is available. Concurrent HTTP client isolation is not established by the stdio routing checks.
Client setup - commands, config, proof level, and client limits
Capabilities - tools, response fields, routing, and configuration
CLI - terminal commands and example output
Benchmark - method, measurements, and failures
Demo - a complete repository walkthrough
Motivation - the design problem and research background
Contributing - local development and evaluation commands
Changelog - release history
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).
| Name | Required | Description | Default |
|---|---|---|---|
| scope | No | Optional path prefix to limit analysis (e.g., 'src/features', 'libs/shared') | |
| project | No | Optional project selector for this call. Accepts a project root path, file path, file:// URI, or a relative subproject path under a configured root. | |
| project_directory | No | Deprecated compatibility alias for older clients. Prefer project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It reveals that results are sorted by length and notes that shorter cycles are often more problematic. However, it does not explicitly state whether the operation is read-only or has side effects, nor does it mention performance implications for large codebases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, efficient but with a minor redundancy: the first sentence about routing ('Routes to the active/current project automatically') is not central to the tool's purpose. Overall, it is well-structured and front-loads the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains return value sorting and interpretation but lacks details on output format, data structure of cycles, or potential limitations (e.g., large graphs). Given no output schema, this is adequate but leaves ambiguity for complex filtering needs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all three parameters with descriptions, achieving 100% schema description coverage. The tool description does not add meaningful detail beyond what the schema already provides (e.g., 'scope' is described as an optional path prefix in both). Baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Analyze the import graph to detect circular dependencies between files.' It identifies a specific verb (analyze/detect) and a distinct resource (circular dependencies in imports), differentiating it from sibling tools like get_codebase_health.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains why circular dependencies are problematic ('can cause initialization issues, tight coupling'), implying the tool's value. However, no explicit guidance on when to use this tool versus alternatives (e.g., get_codebase_health), nor any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| file | No | Optional file path to inspect a single file-level health record. | |
| limit | No | Maximum number of files to return when no file is specified (default: 10). | |
| level | No | Optional minimum health level to return. | |
| project | No | Optional project selector for this call. Accepts a project root path, file path, file:// URI, or a relative subproject path under a configured root. | |
| project_directory | No | Deprecated compatibility alias for older clients. Prefer project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Mentions auto-routing to active project and returns risk info, but does not explicitly state read-only nature or any side effects. Incomplete for a tool with no annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no fluff. First sentence sets behavioral expectation, second states purpose, third gives filtering options. Efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a read tool with good schema coverage, but lacks detail on return format (e.g., what constitutes 'health signals' or 'highest-risk'). Output schema is absent, so more description would help.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. Description adds context for 'file' parameter (why to use it) but largely mirrors schema. Does not compensate for any missing schema details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves actionable codebase health signals, returns highest-risk files with reasons, or single file when requested. It distinguishes from siblings like get_codebase_metadata and detect_circular_dependencies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies routing to active project automatically, so user may not need to specify project, but no explicit when-to-use or when-not-to-use compared to alternatives. Lacks exclusions for specific scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Routes to the active/current project automatically when known. Get codebase metadata including framework information, dependencies, architecture patterns, and project statistics.
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | Optional project selector for this call. Accepts a project root path, file path, file:// URI, or a relative subproject path under a configured root. | |
| project_directory | No | Deprecated compatibility alias for older clients. Prefer project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden of behavioral disclosure. It reveals one behavioral trait (automatic routing), but does not address potential error states, authentication requirements, or the read-only nature of the operation. This provides moderate transparency but leaves gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences, front-loading the key behavioral hint. Every word adds value without redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema and the moderate complexity of the tool (multiple metadata types), the description provides a reasonable overview but does not fully specify the return structure, error conditions, or behavior when no project is known. It is adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for both parameters (project and project_directory). The description adds no additional meaning beyond what the schema already provides. Per the guidelines, with high schema coverage, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves codebase metadata including specific items like framework, dependencies, architecture patterns, and statistics. This sufficiently distinguishes it from sibling tools that have different focuses (e.g., health, style guide), though it could be more explicit about what it does not cover.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions automatic routing to the active project when known, providing some context. However, there is no explicit guidance on when to use this tool versus alternatives like get_codebase_health or get_team_patterns, nor any mention of prerequisites or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | Optional project selector for this call. Accepts a project root path, file path, file:// URI, or a relative subproject path under a configured root. | |
| project_directory | No | Deprecated compatibility alias for older clients. Prefer project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It mentions automatic routing behavior, which is useful. No destructive actions implied, but lacks details on permissions or rate limits. For a read-only status tool, it's transparent enough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff. First sentence gives routing behavior, second gives tool purpose and sibling reference. Exceptionally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, routing, and sibling reference. No output schema, but description mentions return includes state, statistics, and progress. Missing detailed output structure, but adequate for a status check tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. Description adds that project accepts various formats and project_directory is deprecated, slightly complementing schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Get current indexing status: state, statistics, and progress.' Verb and resource are specific, and it distinguishes from sibling refresh_index.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Routes to the active/current project automatically' and 'Use refresh_index to manually trigger re-indexing when needed,' providing clear when-to-use and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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).
| Name | Required | Description | Default |
|---|---|---|---|
| category | No | Filter by category | |
| type | No | Filter by memory type | |
| query | No | Keyword search across memory and reason | |
| project | No | Optional project selector for this call. Accepts a project root path, file path, file:// URI, or a relative subproject path under a configured root. | |
| project_directory | No | Deprecated compatibility alias for older clients. Prefer project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only mentions automatic routing to the active project. It fails to disclose behavioral traits such as read-only nature, side effects, error handling, or limitations, which is a significant gap for a retrieval tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences plus a line listing filters. Every sentence provides essential information without extraneous words, making it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description covers purpose and usage well but lacks details on return values, result count, pagination, or error conditions. It is adequate but not fully complete for a tool that influences important decisions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds value by listing filter enums and query usage, but it omits two parameters (project and project_directory) entirely. Since schema description coverage is 100%, the baseline is 3, but missing param details reduce the added value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves team conventions, architectural decisions, and known gotchas, with automatic routing to the active project. It distinguishes itself from siblings like get_style_guide or get_team_patterns by being a general memory retrieval tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises 'CALL BEFORE suggesting patterns, libraries, or architecture,' providing clear context for when to use. It lacks explicit when-not-to-use or alternative tool mentions, but the usage instruction is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Routes to the active/current project automatically when known. Query style guide rules and architectural patterns from project documentation.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Query for specific style guide rules (e.g., "component naming", "service patterns") | |
| category | No | Filter by category (naming, structure, patterns, testing) | |
| project | No | Optional project selector for this call. Accepts a project root path, file path, file:// URI, or a relative subproject path under a configured root. | |
| project_directory | No | Deprecated compatibility alias for older clients. Prefer project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description reveals the automatic project routing behavior and the query nature, suggesting a read-only operation. However, it does not explicitly state that it is non-destructive, what happens if no project is active, or any error conditions, leaving some behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences, front-loading the key automatic routing feature and then the main query purpose. Every sentence is necessary and without fluff, achieving maximum conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description should explain what the tool returns. It does not describe the return format, error handling, or behavior when no results are found. The deprecated 'project_directory' parameter is not addressed. This leaves significant gaps for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Parameter descriptions in schema cover 100% of parameters, already defining each parameter's purpose. The description adds value by explaining the automatic routing behavior for the optional 'project' parameter, clarifying that omitting it uses the active project, which goes beyond the schema's description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool queries style guide rules and architectural patterns from project documentation, using the verb 'Query' and resource 'style guide rules and architectural patterns'. It distinguishes itself from siblings like search_codebase (which is broader) and get_team_patterns (which is team-specific) by focusing specifically on style guide documentation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for querying style guide rules in the current project due to automatic routing, but does not explicitly state when to use it over alternatives (e.g., search_codebase for general search, get_team_patterns for team patterns). No when-not or explicit alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| symbol | Yes | Symbol name to find references for (for example: parseConfig or UserService) | |
| limit | No | Maximum number of usage snippets to return (default: 10) | |
| project | No | Optional project selector for this call. Accepts a project root path, file path, file:// URI, or a relative subproject path under a configured root. | |
| project_directory | No | Deprecated compatibility alias for older clients. Prefer project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility. It mentions automatic routing to active project and return values, but lacks details on error cases, latency, or index prerequisites. Adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that front-load key information: routing and core function. No fluff, every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description mentions return values (usageCount and snippets). It covers the core function and project routing, but could elaborate on snippet ranking and error conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds little beyond what the schema already provides for parameters. The routing behavior hinted at is not tied explicitly to parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: finding concrete references to a symbol in indexed chunks. It uses specific verbs and resources, and the name itself is descriptive. Though it doesn't explicitly differentiate from siblings, the function is distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like search_codebase or detect_circular_dependencies. The description does not mention prerequisites or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| category | No | Pattern category to retrieve | |
| project | No | Optional project selector for this call. Accepts a project root path, file path, file:// URI, or a relative subproject path under a configured root. | |
| project_directory | No | Deprecated compatibility alias for older clients. Prefer project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Mentions automatic project routing (a behavioral trait) and returns consensus patterns. No side effects or mutability mentioned, but seems read-only.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with key purpose and automatic behavior. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 3 params and no output schema, description is fairly complete: explains what it does, mentions project auto-routing, and lists pattern types. Could clarify return structure or 'consensus patterns' further.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear param descriptions. Description adds context by listing example pattern categories (DI, state, testing) which correspond to the enum values, providing meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool retrieves team pattern recommendations for specific categories (DI, state management, etc.) and mentions automatic project routing. Distinguished from siblings like get_codebase_health and get_style_guide.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance. Context signals and sibling names imply usage for pattern analysis, but no direct alternatives mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No | Reason for refreshing the index (for logging) | |
| incrementalOnly | No | If true, only re-index files changed since last full index (faster). Default: false (full re-index) | |
| project | No | Optional project selector for this call. Accepts a project root path, file path, file:// URI, or a relative subproject path under a configured root. | |
| project_directory | No | Deprecated compatibility alias for older clients. Prefer project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions automatic routeing to the active project and re-indexing behavior, but does not disclose side effects, permissions, or what happens to the existing index. With no annotations, more detail would be beneficial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences conveying essential info, though the first sentence is slightly ambiguous ('Routes to...'). Still, it is concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema is provided, and the description does not explain what the tool returns or how to interpret results, leaving the agent without critical information for a re-index operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All parameters have schema descriptions (100% coverage). The description adds minor guidance on incrementalOnly usage, but mostly restates schema info, so it provides limited added value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it re-indexes the codebase and supports full or incremental modes, distinguishing it from siblings like search_codebase or get_indexing_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It advises using incrementalOnly=true for faster re-indexing of changed files, but does not explicitly state when not to use the tool or mention alternative tools for specific scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | Type of memory being recorded. Use "failure" for things that were tried and failed - prevents repeating the same mistakes. | |
| category | Yes | Broader category for filtering | |
| memory | Yes | What to remember (concise) | |
| reason | Yes | Why this matters or what breaks otherwise | |
| scope | No | Optional scope for this memory. Use { kind: "file", file } or { kind: "symbol", file, symbol }. | |
| project | No | Optional project selector for this call. Accepts a project root path, file path, file:// URI, or a relative subproject path under a configured root. | |
| project_directory | No | Deprecated compatibility alias for older clients. Prefer project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It mentions 'Routes to the active/current project automatically' but does not disclose side effects (e.g., whether memories overwrite, persistence, permissions, or rate limits). The instructions on writing style give some behavioral expectations but leave significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with headings (USER TRIGGERS, DO NOT, HOW TO WRITE) and front-loads the key action. While it is somewhat lengthy, every section serves a purpose. Minor redundancy in listing all triggers could be trimmed, but overall it is well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 7 parameters (4 required) and no output schema, the description provides good guidance on when and how to call, but omits post-call behavior (e.g., success confirmation, error handling). The agent must infer that memories are stored since get_memory exists. Context is adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by providing guidance on how to write 'memory' (5-10 words) and 'reason' (1 sentence), and explains when to use 'failure' type. This enriches the schema descriptions and helps the agent use parameters effectively.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to remember/record something when the user explicitly asks. It lists specific user triggers ('Remember this', 'Record this', 'Save this for next time') and provides instructions for when to call it. This differentiates it from siblings like get_memory, which retrieves memories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidelines: 'CALL IMMEDIATELY when user explicitly asks to remember/record something' and 'DO NOT call unless user explicitly requests it.' It also gives writing conventions ('ONE convention per memory', 'memory: 5-10 words', 'Skip: one-time features, code examples, essays'), making the usage clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Natural language search query | |
| mode | No | Response mode. compact (default): max 6 results with light graph context, pattern summary, best example, next hops, and budget metadata. full: today's richer shape + budget metadata. | compact |
| intent | No | Optional. Use "edit", "refactor", or "migrate" to get the full preflight card before making changes. | |
| limit | No | Maximum number of results to return (default: 5) | |
| includeSnippets | No | Include code snippets in results (default: false). If you need code, prefer read_file instead. | |
| filters | No | Optional filters | |
| project | No | Optional project selector for this call. Accepts a project root path, file path, file:// URI, or a relative subproject path under a configured root. | |
| project_directory | No | Deprecated compatibility alias for older clients. Prefer project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries behavioral transparency. It describes default behavior (compact mode, 6 results, graph context), full mode, intent parameter effects, and hints about response metadata. It also warns about includeSnippets default and recommends read_file for code.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured, front-loading key information about routing and search function. It provides detailed mode and intent guidance but could be more concise by merging some sentences. Overall, it balances detail and readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains the compact mode return shape (graph context, pattern summary, etc.) and mentions budget metadata. It covers filters and parameters. However, it omits error handling, pagination beyond limit, and behavior for empty queries. Still fairly complete for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline is 3. The description adds value by explaining the compact mode result count (at most 6 vs schema default limit of 5), clarifying the intent parameter's role for preflight, and noting the routing behavior for project. This exceeds basic schema info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches the indexed codebase, auto-routes to active project, and details the return format. It distinguishes from siblings like get_codebase_health or detect_circular_dependencies by being a search tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description guides when to use compact vs full mode and when to pass intent for preflight. It notes that includeSnippets is false by default and to prefer read_file. However, it does not contrast with sibling tools or mention when not to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.6.0detect_circular_dependencies2 fields changedInput schema / properties / projectAdded value: +{
+ "description": "Optional project selector for this call. Accepts a project root path, file path, file:// URI, or a relative subproject path under a configured root.",
+ "type": "string"
+}Input schema / properties / project_directoryAdded value: +{
+ "description": "Deprecated compatibility alias for older clients. Prefer project.",
+ "type": "string"
+}get_codebase_healthget_codebase_metadata2 fields changedInput schema / properties / projectAdded value: +{
+ "description": "Optional project selector for this call. Accepts a project root path, file path, file:// URI, or a relative subproject path under a configured root.",
+ "type": "string"
+}Input schema / properties / project_directoryAdded value: +{
+ "description": "Deprecated compatibility alias for older clients. Prefer project.",
+ "type": "string"
+}get_component_usageget_indexing_status2 fields changedInput schema / properties / projectAdded value: +{
+ "description": "Optional project selector for this call. Accepts a project root path, file path, file:// URI, or a relative subproject path under a configured root.",
+ "type": "string"
+}Input schema / properties / project_directoryAdded value: +{
+ "description": "Deprecated compatibility alias for older clients. Prefer project.",
+ "type": "string"
+}get_memory3 fields changedInput schema / properties / projectAdded value: +{
+ "description": "Optional project selector for this call. Accepts a project root path, file path, file:// URI, or a relative subproject path under a configured root.",
+ "type": "string"
+}Input schema / properties / project_directoryAdded value: +{
+ "description": "Deprecated compatibility alias for older clients. Prefer project.",
+ "type": "string"
+}Input schema / properties / type / enumPrevious value: -[
- "convention",
- "decision",
- "gotcha"
-]New value: +[
+ "convention",
+ "decision",
+ "gotcha",
+ "failure"
+]get_style_guide3 fields changedInput schema / properties / projectAdded value: +{
+ "description": "Optional project selector for this call. Accepts a project root path, file path, file:// URI, or a relative subproject path under a configured root.",
+ "type": "string"
+}Input schema / properties / project_directoryAdded value: +{
+ "description": "Deprecated compatibility alias for older clients. Prefer project.",
+ "type": "string"
+}Input schema / requiredRemoved value: -[
- "query"
-]get_symbol_referencesget_team_patterns2 fields changedInput schema / properties / projectAdded value: +{
+ "description": "Optional project selector for this call. Accepts a project root path, file path, file:// URI, or a relative subproject path under a configured root.",
+ "type": "string"
+}Input schema / properties / project_directoryAdded value: +{
+ "description": "Deprecated compatibility alias for older clients. Prefer project.",
+ "type": "string"
+}refresh_index2 fields changedInput schema / properties / projectAdded value: +{
+ "description": "Optional project selector for this call. Accepts a project root path, file path, file:// URI, or a relative subproject path under a configured root.",
+ "type": "string"
+}Input schema / properties / project_directoryAdded value: +{
+ "description": "Deprecated compatibility alias for older clients. Prefer project.",
+ "type": "string"
+}remember5 fields changedInput schema / properties / projectAdded value: +{
+ "description": "Optional project selector for this call. Accepts a project root path, file path, file:// URI, or a relative subproject path under a configured root.",
+ "type": "string"
+}Input schema / properties / project_directoryAdded value: +{
+ "description": "Deprecated compatibility alias for older clients. Prefer project.",
+ "type": "string"
+}Input schema / properties / scopeAdded value: +{
+ "description": "Optional scope for this memory. Use { kind: \"file\", file } or { kind: \"symbol\", file, symbol }.",
+ "properties": {
+ "file": {
+ "type": "string"
+ },
+ "kind": {
+ "enum": [
+ "global",
+ "file",
+ "symbol"
+ ],
+ "type": "string"
+ },
+ "symbol": {
+ "type": "string"
+ }
+ },
+ "type": "object"
+}Input schema / properties / type / descriptionPrevious value: -"Type of memory being recorded"New value: +"Type of memory being recorded. Use \"failure\" for things that were tried and failed - prevents repeating the same mistakes."Input schema / properties / type / enumPrevious value: -[
- "convention",
- "decision",
- "gotcha"
-]New value: +[
+ "convention",
+ "decision",
+ "gotcha",
+ "failure"
+]search_codebase6 fields changedInput schema / properties / filters / properties / framework / descriptionPrevious value: -"Filter by framework (angular, react, vue)"New value: +"Filter by framework (angular, react, nextjs, vue)"Input schema / properties / includeSnippetsAdded value: +{
+ "default": false,
+ "description": "Include code snippets in results (default: false). If you need code, prefer read_file instead.",
+ "type": "boolean"
+}Input schema / properties / intentAdded value: +{
+ "description": "Optional. Use \"edit\", \"refactor\", or \"migrate\" to get the full preflight card before making changes.",
+ "enum": [
+ "explore",
+ "edit",
+ "refactor",
+ "migrate"
+ ],
+ "type": "string"
+}Input schema / properties / modeAdded value: +{
+ "default": "compact",
+ "description": "Response mode. compact (default): max 6 results with light graph context, pattern summary, best example, next hops, and budget metadata. full: today's richer shape + budget metadata.",
+ "enum": [
+ "compact",
+ "full"
+ ],
+ "type": "string"
+}Input schema / properties / projectAdded value: +{
+ "description": "Optional project selector for this call. Accepts a project root path, file path, file:// URI, or a relative subproject path under a configured root.",
+ "type": "string"
+}Input schema / properties / project_directoryAdded value: +{
+ "description": "Deprecated compatibility alias for older clients. Prefer project.",
+ "type": "string"
+}v1.4.1detect_circular_dependenciesget_codebase_metadataget_component_usageget_indexing_statusget_memoryget_style_guideget_team_patternsrefresh_indexremembersearch_codebaseScored 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.
