325 lines
15 KiB
Markdown
325 lines
15 KiB
Markdown
# 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 аналитическая надстройка.**
|