Локальный MCP-сервер для поиска по кодовой базе, не требующий API-ключа. Он сканирует указанные репозитории, разбивает код на окна (чанки) и выполняет гибридную сортировку с использованием 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 и слов в пути, поддержка расширения запросов для распространенного китайского кода, например, «用户登录认证».
Возвращает точные пути к файлам, номера строк, фрагменты кода с номерами строк, причину совпадения и стабильный идентификатор для продолжения чтения.
Чтение по пути ограничено корневым каталогом настроенного репозитория; по умолчанию пропускаются символические ссылки, бинарные файлы, ключи, файлы переменных окружения, сжатый код и большие файлы.
Одновременная поддержка локального 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 = 120В пути TOML для Windows рекомендуется использовать /. В 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Затем клиенту необходимо отправлять Authorization: Bearer <token> для /mcp и /health. Возвращаемые сервисом ссылки автоматически содержат HMAC-подпись, поэтому пользователь может напрямую открыть соответствующий /source; при ручном доступе к неподписанному /source все равно требуется Bearer Token. При публикации через локальный обратный прокси можно продолжать прослушивать 127.0.0.1, а внешнюю аутентификацию оставить на прокси.
Инструмент | Назначение |
| Стандартный поиск документов, возвращает |
| Получение полного файла по ID, возвращаемому |
| Гибридный поиск фрагментов кода с фильтрацией по пути, языку, типу символа и тестовым файлам |
| Получение контекста по chunk ID, расширение до 200 строк |
| Поиск определений классов, функций, методов, интерфейсов, типов и перечислений |
| Возвращает импорты файла и структуру символов |
| Просмотр статистики индекса и причин пропуска |
| Повторное сканирование и перестроение индекса в памяти после изменений файлов |
Рекомендуемый порядок вызова:
Используйте search_code для поиска реализации и связанных фрагментов.
Разверните высокооцененные фрагменты с помощью get_code_context.
Для точного определения используйте find_symbol.
Используйте fetch только когда действительно нужен полный файл.
Индекс полностью работает в локальной памяти:
Файлы кода разбиваются на чанки максимум по 120 строк с перекрытием в 20 строк.
Из объявлений распространенных языков извлекаются символы: class, interface, type, enum, function, method и т.д.
Текст обрабатывается BM25, символы и пути сортируются отдельно.
Используется reciprocal-rank fusion для объединения оценок текста, символов, путей и точного совпадения.
По умолчанию возвращается не более двух фрагментов на файл, чтобы избежать заполнения результатов повторяющимся шаблонным кодом.
В этой версии нет внешней векторной базы данных, и исходный код не загружается. Для масштабного многопроектного, межъязыкового семантического поиска можно добавить embedding-поиск или reranker до и после существующего CodebaseIndex.search, при этом контракты 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 МиБ, максимальное количество файлов — 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 директорий в настоящее время читается корневой .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. 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
