> 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/code-checker/konfiguraciya.md). # Конфигурация ## Переменные окружения ### Обязательные | Переменная | Описание | | --------------- | ------------------------------------------------ | | `LICENSE_KEY` | Лицензионный ключ MCP-сервера | | `ONEC_AI_TOKEN` | Токен для доступа к API 1С:Напарник (code.1c.ai) | ### API подключение | Переменная | Описание | По умолчанию | | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | | `ONEC_AI_BASE_URL` | Базовый URL API 1С.ai | `https://code.1c.ai` | | `ONEC_AI_TIMEOUT` | Таймаут отдельного запроса к API (секунды): connect, write, получение соединения из пула и чтение непотокового запроса. SSE-поток им **не** обрывается | `30` | | `ONEC_AI_OPERATION_TIMEOUT` | Единый бюджет времени на всю операцию, включая чтение SSE и повторные попытки (секунды). Он же — единственная граница чтения потока. Подбирайте под самый крупный модуль и укладывайте в таймаут инструмента своего MCP-клиента | `300` | | `ONEC_AI_TRANSPORT_RETRIES` | Дополнительные попытки при транспортном сбое (сетевая ошибка, таймаут одного запроса, HTTP 5xx/429). Каждая — на свежей дискуссии и внутри бюджета операции; `0` означает одну попытку | `2` | | `ONEC_AI_INPUT_MAX_LENGTH` | Максимальная длина **каждого** входного поля, передаваемого upstream (символы) | `100000` | | `ONEC_AI_WORKSPACE_ROOTS` | Разрешённые корневые каталоги для `files`, разделённые `os.pathsep`; каждый должен быть существующим абсолютным каталогом | `/workspace` в Docker | | `ONEC_AI_WORKSPACE_MAX_FILE_BYTES` | Максимальный размер одного файла, читаемого через `files` | `2000000` | | `ONEC_AI_WORKSPACE_PATH_MAP` | Соответствия `префикс_на_хосте=корень_в_контейнере`, разделённые `;` или переводами строк — **не** `os.pathsep`: в префиксе с буквой диска уже есть свой `:`. Нужны, если агент передаёт абсолютные Windows/UNC-пути; целевой корень обязан входить в `ONEC_AI_WORKSPACE_ROOTS`, иначе сервер не стартует | *(пусто)* | {% hint style="info" %} Ограничение длины применяется к каждому полю отдельно, а не к запросу целиком, и результат несёт **доказательство усечения**: в ответе видно, какое поле и на сколько было укорочено. Ничего не обрезается молча. {% endhint %} ### Режим работы | Переменная | Описание | По умолчанию | | -------------------- | ---------------------------------------------------------------------------- | ------------ | | `MCP_TOOL_CALL_MODE` | Режим вызова upstream: `direct` или `standard` (см. ниже) | `direct` | | `ONEC_AI_SKILL_NAME` | Режим сессии Напарника: `custom` (с инструментами) или `raw` (прямые ответы) | `custom` | ### Языковые настройки | Переменная | Описание | По умолчанию | | ------------------------------ | ---------------------------------- | ------------ | | `ONEC_AI_UI_LANGUAGE` | Язык интерфейса | `russian` | | `ONEC_AI_SCRIPT_LANGUAGE` | Скриптовый язык: `ru` или `en` | `ru` | | `ONEC_AI_PROGRAMMING_LANGUAGE` | Язык программирования по умолчанию | *(пусто)* | ### Документация и конфигурация 1С | Переменная | Описание | По умолчанию | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------ | | `ONEC_AI_DOC_VERSION` | Версия документации платформы по умолчанию — **конкретная версия**, не `latest`. Переопределяется параметром `version` в вызове | `v8.5.1` | | `ONEC_CONFIG_NAME` | Название конфигурации 1С по умолчанию для инструмента `config_help` (например, `ERP`, `Бухгалтерия предприятия`) | *(пусто)* | {% hint style="info" %} Сервер не отслеживает «последнюю» версию документации и не заявляет, что делает это: ответ инструментов поиска сообщает в поле `version_used`, какая версия фактически ответила. {% endhint %} ### Upstream-дискуссии Это диалоги на стороне 1С.ai, а не транспортные сессии MCP. | Переменная | Описание | По умолчанию | | ----------------------------------- | ------------------------------------------------------ | ------------ | | `MAX_ACTIVE_SESSIONS` | Максимум активных upstream-дискуссий | `10` | | `SESSION_TTL` | Время жизни upstream-дискуссии (секунды) | `3600` | | `ONEC_AI_CONVERSATION_BUSY_TIMEOUT` | Сколько ждать освобождения занятой дискуссии (секунды) | `60` | {% hint style="info" %} Дискуссия принадлежит вызывающему: `ask_1c_ai` переиспользует **собственную** последнюю дискуссию звонящего и никогда не делится ею с другим пользователем, проектом или задачей. Остальные инструменты всегда начинают новую. {% endhint %} ### Транспортные сессии MCP | Переменная | Описание | По умолчанию | | -------------------------------------- | ---------------------------------------------------- | ------------ | | `MCP_TRANSPORT_SESSION_IDLE_TIMEOUT` | Простой транспортной сессии до закрытия (секунды) | `900` | | `MCP_TRANSPORT_SESSION_MAX_LIFETIME` | Абсолютное время жизни транспортной сессии (секунды) | `28800` | | `MCP_MAX_TRANSPORT_SESSIONS` | Максимум одновременных транспортных сессий | `100` | | `MCP_TRANSPORT_SESSION_SWEEP_INTERVAL` | Период фоновой уборки истёкших сессий (секунды) | `30` | | `MCP_TRANSPORT_SESSION_SWEEP_BATCH` | Максимум сессий, закрываемых за один проход уборки | `100` | ### Транспорт | Переменная | Описание | По умолчанию | | ----------- | ------------------------------------------------- | ------------ | | `USESSE` | Использовать SSE-транспорт вместо streamable-http | `false` | | `HTTP_PORT` | Порт HTTP-сервера | `8007` | ### Идентичность выпуска (beta-кандидат) | Переменная | Описание | По умолчанию | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | | `CHECKER_IMAGE_DIGEST` | Digest вида `sha256:<64 lowercase hex>`, который оператор передаёт при запуске вместе с образом, закреплённым по тому же digest. Образ не может автоматически знать собственный registry digest | *(не задано)* | {% hint style="warning" %} Без `CHECKER_IMAGE_DIGEST` эндпоинт `/release` возвращает пустой `image_digest`, `image_digest_available=false` и `image_digest_source="not-supplied"`. Корректное значение даёт `image_digest_available=true` и источник `runtime-environment`; некорректное — пустой digest и источник `malformed`. Два пустых digest не доказывают, что экземпляры запущены из одного образа. Этот контракт реализован в текущих исходниках, но ещё не подтверждён в опубликованных образах. {% endhint %} ### Плагины (beta) | Переменная | Описание | По умолчанию | | ------------ | ----------------------- | -------------- | | `PLUGIN_DIR` | Каталог Python-плагинов | `/app/plugins` | ## Проверка конфигурации при старте Конфигурация проверяется один раз при запуске, и проверка **собирает все** проблемные настройки, а не останавливается на первой. Сообщение называет ограничение, но никогда — значение (чтобы токен не попал в журнал). Результат этой проверки виден в `/health`: пока конфигурация не прошла валидацию, эндпоинт отвечает `503`. ## HTTP-эндпоинты | Эндпоинт | Метод | Что возвращает | | ------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/mcp` | POST | MCP (streamable-http; при `USESSE=true` — SSE) | | `/health` | GET | `status` (`healthy` / `degraded`), `config_ok`, `direct_mode_ok`, состояния upstream-возможностей и время их снятия | | `/ready` | GET | Готовность экземпляра принимать трафик | | `/plugins` | GET | Состояние плагинов, активные хуки, ошибки и эпоха | | `/plugins/reload` | POST | Атомарная перезагрузка каталога; при ошибке старый набор остаётся активным | | `/metrics/sessions` | GET | Метрики транспортных сессий: счётчики созданных, закрытых по простою и по времени жизни, отказов по лимиту, возраст старейшей | | `/release` | GET | Идентичность выпуска: версия сервера, доступность/источник переданного digest образа, версия upstream-контракта, идентификатор lock-файла, время сборки | {% hint style="info" %} `/health` не делает ни одного обращения к upstream и не раскрывает секретов: это только индикаторы состояния. Идентичность выпуска намеренно вынесена в отдельный `/release`; отсутствующий digest там обозначает отсутствие доказательства, а не пустой идентификатор. Метрики сессий содержат счётчики и возрасты, но никогда — идентификаторы. {% endhint %} ## Режимы вызова инструментов Переменная `MCP_TOOL_CALL_MODE` определяет, как MCP-инструменты взаимодействуют с API 1С.ai: ### Direct mode (по умолчанию) ``` MCP_TOOL_CALL_MODE=direct ``` Инструменты вызывают **upstream-инструменты** 1С.ai напрямую с точными аргументами. Обеспечивает более точные и структурированные результаты. Маппинг upstream-инструментов: | MCP-инструмент | Upstream-инструмент | | -------------------------------- | ------------------------------------------------- | | `check_1c_code` (синтаксис) | `mcp__syntax-checker__validate` | | `search_1c_documentation` | `mcp__knowledge-hub__Search_Documentation` | | `onec_help` | `mcp__knowledge-hub__Search_Documentation` | | `its_help` | `mcp__knowledge-hub__Search_ITS` | | `fetch_its` | `mcp__knowledge-hub__Fetch_ITS` | | `diff_1c_documentation_versions` | `mcp__knowledge-hub__Diff_Documentation_Versions` | При сбое direct-вызова сервер автоматически переключается на промпт-режим (fallback). ### Standard mode ``` MCP_TOOL_CALL_MODE=standard ``` Все инструменты используют **текстовые промпты** (natural language) для взаимодействия с API. Менее точный, но более устойчивый вариант. {% hint style="info" %} Если в ответах инструментов появляется `[DIRECT_TOOL_ERROR]`, это может означать временную недоступность upstream API. Установите `MCP_TOOL_CALL_MODE=standard` для переключения на промпт-режим. {% endhint %} ## Пример docker run со всеми настройками ```powershell docker run -d -p 8007:8007 ` --name 1c_code_checker ` -e LICENSE_KEY=YOUR_LICENSE_KEY ` -e ONEC_AI_TOKEN=YOUR_NAPARNIR_TOKEN ` -e MCP_TOOL_CALL_MODE=direct ` -e ONEC_AI_TIMEOUT=60 ` -e ONEC_CONFIG_NAME="ERP" ` -e ONEC_AI_SKILL_NAME=custom ` -e MAX_ACTIVE_SESSIONS=10 ` -e SESSION_TTL=3600 ` comol/1c-code-checker:latest ``` ## Транспорт По умолчанию сервер использует **streamable-http** транспорт. Для legacy-клиентов, которые поддерживают только SSE, установите `USESSE=true`. | Режим | Переменная | Эндпоинт | | ------------------------------ | -------------- | --------------------------- | | streamable-http (по умолчанию) | `USESSE=false` | `http://localhost:8007/mcp` | | SSE | `USESSE=true` | `http://localhost:8007/mcp` | ## Доработка плагинами (beta) Каталог `/app/plugins` включён по умолчанию. Полный справочник находится в `/app/MCP_1copilot/plugin_api.py`; доступны `on_startup`, `on_request`, `on_upstream_call`, `on_result` и таблица `TOOL_PRESETS`. Интроспекция и атомарная перезагрузка — `GET /plugins` и `POST /plugins/reload`. Все хуки call-scoped: индекса и derived-state у сервера нет. Подробно: [Система плагинов](/mcp-servery-1c/sistema-pluginov.md) и [справочник 1CCodeChecker](/mcp-servery-1c/sistema-pluginov/spravochnik-hukov.md#1ccodechecker).