SILVER
/
NODEDC_1C
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
NODEDC_1C/IN/1S_MCP_Toolkit_TZ.md

15 KiB
Raw Blame History

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. Скачать репозиторий:
  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. Ссылки

14. Резюме

На текущем этапе 1c-mcp-toolkit — лучший кандидат для первого серьёзного PoC под runtime semantic bridge рядом с существующей 1С, потому что он обещает:

  • локальный запуск;
  • минимальную инвазивность;
  • read-oriented runtime access;
  • query/metadata layer;
  • анонимизацию.

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

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