> For the complete documentation index, see [llms.txt](https://docs.onerpa.ru/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.onerpa.ru/mcp-servery-1c/servery/help-search-server.md). # HelpSearchServer Поиск по справке платформы 1С, руководствам, спецификациям форматов и стандартам разработки с использованием RAG (Retrieval-Augmented Generation). ## Назначение HelpSearchServer — это **самый важный** MCP-сервер для разработки на 1С. Он предоставляет ИИ доступ к официальной справке платформы 1С и к сопутствующим корпусам документации. ### Почему это важно? * Методы и параметры меняются от версии к версии * ИИ без справки может давать устаревшую информацию * Поиск по смыслу, а не только по названию метода ## Что индексируется Сервер держит вместе четыре разных корпуса, и они не взаимозаменяемы: | Вид | Что это | Чем достаётся | | ----------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | | `syntax` | Справка платформы (синтакс-помощник): по странице на объект, метод, свойство, событие | `docsearch` / `docinfo`, `scope="syntax"` | | `docs` | Проза: руководства, учебные материалы, глоссарий, книга по языку запросов | `docsearch` / `docinfo`, `scope="docs"` | | `formats` | Спецификации файловых форматов объектов конфигурации (XML форм, ролей, СКД, табличных документов, расширений) | инструмент `formatspec` | | `standards` | Стандарты разработки и правила код-ревью | инструмент `standards` | {% hint style="success" %} Корпуса `docs`, `formats` и `standards`, а также архив синтакс-помощника `shcntx_ru.hbk` **поставляются внутри образа**. Сервер запускается и отвечает без монтирования папки `bin` платформы. Монтируйте её через `1C_BIN_PATH`, если нужна справка именно вашей версии платформы — тогда используется она. {% endhint %} ## Доступные инструменты MCP ИИ получает следующие инструменты: | Инструмент | Описание | | ------------ | ------------------------------------------------------------------------------------------------------ | | `docsearch` | Гибридный поиск по справке платформы и руководствам — по описанию, вопросу или частичному имени | | `docinfo` | Документация по точному имени объекта, метода или свойства; принимает и `doc_id` из ответа `docsearch` | | `formatspec` | Спецификации файловых форматов 1С: каталог, спецификация целиком или поиск внутри них | | `standards` | Стандарты разработки 1С: каталог, стандарт целиком или поиск внутри них | ### docsearch Поиск по документации 1С с гибридным подходом (векторная и полнотекстовая дорожки, объединение по RRF). Используйте для поиска по описанию, вопросу или частичному имени. Если известно точное имя объекта или метода — используйте `docinfo`. | Параметр | Тип | По умолчанию | Описание | | -------------- | ------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `query` | string | — | Поисковый запрос — описание нужной функциональности или ключевые слова (на русском языке) | | `top_k` | int | *(не задано)* | Сколько документов может содержать **результат целиком**, 1–50. Не задан — результатом становится каждый документ, прошедший порог релевантности | | `doc_type` | string | *(не задано)* | Ограничить ответ одним видом страниц: `method`, `property`, `constructor`, `event`, `object`, `type`, `structure`, `other` | | `scope` | string | *(не задано)* | Какой корпус отвечает: `syntax`, `docs` или `all`. Не задан — отвечают оба | | `max_chars` | int | `20000` | Жёсткий предел размера ответа в символах, 512–400000 | | `max_items` | int | `5` | Максимум документов **в одном ответе**, 1–50 | | `detail_level` | string | `detailed` | `detailed` — префикс документа от начала, `compact` — до четырёх фрагментов, до которых дошёл запрос, в порядке документа | | `cursor` | string | *(не задано)* | `next_cursor` предыдущего ответа — продолжить после уже выданных документов | | `diagnostics` | bool | `false` | Добавить сведения о дорожках поиска, fusion, порогах релевантности и позиции чанков | **Возврат**: JSON-объект версии `schema_version: "4.0"` с полями `outcome`, `total`, `returned`, `truncated`, `next_cursor` и `results`. Каждый результат несёт `doc_id`, компактную `citation`, `snippets` и итоговый `score`. `snippet_count` появляется только у частичного результата и показывает полное число фрагментов документа, поэтому значение больше длины `snippets` прямо доказывает усечение. Поля тяжёлой диагностики, включая вклад дорожек и кандидатов, добавляются только при `diagnostics: true`. Инструмент возвращает JSON один раз как обычный `text content`: `outputSchema` и повторный `structuredContent` в FastMCP не публикуются. {% hint style="info" %} `top_k` и `max_items` — разные ограничения. `top_k` ограничивает **набор результатов** (то, что считает `total` и через что листает курсор), `max_items` — **одну страницу** этого набора. Выход `top_k` за диапазон и неизвестный `doc_type` не подгоняются молча, а отклоняются с ошибкой. {% endhint %} *** ### docinfo Получает документацию по точному имени объекта, метода или свойства платформы 1С. Регистр не важен; зарегистрированный алиас или английское имя API приводят к той же странице, что и русское имя. | Параметр | Тип | По умолчанию | Описание | | -------------- | ------ | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | string | — | Точное имя объекта, метода или свойства. Для членов объекта — формат `ИмяОбъекта.ИмяЧлена`. Допускается форма вызова (`Массив.Найти(Значение)`) для выбора перегрузки, а также `doc_id` из ответа `docsearch` — тогда документ возвращается целиком | | `top_k` | int | *(не задано)* | Сколько документов может содержать ответ целиком, 1–50 | | `doc_type` | string | *(не задано)* | Ограничение по виду страницы; заодно снимает неоднозначность, когда имя носят и метод, и свойство | | `scope` | string | *(не задано)* | `syntax`, `docs` или `all` | | `max_chars` | int | `20000` | Жёсткий предел размера ответа в символах | | `max_items` | int | `5` | Максимум документов в одном ответе | | `detail_level` | string | `detailed` | `detailed` — от начала документа; `compact` — короткая выборка фрагментов, соответствующих запросу | | `cursor` | string | *(не задано)* | Продолжение предыдущего ответа | | `diagnostics` | bool | `false` | Добавить технический отчёт о том, как получен ответ | **Примеры значений параметра `name`:** * `ТаблицаЗначений` — объект * `Массив.Найти` — метод объекта * `Массив.Найти(Значение)` — конкретная перегрузка * `HTTPЗапрос` — объект **Если имя не найдено** — ответ `outcome: "not_found"` с блоком `fallback` и ближайшими документами в качестве кандидатов: у них есть `doc_id` и цитата, но нет тела. Это подсказка «возможно, вы имели в виду», а не ответ. **Если имя неоднозначно** (например, `Найти` документирован на десятках страниц) — `resolution.status` = `ambiguous`, а результатами становится список кандидатов: по одному на документ, с `doc_id`, владеющим объектом и цитатой, без тел. В одном ответе не более 20 кандидатов, `total` считает все, `next_cursor` достаёт остальные. Уточните имя объектом или сигнатурой и спросите снова. *** ### formatspec Спецификации файловых форматов 1С — описание XML объектов конфигурации (формы, роли, схемы СКД, табличные документы, расширения). Написаны, чтобы читаться целиком, поэтому у них отдельный инструмент. | Параметр | Тип | По умолчанию | Описание | | -------------- | ------ | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | string | *(не задано)* | Вернуть спецификацию целиком. Принимает короткое имя (`1c-form-spec`), идентификатор документа из предыдущего ответа или заголовок спецификации | | `query` | string | *(не задано)* | Искать только внутри спецификаций | | `max_chars` | int | `20000` | Предел размера ответа | | `max_items` | int | `5` | Максимум документов в ответе | | `detail_level` | string | `detailed` | `detailed` — от начала документа; `compact` — короткая выборка фрагментов, соответствующих запросу | | `cursor` | string | *(не задано)* | Продолжение предыдущего ответа | | `diagnostics` | bool | `false` | Добавить технический отчёт о маршрутах извлечения | Три способа вызова: ``` formatspec() → каталог: все спецификации, их имена и начало текста formatspec(name="1c-form-spec") → эта спецификация целиком formatspec(query="реквизиты формы") → поиск внутри спецификаций ``` Документ больше `max_chars` **не обрезается, а листается**: он приходит частями по порядку, `next_cursor` продолжает его, а `collection.parts` говорит, сколько всего частей. *** ### standards Стандарты разработки 1С — правила именования, оформления кода, запрещённых конструкций, проектирования запросов, модулей форм, блокировок и транзакций. Вызывается так же, как `formatspec`: ``` standards() → каталог правил с их описаниями standards(name="coding-standards") → этот стандарт целиком standards(query="именование") → поиск внутри стандартов ``` Параметры совпадают с `formatspec`. {% hint style="info" %} `formatspec` и `standards` недостижимы через `scope` — у них собственные инструменты, и второго маршрута к ним нет. {% endhint %} ## Контракт ответа {% hint style="warning" %} Контракт 4.0 описывает текущее состояние исходников beta-кандидата. Перед использованием опубликованного Docker-тега проверьте `schema_version` в ответе и отсутствие `outputSchema` в `tools/list`: stable и ранее скачанные beta-образы могут отвечать по предыдущему контракту. {% endhint %} Все четыре инструмента возвращают один JSON-объект версии `schema_version: "4.0"` с полем `outcome`: | `outcome` | Что означает | | ------------- | ------------------------------------------------------------------------------------------ | | `ok` | Документы возвращены в `results` | | `not_found` | Вызов успешен, но ничего не совпало достаточно близко. Это не ошибка: в корпусе нет ответа | | `unavailable` | Отвечать пока не из чего — индекс стартует, строится или не смонтирован | | `error` | Вызов не удалось обслужить — некорректный запрос или сбой внутри сервера | Контракт 4.0 не повторяет одинаковые сведения. Пустые и избыточные поля цитаты отсутствуют: `object_name`, `full_name`, `section`, `parent_id`, `source` и `doc_type` появляются только когда добавляют информацию и не выводятся однозначно из других полей. Если весь ответ относится к одному корпусу, `corpus` находится в общем envelope; при смешанном ответе он переносится в цитаты отдельных результатов. `score` округляется до четырёх знаков и возвращается только на уровне результата. `snippet_count` отсутствует у полного результата и появляется у частичного как полное число доступных фрагментов; отдельного `results[].truncated` больше нет. Отсутствие прочего необязательного поля означает пустое, `false` или `null`, а не потерю данных. Без `diagnostics` ответ не содержит retrieval-механики: `lanes`, `fusion`, `relevance`, `detail_level` и per-result lane scores отсутствуют. Общий `filter` остаётся частью обычного ответа, а `status` появляется независимо от диагностики, когда индекс ещё не готов. Параметр `diagnostics: true` возвращает технический отчёт: состояние дорожек, fusion, пороги и решение релевантности, `detail_level`, вклад каждой дорожки в результат и координаты чанка в цитате. Для обычного поиска оставляйте диагностику выключенной, чтобы внутренние данные не расходовали `max_chars`, предназначенный для текста документации. Сниппет — один блок документа, отделённый пустой строкой; при сборке полного текста соединяйте `snippets` через `"\n\n"`. `detailed` всегда возвращает префикс документа. `compact` показывает не заголовок по умолчанию, а до четырёх содержательных фрагментов, до которых дошёл запрос, в исходном порядке документа. Если совпавших блоков нет, выбирается содержательное начало, а не служебная метка или пустой заголовок; нерелевантными соседними блоками ответ до четырёх не дополняется. Ответ с `outcome: "error"` несёт объект `error` с полями `type` (`not_found`, `invalid_argument`, `unavailable`, `internal`) и `correlation_id` — идентификатор запроса в журнале сервера. Ни трассировки, ни путей, ни имён модулей клиенту не отдаётся; при обращении в поддержку достаточно назвать `correlation_id`. Пока строится первый индекс, `docsearch` и `docinfo` отвечают типизированным `"status": "indexing"` с прогрессом сборки, а не ошибкой. Если предыдущее поколение индекса уже есть — оно отвечает всё время пересборки, и каждый ответ называет поколение, из которого получен. ## Релевантность Каждый кандидат обязан пройти порог в той дорожке, которая его нашла; запрос, где не прошёл никто, отвечается `outcome: "not_found"` без документов — вместо пяти ближайших, но не относящихся к делу страниц. При `diagnostics: true` каждый порог в `relevance.thresholds` называет оцениваемое поле через `field`, а отчёт различает `admitted`, `rejected` и `cleared`. Для успешного ответа публикуется `best`, для `not_found` — ближайшие отклонённые кандидаты в `closest`. ## Возможности ИИ получает инструменты для: * Получения документации по точному имени объекта или метода * Поиска методов и их параметров по описанию * Чтения руководств и книги по языку запросов * Получения спецификации формата XML объекта конфигурации целиком * Загрузки стандартов разработки перед написанием или ревью кода ## Примеры запросов После подключения сервера ИИ может отвечать на вопросы: * "Как сгенерировать случайное число?" * "Как работать с временными таблицами в запросах?" * "Как получить текущую дату сеанса?" * "Покажи документацию по ТаблицаЗначений" * "Что принимает метод Массив.Найти?" * "Дай спецификацию формата XML управляемой формы" * "Какие стандарты 1С по именованию переменных?" ## Требования * Docker Engine или Docker Desktop с поддержкой Linux-контейнеров * Лицензионный ключ * Embedding модель (LM Studio или встроенная CPU-модель) * Папка `bin` установленной платформы 1С — **опционально**, для справки своей версии платформы ## Порт **8003** ## Образ Docker ``` comol/1c_help_mcp:latest ``` | Вариант | Stable | Beta | Архитектура | Embedding | | ----------- | -------- | ------------- | ----------- | ----------------------------------------- | | полный | `latest` | `latest-beta` | amd64 | Локальная модель в образе или внешний API | | облегчённый | `light` | `light-beta` | amd64 | Только внешний OpenAI-совместимый API | | ARM | `arm64` | `arm64-beta` | arm64 | Локальная модель в образе или внешний API | Новые корпуса, индекс поколений и контракт ответа 4.0 сначала публикуются в beta. У stable индекс монтируется в `/app/chroma_db`, у beta — в `/app/index`; не подключайте один каталог к обоим каналам. Подробнее: [Каналы образов](/mcp-servery-1c/kanaly-obrazov.md). ## Быстрый старт ```powershell docker run -d -p 8003:8003 ` --name 1c_help_mcp ` -e LICENSE_KEY=YOUR_BETA_LICENSE_KEY ` -v "E:/bases/mcp_docs_beta:/app/index" ` comol/1c_help_mcp:latest-beta ``` Справка платформы своей версии — дополнительным монтированием: ```powershell -v "C:/Program Files/1cv8/8.3.23.1997/bin:/1c_docs" ` -e 1C_BIN_PATH=/1c_docs ` ``` {% hint style="warning" %} Индекс хранится в `/app/index` (ранее — `/app/chroma_db`). Если вы обновляетесь с версии, где индекс лежал в `chroma_db`, выполните разовую миграцию — см. [Установка](/mcp-servery-1c/servery/help-search-server/ustanovka.md). {% endhint %} ## HTTP-эндпоинты | Эндпоинт | Метод | Назначение | | ----------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `/mcp` | POST | MCP (streamable-http; при `USESSE=true` — SSE) | | `/health` | GET | Живость процесса и счётчики HTTP-сессий | | `/ready` | GET | Готовность обслуживать: `starting`, `indexing`, `ready`, `degraded`; `200` только когда поколение индекса отвечает и последняя сборка не упала | | `/plugins` | GET | Что загружено из каталога плагинов, какие hooks активны, что отключено и почему | | `/plugins/reload` | POST | Перечитать каталог плагинов без перезапуска | ## Конфигурация Cursor ```json { "mcpServers": { "1c-docs-mcp": { "url": "http://localhost:8003/mcp", "connection_id": "1c_docs_service_001" } } } ``` ## Структура раздела * [Установка](/mcp-servery-1c/servery/help-search-server/ustanovka.md) — команды запуска * [Конфигурация](/mcp-servery-1c/servery/help-search-server/konfiguraciya.md) — все параметры * [Использование](/mcp-servery-1c/servery/help-search-server/ispolzovanie.md) — примеры работы ## Доработка Сервер расширяется плагинами: пять hooks (`on_startup`, `on_request`, `on_query`, `on_result`, `on_document`) и таблицы `ALIASES` и `TOOL_PRESETS`. См. [Систему плагинов](/mcp-servery-1c/sistema-pluginov.md) и [Конфигурацию](/mcp-servery-1c/servery/help-search-server/konfiguraciya.md). ## Процессоры без AVX2 В Help beta от 14.09.2026 для x86-64 требуется SSE4.2 и AVX, без обязательного AVX2. Это относится к `latest-beta` и `light-beta`: они используют совместимую сборку zvec 0.6.0. Проверены профили SandyBridge и IvyBridge в QEMU. ARM-вариант поставляется отдельно как `arm64-beta`. Если прежний `light-beta` завершался с SIGILL (exit 132) до появления логов, обновите образ и пересоздайте контейнер с beta-ключом, сохранив существующие тома и настройки внешнего embedding API. Вариант light по-прежнему использует zvec для хранения и поиска. Stable-теги этим выпуском не обновляются. Также исправлена публикация MCP-схем на Python 3.10: у top\_k, doc\_type и max\_chars сохраняются описания, диапазоны и перечисления допустимых значений. Имена инструментов, значения по умолчанию и поведение поиска не меняются.