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

Загружает .proto или descriptor set.
Система извлекает список services и methods.
Оператор выбирает конкретный unary-метод.
UI показывает структуру request message и response message.
При необходимости загружает примеры JSON для MCP input/output.
Система строит черновую схему и стартовый mapping.
Оператор задает или уточняет входные MCP-параметры.
Настраивает маппинг во входные protobuf fields.
Настраивает маппинг из response fields в MCP output.
При необходимости уточняет mapping через JSONPath.
Выполняет тест.
Публикует operation как MCP tool.

7. Поведение runtime

При выполнении gRPC operation runtime должен:

Валидировать MCP input по нормализованной схеме.
Применить input mapping.
Построить protobuf request message из JSON.
Выполнить unary RPC вызов.
Преобразовать protobuf response в нормализованный JSON.
Применить output mapping.
Вернуть итоговый результат.

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-платформой.

5.8 KiB Raw Blame History