8.8 KiB

Raw Permalink Blame History

Bootstrap Runbook: Полный пайплайн запуска с нуля (новая машина)

Дата: 2026-03-23
Статус: рабочий контур подтвержден (adopt with restrictions)
Цель: поднять наш текущий live read-only bridge к 1С с нуля на новой Windows-машине.

1. Что в итоге должно работать

После выполнения шагов должны одновременно работать:

Python proxy (onec_mcp_toolkit_proxy) на http://127.0.0.1:6003
1С:Предприятие с открытой обработкой MCP_Toolkit.epf в режиме Прокси
Успешные read-only вызовы:
- get_metadata
- execute_query
- get_link_of_object
- get_object_by_link

Важно: это live request/response мост, не оффлайн-реплика.

2. Архитектура (минимум)

Клиент/ассистент -> HTTP -> Python Proxy (6003) -> /1c/poll,/1c/result -> MCP_Toolkit.epf -> База 1С

3. Что нужно на новой машине

Windows (рекомендуемо 64-bit).
Установленная платформа 1С (в нашем контуре: 8.3.27.1936).
Тестовая база 1С (БП 2.0) и рабочий пользователь с read-only правами.
Git.
Miniconda.
Доступ к репозиторию ROCTUP/1c-mcp-toolkit.

4. Рекомендованная структура папок

X:\1C\
  NDC_1C\
    docs\
    external\
      1c-mcp-toolkit\

Если диска X: нет, можно использовать любой путь, но держать единую структуру.

5. Установка и подготовка окружения

5.1 Клонировать toolkit

git clone https://github.com/ROCTUP/1c-mcp-toolkit X:\1C\NDC_1C\external\1c-mcp-toolkit

5.2 Проверить `.epf` артефакты

Get-ChildItem X:\1C\NDC_1C\external\1c-mcp-toolkit\build

Ожидаемые файлы:

MCP_Toolkit.epf (x64)
MCP_Toolkit_x86.epf (x86 fallback)

5.3 Создать изолированную conda-среду

& 'C:\Users\<USER>\miniconda3\Scripts\conda.exe' create -y -n ndc_1c_toolkit python=3.11

5.4 Установить зависимости proxy

& 'C:\Users\<USER>\miniconda3\envs\ndc_1c_toolkit\python.exe' -m pip install --upgrade pip
& 'C:\Users\<USER>\miniconda3\envs\ndc_1c_toolkit\python.exe' -m pip install -r X:\1C\NDC_1C\external\1c-mcp-toolkit\requirements.txt

6. Запуск proxy (read-only профиль)

Запускать из PowerShell:

$env:PORT='6003'
$env:TIMEOUT='180'
$env:ALLOW_DANGEROUS_WITH_APPROVAL='false'
$env:ANONYMIZATION_ENABLED='false'
$env:RESPONSE_FORMAT='json'
$env:LOG_LEVEL='INFO'
& 'C:\Users\<USER>\miniconda3\envs\ndc_1c_toolkit\python.exe' -m onec_mcp_toolkit_proxy

Проверка:

Invoke-WebRequest http://127.0.0.1:6003/health -UseBasicParsing

Ожидаемо: HTTP 200 и status=healthy.

7. Запуск 1С и обработчика

7.1 Открыть 1С:Предприятие

Открывать в режиме Предприятия (не Конфигуратор).
Если UI обработки не появляется в обычном режиме, запускать в управляемом приложении.

7.2 Открыть внешнюю обработку

Файл -> Открыть -> X:\1C\NDC_1C\external\1c-mcp-toolkit\build\MCP_Toolkit.epf

7.3 Настроить форму MCP Toolkit

Режим: Прокси
Адрес сервера: http://127.0.0.1:6003
Идентификатор канала: default (или ваш фиксированный channel)
Нажать Подключиться

Ожидаемо в логе формы:

Подключение к серверу: http://127.0.0.1:6003
Успешное подключение к серверу

8. Smoke-проверка после подключения

8.1 Metadata

