Ариадна

Docker-контейнер с MCP-сервером для быстрого поиска по метаданным конфигураций 1С и анализа кода BSL.

AI-агенты (Claude Code, Cursor, Codex) находят нужный объект, реквизит или процедуру за один MCP-вызов вместо сканирования всей кодовой базы — экономя контекст и токены. Есть и Web UI — искать и индексировать можно и без агента, прямо в браузере.

Возможности

• Поиск по метаданным — объекты, реквизиты (и реквизиты форм), типы, формы; по имени или своими словами («где лежат долги по аренде земельных долей»), формы слов совпадают — годится и для помощника по данным базы. Поиск процедур по описанию — semantic_search_code. Типичный вызов инструмента — доли секунды (замер: search_procedures на крупной типовой конфигурации, около 550 тыс. процедур, — 0,1–0,15 с). Дольше — diagnose_index (читает все файлы выгрузки) и первый запрос к проекту после перезапуска Docker Desktop, пока индекс читается с диска (несколько секунд)

• Граф вызовов BSL — кто вызывает / что вызывает процедура, с резолвингом рёбер по факту (включая перехваты &Вместо/&Around из расширений)

• Полнотекстовый поиск по коду — FTS5 по всему тексту модулей, а не только по вызовам

• RU + EN конфигурации — русские и английские ключевые слова, директивы, менеджеры; регистронезависимый поиск, EN-алиасы видов (Catalog = Справочник)

• Несколько проектов, конфигурация + расширения (несколько source в одном проекте)

• Инкрементальная фоновая индексация — reindex не блокирует, повторный проход перечитывает только изменённые файлы (по хэшу); при изменении кода самого парсера индекс сам делает полный переразбор, вручную удалять index.db не нужно

• Web UI — управление проектами, поиск, playground для MCP tools; светлая и тёмная тема, шрифты и иконки локальные — интерфейс полностью работает без интернета

• MCP Server — streamable HTTP, project-scoped tools

• Эксплуатация — /ready (готовность проектов), манифест индекса, резервная копия и перенос — docs/operations.md

Related MCP server: code-index-mcp

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

Поддерживаемый способ запуска сервера — Docker. Запуск без Docker (python -m src.main) — только для разработки и тестов, см. «Разработка» и SETUP.md.

1. Запуск

git clone https://github.com/amorozov1310/ariadna-mcp.git
cd ariadna-mcp
docker compose up -d

Если образ ещё не собран, а в docker-wheels/ нет .whl-файлов — сборка упадёт: зависимости ставятся в образ офлайн из этого каталога (обход нестабильной сети в docker build). Один раз скачайте колёса (нужен только Docker, сеть используется из runtime-контейнера):

docker run --rm -v "$PWD:/repo" -w /repo python:3.12-slim sh docker-wheels/fetch.sh

Команда запускается из корня репозитория: список зависимостей берётся из pyproject.toml. На Windows — только из PowerShell с полным путём (-v D:\путь\до\ariadna:/repo): Git Bash искажает пути монтирования. Повторять при изменении зависимостей в pyproject.toml — старые колёса заменяются новыми, при сбое сети прежний набор остаётся.

Web UI: http://127.0.0.1:19878 MCP (streamable HTTP): http://127.0.0.1:19879/mcp

Адреса — именно 127.0.0.1, а не localhost: на Docker Desktop под Windows каждое новое HTTP-соединение к localhost стоит около 0,26 с (против ~4 мс к 127.0.0.1), а streamable HTTP открывает соединение на каждый вызов инструмента.

2. Создание проекта

Откройте Web UI → "Создать проект":

• ID: demo

• Название: Демо-конфигурация

3. Добавление данных

Источник — это XML-выгрузка конфигурации (Конфигуратор → «Выгрузить конфигурацию в файлы»). Отчёт по конфигурации выгружать не нужно: метаданные (объекты, реквизиты, типы, формы, подсистемы) индексатор читает прямо из этой же XML.

