Codebase RAG MCP

Локальный 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.

Быстрый старт

Требуется 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-клиента, поэтому терминал остается запущенным — это нормально.

Подключение к Codex

Поместите следующий текст в пользовательский %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.

Запуск HTTP MCP

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, а внешнюю аутентификацию оставить на прокси.

MCP-инструменты

Рекомендуемый порядок вызова:

1. Используйте search_code для поиска реализации и связанных фрагментов.

2. Разверните высокооцененные фрагменты с помощью get_code_context.

3. Для точного определения используйте find_symbol.

4. Используйте fetch только когда действительно нужен полный файл.

Способ поиска

Индекс полностью работает в локальной памяти:

1. Файлы кода разбиваются на чанки максимум по 120 строк с перекрытием в 20 строк.

2. Из объявлений распространенных языков извлекаются символы: class, interface, type, enum, function, method и т.д.

3. Текст обрабатывается BM25, символы и пути сортируются отдельно.

4. Используется reciprocal-rank fusion для объединения оценок текста, символов, путей и точного совпадения.

5. По умолчанию возвращается не более двух фрагментов на файл, чтобы избежать заполнения результатов повторяющимся шаблонным кодом.

В этой версии нет внешней векторной базы данных, и исходный код не загружается. Для масштабного многопроектного, межъязыкового семантического поиска можно добавить 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