bsodfather/crank
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: define streaming mcp architecture

Browse Source
This commit is contained in:
a.tolmachev
2026-04-06 01:45:48 +03:00
parent d7e5ae95d6
commit 04ed704e94
12 changed files with 834 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/protocols/grpc.md
+15 -16
View File
@@ -2,11 +2,12 @@
## 1. Роль протокола в проекте
gRPC поддерживается как третий основной протокол платформы, но в самой узкой и управляемой форме. Цель состоит не в том, чтобы покрыть все возможности gRPC, а в том, чтобы представить unary RPC-методы как обычные MCP tools с формой входа и формой выхода.
gRPC поддерживается как третий основной протокол платформы в управляемой форме. Цель состоит не в том, чтобы покрыть все возможности gRPC, а в том, чтобы представить unary и bounded server-streaming методы как MCP tools с предсказуемым жизненным циклом.
## 2. Что поддерживается в MVP
- только unary RPC
- unary RPC
- bounded server-streaming через execution modes `window`, `session`, `async_job`
- загрузка `.proto`
- загрузка descriptor set
- загрузка примеров JSON для MCP input/output при необходимости
@@ -22,7 +23,6 @@ gRPC поддерживается как третий основной прот
## 3. Что не входит в MVP
- `server streaming`
- `client streaming`
- `bidirectional streaming`
- обязательная поддержка server reflection
@@ -31,17 +31,15 @@ gRPC поддерживается как третий основной прот
## 4. Ключевое архитектурное ограничение
В проекте поддерживаются только unary-методы, потому что MCP tool в этой архитектуре соответствует модели `один запрос -> один ответ`.
В проекте поддерживаются unary-методы и bounded server-streaming, потому что MCP tool в этой архитектуре должен оставаться управляемым.
Это означает:
- один request message;
- один response message;
- один завершенный вызов;
- отсутствие потоковых сообщений;
- отсутствие отдельного жизненного цикла stream-сессии.
- один bounded response или управляемая session/job-семантика;
- явно ограниченный lifecycle stream-сессии.
Streaming gRPC не нужен для выбранной модели взаимодействия с LLM и только усложнит runtime, UI и хранение состояния.
Streaming gRPC не публикуется как бесконечный raw stream. Он допускается только там, где runtime умеет bounded-ить, агрегировать и завершать результат.
## 5. Внутренняя модель gRPC operation
@@ -64,7 +62,7 @@ gRPC operation должна включать:
1. Загружает `.proto` или descriptor set.
2. Система извлекает список services и methods.
3. Оператор выбирает конкретный unary-метод.
3. Оператор выбирает конкретный unary- или server-streaming метод.
4. UI показывает структуру request message и response message.
5. При необходимости загружает примеры JSON для MCP input/output.
6. Система строит черновую схему, стартовый mapping и runtime-ready snapshot descriptor set для выбранного метода.
@@ -82,10 +80,11 @@ gRPC operation должна включать:
1. Валидировать MCP input по нормализованной схеме.
2. Применить input mapping.
3. Построить protobuf request message из JSON.
4. Выполнить unary RPC вызов.
5. Преобразовать protobuf response в нормализованный JSON.
6. Применить output mapping.
7. Вернуть итоговый результат.
4. Для unary выполнить unary RPC вызов.
5. Для server-streaming собрать bounded окно или session step.
6. Преобразовать protobuf response или stream items в нормализованный JSON.
7. Применить output mapping.
8. Вернуть итоговый результат.
## 8. Критические нюансы
@@ -99,7 +98,7 @@ gRPC operation должна включать:
- пользователь не должен видеть внутреннюю сложность protobuf-контракта больше, чем это нужно для настройки operation.
- `JSONPath` используется как единый способ точечной адресации вложенных полей при настройке mapping поверх нормализованной JSON-модели.
## 9. Почему gRPC ограничивается unary
## 9. Почему gRPC ограничивается controlled streaming
Причина не только в сложности реализации. Главное ограничение архитектурное:
@@ -108,4 +107,4 @@ gRPC operation должна включать:
- UI платформы построен вокруг формы входа и формы выхода;
- streaming требует отдельной session-модели, buffering, cancellation и состояния.
Поэтому unary gRPC - это не "обрезанная" поддержка, а осознанно выбранная форма, которая действительно совместима с MCP-платформой.
Поэтому поддержка gRPC в Crank ограничивается unary и bounded server-streaming. Client-streaming и bidi остаются вне scope до появления полноценной interactive session model.