mcp-1c-homework
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
1C MCP RAG Search
Поисковый слой для выгрузки 1С, доступный LLM-агенту через MCP: находит нужную бизнес-логику по BSL-коду и по метаданным конфигурации. Работает локально, без внешних API: данные не покидают машину.
Внутри — гибридный retrieval с двумя независимыми сигналами: семантическим (e5-small + Chroma) и лексическим (собственный BM25), объединёнными через Reciprocal Rank Fusion. Качество измерено на собственном gold-set: hybrid — дефолт, потому что на dev-наборе он значимо лучше vector, а на независимом hold-out — не хуже. Дополнительно включён source-dedup: не более 2 чанков из одного файла (MAX_PER_SOURCE=2, MCP_1C_MAX_PER_SOURCE=0 отключает).
Показатель | Значение |
Индекс | 179 586 чанков: 154 560 кода (нарезка по процедурам) + 25 026 метаданных (XML) |
Лексический индекс | глобальный BM25: 179 586 документов, 236 320 термов, 81 МБ ( |
Качество, v2 dev (nDCG@10) | hybrid 0.442 ± 0.012 против vector 0.331 ± 0.028; Δ = −0.112, CI [−0.184; −0.038], p = 0.0037 |
Качество, v3 hold-out | hybrid 0.217 ± 0.015, vector 0.208 ± 0.020; p = 0.635 — не хуже (исторический расчёт на 71 code-запросе; текущий |
Diversity, v2/v3/v4 (nDCG@10 Δ) | +0.028 / +0.003 / +0.012; unique sources 5.86→7.37 / 6.72→7.97 / 5.21→7.47; latency 48→54 мс (1.115×) |
Латентность (CPU) | 50–105 мс |
Инженерные проверки | 258 тестов, |
Задача
Выгрузка 1С — тысячи .bsl-модулей и XML-метаданные. Разработчику нужно быстро найти, где реализована конкретная логика, а LLM-агенту — надёжный инструмент поиска вместо grep. Проект даёт и то и другое: MCP-сервер со стандартными инструментами и воспроизводимый retrieval-пайплайн с метриками, ADR и публично зафиксированными ограничениями.
Related MCP server: Onec Platform Help MCP Server
Как это работает
flowchart LR
Q[query] --> E[e5-small<br/>«query: »]
E --> C[Chroma cosine<br/>top-N]
Q --> B[BM25 индекс<br/>179 586 чанков<br/>code_proc + metadata_xml]
B --> BT[BM25<br/>top-N]
C --> R{RRF<br/>k=60}
BT --> R
C -->|mode=vector| OUT[top-k]
R -->|mode=hybrid·текущий дефолт| OUT
R -->|mode=hybrid_rerank| RR[flashrank<br/>ms-marco-MultiBERT-L-12]
RR --> OUTCosine по e5-small и глобальный BM25 по 179 586 чанкам двух коллекций (code_proc + metadata_xml) объединяются по рангам через RRF. Cross-encoder подключается опционально вторым этапом. Устройство — в docs/ARCHITECTURE.md.
Быстрый старт
Нужны Python 3.11–3.12, дерево .bsl и XML-выгрузка конфигурации, 2+ ГБ на модель и индекс (6–8 ГБ RAM для полной индексации).
git clone https://github.com/Smaturus/1c-mcp-rag-search.git
cd 1c-mcp-rag-search
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"
$env:MCP_1C_STUDY_ROOT="1C-Corpus\1C_Corpus" # дерево .bsl и XML выгрузки
# XML-дамп для сборки metadata_xml; по умолчанию не задан
# $env:MCP_1C_METADATA_XML_ROOT="1C-Corpus\1C_Corpus"
$env:MCP_1C_CHROMA_DIR="data\chroma_xml" # код + метаданные
$env:MCP_1C_BM25_DIR="data\bm25_all" # глобальный BM25
# опционально: $env:MCP_1C_SKIP_STARTUP_CHECK="1" # пропустить проверку индекса при старте MCP
# прогрев: $env:MCP_1C_WARMUP="0" # отключить фоновый прогрев индекса и модели
# $env:MCP_1C_WARMUP_DELAY_S="3" # задержка прогрева после старта (секунды)
# логи (только stderr): $env:MCP_1C_LOG_LEVEL="INFO" # DEBUG|INFO|WARNING|ERROR
# $env:MCP_1C_LOG_JSON="1" # JSON-строки
# $env:MCP_1C_LOG_QUERIES="1" # opt-in: логировать текст запроса (default 0)
# манифест индекса: $env:MCP_1C_MANIFEST_PATH="data\manifests\chroma_xml.json"
# python scripts\build_manifest.py --chroma-dir data\chroma_xml --bm25-dir data\bm25_all --out data\manifests\chroma_xml.json
# локальный eval-suite: python scripts\eval_suite.py --sets v2 --record
# (gold и data/manifests/ — локально, не в git; не для публичного CI)
python scripts\build_procedure_index.py --no-lock # code_proc
python scripts\parse_config_xml.py --root $env:MCP_1C_METADATA_XML_ROOT
python scripts\build_metadata_index.py --reset # metadata_xml
python scripts\build_bm25.py --chroma-dir data\chroma_xml --out data\bm25_all
python scripts\eval_pipeline.py --golden data\eval\gold_set_v2.jsonl --out-dir data\eval\code_procПервый запуск индексации скачивает intfloat/multilingual-e5-small. MCP-сервер стартует с HF_HUB_OFFLINE=1 (по умолчанию) и берёт модель только из локального кэша, не обращаясь к huggingface.co; $env:HF_HUB_OFFLINE="0" разрешает загрузку и для сервера. Корпус по умолчанию — 1C-Corpus\1C_Corpus в корне репозитория. Legacy-индексатор (символьные окна + текстовый отчёт) остаётся для ablation: python -m mcp_1c_rag.indexer --reset и python scripts\build_bm25.py --chroma-dir data\chroma --out data\bm25. Смоук — --files 300 --collection code_proc_smoke --reset.
MCP-инструменты
Четыре MCP-инструмента. Основные коллекции — code_proc и metadata_xml. code и metadata — legacy: могут быть пустыми и как основные не используются (code/metadata в search ведут в канонические коллекции).
Tool | Назначение |
| единый пайплайн: |
| Hit@k, Recall@k, MRR, nDCG по одному запросу; |
| маршрут → |
| индекс (каталог, коллекции, размеры, режим) + readiness ( |
Каждый результат search содержит uri: bsl://<путь> — модуль BSL целиком из MCP_1C_STUDY_ROOT (только .bsl, путь не выходит за каталог; выбор одной процедуры не поддерживается), metadata://<вид>/<имя> — карточка объекта из коллекции XML-метаданных metadata_xml. Статические ресурсы index://stats и index://manifest отдают тот же текст, что index_stats, и JSON манифеста; оба не открывают Chroma. Читаются как ресурсы MCP.
Все четыре tools — только чтение: схема аргументов отдаётся с enum для mode/collection, а ToolAnnotations помечают их readOnlyHint=true, openWorldHint=false. Значения вне схемы отклоняются до запуска поиска.
Примеры search:
search("ПередЗаписью", mode="lexical", collection="metadata_xml")
search("как настроить обмен", mode="vector", collection="all")
search("НДС с аванса", mode="hybrid", collection="all")
search("ПровестиДокумент", collection="code_proc")Legacy Python aliases (not MCP tools)
В модуле mcp_1c_rag.server остались обычные Python-функции для совместимости:
codesearch, metadatasearch, search_1c_metadata, search_knowledge_base,
search_hybrid. Они не регистрируются как MCP tools.
Стек: MCP Python SDK 2.x + Chroma + intfloat/multilingual-e5-small + собственный BM25 + flashrank (опция).
Маршрутизация
Правила выбора mode/collection для search — код с тестами (router.py, tests/test_router.py), а не текст промпта.
Признак в запросе | Маршрут |
CamelCase-имена, коды ( |
|
«как сделать», «почему не работает», «инструкция», «опыт», «лучшие практики» |
|
требования, ТЗ, регламент, Confluence; смесь точного и смыслового |
|
признаков нет |
|
Регрессия — 68/68, но кейсы использовались при настройке. На независимом hold-out v3 роутер даёт 58/100 (43/76 на отвечаемых); основная ошибка — lexical→hybrid. Маршрутизация не ухудшает качество, но доказанного прироста нет. Контракт — ADR 0006, детали — docs/EVALUATION.md.
Retrieval pipeline
Единая точка входа — search(query, top_k, mode) в search_modes.py.
Режим | Что делает | Латентность |
| только cosine (baseline) | ~50–105 мс |
| взвешенный | ~85–160 мс |
| cosine + глобальный BM25 через RRF (дефолт) | ~100–120 мс |
| RRF + cross-encoder вторым этапом | ~2,4 с |
RRF по рангам:
score(d) = Σ 1/(k_rrf + rank_i(d)),k_rrf = 60.Глобальный BM25 по 179 586 чанкам: собственный инвертированный индекс.
Токенизация под 1С: кириллица, цифры, дефисные коды, CamelCase/snake_case с сохранением исходного токена (ADR 0010).
Префиксы e5 (
query:/passage:) сохраняются.Reranker переупорядочивает 20 кандидатов RRF, а не заменяет e5.
Параметры — переменные окружения в
config.py.
python -c "from mcp_1c_rag.search_modes import search; print(search('НДС с аванса', top_k=3, mode='hybrid'))"Chunking по процедурам
.bsl режется по границам Процедура/Функция … КонецПроцедуры/КонецФункции (chunking_procedures.py, ADR 0007). Чанк получает префикс // file: <path> · proc: <name>; код вне процедур идёт отдельным чанком; длинная процедура делится на части с перекрытием 150 символов. Параметры: max_chars=1000, overlap=150.
Смоук на 800 файлах: покрытие кода 99,6 %, чанков сверх 512 токенов 0,3 %, токены p50/p99/max — 179/472/554. Отчёт — data/eval/procedure_chunking_smoke.md.
chunking_tokens.py и chunking_xml_tokens.py — эксперимент: режут по токенам и в обслуживаемый индекс не входят. Отдельный индекс и сравнение качества — только отдельным решением. Коллекцию config_xml в текущий индекс не добавлять: это меняет метрики v2/v3.
Оценка качества
Релевантность — на уровне файла-источника, повторные чанки схлопываются до расчёта метрик (ADR 0003–0004). v2 — dev-набор, v3 — независимый hold-out.
v2, 70 запросов, 4 прогона:
Конфигурация | Hit@1 | MRR@10 | nDCG@10 | Recall@10 |
| 0.271 | 0.355 | 0.426 | 0.571 |
| 0.164 ± 0.018 | 0.266 ± 0.026 | 0.331 ± 0.028 | 0.511 ± 0.044 |
| 0.207 ± 0.038 | 0.313 ± 0.039 | 0.383 ± 0.040 | 0.562 ± 0.053 |
| 0.221 ± 0.008 | 0.368 ± 0.010 | 0.442 ± 0.012 | 0.652 ± 0.024 |
Парный тест (n = 70): Δ nDCG@10 (vector − hybrid) = −0.112, CI [−0.184; −0.038], p = 0.0037, побед/ничьих/поражений — 22/22/26.
v3 hold-out, 71 code-запрос (исторический расчёт; текущий --scope code — 64), 3 прогона: hybrid 0.217 ± 0.015, vector 0.208 ± 0.020, pearson 0.229 ± 0.019, lexical 0.218; Δ = −0.0097, p = 0.635 — не значимо. Метаданные: XML-выгрузка (25 026 чанков) даёт BM25 Hit@3 99,7 % против 93,0 % у текстового отчёта.
Source-dedup (live, 2026-11-06): max_per_source=2 против 0, pool=30, same-process harness. nDCG@10 Δ +0.0275 / +0.0030 / +0.0119; recall@10 Δ +0.071 / +0.008 / +0.030; unique_sources@10 +1.51 / +1.25 / +2.26; latency 48.1→53.6 мс (1.115×). Детали — локальные заметки data/local_notes/algo_glm5/final_decision.md (в git не входят).
Методика, латентность и разбивка по типам — docs/EVALUATION.md. История чисел и отклонённые гипотезы — docs/HISTORY.md.
Воспроизводимость
Параметр | Значение |
Корпус |
|
Embedding |
|
HNSW | cosine ( |
BM25 | собственный индекс ( |
RRF |
|
Дефолтный режим |
|
Source diversity |
|
Подключение к клиенту
В mcp.json (Cursor) или mcp.servers (ZCode):
"1c-mcp-rag-search": {
"command": "D:\\path\\to\\repo\\.venv\\Scripts\\python.exe",
"args": ["-m", "mcp_1c_rag"]
}После перезапуска клиента появятся 4 tools (search, evaluate_retrieval, route_query, index_stats). Проверка без клиента:
python -c "import asyncio; from mcp_1c_rag import server; print(sorted(t.name for t in asyncio.run(server.mcp.list_tools())))"Разработка и качество
pytest -q # 258 тестов (ML-стек не требуется: импорты ленивые)
ruff check . # линтер
mypy # типы (35 source-файлов)
python scripts\check_complexity.py # гейт сложности (radon)
pytest -q --cov=src/mcp_1c_rag # покрытиеCI (.github/workflows/ci.yml): ruff + mypy + гейт цикломатической сложности + pytest с покрытием на Python 3.11 и 3.12; тяжёлые зависимости импортируются лениво.
Гейт | Порог | Сейчас |
| без замечаний | 0 / 0 |
Сложность ( | средняя ≤ 6, блоки > 20 только из baseline, MI ≥ 20 | 4.37 (A), 143 блока |
Baseline сложных функций | не расти, только сокращать | 2 записи: |
Покрытие | floor 25 %, цель 60 % | ≥ 25 % |
Unit-тесты | не уменьшать | 258 |
Структура
src/mcp_1c_rag/ 35 source-файлов: server, search_modes, bm25, rrf, rerank,
router, chunking*, embeddings, store, metrics, index_guard, dedup
scripts/ сборка индексов, eval, диагностика
tests/ 258 тестов
docs/ ARCHITECTURE.md, EVALUATION.md, HISTORY.md, adr/
data/eval/ gold-set и отчёты (индекс — data/eval/README.md)Ограничения
HNSW не персистится при
hnsw:sync_threshold=1000000(защита от chroma#7090): каждый запуск процесса пересобирает индекс из sqlite. Сервер отвечает клиенту за ~2–3 с (проверка при старте считает записи по sqlite, не загружая HNSW), а пересборку HNSW обеих коллекций, загрузку BM25 и e5 делает фоновый прогрев (~35 с после задержкиMCP_1C_WARMUP_DELAY_S).searchиevaluate_retrievalждут его окончания: первый поиск сразу после запуска по-прежнему занимает ~35–40 с, после прогрева — ~50–180 мс. Пересборка HNSW держит GIL, поэтому на время прогрева сервер не отвечает и на другие запросы.Один писатель; параллельная индексация не поддерживается.
Инкрементального обновления нет: после изменения выгрузки индекс пересобирается целиком (прерванную сборку можно возобновить).
Gold-set частично синтетический, e5-small не обучена на BSL: абсолютные метрики скромные, корректно сравнивать конфигурации на одном наборе.
Выгрузки 1С и векторные индексы в репозиторий не попадают.
Клетка 2×2 «старая выгрузка × процедурная нарезка» не измерима, остальные сняты до ADR 0010; повторный замер — в roadmap.
Roadmap
Код-ориентированная embedding-модель и новый baseline
RRF с весами источников, preprocessing и глубина каналов — проверено, значимого прироста на v2 нет (docs/HISTORY.md)
Новый независимый hold-out для маршрутизации (≥ 20 фраз)
Повторный замер 2×2 исправленным токенизатором BM25
English README (
README.en.md)Ресурс
bsl://с выбором процедуры (?proc) и полеprocв выдачеsearch
Завершённые этапы и отклонённые гипотезы — docs/HISTORY.md.
Документация
Документ | Содержание |
компоненты, потоки данных, хранение, риски | |
методика, наборы, метрики, воспроизведение | |
таймлайн и отклонённые гипотезы | |
архитектурные решения со статусами | |
индекс отчётов: актуально / историческое / superseded | |
история релизов | |
как внести изменение и сообщить об уязвимости |
Данные и безопасность
В репозитории нет выгрузок 1С, готовых индексов и персональных данных. Примеры и скриншоты используют стандартные имена объектов конфигурации; абсолютные пути в отчётах заменены на относительные. О проблеме — SECURITY.md.
Лицензия
MIT — см. LICENSE.
Контакты
Автор — Sergey Matyukhin.
GitHub: @Smaturus
Email: smaturus@gmail.com
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Cloud or self-hosted knowledge for AI agents: hybrid search, reranking, GraphRAG, scoped MCP tools.
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
Private, multimodal knowledge store for agents: hybrid search with cited, provenance-backed results.
Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables semantic search through 1C codebase exports using local CPU-based RAG with sentence transformers and FAISS indexing. Supports fast XML file indexing and retrieval of 1C code with metadata parsing.11MIT
- AlicenseNot gradedqualityDmaintenanceProvides a RAG-based search system for 1C:Enterprise platform documentation using hybrid BM25 and semantic search across multiple versions. It enables developers to retrieve API signatures, methods, and usage examples directly within IDEs or through a REST API.22MIT
- AlicenseNot gradedqualityAmaintenanceRust-native code index MCP server with first-class 1C:Enterprise (BSL) support. Static binary, no runtime — 25 MCP tools (18 universal + 7 BSL-specific), tree-sitter AST for 10 languages, federation across multiple repos.165MIT
- AlicenseNot gradedqualityBmaintenanceFast hybrid code search for agents. Pure Go, single static binary, BM25 lexical + Model2Vec semantic embeddings + RRF fusion + a code-aware reranker, with the retrieval algorithm ported verbatim from semble34MIT