Вариант A — Upload через Web UI:

На странице проекта нажмите «+ Добавить источник» и загрузите XML-выгрузку (.zip или .tar.gz). Архив проверяется до распаковки: пути только внутри выгрузки, без ссылок, не больше 1 млн файлов и 64 ГБ в распакованном виде (ARIADNA_ARCHIVE_MAX_FILES, ARIADNA_ARCHIVE_MAX_BYTES). Отклонённый архив не трогает прежнюю выгрузку источника.

Вариант B — Монтирование volume:

# Положить выгрузку на хосте:
mkdir -p data/projects/demo/sources/main/xml
cp -r ВыгрузкаКонфигурации/* data/projects/demo/sources/main/xml/

# Для расширения:
mkdir -p data/projects/demo/sources/ext1/xml
cp -r ВыгрузкаРасширения/* data/projects/demo/sources/ext1/xml/

# Затем в Web UI добавить source и переиндексировать

4. Индексация

На странице проекта нажмите «Переиндексировать». Прогресс (процент, фаза, оценка оставшегося времени) виден на дашборде, в том числе если открыть страницу заново или запустить индексацию из другой вкладки или из MCP. По завершении страница обновляется сама.

Индексация — фоновый поток внутри процесса и перезапуск не переживает. Если сервер остановили посреди прогона, при следующем старте статус indexing снимается автоматически (в лог пишется предупреждение), а прежний индекс остаётся пригодным — прогон достаточно повторить.

Без сервера — командой ariadna-index <проект> [--source <источник>] (ставится с пакетом, pip install .); без установки пакета из корня репозитория — python -m src.core.indexer <проект>. Не запускайте её параллельно с работающим сервером на тех же data/: реестр projects.json у них общий.

5. Подключение MCP к агенту (по желанию)

Шаги 1–4 уже дают рабочий сервер: искать по метаданным, коду и графу вызовов можно прямо в Web UI, без какого-либо агента (см. «Web UI» ниже). Этот шаг — только если нужен доступ из Claude Code, Cursor, Codex и т.п.

Сервер должен быть запущен (docker compose up -d), проверка — curl http://127.0.0.1:19878/health.

Claude Code — одной командой, для всех проектов на машине:

claude mcp add --transport http --scope user ariadna http://127.0.0.1:19879/mcp

Без --scope user сервер подключится только в текущем каталоге. Чтобы подключение ехало вместе с репозиторием (у всей команды), положите в корень проекта .mcp.json — Claude Code спросит подтверждение при первом запуске:

{
  "mcpServers": {
    "ariadna": {
      "type": "http",
      "url": "http://127.0.0.1:19879/mcp"
    }
  }
}

"type": "http" обязателен. .claude/settings.json MCP-серверы не читает — конфигурация, положенная туда, молча игнорируется.

Проверка: в Claude Code команда /mcp показывает ariadna со статусом connected и 17 инструментами.

Cursor — .cursor/mcp.json в проекте или ~/.cursor/mcp.json:

{
  "mcpServers": {
    "ariadna": { "url": "http://127.0.0.1:19879/mcp" }
  }
}

Если Cursor запустился раньше сервера (например, сразу после входа в систему, пока поднимается Docker Desktop), он помечает ariadna ошибкой подключения и сам не переподключается — инструментов Ариадны у агента не будет, хотя Web UI уже работает. Переподключить: Settings → MCP → выключить и включить ariadna (или Ctrl+Shift+P → Reload Window). Ариадну достаточно прописать в одном месте — либо в ~/.cursor/mcp.json, либо в .cursor/mcp.json проекта: с одинаковым именем в обоих Cursor использует одну запись, и вторая только путает.

Codex CLI — одной командой:

codex mcp add ariadna --url http://127.0.0.1:19879/mcp

Или вручную в ~/.codex/config.toml (либо .codex/config.toml в проекте — только для доверенных проектов):

[mcp_servers.ariadna]
url = "http://127.0.0.1:19879/mcp"

Проверка: в composer Codex команда /mcp показывает ariadna со статусом connected.

Сервер на другой машине. По умолчанию порты публикуются только на 127.0.0.1 — с других машин сервер недоступен. Чтобы открыть доступ, задайте адрес публикации явно:

BIND_ADDR=0.0.0.0 MCP_ALLOWED_HOSTS=192.168.1.10,ariadna.lan docker compose up -d

и в клиенте замените 127.0.0.1 на адрес машины. MCP_ALLOWED_HOSTS — имена и адреса, под которыми к серверу обращаются (через запятую; host — любой порт, host:port — только этот). MCP и Web UI отклоняют запросы с другим заголовком Host — это защита от DNS rebinding: без неё страница в браузере могла бы обращаться к серверу на 127.0.0.1 от имени своего домена. Без MCP_ALLOWED_HOSTS пускаются только 127.0.0.1, localhost и [::1]. Авторизации нет: любой, кто достаёт до этих портов, может искать по конфигурации, запускать переиндексацию и удалять источники. Открывайте порты только в доверенной сети.

При подключении сервер сам передаёт агенту инструкцию: какой инструмент для какого вопроса и в каком порядке их вызывать. Типовой диалог:

> list_projects()                                   # если проектов несколько — узнать project_id
> search_metadata(project_id="demo", query="Номенклатура")
> get_object_details(project_id="demo", full_name="Справочник.Номенклатура")
> search_procedures(project_id="demo", query="ЗначениеРеквизитаОбъекта", export_only=true)
> get_procedure_code(project_id="demo", module_name="ОбщегоНазначения",
                     procedure_name="ЗначениеРеквизитаОбъекта")
> get_call_tree(project_id="demo", procedure_name="ЗначениеРеквизитаОбъекта",
                module_name="ОбщегоНазначения", direction="up", depth=2)
> search_code(project_id="demo", query="ВЫБРАТЬ ПЕРВЫЕ 1")
> semantic_search_code(project_id="demo", query="где рассчитывается себестоимость")

Без своих правил ничего настраивать не нужно: инструкция сервера уже объясняет агенту и поиск по описанию (semantic_search_code).

Правила для агента в проекте 1С. Если в проекте уже есть свои правила (Cursor rules, CLAUDE.md, AGENTS.md) и другие MCP-серверы для 1С, агенту нужно явно сказать, когда звать Ариадну. Готовые шаблоны — в docs/agent-rules: Ариадна как основной индекс, как вспомогательный рядом с другим сервером или блок для встраивания в уже существующую цепочку серверов.

Web UI

http://127.0.0.1:19878 — работает сразу после docker compose up -d, агент не нужен. Здесь же выполняются шаги 2–4 быстрого старта:

• Проекты — создание, добавление источников (upload .zip или volume), запуск переиндексации, прогресс и статистика по каждому.

• Поиск — по метаданным (объекты, реквизиты, типы, формы) и по коду (FTS5 полнотекстовый).

• Playground — вызвать любой из 16 MCP-инструментов вручную с формой параметров и увидеть тот же ответ, что получит агент, — удобно для проверки сервера и данных без настройки Claude Code/Cursor/Codex. Инструменты, параметры, их описания и умолчания берутся из схемы MCP-сервера, ответ строит тот же код, что отвечает агенту; project_id подставляется из проекта страницы. Ошибка инструмента (у агента — isError) выделена. remove_source без флажка confirm только показывает, что будет удалено.

• Светлая/тёмная тема, шрифты и иконки — локальные файлы, работает без интернета.

Порты

# Свои порты:
MCP_HTTP_HOST_PORT=33002 WEB_HOST_PORT=33001 docker compose up -d

MCP Tools

17 инструментов. Все, кроме reindex и remove_source, только читают (помечены readOnlyHint), remove_source помечен destructiveHint.

Соглашения, общие для всех инструментов:

• project_id — необязателен, только если в реестре один проект; иначе ошибка перечисляет доступные id.

• Имена — как в конфигураторе, русские или английские, регистр не важен: kind="Catalog" равно kind="Справочник".

• Имя модуля (module_name — в get_procedure_code, get_module_outline, get_call_tree) — полное (ОбщийМодуль.ОбщегоНазначения.Модуль, Документ.РеализацияТоваровУслуг.МодульОбъекта), короткое имя общего модуля (ОбщегоНазначения) или часть имени. Точное совпадение выигрывает у частичного; самый надёжный вариант — скопировать имя из вывода search_procedures.

• source_id — сужает выдачу до конфигурации или одного расширения.

• Пагинация — limit/offset; строка use offset=N for more в конце выдачи значит, что есть продолжение. limit больше 500 урезается до 500 (об этом сказано в конце ответа).

• Ошибки приходят клиенту как ошибка инструмента (isError) с понятным текстом: какой проект или источник не найден и какие есть.

• search_code ищет подстроку без учёта регистра, не регулярное выражение.

Структура данных

data/
├── projects.json              # Реестр проектов
└── projects/
    └── demo/
        ├── index.db           # SQLite индекс (FTS5) — при запуске без Docker
        └── sources/
            ├── main/
            │   ├── xml/       # XML-выгрузка конфигурации — единственный вход
            │   └── report.txt # отчёт по конфигурации, только если нет xml/
            └── ext1/
                └── xml/

В Docker индексы лежат не в data/, а на именованном томе ariadna-index (в контейнере — /index/{проект}/index.db, переменная INDEX_DIR). В ./data остаются выгрузки и projects.json.

Индексы в Docker: том ariadna-index

Зачем отдельный том. На Docker Desktop под Windows ./data виден контейнеру через файловую систему 9p. Поиск процедур делает полный проход по индексу, и через 9p файл перечитывается при каждом вызове: 3,5–4,5 с на вызов против 0,1 с на томе. Кроме того, через 9p не работают WAL и блокировки SQLite.

Первый старт после обновления. Сервер один раз переносит существующие data/projects/*/index.db на том: копирует через SQLite backup API (с данными из WAL) до запуска MCP и Web UI. Каждый перенос с размером и временем пишется в лог (docker compose logs). Время — однократное чтение файла с ./data через 9p и запись на том: на Docker Desktop под Windows индекс крупной конфигурации (~1,2 ГБ) переносится за 25–30 с. Если копирование проекта не удалось, это тоже будет в логе, а проект просто переиндексируется.

