ローカルファースト、API Key不要のコードベース検索MCPサーバー。指定されたリポジトリをスキャンし、コードウィンドウでチャンク分割し、BM25、シンボル名、ファイルパス、完全一致によるハイブリッドランキングを実行。Codexに直接接続可能で、ChatGPTの知識検索シナリオ向けに標準の search / fetch ツールも提供します。
優先的に 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サーバーが起動し、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行まで拡張 |
| クラス、関数、メソッド、インターフェース、型、列挙型の定義を検索 |
| ファイルのimportとシンボルアウトラインを返す |
| インデックス統計とスキップ理由を表示 |
| ファイル変更後に再スキャンし、メモリ内インデックスを再構築 |
推奨される呼び出し順序：
search_code を使用して実装と関連スニペットを検索します。
get_code_context を使用して高スコアのスニペットを展開します。
定義を正確に特定する必要がある場合は find_symbol を使用します。
本当に完全なファイルが必要な場合のみ fetch を使用します。
インデックスは完全にローカルメモリ上で動作します：
コードファイルは最大120行、20行のオーバーラップでスライスされます。
一般的な言語宣言からclass、interface、type、enum、function、methodなどのシンボルを抽出します。
本文はBM25で再現性を高め、シンボルとパスは個別にランキングされます。
reciprocal-rank fusionを使用して、本文、シンボル、パス、完全一致のスコアを統合します。
デフォルトでは、各ファイルから最大2つのスニペットを返し、重複するテンプレートコードで結果が埋め尽くされるのを防ぎます。
このバージョンには外部ベクトルデータベースはなく、ソースコードがアップロードされることもありません。大規模なマルチリポジトリ、クロスランゲージセマンティック検索の場合は、既存の 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サーバーガイド および標準の 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.
