code-index

---

code-index-mcp

面向 AI Agent 的代码搜索。单个二进制文件，使用 SQLite 建立索引，毫秒级响应。 可解析 1C:Enterprise 8.3 导出文件——包括来自 Configurator 和 1C:EDT 的导出文件。

完整指南 · English · 文档 · 更新日志

支持文件名采用 Unicode NFC 和 NFD 形式的导出文件；要恢复旧索引中的数据，需要重新构建索引（数据版本 6）。

---

安装

Windows — 一条命令安装

irm https://raw.githubusercontent.com/Regsorm/code-index-mcp/main/install.ps1 | iex

将最新发行版下载到 C:\tools\code-index，将文件夹路径保存到 环境变量中，创建设置文件模板，并打印可直接使用的 .mcp.json 配置块。

使用参数指定安装文件夹、源代码文件夹以及登录系统时自动启动：

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/Regsorm/code-index-mcp/main/install.ps1))) `
    -InstallDir 'D:\code-index' -Repo 'main=D:\Repo1C' -RegisterAutostart

自动启动通过用户的启动文件夹实现：无需管理员权限，也不会显示窗口。 其他参数包括：-Flavor core，用于不含 1C 的构建版本；-Version 1.0.0，用于指定发行版；如果默认端口被占用，则可使用 -Port 和 -DaemonPort。完整列表请查看 Get-Help .\install.ps1 -Detailed。

Windows — 手动安装，使用发行版中的预构建压缩包

下载最新发行版，解压到 C:\tools\code-index，并将该文件夹路径 保存到环境变量中：

$dst = 'C:\tools\code-index'
New-Item -ItemType Directory -Force $dst | Out-Null
$url = (Invoke-RestMethod https://api.github.com/repos/Regsorm/code-index-mcp/releases/latest).assets |
       Where-Object name -eq 'bsl-indexer-windows-x64.zip' |
       Select-Object -ExpandProperty browser_download_url
Invoke-WebRequest $url -OutFile "$env:TEMP\code-index.zip"
Expand-Archive "$env:TEMP\code-index.zip" -DestinationPath $dst -Force
setx CODE_INDEX_HOME $dst

bsl-indexer 是支持 1C 的构建版本（42 个工具）。若需不含 1C 的版本， 请下载 code-index-windows-x64.zip（25 个工具）。同一发行版中还提供 Linux 和 macOS 版本，文件名分别为 *-linux-x64.tar.gz 和 *-macos-arm64.tar.gz。

接下来介绍设置文件、启动、连接客户端和自动启动。 无需脚本，按步骤操作即可：手动安装 (English)。

npm

npm install -g @regsorm/code-index-mcp
npx @regsorm/code-index-mcp serve --path /путь/к/репозиторию

postinstall 步骤会下载适用于您平台的预构建二进制文件——无需编译。 此软件包也收录于 MCP 注册表，名称为 io.github.Regsorm/code-index。此封装仅提供不含 1C 的构建版本。

serve 服务只读取索引，后台索引器负责构建索引。因此，必须运行 npx @regsorm/code-index-mcp daemon run，并设置 环境变量 CODE_INDEX_HOME，否则工具会返回 daemon_offline。 设置方法请参阅完整指南。

从源代码构建

git clone https://github.com/Regsorm/code-index-mcp.git
cd code-index-mcp
cargo build --release -p code-index                          # без 1С
cargo build --release -p bsl-indexer --features enrichment   # с поддержкой 1С

需要 Rust 1.77+。

连接到客户端

所有会话和项目共用一个 HTTP 进程和索引。HTTP 服务器内置于程序中，无需单独的 Web 服务器；默认仅监听 127.0.0.1：

{
  "mcpServers": {
    "code-index": {
      "type": "http",
      "url": "http://127.0.0.1:8011/mcp"
    }
  }
}

仅监听 127.0.0.1，并且只接受 Host 标头中的 loopback 值。 若要让服务器在网络上提供服务（使用 --host 0.0.0.0 或在 serve.toml 中设置 [me].ip），请在 [me].allowed_hosts 或 CODE_INDEX_ALLOWED_HOSTS 中列出客户端名称，否则 /mcp 会返回 403 Host header is not allowed。详情请参阅 完整指南。

每个会话使用独立进程（stdio）——客户端会在会话打开时自行启动服务器，无需端口。后台索引器（daemon run）也必须运行：服务器只读取索引，索引由索引器构建。若索引器未运行，工具会返回 daemon_offline：

{
  "mcpServers": {
    "code-index": {
      "command": "npx",
      "args": ["-y", "@regsorm/code-index-mcp", "serve", "--path", "."]
    }
  }
}

兼容 Claude Code、Cursor、VS Code、LibreChat，以及任何 MCP 客户端。 后台守护进程设置、存储库列表和高级参数请参阅 完整指南。

Гард: чтение через индекс (необязательно)

Правило «по индексированным каталогам читай через code-index» модель под нагрузкой забывает и уходит в обычное чтение файлов, которое в 3–10 раз дороже по токенам. code-index-guard — хук PreToolUse для Claude Code и Codex CLI: отклоняет обычное чтение, поиск и обход каталога только там, где индекс отдаёт тот же файл, и подсказывает нужный инструмент. Новый, ещё не проиндексированный или исключённый из индекса файл читается как обычно. Сборка и установка — crates/code-index-guard.

Копия проекта с готовым индексом

code-index-copy делает копию проекта (файлы под контролем git или git worktree на новой ветке) и переносит в неё базу индекса, так что индекс копии не строится заново: демон копии при запуске только сверяет файлы с базой. Файлы исходника вне git из базы копии убираются, конфиги демона и сервера выдачи копии пишутся сразу. Подробности — crates/code-index-copy.

Зачем это нужно

Языковая модель без индекса ищет по коду тем же способом, что и человек без среды разработки: перебором. Один вопрос «кто вызывает эту процедуру» превращается в десяток последовательных обходов файлов, каждый из которых читает тысячи файлов и возвращает в контекст модели куски текста — вместе с оплатой этих кусков.

code-index делает работу заранее: разбирает исходники в синтаксическое дерево, складывает символы, тела, вызовы и метаданные в SQLite и отдаёт агенту готовый ответ по протоколу MCP. Модель получает три строки вместо трёх файлов.

Цифры

Кодовая база	Файлов	Полная индексация	Запуск на готовом индексе
1С:Управление Торговлей	57 072	2 мин 41 с	2,3 с
1С:Бухгалтерия предприятия	88 284	5 мин 51 с	5,3 с
сайт на PHP	157 772	13 мин 1 с	8,0 с

Полная индексация — разбор всего с нуля, делается один раз. У Бухгалтерии эти 5 мин 51 с складываются так: 2 мин 38 с ядро (синтаксические деревья и запись), 1 мин 58 с надстройка 1С (метаданные, формы, права, граф вызовов), 56 с сброс базы на диск. Дальше правки подхватываются по одной, за миллисекунды.

Запуск на готовом индексе сверяет время правки и размер каждого файла — ни одного чтения содержимого, ни одного хеша.

Ответ на запрос	около 10 мс по HTTP, повторный из кэша — доли миллисекунды
Размер бинарника	39 МБ без 1С, 41 МБ с 1С
Функций в индексе Управления Торговлей	261 548
Вызовов в графе там же	1 962 941

Замеры сделаны на одной машине под Windows с обычным жёстким диском, август 2026.

Инструменты

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

Поиск и навигация

search_function search_class	полнотекстовый поиск по функциям и классам
get_function get_class	точное имя → готовое тело; при промахе подсказывает похожие имена
find_symbol	символ любого рода: функция, класс, переменная, импорт
get_imports	импорты модуля или файла
get_file_summary	карта файла без чтения исходника

Граф вызовов

get_callers get_callees	кто вызывает процедуру и кого вызывает она
find_path	кратчайшая цепочка вызовов между двумя функциями
get_call_tree	дерево вызовов вниз или вверх на заданную глубину

Содержимое файлов

read_file	чтение с диапазоном строк; содержимое кода лежит в индексе, сжатое zstd
list_files stat_file	список файлов по маске и метаданные одного файла
grep_body	подстрока или регулярное выражение в телах функций и классов
grep_code grep_text	то же по всему тексту файлов кода и текстовых файлов
search_text	полнотекстовый поиск по текстовым форматам
get_stats health	состояние индекса и сервера

Git (включается git = true у записи [[paths]]; git_path — если репозиторий лежит выше индекса)

git_log	история коммитов ревизии или локальной даты с фильтром по пути
git_changed_files	изменённые файлы между двумя снимками: статусы, переименования, бинарные
git_changes_by_object	те же изменения, сгруппированные по объектам метаданных 1С
git_diff	unified diff одного файла с контекстом и пределом длины
git_show_file	историческое содержимое файла с диапазоном строк

Даты — YYYY-MM-DD, YYYY-MM-DD HH:MM, YYYY-MM-DDTHH:MM; зону можно задать параметром tz (+03:00 или UTC), иначе берётся локальная зона исполняющей машины (в контейнере ноды это UTC, timezone есть в каждом ответе). Пути — от корня индекса (для подкаталога изменения вне его не видны; для bare — от корня репозитория). Shallow-клон отвергается с подсказкой git fetch --unshallow, сеть инструменты не используют, а правка git/git_path применяется без перезапуска.

Для конфигураций 1С (сборка bsl-indexer, появляются сами при наличии репозитория с выгрузкой)

get_object_structure	реквизиты с типами и синонимами, табличные части, измерения и ресурсы, предопределённые элементы, свойства проведения
get_object_profile	паспорт объекта одним вызовом: структура, формы, модули, связи
get_form_handlers	обработчики событий управляемой формы, с привязкой к элементу
get_event_subscriptions	подписки на события: явные источники, наборы и определяемые типы, менеджеры, расширения; способ совпадения и предупреждения о неполноте
get_data_links find_data_path	граф связей данных: кто на кого ссылается и цепочка между двумя объектами
find_references	карта влияния: ссылки из метаданных, обращения в коде, права ролей
get_register_writers	регистраторы регистра и движения документа
find_path_bsl	цепочка вызовов процедур по графу выгрузки
query_call_sites	вызовы с контекстом места: в цикле, в Попытке, с глубиной вложенности
get_node_structure	скелет процедуры: циклы, Попытка и ветки с номерами строк
get_line_context	что находится на строке: процедура, содержащие её блоки, признаки
search_terms	смысловой поиск процедур по именам, синонимам и комментариям
get_role_rights	права ролей на объект и права одной роли
bsl_sql	произвольный запрос на чтение к таблицам метаданных и графов

1С 支持带来的功能

• 支持解析两种导出格式：来自配置器的 XML 和来自 1С:EDT 的 .mdo。
• 根据属性、维度和表格部分中的引用类型构建数据关系图：对于企业会计系统，包含 65 421 条边。
• 从模块中提取编译指令（&НаСервере、&НаКлиенте）和扩展注释（&Вместо、&После、&Перед），以及被重写过程的名称。
• 支持 BSL 的俄语和英语两种语法。
• 对象名称不区分大小写：西里尔字母名称会规范为配置中的写法，响应中显示规范名称。

详情请见 docs/bsl-indexer.md。

语言

完整语法解析：Python、JavaScript、TypeScript、Java、Rust、Go、PHP、C、C++、C#、Ruby、Swift、1С（BSL）、HTML。1С 元数据支持配置器 XML 和来自 EDT 的 .mdo。此外，还支持对 50 多种文本格式进行全文索引（.md、.json、.yaml、.toml、.sql 等）。

后续

• 俄语完整指南 — 守护进程、配置、CLI、架构
• docs/operations.md — 运维：重启、添加存储库、诊断
• docs/bsl-indexer.md — 1С 构建
• CHANGELOG.md — 更新日志

参与贡献

错误报告和建议请提交到 issues，问题和讨论请前往 Discussions。如何提交修改，请参阅 CONTRIBUTING.md；有关漏洞的信息，请参阅 SECURITY.md。

许可证

MIT，详见 LICENSE。

本项目基于 tree-sitter、1c-syntax 社区提供的 BSL 语法、rusqlite、rayon 和 MCP Rust SDK。