# 1S MCP Toolkit — ТЗ на установку и первичный PoC

## 1. Контекст и цель

Нужно поднять **локальный, изолированный runtime-мост** к уже существующей 1С-базе без передачи данных во внешние сервисы и без изменения операционной логики бухгалтерии.

Цель этого этапа:
- проверить, можно ли использовать **1c-mcp-toolkit** как **живой read-only semantic bridge** рядом с существующей 1С;
- получить не только доступ к OData, но и более глубокий runtime-доступ к метаданным, объектам и запросам;
- подтвердить, что мост можно запустить **без merge чужой тяжёлой конфигурации** в базу и без ломки клиентского контура;
- проверить, подходит ли этот инструмент как основа для:
  - runtime-анализа бухгалтерии;
  - фоновых аналитических прогонов;
  - интерактивных запросов ассистента;
  - построения полной семантической картины по документам, движениям, счетам, субконто и связям.

Ожидаемый результат этапа:
- поднят локальный экземпляр **1c-mcp-toolkit**;
- подтверждён запуск на нашей платформе 1С;
- проверены read-only методы;
- подтверждено или опровергнуто, что toolkit пригоден как основной runtime-мост.

---

## 2. Почему рассматривается именно 1c-mcp-toolkit

`ROCTUP/1c-mcp-toolkit` позиционируется как мост через внешнюю обработку `.epf`, с встроенным HTTP-сервером, без публикации 1С-сервера и без COM-соединения как обязательного требования. В репозитории также заявлены:
- MCP Server;
- local REST API;
- `execute_query`;
- `get_metadata`;
- `get_object_by_link`;
- анонимизация/токенизация сущностей.

Для нашей архитектуры это важно, потому что инструмент выглядит как:
- **минимально инвазивный**;
- **локально разворачиваемый**;
- **не требующий передачи данных наружу**;
- **не требующий тяжёлого внедрения в конфигурацию**;
- потенциально дающий более глубокий доступ, чем OData.

---

## 3. Наша архитектурная позиция

### 3.1. Что мы делаем
Мы строим **аналитическую надстройку** над существующей 1С.

### 3.2. Что мы не делаем
**Ни на каком этапе этого проекта мы не пишем в клиентскую 1С-базу операционные данные.**  
**Мы не редактируем документы, не проводим документы, не меняем движения, не меняем регистры, не меняем бухгалтерскую логику и не берём на себя ответственность за операционный контур 1С.**

Это принципиальное и жёсткое ограничение проекта.

### 3.3. Допустимый формат работы
Допустим только:
- read-only доступ;
- выполнение запросов на чтение;
- чтение метаданных;
- чтение объектов по ссылкам;
- чтение связей и аналитик;
- локальный runtime-мост рядом с 1С.

---

## 4. Главный риск и как с ним работать

В toolkit есть не только read-only методы, но и возможность выполнения произвольного кода (`execute_code`) через интерфейс проекта. Это **неприемлемо** для нашего проекта как рабочий режим.

### Жёсткое правило:
Использовать **только read-only методы**, в первую очередь:
- `get_metadata`
- `get_object_by_link`
- `execute_query`
- и иные методы чтения, если они не меняют состояние базы.

### Категорически запрещено:
- `execute_code`
- любые write-операции
- любые операции, создающие или изменяющие объекты
- любые действия, меняющие состояние базы

### Требование к внедрению:
- организационно запретить использование write/mutation-вызовов;
- сетево не публиковать мост наружу;
- запускать только в локальном/изолированном контуре;
- ограничить доступ к endpoint только локальной машине или доверенной внутренней сети;
- использовать отдельного технического пользователя 1С.

---

## 5. Совместимость и текущая гипотеза

По документации проекта явно фигурирует совместимость с диапазоном `8.2.13+ / 8.3.25`. У нас платформа:
- **1С:Предприятие 8.3.27.1936**
- конфигурация: **Бухгалтерия предприятия, редакция 2.0 (2.0.67.20)**

Это значит:
- явного подтверждения `8.3.27` в документации нет;
- явного запрета на `8.3.27` тоже нет;
- значит нужен **практический smoke test**.

Текущая гипотеза:
**1c-mcp-toolkit — приоритетный PoC-кандидат, но совместимость с 8.3.27.1936 должна быть подтверждена на стенде.**

---

## 6. Что конкретно мы хотим получить от этой штуки

Инструмент должен, по возможности, дать:

### 6.1. Discovery / introspection
- список сущностей и типов;
- метаданные;
- структуру объектов;
- типы ссылок;
- поля и их типы;
- навигацию по объектам.

### 6.2. Runtime access
- чтение документа по ссылке;
- чтение движений/регистров;
- чтение проводок;
- чтение аналитик `subconto[1..3]`;
- выполнение произвольных **read-only** запросов на языке запросов 1С.

### 6.3. Semantic bridge
- возможность проходить цепочки:
  - `document -> posting`
  - `posting -> debit/credit account`
  - `posting -> subconto[1..3]`
  - `counterparty -> contract -> documents`
  - `account -> movements -> balance`

### 6.4. Privacy / masking
- анонимизация сущностей, если нужно для AI-слоя;
- токенизация чувствительных идентификаторов без передачи наружу.

---

## 7. Что должен сделать Codex

### 7.1. Подготовка
1. Скачать репозиторий:
   - <https://github.com/ROCTUP/1c-mcp-toolkit>
