Provides tools for retrieving and searching codebases, enabling AI agents to fetch code snippets, search for symbols, and get file outlines for context in code generation or analysis tasks.
Click on "Install 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-rag-mcp search for the authenticate function in auth.ts"
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.
A local-first, no API Key codebase retrieval MCP Server. It scans specified repositories, chunks code by code windows, and performs hybrid ranking via BM25, symbol names, file paths, and exact matches. It can be directly connected to Codex and also provides standard search / fetch tools for ChatGPT knowledge retrieval scenarios.
Uses git ls-files preferentially, respects nested .gitignore files of the repository; non-Git directories use filesystem scanning.
Supports common text code formats such as TypeScript, JavaScript, Python, Go, Rust, Java, C/C++, C#, Ruby, Shell, SQL, Markdown, Vue, Svelte.
Automatically splits camelCase, snake_case, and path words, supports common Chinese code query expansions, e.g., "用户登录认证".
Returns precise file paths, line numbers, code snippets with line numbers, match reasons, and stable IDs for further reading.
Path reading is restricted to the configured repository root; symbols links, binaries, secrets, environment variable files, minified code, and large files are skipped by default.
Supports both local stdio and stateless Streamable HTTP /mcp.
Related MCP server: mcplens
Requires Node.js 20 or higher.
Get the project from GitHub:
git clone https://github.com/sudoriaa/codebase-rag-mcp.git
cd codebase-rag-mcpInstall dependencies and build:
npm install
npm run build
node dist/cli.js --root C:/path/to/your-repositoryThe last command starts the stdio MCP Server, which waits for an MCP client to connect, so it is normal for the terminal to keep running.
Put the following into the user-level %USERPROFILE%/.codex/config.toml, or a trusted repository's .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 = 120It is recommended to use / for Windows TOML paths. Only fill in the executable for command, and put other parameters in args respectively. The PATH inherited by desktop applications may differ from PowerShell, so it is recommended to use the absolute path of node.exe for long-term use.
You can also register via the 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 --jsonAfter configuration, restart the Codex desktop application or IDE extension. See examples/codex-config.toml for an example configuration.
node dist/cli.js --root C:/path/to/your-repository --transport http --host 127.0.0.1 --port 3000Endpoints:
MCP: http://127.0.0.1:3000/mcp
Health check: http://127.0.0.1:3000/health
Reference source file: http://127.0.0.1:3000/source/:documentId
By default, it only listens to the local machine. When deploying to other machines, TLS, authentication, and access control should be added at the reverse proxy layer, and use --public-base-url to set the canonical address accessible by the model.
When listening directly on 0.0.0.0 or other non-local addresses, the service requires a 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 3000The client then needs to send Authorization: Bearer <token> for /mcp and /health. The reference addresses returned by the service will automatically include an HMAC signature, so users can directly open the corresponding /source link; manually accessing unsigned /source addresses still requires the Bearer Token. When publishing via a local reverse proxy, the service can continue to listen on 127.0.0.1, and the proxy handles external authentication.
Tool | Purpose |
| Standard document search, returns |
| Gets the full file based on the ID returned by |
| Hybrid retrieval of code snippets, filterable by path, language, symbol type, and test files |
| Gets context based on chunk ID, up to 200 lines of expansion |
| Finds definitions of classes, functions, methods, interfaces, types, and enums |
| Returns file imports and symbol outline |
| Views index statistics and skip reasons |
| Rescans files and rebuilds the in-memory index after file changes |
Recommended calling order:
Use search_code to find implementations and related snippets.
Use get_code_context to expand high-scoring snippets.
Use find_symbol for precise definition location.
Only use fetch when the full file is truly necessary.
The index runs entirely in local memory:
Code files are sliced into chunks of up to 120 lines with a 20-line overlap.
Symbols like class, interface, type, enum, function, method are extracted from common language declarations.
The body text uses BM25 retrieval; symbols and paths are ranked separately.
Reciprocal-rank fusion is used to combine scores from body text, symbols, paths, and exact matches.
By default, at most two snippets are returned per file to avoid filling up results with duplicate boilerplate code.
This version has no external vector database and does not upload source code. For large-scale multi-repository, cross-language semantic retrieval, embedding retrieval or rerankers can be added before or after the existing CodebaseIndex.search, without changing the MCP tool contract.
--root PATH
--transport stdio|http
--host HOST
--port PORT
--public-base-url URL
--max-file-bytes N
--max-files NThe corresponding environment variables are:
CODEBASE_ROOT
CODEBASE_TRANSPORT
CODEBASE_HOST
CODEBASE_PORT
CODEBASE_PUBLIC_BASE_URL
CODEBASE_MCP_TOKEN
CODEBASE_MAX_FILE_BYTES
CODEBASE_MAX_FILESDefault single file size limit is 1 MiB, file count limit is 20,000.
npm run build
npm testTests cover index building, .gitignore, Chinese query expansion, symbol and path filtering, path traversal, standard search/fetch, in-memory MCP, real stdio subprocesses, and Streamable HTTP.
The MCP Inspector can also directly inspect the HTTP service:
npx @modelcontextprotocol/inspectorThen select Streamable HTTP and fill in http://127.0.0.1:3000/mcp.
The implementation follows the OpenAI Official MCP Server Guide and the standard search / fetch data shapes.
The index is rebuilt after a process restart; there is no persistent cache.
Git repositories fully respect Git ignore rules; non-Git directories currently read the root .gitignore.
Symbol extraction uses lightweight declaration parsing and is not equivalent to a full compiler AST.
Call refresh_index after file changes; file watching is not enabled in the current version.
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. Dates show when Glama detected each change.
v0.1.0fetchfind_symbolget_code_contextget_file_outlineget_index_statusrefresh_indexsearchsearch_codeEach 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.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
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…
Self-hosted AI-native knowledge workspace with hybrid search, GraphRAG, and MCP.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/sudoriaa/codebase-rag-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
