一个本地优先、无需 API Key 的代码库检索 MCP Server。它扫描指定仓库，按代码窗口分块，并通过 BM25、符号名、文件路径和精确匹配进行混合排序，可直接接入 Codex，也提供标准 search / fetch 工具用于 ChatGPT 知识检索场景。
优先使用 git ls-files，遵守仓库的嵌套 .gitignore；非 Git 目录使用文件系统扫描。
支持 TypeScript、JavaScript、Python、Go、Rust、Java、C/C++、C#、Ruby、Shell、SQL、Markdown、Vue、Svelte 等常见文本代码格式。
自动拆分 camelCase、snake_case 和路径词，支持常见中文代码查询扩展，例如“用户登录认证”。
返回精确文件路径、行号、带行号代码片段、匹配原因和可继续读取的稳定 ID。
路径读取限定在配置的仓库根目录；默认跳过符号链接、二进制、密钥、环境变量文件、压缩代码和大文件。
同时支持本地 stdio 与无状态 Streamable HTTP /mcp。
Related MCP server: mcplens
要求 Node.js 20 或更高版本。
从 GitHub 获取项目：
git clone https://github.com/sudoriaa/codebase-rag-mcp.git
cd codebase-rag-mcp安装依赖并构建：
npm install
npm run build
node dist/cli.js --root C:/path/to/your-repository最后一条命令会启动 stdio MCP Server，它会等待 MCP 客户端连接，因此终端保持运行属于正常状态。
将以下内容放进用户级 %USERPROFILE%/.codex/config.toml，或者受信任仓库的 .codex/config.toml：
[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 = 120Windows TOML 路径建议使用 /。command 只填写可执行程序，其他参数分别放入 args。桌面应用继承的 PATH 可能与 PowerShell 不同，因此长期使用时建议填写 node.exe 的绝对路径。
也可以用 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配置后重启 Codex 桌面应用或 IDE 扩展。示例配置见 examples/codex-config.toml。
node dist/cli.js --root C:/path/to/your-repository --transport http --host 127.0.0.1 --port 3000端点：
MCP：http://127.0.0.1:3000/mcp
健康检查：http://127.0.0.1:3000/health
引用源文件：http://127.0.0.1:3000/source/:documentId
默认仅监听本机。部署到其他机器时，应在反向代理层加入 TLS、身份认证和访问控制，并用 --public-base-url 设置模型可访问的规范地址。
直接监听 0.0.0.0 或其他非本机地址时，服务会要求设置 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客户端随后需要为 /mcp 和 /health 发送 Authorization: Bearer <token>。服务返回的引用地址会自动附带 HMAC 签名，因此用户可以直接打开对应 /source 链接；手工访问未签名的 /source 地址仍需 Bearer Token。通过本机反向代理发布时，可以继续让服务监听 127.0.0.1，并由代理负责外部认证。
工具 | 用途 |
| 标准文档搜索，返回 |
| 根据 |
| 混合检索代码片段，可按路径、语言、符号类型和测试文件过滤 |
| 根据 chunk ID 获取前后文，最多扩展 200 行 |
| 查找类、函数、方法、接口、类型和枚举定义 |
| 返回文件的 imports 和符号大纲 |
| 查看索引统计及跳过原因 |
| 文件变化后重新扫描并重建内存索引 |
推荐调用顺序：
用 search_code 查找实现和相关片段。
用 get_code_context 展开高分片段。
精确定位定义时用 find_symbol。
只有确实需要完整文件时再用 fetch。
索引完全运行在本机内存中：
代码文件按最多 120 行、20 行重叠切片。
从常见语言声明中提取 class、interface、type、enum、function、method 等符号。
正文使用 BM25 召回，符号和路径单独排序。
使用 reciprocal-rank fusion 合并正文、符号、路径和精确匹配得分。
默认每个文件最多返回两个片段，避免重复模板代码占满结果。
这一版没有外部向量数据库，也不会上传源码。对于大规模多仓库、跨语言语义检索，可以在现有 CodebaseIndex.search 前后增加 embedding 召回或 reranker，MCP 工具契约无需变化。
--root PATH
--transport stdio|http
--host HOST
--port PORT
--public-base-url URL
--max-file-bytes N
--max-files N对应环境变量为：
CODEBASE_ROOT
CODEBASE_TRANSPORT
CODEBASE_HOST
CODEBASE_PORT
CODEBASE_PUBLIC_BASE_URL
CODEBASE_MCP_TOKEN
CODEBASE_MAX_FILE_BYTES
CODEBASE_MAX_FILES默认单文件上限为 1 MiB，文件数量上限为 20,000。
npm run build
npm test测试覆盖索引构建、.gitignore、中文查询扩展、符号与路径过滤、路径越界、标准 search/fetch、内存 MCP、真实 stdio 子进程和 Streamable HTTP。
MCP Inspector 也可以直接检查 HTTP 服务：
npx @modelcontextprotocol/inspector然后选择 Streamable HTTP 并填写 http://127.0.0.1:3000/mcp。
实现遵循 OpenAI 官方 MCP Server 指南及标准 search / fetch 数据形状。
索引在进程重启后重建，没有持久化缓存。
Git 仓库完整遵守 Git 忽略规则；非 Git 目录目前读取根目录 .gitignore。
符号抽取采用轻量声明解析，不等同于完整编译器 AST。
文件变化后调用 refresh_index；当前版本未启用文件监听。
MIT
Fetch the complete text and metadata for a document ID returned by search or search_code.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Document ID returned by search, such as code:... |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| url | Yes | |
| text | Yes | |
| title | Yes | |
| metadata | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only behavior. The description adds that the tool returns 'complete text and metadata', which is useful beyond the annotations. It does not disclose potential size limits or error handling, but the added value is solid.
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?
A single sentence that is completely front-loaded, containing all essential information without any wasted words. It is optimally 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?
Given the tool's low complexity (one parameter, output schema exists), the description is fully complete. It explains what the tool does, what input is expected, and where that input comes from, leaving no gaps.
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 schema has 100% description coverage, but the description enriches the parameter by specifying the source of the ID ('returned by search or search_code') and providing an example format ('code:...'), which adds meaning beyond the schema's minimal 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 action ('fetch complete text and metadata') and the specific resource ('document ID returned by search or search_code'). It distinguishes from sibling tools like search and search_code by focusing on retrieval of a single document by ID, not searching.
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 ties usage to document IDs from search or search_code, providing clear context for when to use. It does not explicitly state when not to use or list alternatives, but the context is sufficient given the sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find class, function, method, interface, type, enum, module, or variable definitions by identifier.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | ||
| name | Yes | ||
| topK | No | ||
| pathGlob | No |
| Name | Required | Description |
|---|---|---|
| results | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description does not need to restate these. The description adds the list of symbol kinds, which partially overlaps with the enum in the schema. It does not disclose further behavioral traits such as case sensitivity, fuzzy matching, scope (entire workspace vs. single file), or whether an index must be present. Given the annotations, the description is adequate but not additive beyond them.
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 a single, well-formed sentence that front-loads the core purpose. It contains zero wasted words and is as concise as possible while remaining informative.
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 tool has 4 parameters and an output schema (not shown). The description covers the high-level purpose but lacks context about tool dependencies (e.g., requiring an index, since sibling refresh_index exists). It does not mention behavior when no symbols are found, scope of search, or return structure. With an output schema present, return values are covered, but completeness still falls short on behavioral context for tool selection.
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 0%, so the description must compensate. It mentions 'by identifier' which maps to the required 'name' parameter. The listing of symbol kinds (class, function, etc.) corresponds to the optional 'kind' enum, but the description does not clarify that this is a filter parameter. The 'topK' and 'pathGlob' parameters are not mentioned at all. The description adds partial value but not enough to fully compensate for the 0% schema coverage.
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 'Find class, function, method, interface, type, enum, module, or variable definitions by identifier.' The verb 'find' and resource 'definitions by identifier' are specific. It lists all supported symbol kinds, differentiating it from sibling tools like search (general text) and search_code (code content search).
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 symbol definition lookup by name, but does not explicitly state when to use this tool versus alternatives like search for text or search_code for code snippets. There is no mention of prerequisites (e.g., requirement for an indexed repository) or exclusions. Usage context is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a matched code chunk with configurable surrounding lines. Use the chunkId returned by search_code.
| Name | Required | Description | Default |
|---|---|---|---|
| chunkId | Yes | ||
| contextLines | No |
| Name | Required | Description |
|---|---|---|
| url | Yes | |
| path | Yes | |
| text | Yes | |
| chunkId | Yes | |
| endLine | Yes | |
| language | Yes | |
| startLine | Yes | |
| documentId | Yes | |
| chunkEndLine | Yes | |
| chunkStartLine | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description need not restate safety. It adds value by noting that the output is a 'code chunk' with surrounding lines, and the chunkId follows a pattern '^chunk:.*'. No contradictions.
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, zero wasted words. The first sentence states core function and key feature. The second sentence connects to the only required parameter's source. Perfectly 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?
The tool has only 2 parameters (1 required), a clear input schema, an output schema (acknowledged in context but not needed to explain), and strong annotations. The description plus schema fully cover what an agent needs to select and invoke this tool correctly. No gaps remain.
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 0%, so the description must compensate. It clearly explains the purpose of chunkId (a matched chunk identifier from search_code) and contextLines (configurable surrounding lines). This adds meaningful context beyond the bare schema fields. The description does not specify the units of contextLines, but the schema's default of 20 implies it's number of lines, which is reasonable.
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 a 'matched code chunk' and specifies the configurable 'surrounding lines' feature. It also tells the agent to use the 'chunkId returned by search_code', which distinguishes it from sibling tools like search_code or search.
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 says to use the chunkId returned by search_code, providing a clear prerequisite and linking to a sibling tool. However, it does not mention when not to use it or provide alternatives, e.g., if the agent needs the whole file, fetch or get_file_outline might be more suitable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return imports and symbol definitions for an indexed repository-relative path.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
| Name | Required | Description |
|---|---|---|
| url | Yes | |
| path | Yes | |
| imports | Yes | |
| symbols | Yes | |
| language | Yes | |
| documentId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds that the tool requires an 'indexed' path and returns imports plus symbol definitions, which is useful beyond the readOnlyHint annotation. However, it does not explain what 'indexed' means, error handling for non-indexed files, or any limits, leaving gaps that the output schema may partially fill.
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 a single sentence with the verb upfront, no redundant words. Every part contributes meaning, and it is appropriately brief for a simple tool.
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 tool's simplicity (one parameter, output schema exists), the description is mostly complete. It covers the input and output concept. It could note that the file must be indexed (implied but not explicit) or mention error states, but the presence of an output schema reduces the burden.
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 0% description coverage with one parameter 'path.' The description clarifies it must be a 'repository-relative path' that is indexed, adding meaning beyond the raw schema type and constraints. This compensates well for the lack of schema descriptions, though a bit more specificity (e.g., leading slash format) would be ideal.
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 verb 'Return' and the resource 'imports and symbol definitions' for an 'indexed repository-relative path.' This distinguishes it from sibling tools like search, fetch, or find_symbol, which serve different purposes.
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 guidance is provided on when to use this tool versus alternatives like find_symbol or get_code_context. The description does not mention when not to use it or any prerequisites, leaving the agent to infer from the name and context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return repository root, index time, counts, duration, and skipped-file statistics.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| root | Yes | |
| skipped | Yes | |
| fileCount | Yes | |
| indexedAt | Yes | |
| chunkCount | Yes | |
| durationMs | Yes | |
| symbolCount | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds value by specifying the returned fields, but does not disclose any additional behavioral traits (e.g., whether the data is cached, if it requires prior indexing, or if it's always available).
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?
Single sentence, front-loaded with the action verb 'Return', and no extraneous words. Every element is necessary and informative.
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 tool has no parameters, an output schema, and safe annotations, the description is mostly complete. It lists all key return fields. However, it lacks detail on the format or units of 'duration' and what 'counts' specifically includes (e.g., total files, indexed vs skipped). Slight room for improvement.
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?
There are zero parameters, so schema coverage is 100% by default. The description compensates by explaining what the tool returns, which adds meaning beyond the empty schema. However, it could be more precise about the structure of 'counts' and 'duration'.
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 uses a specific verb 'Return' and lists exact data points (repository root, index time, counts, duration, skipped-file statistics), clearly distinguishing it from sibling tools like search (queries) and refresh_index (modifies).
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 is provided on when to use this tool versus alternatives. For example, it does not indicate that it should be used to check index readiness before searching or that it complements refresh_index. The description is purely functional.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rescan the configured repository and rebuild the in-memory retrieval index after files change. Repository files are never modified.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| root | Yes | |
| skipped | Yes | |
| fileCount | Yes | |
| indexedAt | Yes | |
| chunkCount | Yes | |
| durationMs | Yes | |
| symbolCount | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=false and destructiveHint=false. The description adds valuable context: 'Repository files are never modified,' which clarifies that the mutation is limited to an in-memory index. This goes beyond the annotations but could mention other behaviors like reindexing scope or performance impact.
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 wasted words. The first sentence delivers the core purpose and trigger condition; the second sentence adds a safety clarification. Front-loaded and efficient.
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 tool has no parameters and an output schema exists, the description is largely complete. It covers the action, trigger, and safety guarantee. It could be slightly more explicit about prerequisites (e.g., 'configured repository' is assumed), but overall it's sufficient for a simple 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?
There are no parameters, so the description cannot add meaning beyond the schema. The zero-parameter baseline is 4, and the description does not misrepresent 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 action ('Rescan the configured repository and rebuild the in-memory retrieval index') and the condition ('after files change'). It uses specific verbs and resources, and distinguishes this tool from siblings like search and fetch by focusing on index maintenance.
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 when to use the tool ('after files change') but provides no explicit guidance on when not to use it or alternatives (e.g., 'use search_code for queries'). The context is clear but lacks exclusionary language.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search indexed repository files. This standard read-only search tool is compatible with ChatGPT company knowledge and returns document IDs for fetch.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Natural-language, identifier, error text, or path query. |
| Name | Required | Description |
|---|---|---|
| results | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds value by specifying that it returns document IDs (implying no inline content) and that it is compatible with ChatGPT company knowledge, providing additional behavioral context beyond the 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?
Two sentences, front-loaded with the primary action, and each sentence adds unique value (scope, read-only nature, output type). No wasted words; ideal length.
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 one parameter, annotations covering safety, an output schema (so return values not needed in description), and sibling tools providing contrast, the description is mostly complete. It mentions compatibility with ChatGPT company knowledge and the flow to fetch, which is sufficient. Minor gap: no mention of result limits or ordering, but not critical.
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 already describes the single parameter 'query' with a full description ('Natural-language, identifier, error text, or path query.'). The description adds no additional parameter guidance, so with 100% schema coverage the baseline score 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 'Search indexed repository files' as the verb+resource, and further distinguishes itself from siblings by noting it is a general search (not code-specific) that returns document IDs compatible with the 'fetch' tool. This provides clear differentiation from sibling tools like search_code.
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 clear context: it is a standard read-only search tool for indexed repository files, compatible with ChatGPT company knowledge, and returns IDs for subsequent fetch. While it does not explicitly list when not to use it, the mention of returning IDs for fetch implicitly guides the agent to use fetch for retrieval, and the sibling names help differentiate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run hybrid BM25, symbol, path, and exact-match retrieval over code chunks. Use this first for implementation, behavior, error, and call-site questions.
| Name | Required | Description | Default |
|---|---|---|---|
| topK | No | ||
| query | Yes | ||
| pathGlob | No | Optional repository-relative globs, for example ['src/**/*.ts', 'packages/api/**']. | |
| languages | No | ||
| symbolKinds | No | ||
| includeTests | No |
| Name | Required | Description |
|---|---|---|
| query | Yes | |
| results | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is clear. The description adds behavioral detail: 'hybrid BM25, symbol, path, and exact-match retrieval' and 'over code chunks,' which informs the agent about the retrieval strategy and granularity. This goes beyond the 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?
The description is two sentences long, front-loaded with the action, and every word adds value. There is no redundancy or fluff. It efficiently conveys the tool's purpose and primary usage scenario.
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 tool has 6 parameters, an output schema, and annotations, the description adequately covers purpose and usage but lacks guidance on parameter usage and interpretation of results. The output schema exists, so return values need not be detailed, but the description does not help the agent understand how to leverage the filtering parameters (pathGlob, languages, symbolKinds) effectively. This leaves gaps for a complex 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?
The input schema has 6 parameters with only 17% description coverage (only pathGlob has a description). The description does not mention any parameter or provide additional meaning beyond the schema. For a tool with low schema coverage, the description should compensate but does not, leaving the agent uninformed about how to use parameters like languages, symbolKinds, or includeTests.
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 starts with a specific verb ('Run hybrid BM25, symbol, path, and exact-match retrieval') and clearly identifies the resource ('code chunks'). It distinguishes from sibling tools by stating 'Use this first for implementation, behavior, error, and call-site questions,' implying it is the primary general-purpose code search tool, whereas tools like 'find_symbol' or 'get_code_context' are more specialized.
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 when to use this tool: 'Use this first for implementation, behavior, error, and call-site questions.' This gives clear context for usage. However, it does not mention when not to use it or name specific alternatives (e.g., 'for symbol lookup, use find_symbol'), which would strengthen the guidance.
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.
v0.1.0fetchfind_symbolget_code_contextget_file_outlineget_index_statusrefresh_indexsearchsearch_codeScored across 8 tools
Each tool has a clearly distinct purpose. search and search_code are differentiated as general text search vs. code-specific retrieval, with paired fetch and get_code_context for results. find_symbol, get_file_outline, get_index_status, and refresh_index each serve unique, non-overlapping functions.
All tool names follow a consistent verb_noun pattern with lowercase and underscores (e.g., search_code, get_code_context, find_symbol). Even simple verbs like search and fetch fit the pattern. No mixing of conventions.
With 8 tools, the server is well-scoped for a codebase RAG assistant. The set covers search, retrieval, symbol lookup, file outline, indexing status, and index refresh without unnecessary bloat or excessive minimalism.
Core workflows are well-covered: search (general and code), retrieve (full doc and chunk), symbol resolution, file outline, and index management. Minor gaps like listing all files or a 'get_by_path' could exist, but the current set handles most agent needs effectively.
An MCP server that gives your AI access to the source code and docs of all public github repos
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Repository knowledge graph MCP server for codebase understanding and debugging.
