community: remove premium protocols and streaming surface
This commit is contained in:
a.tolmachev
@@ -1,109 +0,0 @@
|
||||
# GraphQL
|
||||
|
||||
## 1. Роль протокола в проекте
|
||||
|
||||
GraphQL поддерживается как отдельный тип интеграции, но на слое MCP намеренно ограничивается. Цель платформы не в том, чтобы дать LLM универсальный доступ ко всему GraphQL endpoint, а в том, чтобы превратить конкретный GraphQL-запрос в узкий и предсказуемый MCP tool.
|
||||
|
||||
## 2. Что поддерживается в целевом продукте
|
||||
|
||||
- `query`
|
||||
- `mutation`
|
||||
- один GraphQL endpoint на operation
|
||||
- фиксированный `query_template`
|
||||
- фиксированный `selection set`
|
||||
- загрузка примера выходного `JSON`
|
||||
- схема переменных
|
||||
- variables mapping
|
||||
- response extraction из `data`
|
||||
- разбор `errors`
|
||||
- auth и headers
|
||||
- автогенерация чернового mapping
|
||||
- ручная донастройка через `JSONPath`
|
||||
- тестовый вызов перед публикацией
|
||||
|
||||
## 3. Что отложено
|
||||
|
||||
- `subscription`
|
||||
- универсальный GraphQL explorer для LLM
|
||||
- передача произвольного GraphQL-документа от LLM
|
||||
- визуальный конструктор сложных selection set
|
||||
- обязательная зависимость от introspection
|
||||
- автоматическое построение любого запроса по полной GraphQL schema
|
||||
|
||||
`subscription` допускается только как future scope после появления отдельного websocket/subscription adapter и controlled streaming lifecycle.
|
||||
|
||||
## 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` не входит в текущий scope, потому что требует отдельной lifecycle-модели, близкой к `session` mode, и отдельного transport adapter.
|
||||
- `JSONPath` используется для точечного извлечения вложенных данных из `data` и для управления структурой итогового ответа.
|
||||
|
||||
## 9. Почему GraphQL не считается "почти REST"
|
||||
|
||||
GraphQL похож на REST только тем, что часто передается по HTTP. Но с точки зрения платформы это другой тип контракта:
|
||||
|
||||
- смысл операции задается не endpoint, а запросом;
|
||||
- ответ зависит от `selection set`;
|
||||
- ошибки живут в теле ответа, а не только в HTTP status;
|
||||
- одна и та же точка входа может обслуживать много операций.
|
||||
|
||||
Поэтому GraphQL в системе должен иметь отдельный адаптер и отдельную конфигурационную модель.
|
||||
@@ -1,110 +0,0 @@
|
||||
# gRPC
|
||||
|
||||
## 1. Роль протокола в проекте
|
||||
|
||||
gRPC поддерживается как третий основной протокол платформы в управляемой форме. Цель состоит не в том, чтобы покрыть все возможности gRPC, а в том, чтобы представить unary и bounded server-streaming методы как MCP tools с предсказуемым жизненным циклом.
|
||||
|
||||
## 2. Что поддерживается в целевом продукте
|
||||
|
||||
- unary RPC
|
||||
- bounded server-streaming через execution modes `window`, `session`, `async_job`
|
||||
- загрузка `.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. Что отложено
|
||||
|
||||
- `client streaming`
|
||||
- `bidirectional streaming`
|
||||
- обязательная поддержка server reflection
|
||||
- генерация нового Rust-кода под каждый загруженный `.proto`
|
||||
- сложные сценарии с долгоживущими сессиями вызовов
|
||||
|
||||
## 4. Ключевое архитектурное ограничение
|
||||
|
||||
В проекте поддерживаются unary-методы и bounded server-streaming, потому что MCP tool в этой архитектуре должен оставаться управляемым.
|
||||
|
||||
Это означает:
|
||||
|
||||
- один request message;
|
||||
- один bounded response или управляемая session/job-семантика;
|
||||
- явно ограниченный lifecycle stream-сессии.
|
||||
|
||||
Streaming gRPC не публикуется как бесконечный raw stream. Он допускается только там, где runtime умеет bounded-ить, агрегировать и завершать результат.
|
||||
|
||||
## 5. Внутренняя модель gRPC operation
|
||||
|
||||
gRPC operation должна включать:
|
||||
|
||||
- `server_addr`
|
||||
- `package`
|
||||
- `service`
|
||||
- `method`
|
||||
- `descriptor_ref`
|
||||
- `descriptor_set_b64`
|
||||
- `input_schema`
|
||||
- `output_schema`
|
||||
- `input_mapping`
|
||||
- `output_mapping`
|
||||
- `execution_config`
|
||||
- `tool_description`
|
||||
|
||||
## 6. Как оператор настраивает gRPC operation
|
||||
|
||||
1. Загружает `.proto` или descriptor set.
|
||||
2. Система извлекает список services и methods.
|
||||
3. Оператор выбирает конкретный unary- или server-streaming метод.
|
||||
4. UI показывает структуру request message и response message.
|
||||
5. При необходимости загружает примеры JSON для MCP input/output.
|
||||
6. Система строит черновую схему, стартовый mapping и runtime-ready snapshot descriptor set для выбранного метода.
|
||||
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 выполнить unary RPC вызов.
|
||||
5. Для server-streaming собрать bounded окно или session step.
|
||||
6. Преобразовать protobuf response или stream items в нормализованный JSON.
|
||||
7. Применить output mapping.
|
||||
8. Вернуть итоговый результат.
|
||||
|
||||
## 8. Критические нюансы
|
||||
|
||||
- `.proto` и descriptor handling должны быть отделены от runtime-вызова;
|
||||
- protobuf discovery не должен жить внутри gRPC adapter;
|
||||
- runtime использует сохраненный `descriptor_set_b64`, а не исходный `.proto`;
|
||||
- `oneof`, `enum`, `repeated`, `map` и well-known types требуют отдельной нормализации;
|
||||
- `map` на слое нормализованной schema модели представляется как `array` объектов вида `{ key, value }`;
|
||||
- `oneof` на слое нормализованной schema модели представляется как `oneof` с вариантами-объектами, каждый из которых содержит одно допустимое поле;
|
||||
- схема сообщения должна быть представлена в UI как обычная форма полей, а не как сырой protobuf descriptor;
|
||||
- пользователь не должен видеть внутреннюю сложность protobuf-контракта больше, чем это нужно для настройки operation.
|
||||
- `JSONPath` используется как единый способ точечной адресации вложенных полей при настройке mapping поверх нормализованной JSON-модели.
|
||||
|
||||
## 9. Почему gRPC ограничивается controlled streaming
|
||||
|
||||
Причина не только в сложности реализации. Главное ограничение архитектурное:
|
||||
|
||||
- MCP tool моделируется как завершенный вызов;
|
||||
- LLM работает с запросом и конечным ответом;
|
||||
- UI платформы построен вокруг формы входа и формы выхода;
|
||||
- streaming требует отдельной session-модели, buffering, cancellation и состояния.
|
||||
|
||||
Поэтому поддержка gRPC в Crank ограничивается unary и bounded server-streaming. Client-streaming и bidi остаются вне scope до появления полноценной interactive session model.
|
||||
@@ -1,162 +0,0 @@
|
||||
# SOAP
|
||||
|
||||
## 1. Роль протокола в проекте
|
||||
|
||||
SOAP поддерживается как enterprise-oriented upstream protocol для интеграций с системами, где REST уже не является стандартом де-факто.
|
||||
|
||||
Типичные домены:
|
||||
|
||||
- ERP;
|
||||
- banking;
|
||||
- insurance;
|
||||
- government and B2B gateways;
|
||||
- legacy enterprise systems;
|
||||
- ESB-oriented internal APIs.
|
||||
|
||||
## 2. Что поддерживается в целевом продукте
|
||||
|
||||
- SOAP 1.1 и SOAP 1.2;
|
||||
- WSDL upload/import;
|
||||
- выбор `service`, `port` и `operation`;
|
||||
- document/literal first;
|
||||
- XML schema extraction из WSDL/XSD;
|
||||
- input/output schema generation;
|
||||
- mapping `MCP JSON -> SOAP body`;
|
||||
- mapping `SOAP response -> normalized JSON`;
|
||||
- SOAP headers config;
|
||||
- basic auth, bearer auth и auth profiles;
|
||||
- test run;
|
||||
- publish as MCP tool.
|
||||
|
||||
## 3. Что не входит в текущий продуктовый scope
|
||||
|
||||
- полный стек WS-* расширений;
|
||||
- MTOM attachments;
|
||||
- arbitrary XML transformation engine;
|
||||
- full schema authoring inside UI;
|
||||
- server-side SOAP hosting.
|
||||
|
||||
## 4. Ключевое архитектурное ограничение
|
||||
|
||||
SOAP не является просто HTTP POST с XML body.
|
||||
|
||||
Для платформы SOAP operation определяется:
|
||||
|
||||
- WSDL model;
|
||||
- service/port/operation binding;
|
||||
- envelope structure;
|
||||
- namespaces;
|
||||
- optional SOAPAction;
|
||||
- fault model;
|
||||
- XML schema contract.
|
||||
|
||||
Поэтому SOAP должен иметь отдельный adapter и отдельную конфигурационную модель.
|
||||
|
||||
## 5. Типовые use cases
|
||||
|
||||
- enterprise CRM/ERP operations;
|
||||
- payment and settlement integrations;
|
||||
- policy and claims systems;
|
||||
- regulated B2B data exchange;
|
||||
- legacy internal service contracts.
|
||||
|
||||
## 6. Внутренняя модель SOAP operation
|
||||
|
||||
SOAP operation должна включать:
|
||||
|
||||
- `wsdl_ref`
|
||||
- `service_name`
|
||||
- `port_name`
|
||||
- `operation_name`
|
||||
- `endpoint_override`
|
||||
- `soap_version`
|
||||
- `soap_action`
|
||||
- `input_schema`
|
||||
- `output_schema`
|
||||
- `input_mapping`
|
||||
- `output_mapping`
|
||||
- `header_config`
|
||||
- `execution_config`
|
||||
- `tool_description`
|
||||
|
||||
Code-level model:
|
||||
|
||||
- `crank_core::SoapTarget`
|
||||
- `crank_core::SoapProtocolOptions`
|
||||
- `crank_core::SoapVersion`
|
||||
- `crank_core::SoapBindingStyle`
|
||||
- `crank_core::SoapHeaderConfig`
|
||||
- `crank_core::SoapFaultContract`
|
||||
- `crank_core::SoapOperationMetadata`
|
||||
- `crank_schema::XmlNodeKind`
|
||||
- `crank_schema::XmlQualifiedName`
|
||||
- `crank_schema::XmlSchemaBinding`
|
||||
|
||||
Execution constraints:
|
||||
|
||||
- `Protocol::Soap` поддерживает только `unary` и `async_job`;
|
||||
- `window` и `session` для SOAP не поддерживаются;
|
||||
- runtime foundation поддерживает `unary` SOAP request-response execution;
|
||||
- `window` и `session` execution по-прежнему отклоняются как unsupported mode.
|
||||
|
||||
## 7. Как оператор настраивает SOAP operation
|
||||
|
||||
1. Загружает WSDL.
|
||||
2. При необходимости загружает supporting XSD.
|
||||
3. Система извлекает services, ports и operations из WSDL.
|
||||
4. Оператор выбирает service, port и operation.
|
||||
5. UI показывает input/output schema в JSON-oriented виде.
|
||||
6. Оператор настраивает mapping `MCP input -> SOAP body`.
|
||||
7. При необходимости задает SOAP headers и auth profile.
|
||||
8. Настраивает output mapping и fault handling.
|
||||
9. Выполняет test run.
|
||||
10. Публикует operation как MCP tool.
|
||||
|
||||
Foundation routes:
|
||||
|
||||
- `POST /operations/{operation_id}/descriptors/wsdl`
|
||||
- `POST /operations/{operation_id}/descriptors/xsd`
|
||||
- `GET /operations/{operation_id}/soap/services`
|
||||
|
||||
Current UI foundation:
|
||||
|
||||
- protocol selection card on wizard step 1;
|
||||
- dedicated SOAP step 3 panel;
|
||||
- WSDL upload;
|
||||
- optional XSD upload;
|
||||
- backend-driven inspection of `service -> port -> operation`;
|
||||
- applying selected binding metadata into the operation draft target.
|
||||
|
||||
## 8. Поведение runtime
|
||||
|
||||
При выполнении SOAP operation runtime должен:
|
||||
|
||||
1. Валидировать MCP input.
|
||||
2. Построить XML envelope.
|
||||
3. Подставить namespaces, `Content-Type` и `SOAPAction`.
|
||||
4. Выполнить HTTP request.
|
||||
5. Разобрать SOAP response и SOAP Fault.
|
||||
6. Нормализовать XML result в JSON.
|
||||
7. Применить output mapping.
|
||||
8. Вернуть итоговый результат.
|
||||
|
||||
## 9. Критические нюансы
|
||||
|
||||
- WSDL import должен быть отделен от runtime call;
|
||||
- XML namespaces должны быть first-class частью конфигурации;
|
||||
- SOAP Fault нельзя сводить только к HTTP error;
|
||||
- input/output schema должны отображаться в UI как нормализованные поля, а не как raw XML;
|
||||
- auth и headers должны настраиваться отдельно от body mapping.
|
||||
|
||||
## 10. Почему SOAP должен входить в product scope
|
||||
|
||||
Если Crank позиционируется как enterprise integration platform, отсутствие SOAP оставляет большую часть legacy и regulated environments вне продукта.
|
||||
|
||||
Поэтому SOAP должен быть частью общей protocol strategy наравне с:
|
||||
|
||||
- REST
|
||||
- GraphQL
|
||||
- gRPC
|
||||
- WebSocket
|
||||
|
||||
Но при этом он должен оставаться request-response oriented adapter, а не ломать общую execution model.
|
||||
@@ -1,159 +0,0 @@
|
||||
# WebSocket
|
||||
|
||||
## 1. Роль протокола в проекте
|
||||
|
||||
WebSocket поддерживается как полноценный upstream protocol для realtime, push-oriented и stateful integrations. Он не заменяет downstream MCP transport, а работает за Crank proxy.
|
||||
|
||||
Иными словами:
|
||||
|
||||
- downstream: MCP `Streamable HTTP`;
|
||||
- upstream: WebSocket;
|
||||
- Crank нормализует WebSocket lifecycle в bounded MCP tool semantics.
|
||||
|
||||
## 2. Что поддерживается в целевом продукте
|
||||
|
||||
- клиентское WebSocket подключение к внешнему upstream;
|
||||
- custom headers и auth profiles;
|
||||
- handshake config;
|
||||
- optional subprotocol selection;
|
||||
- subscription payload или start message;
|
||||
- bounded `window` mode;
|
||||
- `session` mode с `start/poll/stop`;
|
||||
- `async_job` mode для control-plane и progress channels;
|
||||
- JSON message parsing;
|
||||
- text-frame based event collection;
|
||||
- mapping `MCP input -> subscribe payload`;
|
||||
- mapping `WebSocket message -> normalized JSON`;
|
||||
- heartbeat/keepalive config;
|
||||
- reconnect policy для controlled session modes.
|
||||
|
||||
## 3. Что не входит в текущий продуктовый scope
|
||||
|
||||
- raw binary frame passthrough в LLM;
|
||||
- arbitrary bidirectional conversation tunnel;
|
||||
- full message bus semantics;
|
||||
- generic browser-like socket inspector;
|
||||
- guaranteed resumability across arbitrary upstream websocket providers.
|
||||
|
||||
## 4. Ключевое архитектурное ограничение
|
||||
|
||||
WebSocket не публикуется как "живой канал в чат". Он должен быть выражен в одной из execution models:
|
||||
|
||||
- `window`
|
||||
- `session`
|
||||
- `async_job`
|
||||
|
||||
Недопустимо:
|
||||
|
||||
- бесконечно проксировать frames напрямую в MCP client;
|
||||
- скрывать жизненный цикл сокета за одним неопределенным tool call;
|
||||
- смешивать downstream SSE transport и upstream WebSocket semantics в одну абстракцию.
|
||||
|
||||
## 5. Типовые use cases
|
||||
|
||||
### 5.1. Monitoring and telemetry
|
||||
|
||||
- realtime метрики;
|
||||
- device telemetry;
|
||||
- market data;
|
||||
- anomaly events.
|
||||
|
||||
### 5.2. Event subscriptions
|
||||
|
||||
- alert streams;
|
||||
- queue events;
|
||||
- workflow transitions;
|
||||
- security events.
|
||||
|
||||
### 5.3. Stateful control channels
|
||||
|
||||
- rollout progress;
|
||||
- remote task status;
|
||||
- infrastructure control plane updates;
|
||||
- long-running remote sessions.
|
||||
|
||||
## 6. Внутренняя модель WebSocket operation
|
||||
|
||||
WebSocket operation должна включать:
|
||||
|
||||
- `url`
|
||||
- `headers`
|
||||
- `subprotocols`
|
||||
- `subscribe_message_template`
|
||||
- `unsubscribe_message_template`
|
||||
- `input_mapping`
|
||||
- `output_mapping`
|
||||
- `execution_config`
|
||||
- `tool_description`
|
||||
|
||||
Protocol-specific runtime tuning хранится отдельно в `ProtocolOptions.websocket`:
|
||||
|
||||
- `heartbeat_interval_ms`
|
||||
- `reconnect_max_attempts`
|
||||
- `reconnect_backoff_ms`
|
||||
|
||||
## 7. Как оператор настраивает WebSocket operation
|
||||
|
||||
1. Указывает URL WebSocket upstream.
|
||||
2. При необходимости выбирает auth profile и headers.
|
||||
3. Указывает subprotocol или оставляет пустым.
|
||||
4. Выбирает execution mode: `window`, `session` или `async_job`.
|
||||
5. Настраивает subscribe payload.
|
||||
6. Указывает правила извлечения items, status и cursor.
|
||||
7. Настраивает aggregation limits.
|
||||
8. Выполняет test run.
|
||||
9. Публикует operation как MCP tool или tool family.
|
||||
|
||||
## 7.1. Текущий UI foundation
|
||||
|
||||
Текущий wizard support для WebSocket уже включает:
|
||||
|
||||
- выбор `WebSocket` как protocol family на шаге 1;
|
||||
- step 2 reuse общего upstream/auth selector;
|
||||
- отдельный step 3 для:
|
||||
- socket path override;
|
||||
- subprotocol list;
|
||||
- subscribe message template;
|
||||
- unsubscribe message template;
|
||||
- `heartbeat_interval_ms`;
|
||||
- `reconnect_max_attempts`;
|
||||
- `reconnect_backoff_ms`.
|
||||
|
||||
На текущем этапе wizard сериализует:
|
||||
|
||||
- `Target::Websocket`
|
||||
- `ExecutionConfig.protocol_options.websocket`
|
||||
|
||||
Это дает оператору usable foundation для `window`, `session` и `async_job` flows even before deeper inspection/test-run polish.
|
||||
|
||||
## 8. Поведение runtime
|
||||
|
||||
При выполнении WebSocket operation runtime должен:
|
||||
|
||||
1. Валидировать MCP input.
|
||||
2. Построить subscribe payload.
|
||||
3. Открыть WebSocket connection.
|
||||
4. Пройти handshake и auth.
|
||||
5. Отправить subscribe message.
|
||||
6. Собрать bounded window или session step.
|
||||
7. Нормализовать messages в JSON.
|
||||
8. Применить output mapping.
|
||||
9. Закрыть соединение или сохранить session state.
|
||||
|
||||
## 9. Критические нюансы
|
||||
|
||||
- upstream WebSocket может быть stateful и требовать explicit unsubscribe;
|
||||
- heartbeat и reconnect должны быть управляемыми через config, а не захардкоженными;
|
||||
- session state должен хранить cursor, last_event и subscription metadata;
|
||||
- disconnect downstream MCP client не означает cancel upstream session;
|
||||
- runtime обязан уметь cleanly завершать orphaned connections.
|
||||
|
||||
## 10. Почему WebSocket должен быть отдельным adapter
|
||||
|
||||
WebSocket нельзя свести к "почти SSE" или "почти HTTP", потому что:
|
||||
|
||||
- transport двунаправленный;
|
||||
- lifecycle connection stateful;
|
||||
- есть handshake, heartbeat и reconnect;
|
||||
- подписка часто задается сообщением, а не URL;
|
||||
- semantics событий и прогресса отличаются от request-response вызова.
|
||||
Reference in New Issue
Block a user