2. Изучить:
   - `README.md`
   - `README_FULL.md`
   - `ANONYMIZATION.md`
3. Зафиксировать:
   - способ запуска;
   - требуемые компоненты;
   - какой файл `.epf` нужен для запуска;
   - какой локальный endpoint должен подняться.

### 7.2. Проверка состава репозитория
Codex должен определить:
- где лежит финальный `.epf` или как он собирается;
- нужен ли предварительный build;
- нужен ли OneScript / .NET / Node / Python runtime вокруг проекта;
- какие environment variables обязательны.

### 7.3. Подготовка стенда
Codex должен подготовить:
- локальную инструкцию запуска под нашу Windows-машину;
- чеклист запуска рядом с уже существующей 1С;
- список того, что пользователь должен сделать руками в 1С, если это необходимо.

### 7.4. Запуск PoC
Codex должен:
1. Поднять toolkit локально;
2. Проверить, что endpoint отвечает;
3. Проверить read-only методы;
4. Провести smoke test по метаданным;
5. Провести test query;
6. Проверить пригодность для наших бухгалтерских цепочек.

---

## 8. Предварительные ограничения для Codex

Codex **не должен**:
- пытаться встроить toolkit в конфигурацию 1С без явной необходимости;
- включать write-режимы;
- использовать `execute_code`;
- публиковать endpoint во внешний интернет;
- открывать доступ неограниченному числу клиентов;
- менять конфигурацию продовой 1С.

Codex **должен**:
- ориентироваться только на изолированный контур;
- трактовать проект как read-only analytics bridge;
- сначала подтвердить локальный запуск;
- все сомнительные действия помечать как `manual required`.

---

## 9. Практический план установки

### Этап A. Подготовка артефактов
1. Клонировать репозиторий.
2. Найти финальный `.epf` или build-инструкцию.
3. Проверить наличие:
   - примеров запуска;
   - конфигурации endpoint;
   - описания REST/MCP режима.

### Этап B. Локальный запуск
1. Открыть `.epf` в нашей тестовой 1С.
2. Попробовать поднять встроенный сервер toolkit.
3. Зафиксировать:
   - URL;
   - порт;
   - режим запуска;
   - тип авторизации.

### Этап C. Smoke test
Проверить:
- `get_metadata`
- `get_object_by_link`
- `execute_query` на безопасном select
- наличие анонимизации
- отсутствие необходимости публикации 1С через IIS для базового запуска, если toolkit реально работает через свой внутренний сервер

### Этап D. Семантический PoC
Проверить, можно ли через toolkit достать:
- документ + движения;
- счёт + проводки;
- `subconto[1..3]`;
- реальное сальдо и его расшифровку;
- метаданные по нужным бухгалтерским объектам.

---

## 10. Что считать успехом

### Минимальный успех
- toolkit запускается на 8.3.27.1936;
- endpoint отвечает локально;
- `get_metadata` работает;
- `execute_query` на чтение работает.

### Рабочий успех
- toolkit позволяет читать нужные бухгалтерские сущности;
- toolkit позволяет проходить критические цепочки;
- toolkit может использоваться как runtime semantic bridge рядом с OData.

### Провал PoC
- toolkit не стартует на 8.3.27;
- toolkit требует неприемлемых модификаций 1С;
- toolkit не даёт read-only универсального доступа;
- toolkit usable only through dangerous mutation/code paths.

---

## 11. Deliverables от Codex

Codex должен вернуть:

1. `toolkit_inventory.md`
   - состав проекта
   - способ запуска
   - файлы и зависимости

2. `toolkit_install_runbook.md`
   - пошаговая инструкция запуска под наш стенд

3. `toolkit_smoke_test_report.md`
   - что завелось
   - что не завелось
   - ошибки
   - версия 1С
   - endpoint

4. `toolkit_semantic_probe_report.md`
   - что доступно по метаданным
   - какие цепочки реально читаются
   - где остались провалы

5. `toolkit_decision_note.md`
   - verdict:
     - `adopt`
     - `adopt with restrictions`
     - `reject`

---

## 12. Отдельный акцент для Codex

Нужно смотреть на проект **не как на “чат-надстройку”**, а как на **универсальный runtime-мост**.

Нас интересует не “умеет ли он ответить на 5 сценариев”, а:
- даёт ли он живой доступ к актуальной 1С;
- даёт ли он runtime-метаданные;
- даёт ли он доступ к семантике;
- можно ли его использовать как базовый нижний слой для:
  - онтологии;
  - графа связей;
  - фоновой аналитики;
  - ассистента.

---

## 13. Ссылки

- GitHub: <https://github.com/ROCTUP/1c-mcp-toolkit>
- README FULL: <https://github.com/ROCTUP/1c-mcp-toolkit/blob/main/README_FULL.md>
- Anonymization: <https://github.com/ROCTUP/1c-mcp-toolkit/blob/main/ANONYMIZATION.md>

---

## 14. Резюме

На текущем этапе `1c-mcp-toolkit` — **лучший кандидат для первого серьёзного PoC** под runtime semantic bridge рядом с существующей 1С, потому что он обещает:
- локальный запуск;
- минимальную инвазивность;
- read-oriented runtime access;
- query/metadata layer;
- анонимизацию.

Но это всё должно быть **доказано практическим запуском на нашей версии 1С**.

Главное правило этапа:
**никаких write/mutation-операций, никакого изменения операционного контура 1С, только read-only аналитическая надстройка.**