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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

```powershell
& '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:

```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
```

Проверка:

```powershell
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

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

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

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

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

### 8.1 Metadata

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

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

### 8.2 Query

```powershell
$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

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

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

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

### Старт дня

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

### Стоп дня

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

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

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

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

```powershell
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. Жёсткие правила безопасности

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

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

### Даёт

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

### Не даёт

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

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

1. Добавить one-click старт скрипт (`Start-NDC1CBridge.ps1`).
2. Добавить one-click smoke скрипт (`Test-NDC1CBridge.ps1`).
3. Поднять плановую аналитическую витрину (например, 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.