Конфигурация
Переменные окружения
Обязательные
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, иначе сервер не стартует
(пусто)
Режим работы
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, Бухгалтерия предприятия)
(пусто)
Upstream-дискуссии
Это диалоги на стороне 1С.ai, а не транспортные сессии MCP.
MAX_ACTIVE_SESSIONS
Максимум активных upstream-дискуссий
10
SESSION_TTL
Время жизни upstream-дискуссии (секунды)
3600
ONEC_AI_CONVERSATION_BUSY_TIMEOUT
Сколько ждать освобождения занятой дискуссии (секунды)
60
Транспортные сессии 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
Идентичность выпуска
CHECKER_IMAGE_DIGEST
Digest вида sha256:<64 lowercase hex>, который оператор передаёт при запуске вместе с образом, закреплённым по тому же digest. Образ не может автоматически знать собственный registry digest
(не задано)
Плагины
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-файла, время сборки
Режимы вызова инструментов
Переменная MCP_TOOL_CALL_MODE определяет, как MCP-инструменты взаимодействуют с API 1С.ai:
Direct mode (по умолчанию)
Инструменты вызывают upstream-инструменты 1С.ai напрямую с точными аргументами. Обеспечивает более точные и структурированные результаты.
Маппинг 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
Все инструменты используют текстовые промпты (natural language) для взаимодействия с API. Менее точный, но более устойчивый вариант.
Бюджет времени и прогресс
С 08.10.2026 ONEC_AI_OPERATION_TIMEOUT ограничивает весь вызов. Если прямой вызов не удался, запасной промпт получает остаток бюджета. Если остатка меньше 10 секунд (или десятой части бюджета, если она меньше), запасной промпт не запускается, и вызов завершается ошибкой operation_timeout. Раньше запасной промпт получал ещё один полный бюджет, и вызов мог длиться почти вдвое дольше настройки.
Если клиент передал progressToken, сервер каждые 10 секунд ожидания ответа 1С.ai шлёт notifications/progress: этап (direct, prompt, fallback), сколько секунд прошло и сколько осталось. Некоторые клиенты, например Cursor IDE, по ним продлевают свой таймаут. Клиенту с жёстким таймаутом без продления (Cursor CLI — 60 секунд) прогресс не поможет: ставьте бюджет меньше таймаута клиента.
Большие модули в direct-режиме
В direct-режиме модель 1С.ai повторяет весь переданный код в аргументах вызова анализатора, а сервер принимает вызов, только если код повторён без изменений. На больших фрагментах это долго, и модель часто меняет код ([DIRECT_TOOL_ERROR] … расходятся: code) — тогда ответ даёт запасной промпт. Замер 08.10.2026 на модуле ЗУП в 95 тыс. символов: прямой вызов вернул изменённый код через 92 секунды, а standard дал ответ за 85 секунд. В standard теряется только гарантированный запуск анализатора 1С.ai: проверку выполняет модель по промпту, fallback_reason в ответах не бывает. Для небольших фрагментов direct-режим точнее; для модулей в десятки тысяч символов быстрее и надёжнее standard или проверка по частям.
С 14.10.2026 это условие пишется в журнал сервера уровнем WARNING (раньше ERROR): сервер не сбоил, вызов с изменённым кодом не подтверждён, ответ дал запасной промпт, и у результата есть fallback_reason. Единичная такая строка не повод откатывать образ — смотрите долю ответов с fallback_reason. Для изменённого code в той же записи журнала есть строка code_difference: сколько символов отправлено и получено, где первое расхождение (символ и строка) и в чём оно — только пробелы и переводы строк, только регистр букв или больше. Сам код в журнал не пишется.
Пример docker run со всеми настройками
Транспорт
По умолчанию сервер использует streamable-http транспорт. Для legacy-клиентов, которые поддерживают только SSE, установите USESSE=true.
streamable-http (по умолчанию)
USESSE=false
http://localhost:8007/mcp
SSE
USESSE=true
http://localhost:8007/mcp
Доработка плагинами
Каталог /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 у сервера нет.
Подробно: Система плагинов и справочник 1CCodeChecker.
Last updated