Initialize project scaffold and domain model

2026-03-25 12:20:42 +03:00
commit fb302b2a2c
51 changed files with 6815 additions and 0 deletions
@@ -0,0 +1,107 @@
+# GraphQL
+
+## 1. Роль протокола в проекте
+
+GraphQL поддерживается как отдельный тип интеграции, но на слое MCP намеренно ограничивается. Цель платформы не в том, чтобы дать LLM универсальный доступ ко всему GraphQL endpoint, а в том, чтобы превратить конкретный GraphQL-запрос в узкий и предсказуемый MCP tool.
+
+## 2. Что поддерживается в MVP
+
+- `query`
+- `mutation`
+- один GraphQL endpoint на operation
+- фиксированный `query_template`
+- фиксированный `selection set`
+- загрузка примера выходного `JSON`
+- схема переменных
+- variables mapping
+- response extraction из `data`
+- разбор `errors`
+- auth и headers
+- автогенерация чернового mapping
+- ручная донастройка через `JSONPath`
+- тестовый вызов перед публикацией
+
+## 3. Что не входит в MVP
+
+- `subscription`
+- универсальный GraphQL explorer для LLM
+- передача произвольного GraphQL-документа от LLM
+- визуальный конструктор сложных selection set
+- обязательная зависимость от introspection
+- автоматическое построение любого запроса по полной GraphQL schema
+
+## 4. Ключевое архитектурное ограничение
+
+Платформа не должна публиковать в MCP общий GraphQL tool, который умеет получать любые поля и принимать любые параметры в зависимости от намерения LLM.
+
+Правильная модель только одна:
+
+- один tool;
+- один конкретный `query` или `mutation`;
+- один заранее зафиксированный `selection set`;
+- фиксированный набор входных параметров;
+- один предсказуемый формат ответа.
+
+Иными словами, на MCP-слое GraphQL сознательно сужается до модели, близкой к RPC или REST operation. Это делается потому, что LLM должен работать с понятным контрактом, а не конструировать произвольный GraphQL-запрос на лету.
+
+## 5. Внутренняя модель GraphQL operation
+
+GraphQL operation должна включать:
+
+- `endpoint`
+- `operation_type`
+- `operation_name`
+- `query_template`
+- `variables_schema`
+- `input_mapping`
+- `response_path`
+- `error_policy`
+- `headers`
+- `auth_profile`
+
+## 6. Как оператор настраивает GraphQL operation
+
+1. Указывает GraphQL endpoint.
+2. Выбирает `query` или `mutation`.
+3. Задает имя операции.
+4. Вставляет готовый шаблон запроса.
+5. Описывает переменные, которые разрешено передавать в эту операцию.
+6. При необходимости загружает пример JSON-ответа.
+7. Система строит черновую схему ответа и стартовый mapping.
+8. Настраивает маппинг `MCP input -> GraphQL variables`.
+9. Указывает `response_path`, по которому извлекается полезный результат из `data`.
+10. При необходимости уточняет mapping через `JSONPath`.
+11. Выполняет тест.
+12. Публикует operation как MCP tool.
+
+## 7. Поведение runtime
+
+При выполнении GraphQL operation runtime должен:
+
+1. Валидировать вход по фиксированной схеме переменных.
+2. Применить input mapping.
+3. Собрать GraphQL payload вида `query + variables`.
+4. Выполнить HTTP request.
+5. Отдельно разобрать `data` и `errors`.
+6. Применить output mapping или `response_path`.
+7. Вернуть нормализованный результат.
+
+## 8. Критические нюансы
+
+- HTTP `200 OK` не означает успешное выполнение, если в теле присутствует `errors`.
+- структура ответа зависит от `selection set`, значит она должна быть фиксирована заранее;
+- GraphQL endpoint обычно один, поэтому операция определяется не URL, а телом запроса;
+- variables должны быть строго ограничены, иначе один tool станет слишком широким и плохо управляемым;
+- `subscription` по смыслу не подходит модели MCP tool, потому что это потоковая, а не request-response интеграция.
+- `JSONPath` используется для точечного извлечения вложенных данных из `data` и для управления структурой итогового ответа.
+
+## 9. Почему GraphQL не считается "почти REST"
+
+GraphQL похож на REST только тем, что часто передается по HTTP. Но с точки зрения платформы это другой тип контракта:
+
+- смысл операции задается не endpoint, а запросом;
+- ответ зависит от `selection set`;
+- ошибки живут в теле ответа, а не только в HTTP status;
+- одна и та же точка входа может обслуживать много операций.
+
+Поэтому GraphQL в системе должен иметь отдельный адаптер и отдельную конфигурационную модель.
@@ -0,0 +1,107 @@
+# gRPC
+
+## 1. Роль протокола в проекте
+
+gRPC поддерживается как третий основной протокол платформы, но в самой узкой и управляемой форме. Цель состоит не в том, чтобы покрыть все возможности gRPC, а в том, чтобы представить unary RPC-методы как обычные MCP tools с формой входа и формой выхода.
+
+## 2. Что поддерживается в MVP
+
+- только unary RPC
+- загрузка `.proto`
+- загрузка descriptor set
+- загрузка примеров JSON для MCP input/output при необходимости
+- извлечение `services`, `methods`, request/response messages
+- отображение входных и выходных параметров в UI
+- mapping `MCP input -> protobuf request`
+- mapping `protobuf response -> MCP output`
+- автогенерация чернового mapping
+- ручная донастройка через `JSONPath`
+- вызов метода по descriptor metadata
+- auth/transport settings на уровне соединения
+- тестовый вызов перед публикацией
+
+## 3. Что не входит в MVP
+
+- `server streaming`
+- `client streaming`
+- `bidirectional streaming`
+- обязательная поддержка server reflection
+- генерация нового Rust-кода под каждый загруженный `.proto`
+- сложные сценарии с долгоживущими сессиями вызовов
+
+## 4. Ключевое архитектурное ограничение
+
+В проекте поддерживаются только unary-методы, потому что MCP tool в этой архитектуре соответствует модели `один запрос -> один ответ`.
+
+Это означает:
+
+- один request message;
+- один response message;
+- один завершенный вызов;
+- отсутствие потоковых сообщений;
+- отсутствие отдельного жизненного цикла stream-сессии.
+
+Streaming gRPC не нужен для выбранной модели взаимодействия с LLM и только усложнит runtime, UI и хранение состояния.
+
+## 5. Внутренняя модель gRPC operation
+
+gRPC operation должна включать:
+
+- `server_addr`
+- `package`
+- `service`
+- `method`
+- `descriptor_ref`
+- `input_schema`
+- `output_schema`
+- `input_mapping`
+- `output_mapping`
+- `execution_config`
+- `tool_description`
+
+## 6. Как оператор настраивает gRPC operation
+
+1. Загружает `.proto` или descriptor set.
+2. Система извлекает список services и methods.
+3. Оператор выбирает конкретный unary-метод.
+4. UI показывает структуру request message и response message.
+5. При необходимости загружает примеры JSON для MCP input/output.
+6. Система строит черновую схему и стартовый mapping.
+7. Оператор задает или уточняет входные MCP-параметры.
+8. Настраивает маппинг во входные protobuf fields.
+9. Настраивает маппинг из response fields в MCP output.
+10. При необходимости уточняет mapping через `JSONPath`.
+11. Выполняет тест.
+12. Публикует operation как MCP tool.
+
+## 7. Поведение runtime
+
+При выполнении gRPC operation runtime должен:
+
+1. Валидировать MCP input по нормализованной схеме.
+2. Применить input mapping.
+3. Построить protobuf request message из JSON.
+4. Выполнить unary RPC вызов.
+5. Преобразовать protobuf response в нормализованный JSON.
+6. Применить output mapping.
+7. Вернуть итоговый результат.
+
+## 8. Критические нюансы
+
+- `.proto` и descriptor handling должны быть отделены от runtime-вызова;
+- protobuf discovery не должен жить внутри gRPC adapter;
+- `oneof`, `enum`, `repeated`, `map` и well-known types требуют отдельной нормализации;
+- схема сообщения должна быть представлена в UI как обычная форма полей, а не как сырой protobuf descriptor;
+- пользователь не должен видеть внутреннюю сложность protobuf-контракта больше, чем это нужно для настройки operation.
+- `JSONPath` используется как единый способ точечной адресации вложенных полей при настройке mapping поверх нормализованной JSON-модели.
+
+## 9. Почему gRPC ограничивается unary
+
+Причина не только в сложности реализации. Главное ограничение архитектурное:
+
+- MCP tool моделируется как завершенный вызов;
+- LLM работает с запросом и конечным ответом;
+- UI платформы построен вокруг формы входа и формы выхода;
+- streaming требует отдельной session-модели, buffering, cancellation и состояния.
+
+Поэтому unary gRPC - это не "обрезанная" поддержка, а осознанно выбранная форма, которая действительно совместима с MCP-платформой.
@@ -0,0 +1,112 @@
+# REST
+
+## 1. Роль протокола в проекте
+
+REST - базовый и первый по очередности реализации протокол платформы. На нем должна быть обкатана общая модель `Operation`, схема входа и выхода, маппинг, тестовый запуск и публикация MCP tool.
+
+## 2. Что поддерживается в MVP
+
+- HTTP methods: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`
+- загрузка примера входного `JSON`
+- загрузка примера выходного `JSON`
+- path parameters
+- query parameters
+- headers
+- JSON request body
+- JSON response body
+- auth: `Bearer`, `Basic`, API key
+- timeout и базовые transport settings
+- request mapping
+- response mapping
+- автогенерация чернового mapping
+- ручная донастройка через `JSONPath`
+- тестовый вызов перед публикацией
+
+## 3. Что не входит в MVP
+
+- multipart/form-data
+- file upload/download как отдельный сценарий
+- XML payload как основной формат
+- OpenAPI import с автоматическим созданием mappings
+- webhooks
+- long polling как специальный режим
+- `HEAD` и `OPTIONS` как отдельные пользовательские сценарии
+
+## 4. Внутренняя модель REST operation
+
+REST operation в системе описывается следующими основными частями:
+
+- `base_url`
+- `method`
+- `path_template`
+- `headers`
+- `auth_profile`
+- `input_schema`
+- `input_mapping`
+- `output_schema`
+- `output_mapping`
+- `tool_description`
+
+На слое MCP REST operation всегда выглядит как вызов `запрос -> ответ` с фиксированной схемой входа и выхода.
+
+## 5. Как оператор настраивает REST operation
+
+1. Указывает `base_url`.
+2. Выбирает HTTP method.
+3. Указывает `path_template`.
+4. При необходимости загружает пример входного и выходного `JSON`.
+5. Система строит черновую схему и стартовый mapping.
+6. Описывает или уточняет входные MCP-параметры.
+7. Сопоставляет параметры с `path`, `query`, `headers` и `body`.
+8. Указывает, откуда извлекать полезные данные в ответе.
+9. При необходимости уточняет mapping через `JSONPath`.
+10. Запускает тест.
+11. Публикует operation как MCP tool.
+
+## 6. Требования к маппингу
+
+Input mapping должен поддерживать:
+
+- `$.mcp.* -> $.request.path.*`
+- `$.mcp.* -> $.request.query.*`
+- `$.mcp.* -> $.request.headers.*`
+- `$.mcp.* -> $.request.body.*`
+- константы
+- значения по умолчанию
+
+Output mapping должен поддерживать:
+
+- `$.response.body.* -> $.output.*`
+- извлечение вложенных полей
+- нормализацию отсутствующих значений
+
+`JSONPath` является основным способом адресации конкретных параметров при работе со вложенными объектами и массивами.
+
+## 7. Поведение runtime
+
+При выполнении REST operation runtime должен:
+
+1. Валидировать вход по нормализованной схеме.
+2. Применить input mapping.
+3. Собрать HTTP request.
+4. Выполнить вызов через `reqwest`.
+5. Преобразовать ответ в нормализованный JSON.
+6. Применить output mapping.
+7. Вернуть итоговый результат MCP server.
+
+## 8. Нюансы и ограничения
+
+- `DELETE` допускается, но body для него не считается обязательным сценарием совместимости.
+- `PATCH` требует аккуратной работы с частичными payload, поэтому mapping должен позволять заполнять только выбранные поля.
+- Успешный HTTP status сам по себе не гарантирует корректность бизнес-ответа, если response mapping не может извлечь ожидаемые данные.
+- REST adapter не должен содержать бизнес-логику маппинга, только transport-логику.
+- Загруженные JSON-примеры используются для генерации черновика, но не заменяют явную конфигурацию operation.
+
+## 9. Почему REST остается отдельным протоколом
+
+REST нельзя считать просто частным случаем другого HTTP-based интерфейса, потому что:
+
+- контракт определяется URL, методом и payload;
+- semantics HTTP methods важны;
+- поведение интеграции часто завязано на headers и auth;
+- UX настройки REST operation отличается от GraphQL и gRPC.