Старые файлы. После переноса data/projects/*/index.db (и -wal, -shm рядом) контейнером больше не используются — их можно удалить вручную, когда убедитесь, что поиск работает. Сервер их не удаляет.

Пересобрать индекс с нуля: reindex в Web UI или через MCP (переиндексация одного проекта), либо целиком: docker compose down && docker volume rm ariadna-index && docker compose up -d — затем reindex каждого проекта. Если старые data/projects/*/index.db ещё не удалены, при следующем старте они снова будут перенесены.

Доступ к индексу с хоста. В Docker-режиме index.db лежит на томе и с хоста напрямую не виден — открыть его sqlite3 или DB Browser можно только внутри контейнера (docker compose exec ariadna bash). Поэтому прежнее правило «не открывать data/projects/*/index.db, пока контейнер запущен» для Docker больше не актуально: контейнер эти файлы не читает. Оно остаётся в силе, только если запускать контейнер без INDEX_DIR (индексы снова в ./data через 9p): тогда процесс на хосте, закрывая соединение, удаляет WAL-файлы из-под сервера, и MCP с Web UI отвечают unable to open database file (лечится docker restart ariadna).

Не запускайте сервер без Docker одновременно с контейнером на одном data/ (docker compose stop перед python -m src.main): у них общие projects.json и выгрузки. Slow-тесты (pytest -m slow) в data/ не пишут — для них контейнер останавливать не нужно.

Эксплуатация

Готовность проектов для оркестратора и скриптов — GET /ready (200 / 503, ?project=ID — один проект), отдельно от /health (процесс жив). Из чего и чем построен индекс — GET /api/projects/{id}/manifest: версии конфигураций, время индексации, версия парсера, покрытие поисковыми карточками и что требует переиндексации. Резервная копия, перенос на другую машину и восстановление — docs/operations.md.

Разработка

Для работы сервер запускается в Docker (см. «Быстрый старт»). Запуск без Docker — для правки кода и тестов; подробно — SETUP.md, «Разработка без Docker». Серверы слушают только 127.0.0.1 (LISTEN_ADDR).

# Окружение по pyproject.toml — без него тесты сразу остановятся
# со списком неподходящих пакетов
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev]"

# Переменные (необязательно — ниже значения по умолчанию)
export DATA_DIR=./data
export INDEX_DIR=./index    # индексы отдельно от data/ (без неё — data/projects/{id}/index.db)
export WEB_PORT=9878
export MCP_HTTP_PORT=9879   # streamable HTTP

# Сервер без Docker — режим разработки (контейнер на том же data/ остановить)
python -m src.main

# Тесты (быстрые)
python -m pytest tests -q

# Полная переиндексация своих проектов из data/ (id через запятую)
ARIADNA_CORPUS=demo,myconf python -m pytest tests -q -m slow

# Проверка работающего сервера по сети (Docker или без него)
python scripts/live_check.py --project demo

Проверка работающего сервера: scripts/live_check.py

Быстрые тесты гоняют код в одном процессе; часть ошибок видна только против запущенного сервера. live_check.py проверяет сервер по сети — так, как его видят агент (MCP, streamable HTTP) и браузер (Web UI):

• регрессия: версия, 17 инструментов, ошибки, проверка Host/Origin;

• индексация: сразу после reindex статус indexing, затем ready;

• playground против MCP: для всех 17 инструментов ответы совпадают;

• пересоздание и удаление проекта под нагрузкой MCP и Web UI (ни одного 500, только «not found»/«проект удалён»);

• стресс: создание и удаление проектов рядом с чтением реестра;

• с --docker-container ariadna — нет /index/<id> удалённого проекта и ни одной трассировки или строки ERROR в логе контейнера;

• с --project ID — несколько инструментов на вашем проекте (только чтение) и время search_procedures.

Работает на своём временном проекте zz_live_<суффикс> из tests/fixtures/xml_ru и удаляет его сам в конце, даже при падении проверок; существующие проекты не трогает. После обновления сервера:

python scripts/live_check.py --project demo              # Docker, адреса по умолчанию
python scripts/live_check.py --quick --web http://127.0.0.1:9878 --mcp http://127.0.0.1:9879/mcp   # без Docker

--quick — один прогон удаления под нагрузкой и 5 с стресса вместо 5 и 30 с. Код выхода 1 при любом FAIL, в конце — сводка. В CI то же самое идёт на каждый PR: Docker-образ целиком на Linux и запуск без Docker на Windows.

Статус

Текущая версия — 1.2.0, история изменений — CHANGELOG.md. Проверено вживую на реальных конфигурациях: две крупные типовые (одна с расширением), конфигурация с одиннадцатью расширениями и собственная конфигурация в работе — через Cursor и Claude Code.

Контракт стабилен: в пределах 1.x имена инструментов MCP, их параметры и смысл ответов не меняются ломающе (подробно — CHANGELOG, «Что гарантирует 1.0»). Новые инструменты и необязательные параметры могут появляться в минорных версиях; ломающие изменения — только в 2.0.

Замечания из работы (неверный или неполный ответ, лишние вызовы агента, непонятное описание инструмента) — в GitHub Issues по шаблону «Замечание из работы» (метка dogfood).