Invoke-WebRequest "http://127.0.0.1:6003/api/get_metadata?channel=default&meta_type=Документ&limit=20" -UseBasicParsing

Ожидаемо: success=true.

8.2 Query

$body = @{ query = "ВЫБРАТЬ ПЕРВЫЕ 1 1 КАК Test"; limit = 1 } | ConvertTo-Json
Invoke-WebRequest "http://127.0.0.1:6003/api/execute_query?channel=default" `
  -Method POST -ContentType "application/json; charset=utf-8" -Body $body -UseBasicParsing

Ожидаемо: success=true, Test=1.

8.3 Object link flow

Получить object_description (например, из execute_query).
Вызвать get_link_of_object.
Передать ссылку в get_object_by_link.

Ожидаемо: объект документа читается.

9. Ежедневный рабочий цикл (операторский)

Старт дня

Запустить proxy.
Проверить /health.
Запустить 1С и открыть MCP_Toolkit.epf.
Проверить статус Подключено.
Выполнить быстрый test query.

Стоп дня

Отключиться в форме MCP Toolkit.
Закрыть 1С.
Остановить proxy (Ctrl+C/Stop-Process).

10. Траблшутинг (частые проблемы)

10.1 Ошибка `Не могу установить соединение` в форме 1С

Причина: proxy не запущен или не слушает 6003.
Проверка:

Invoke-WebRequest http://127.0.0.1:6003/health -UseBasicParsing

10.2 `timeout waiting for 1C response` на API

Причина: нет активного .epf в том же channel, форма закрыта, либо канал не совпадает.

10.3 `UI не показывается` при открытии `.epf`

Обработка имеет управляемые формы.
Запускать в 1С:Предприятии (управляемый режим), не в Конфигураторе для рабочего контура.

10.4 Кодировка ссылки из `get_link_of_object` выглядит “кракозябрами”

Нюанс текущего ответа proxy; вызов рабочий, ссылку можно нормализовать при постобработке.

11. Жёсткие правила безопасности

Только read-only операции.
Не использовать execute_code.
Не выставлять 6003 во внешний интернет.
Держать ALLOW_DANGEROUS_WITH_APPROVAL=false.
Работать под отдельным техпользователем с минимальными правами чтения.

12. Что это даёт и чего не даёт

Даёт

Живой доступ к текущим данным 1С по запросу.
Runtime metadata + deep read semantics (документы, проводки, субконто, сальдо).

Не даёт

Мгновенный “весь срез компании” в одном запросе для тяжёлой аналитики.
Автоматическую фоновой репликацию без отдельного слоя витрин/снэпшотов.

13. Рекомендованный next step после bootstrap

Добавить one-click старт скрипт (Start-NDC1CBridge.ps1).
Добавить one-click smoke скрипт (Test-NDC1CBridge.ps1).
Поднять плановую аналитическую витрину (например, 15/60 минут) для тяжёлых задач.

Итог bootstrap: на новой машине поднимаем контур за последовательность
Proxy -> MCP_Toolkit.epf -> Подключение -> Smoke
и получаем рабочий live read-only мост к 1С на текущем этапе проекта.

ЗАПУСК ПРКСИ ПЕРЕД ПОДКЛЮЮЧЕНИЕМ К ТУЛКИТ 1С

Запускай так в PowerShell:

$env:PORT='6003' $env:TIMEOUT='180' $env:ALLOW_DANGEROUS_WITH_APPROVAL='false' $env:ANONYMIZATION_ENABLED='false' $env:RESPONSE_FORMAT='json' $env:LOG_LEVEL='INFO' & 'C:\Users\DCTOUCH\miniconda3\envs\ndc_1c_toolkit\python.exe' -m onec_mcp_toolkit_proxy

Проверка, что поднялся:

Invoke-WebRequest http://127.0.0.1:6003/health -UseBasicParsing

Должен вернуть status":"healthy".

Остановить:

в том же окне Ctrl + C.

8.8 KiB Raw Permalink Blame History Unescape Escape