onec-vecgraph

MCP-сервер для векторизации конфигураций 1С:Предприятие (XML-выгрузка Конфигуратора и проекты 1C:EDT, база + расширения) и построения графа зависимостей (включая граф вызовов BSL) в Neo4j — граф, векторы и полнотекст в одном хранилище. Мультиарендный, read-only MCP по Streamable HTTP; запись — через отдельные CLI/admin/overlay-контуры, не read-MCP.

onec-lite: MCP по живой рабочей копии — без Neo4j и векторов

Для машины разработчика есть lite-режим: 32 инструмента (по умолчанию публикуются 23 — см. профили) по живой рабочей копии (несколько репозиториев как именованные воркспейсы — выбор явно в каждом MCP-вызове) (Конфигуратор XML и EDT, база + расширения), код-анализ BSL-парсером, поиск ripgrep + опц. FTS5 (BM25), справка платформы из .hbk, git-осведомлённость. Запуск — двойной клик lite-admin.cmd или uv run onec-lite admin (пути задаются в браузере).

Рекомендуемый стандарт — один HTTP-сервер + явный workspace в каждом MCP-вызове. Поднимите долгоживущий сервис (uv run onec-lite admin → http://127.0.0.1:8010/mcp) и зарегистрируйте URL в project-scope .mcp.json:

{ "mcpServers": { "onec-lite": {
  "type": "http", "url": "http://127.0.0.1:8010/mcp"
} } }

Сначала вызовите list_workspaces(), затем, например, overview(workspace="ut"). Все остальные MCP-инструменты требуют непустой явный строковый workspace, включая platform_* и list_kinds, даже если настроена одна конфигурация. Пропуск, null, другой тип, пустое/пробельное или неизвестное имя отклоняются до доступа к данным, кэшам, индексам и git. Заголовки X-Workspace/X-Tenant-Id, env, CLI --workspace и отметка active не заменяют аргумент. Добавьте в инструкции проекта: «В каждом вызове onec-lite передавай workspace="ut"». К другой конфигурации обращайтесь только по явной просьбе пользователя. Инициализация и список инструментов доступны без выбора; list_workspaces также не требует аргументов. Предвыборы CLI/админки сохранены отдельно от строгого MCP-контракта. Справка платформы и дополнительные корпуса БСП принадлежат workspace и не смешиваются. Альтернатива транспорта — stdio per-session (claude mcp add … onec-lite --workspace <имя>); аргумент workspace в каждом MCP-вызове всё равно обязателен. На больших конфигурациях FTS может не успеть собраться за сессию. Порт — ONEC_LITE_PORT (дефолт 8010). Руководство: docs/LITE_USAGE.md.

Что выбрать: lite или big

Это два режима одного проекта, а не одинаковые серверы с разными требованиями.

	onec-lite	onec-vecgraph (big)
Источник	Локальные файлы выгрузки Конфигуратора XML или EDT, база + расширения	Проиндексированный снимок конфигураций и документов в Neo4j
Поиск	ripgrep / Python-fallback; SQLite FTS5, BM25 и лексическое переранжирование	Векторный и полнотекстовый поиск, RRF, GraphRAG
Зависимости при запуске	Python 3.12 + uv; rg рекомендуется; не нужны Neo4j, Docker, GPU и embedding API	Neo4j; для векторного поиска — настроенный провайдер эмбеддингов (локальный или облачный)
Свежесть	Чтение файлов и кэши; индекс обновляется отдельно, часть кодовых ответов дополняется живыми изменениями	Зависит от последней индексации / векторизации
Разделение проектов	Именованные workspaces; обязательный аргумент workspace в каждом MCP-вызове — маршрутизация, не авторизация	Tenant-контур; bearer-auth включается настройкой
Основной сценарий	Навигация разработчика, текущая ветка, ревью и локальная справка	Общий сервис поиска и знаний команды, документационные корпуса

GPU не является обязательным условием big: выбор провайдера и способ развёртывания описаны ниже. Lite не заменяет векторный поиск big и не подключается к работающей информационной базе 1С — ему нужны выгруженные исходники.

Быстрый старт именно onec-lite

Установите Git и uv, подготовьте свою XML-выгрузку или EDT-проект. Затем:

git clone https://github.com/Ailirag/onec-vecgraph.git
cd onec-vecgraph
uv sync
uv run onec-lite admin

1. В http://127.0.0.1:8010/admin создайте workspace, например demo, задайте корень конфигурации и при необходимости отдельные корни расширений. Сохраните настройки.
2. Подключите MCP-клиент к http://127.0.0.1:8010/mcp по примеру выше; в каждом вызове инструмента (кроме list_workspaces) передавайте workspace="demo". Для stdio и глобальной установки есть отдельные рецепты в руководстве.
3. Попросите агента вызвать list_workspaces(), затем overview(workspace="demo"): проверьте, что видны нужная база и все расширения. uv run onec-lite check дополнительно показывает настроенные источники из терминала.
4. Начните с точного поиска find_routine(routine_name="<имя>", workspace="demo") или карточки get_object(kind="Catalog", name="<имя>", workspace="demo"). Для поиска по формулировке используйте fts_search и проверьте состояние индекса; для справки добавьте свои .hbk / каталог bin платформы и вызовите platform_versions(workspace="demo").

Не публикуйте машинные пути, ключи и локальный state-файл в Git. Имена объектов в примерах заменяются на реальные имена из вашей конфигурации; исходники и справку подключайте локально.

Что разбирает lite и где его пределы

• Метаданные: get_object объединяет базу и заимствованные объекты расширений; get_dependencies, find_type_usages и writes_to показывают структурные связи. get_form и get_service читают формы и HTTP/Web-сервисы, а get_template — структуру СКД, поля, параметры и текст запроса (с лимитом и признаком усечения).
• BSL: собственный переносимый эвристический парсер выделяет рутины, вызовы, директивы и перехваты расширений, исключая комментарии и строковые литералы. Это не полный AST, не BSL Language Server и не компилятор 1С. find_callers, find_callees, call_graph, find_handlers, find_overrides помогают навигации, но не доказывают полноту динамических вызовов или отсутствие внешних потребителей.
• Запросы: текст запроса СКД можно получить через get_template, но это не выполнение или полная семантическая проверка языка запросов 1С. bsl_sql — совсем другое: SQLite SELECT / WITH … SELECT по локальному индексу рутин и вызовов, не запрос к ИБ. Пустой sql возвращает схему; один оператор, до 5 000 строк, проверяемый дедлайн 10 с. Этот инструмент не подмешивает свежие файлы: проверяйте index.built_at, sources_changed и live_merge: false.
• FTS и БСП: fts_search использует BM25, нормализацию слов и идентификаторов, точный FQN и полноту совпавших термов. Это лексический поиск, не эмбеддинги. Дополнительные исходники БСП включаются в поиск конкретного workspace, но не в его метаданные. Это не готовый версионный корпус документации БСП.
• Справка: platform_docinfo — точное имя API, platform_search — FTS5 по названию и тексту темы, platform_get_document — полная тема, platform_versions — сборки. Справка задаётся отдельно для workspace; при нескольких версиях передавайте platform_version явно. Поставлять нужно свои доступные на законных основаниях .hbk. Общий workspace справки (например, help) оператор создаёт и настраивает сам; это не встроенный workspace и не автоматический fallback. Его имя берите из list_workspaces() и передавайте явно, например platform_versions(workspace="help").
• Git и свежесть: review_set связывает diff с рутинами и вызывающими. «Живая копия» не означает нулевую задержку каждого ответа: есть кэши, фоновая сборка, индекс и fallback. Читайте engine, degraded, truncated и состояние индекса, если они присутствуют; усечённая выдача и пустой ответ не доказывают отсутствия кода.

Профили и границы read-only

Фактическая регистрация инструментов в текущем коде (до ONEC_LITE_DISABLED_TOOLS):

Профиль	Инструментов	Для кого
lean (по умолчанию)	23	У агента есть shell, rg, чтение файлов и git
full	32	Нужны также текстовый поиск, чтение файлов/модулей и списки через MCP
review	11	Узкий набор для ревью

Например, в PowerShell $env:ONEC_LITE_PROFILE="full"; uv run onec-lite admin. После смены профиля перезапустите сервер и обновите список инструментов в клиенте. Авторитетен tools/list подключённого экземпляра, не исторические числа и не число функций в Python-модуле. Состав профилей.

Read-only относится к MCP-инструментам анализа, а не ко всему процессу: строятся локальные индексы и кэши, админка сохраняет конфигурацию; отдельные CLI/admin-операции могут делать clone/fetch/pull. Если для workspace настроено обновление при старте, оно может сработать при его первом обращении через MCP — для анализа без обновления дерева отключите этот режим. Аргумент workspace обязателен, но не является проверкой прав; заголовки не заменяют его. list_workspaces показывает рабочие копии сервера. Держите lite и его неаутентифицированную админку на loopback; для общего доступа нужен отдельный защищающий контур. В big операции записи/управления также вынесены в отдельные CLI/admin/overlay-поверхности.

Сравнение с другими решениями

• code-index-mcp / bsl-indexer — индекс кода разных языков, включая BSL и метаданные 1С; сравнивать нужно конкретные задачи и сборки, а не только число инструментов.
• 1C-docs-mcp — отдельный поиск по справке/руководствам платформы, стандартам и форматам XML.
• 1c-ssl-mcp — поиск по документации БСП; документация библиотеки и её фактическая реализация в проекте — разные источники.

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

Эти инструменты не заменяют ripgrep

Правило: нужен разбор BSL/метаданных 1С — MCP; нужен текст или счёт вхождений — rg. В прежних локальных замерах компетентный rg требовал в 2–5 раз меньше токенов (на агрегатах через конвейер — в 10–25): он отдаёт путь:строка:текст без обвязки. Эти множители относятся к тем задачам и корпусу, не являются универсальной гарантией; MCP нужен прежде всего для структурного анализа.

Задача	Чем
Вызов это или объявление; полный счёт вызовов	find_callers / call_graph / find_callees
Реквизиты с типами и обязательностью, движения — со слиянием базы и расширений	get_object / writes_to
Кому принадлежит перехват расширения	find_overrides
«Где считается X» человеческим языком	fts_search (BM25)
Дифф → затронутые рутины → их вызывающие	review_set
Сколько чего и по каким объектам (агрегаты)	bsl_sql — один GROUP BY по индексу
Текст, подстрока, regex	rg -n "<regex>" <корни>
Сколько всего и по каким объектам	rg -c … | sort | uniq -c (×10–25 дешевле)
Что изменилось в ветке	git diff --name-status (×5 дешевле)

Поэтому профиль по умолчанию (lean, 23 инструмента) не публикует search_code, search_metadata, list_routines, read_file/read_module, changed_objects — это не потеря, а замена; профиль full возвращает их, если у агента нет шелла. Корни для rg берите из overview(workspace="demo"): база и каждое расширение — отдельный корень, иначе теряется до 75 % результатов. Полная карта с замерами — docs/LITE_USAGE.md#rg-или-mcp-карта-маршрутизации.

Документация

Документ	О чём
docs/SERVICE_OVERVIEW.md	Точка входа: что это, архитектура за 30 секунд, карта документации
docs/STATE.md	Живой снимок состояния: что готово, данные, ограничения, гочи
docs/MCP_USAGE.md	Гайд потребителя MCP (подключение, заголовки/auth, fqn, 30 инструментов, сценарии)
docs/LITE_USAGE.md	Руководство onec-lite (запуск, админка, инструменты, lite vs big)
docs/COMPARISON.md	Назначения решений, источники и оговорки к прежним сравнениям
docs/OPERATOR_PLAYBOOK.md	Операторская сторона: index / callgraph / vectorize / ingest
docs/VECTORIZATION_GUIDE.md	Рецепты корпусов: ИТС, стандарты v8std, справка платформы
docs/DEPLOYMENT.md · docs/DEPLOY_RUNBOOK.md · docs/DEPLOY_DETAILED.md	Docker, варианты образа (CPU/GPU/cloud), auth, пошаговый runbook
docs/OVERLAY.md · docs/ORCHESTRATOR_CONTRACT.md	Overlay-тенанты per-task и контракт оркестратора (write/admin-серверы)
PLAN.md · AGENTS.md	Полный план/архитектура · точка входа для AGENTS.md-совместимых агентов

Что умеет (кратко)

• Граф метаданных — объекты, реквизиты и типы, ТЧ, перечисления, предопределённые, подсистемы (квалиф. fqn), права ролей, подписки, владельцы, формы, WRITES_TO (движения); слой :Detail с полным набором <Properties> по запросу. Оба формата: Конфигуратор XML и EDT.
• Граф вызовов BSL — портируемый Python-парсер: CALLS (local / общие модули / менеджерные, с confidence), модули форм + HANDLES, точки входа (проведение/запись/…), OVERRIDES для переопределений расширений (&Вместо/&Перед/&После/&ИзменениеИКонтроль).
• Векторизация и поиск — мульти-вектор (имя × смысл) + полнотекст c токенизацией идентификаторов, слияние RRF, фильтры (вид/чанк/подсистема/источник/версия), GraphRAG-достройка контекста; чанки метаданных, форм, кода (cAST), подсистем и ролей. Эмбеддинги: локальные Qwen3 (CUDA) или облачные (OpenAI-совместимые / Voyage).
• Документационные корпуса — ИТС, git-артефакты проекта, справка платформы из .hbk (версионная), стандарты разработки v8std; общий тенант __shared__ читается всеми аддитивно.
• Мультиарендность и auth — tenant из заголовка или bearer-токена (AUTH_ENABLED), runtime-провижининг тенантов с токенами в Neo4j; строгая изоляция арендаторов.
• Инкрементальность — по configVersion (Конфигуратор) / content-hash (EDT): обновляются только изменённые объекты, входящие связи сохраняются.
• Контур оркестрации — overlay-write сервер (per-task дельты поверх baseline, :8001) и admin-сервер (:8002): baseline-реиндекс по MCP (fire-and-poll), веб-дашборд джоб, провижининг.
• 30 read-only MCP-инструментов — поиск, структура, зависимости/импакт, код и граф вызовов, документация по источникам, стандарты, метрики. Полный список — docs/MCP_USAGE.md.
• onec-lite — локальная навигация по живой рабочей копии без Neo4j и эмбеддингов; не полный эквивалент big (режимы и ограничения — выше).

Проверено на реальных базах: УТ (≈14,9k объектов, EDT с расширениями) и ERP/УХ (≈24k объектов). Актуальный статус и ограничения — docs/STATE.md.

Команды

uv run onec-vecgraph index "<путь к выгрузке>" --tenant-id <t> --reset        # построить граф (Конфигуратор|EDT)
uv run onec-vecgraph index "<путь к выгрузке>" --tenant-id <t> --incremental  # только изменённые
uv run onec-vecgraph callgraph --tenant-id <t>                             # граф вызовов BSL (+формы/HANDLES/OVERRIDES)
uv run onec-vecgraph vectorize --tenant-id <t> [--code]                    # эмбеддинги (нужен --extra local-embeddings)
uv run onec-vecgraph search "запрос" --tenant-id <t> --mode hybrid         # поиск (+--kind/--chunk-kind/--subsystem/--expand)
uv run onec-vecgraph show Catalog.Имя --tenant-id <t> [--detail]           # карточка объекта (+полные свойства)
uv run onec-vecgraph deps Catalog.Имя --tenant-id <t>                      # зависимости
uv run onec-vecgraph ingest <manifest.yaml> --tenant-id <t>                # доки: ИТС / git-артефакты / справка
uv run onec-vecgraph ingest-help --tenant-id __shared__ --bin "<.../1cv8/8.3.x/bin>" --domain shcntx --domain shlang  # справка платформы (.hbk)
uv run onec-vecgraph platform-docinfo "Массив.Найти" --tenant-id <t>       # синтаксис-помощник: точный лукап
uv run onec-vecgraph serve --transport http                                # read-MCP: http://127.0.0.1:8000/mcp
uv run onec-lite admin                                                     # lite: живая рабочая копия + веб-админка (:8010)

Локальные эмбеддинги: uv sync --extra local-embeddings (torch cu128 под RTX 50xx), в .env — EMBEDDING_PROVIDER=local. По умолчанию модель Qwen3-Embedding-0.6B (для качества — EMBEDDING_MODEL=Qwen/Qwen3-Embedding-4B). Облачные — --extra cloud-embeddings.

Требования

• Python 3.12 и uv (winget install astral-sh.uv)
• Docker + Docker Compose — для Neo4j и контейнерного деплоя (для onec-lite не нужны)

Данные Neo4j — в ./data/neo4j, кеш модели эмбеддингов — в ./data/hf-cache (тома compose).

Быстрый старт big (Neo4j)

# 1) Зависимости (создаст .venv в проекте)
uv sync

# 2) Поднять Neo4j
docker compose up -d --wait neo4j
#    Браузер Neo4j: http://localhost:7474  (neo4j / onec_vecgraph_dev)

# 3) Проверить связность
uv run onec-vecgraph health

# 4) Запустить MCP-сервер
uv run onec-vecgraph serve --transport http     # http://127.0.0.1:8000/mcp
uv run onec-vecgraph serve --transport stdio    # для локальных MCP-клиентов

# Тесты (именно tests/ — без аргумента pytest соберёт 0)
uv run pytest tests/

Docker

MCP-сервер пакуется в образ; Neo4j, read-сервер (app) и admin-сервер поднимаются через compose. Эмбеддинги конфигурируемы на сборке: CPU (по умолчанию) или GPU (cu128).

# Сборка + запуск (MCP: http://127.0.0.1:8000/mcp, admin: :8002)
docker compose up -d --build

В текущем compose у сервисов app/app-admin включён GPU (deploy.resources + TORCH_INDEX_URL=cu128) — нужен NVIDIA Container Toolkit; для CPU-хоста закомментируйте блок deploy.resources и соберите с дефолтным (CPU) TORCH_INDEX_URL. Тяжёлая индексация/векторизация запускается отдельно (CLI, обычно на GPU-хосте) — данные пишутся в тот же Neo4j. Модель кешируется в томе ./data/hf-cache (первый запрос качает ~1.2 ГБ).

Аутентификация (для сетевого доступа): включить bearer-токены — AUTH_ENABLED=true, AUTH_TOKENS="tok_abc=acme,tok_xyz=globex:ext_crm" (токен→tenant[:config]; X-Tenant-Id тогда игнорируется как недоверенный), либо runtime-провижининг тенантов через admin-сервер (PROVISIONING_ENABLED). Иначе разворачивать строго за аутентифицирующим gateway. Подробности — docs/DEPLOYMENT.md и docs/MCP_USAGE.md.

Конфигурация

Все настройки — через .env (см. .env.example, каждая настройка прокомментирована в docs/DEPLOY_DETAILED.md): Neo4j, провайдер эмбеддингов (hashing для разработки, local, openai, voyage), MCP, auth, admin/overlay. Настройки onec-lite — ONEC_LITE_* (см. docs/LITE_USAGE.md).

Структура

src/onec_vecgraph/
  config.py         # настройки (pydantic-settings, .env)
  tenancy.py        # резолв арендатора: заголовки / bearer-токены
  server.py         # read-MCP (FastMCP, 30 инструментов)
  write_server.py   # overlay-write MCP (:8001, opt-in)
  admin_server.py   # admin MCP (:8002): baseline-реиндекс, провижининг, дашборд
  cli.py            # CLI: serve*/index/callgraph/vectorize/search/ingest/…
  indexer.py        # выгрузка → граф метаданных (полный/инкремент)
  callgrapher.py    # граф вызовов BSL (+формы, HANDLES, OVERRIDES)
  vectorizer.py     # чанки → эмбеддинги (мульти-вектор)
  chunking.py       # построение чанков, cAST, токенизация, точки входа
  queries.py        # поиск/граф/документы для MCP-инструментов
  ingest.py         # мультиисточник: ИТС / артефакты / справка (.hbk)
  baseline.py, jobs.py, dashboard.py, overlay*.py  # admin/overlay-контур
  parsing/          # Конфигуратор XML + parsing/edt/ (формат-агностичный шов)
  bsl/              # портируемый BSL-парсер (рутины, вызовы, аннотации)
  graph/            # схема и построение графа Neo4j
  storage/          # драйвер Neo4j (граф, векторы, doc-корпуса, callgraph)
  embeddings/       # hashing | local (Qwen3/CUDA) | cloud (+реранкер)
  sources/          # адаптеры корпусов: its, git_artifacts, hbk
  lite/             # onec-lite: MCP по живой рабочей копии (без Neo4j)

Лицензия и проверка изменений

Код проекта распространяется по лицензии MIT — см. LICENSE. Автор в pyproject.toml — GrandTrade. Лицензия разрешает использование, изменение и распространение кода при сохранении уведомления об авторских правах и текста лицензии; код предоставляется без гарантий. MIT не распространяет дополнительные права на сторонние конфигурации, материалы ИТС, справку .hbk и другие подключаемые корпуса: их использование регулируется условиями соответствующих правообладателей.

Тестовый CI запускает tests/ на Python 3.12 в Ubuntu и Windows, без деплоя, Neo4j, GPU и внешних API-ключей:

uv sync --locked --extra ingest --extra wiki
uv run --no-sync python -m pytest tests/ -ra

Dev-зависимости устанавливаются по умолчанию. Тесты используют синтетические данные и моки; проверки реальных .hbk и локальной выгрузки могут быть пропущены, если их нет. Зелёный CI не заменяет интеграционную проверку Neo4j, провайдеров эмбеддингов или конкретной конфигурации 1С.