a.tolmachev
75 lines
6.7 KiB
Markdown
75 lines
6.7 KiB
Markdown
# MCPaaS
|
||
|
||
MCPaaS - это low-code платформа для публикации внешних API в виде MCP tools без написания нового backend-обработчика под каждую интеграцию. Система предоставляет единый административный UI, в котором оператор может подключать REST, GraphQL и gRPC операции, настраивать маппинг входных и выходных данных, выполнять тестовый вызов и публиковать результат как MCP tool.
|
||
|
||
На текущем этапе репозиторий содержит проектную документацию и архитектурные решения, которые задают границы MVP и подход к реализации.
|
||
|
||
## Цели
|
||
|
||
- Разработать MCP server на Rust.
|
||
- Поддержать динамическое добавление интеграций через UI или конфигурацию.
|
||
- Обеспечить единый сценарий работы оператора для REST, GraphQL и gRPC.
|
||
- Нормализовать внешние протоколы в единую внутреннюю модель операции.
|
||
- Избежать генерации и деплоя нового backend-кода при добавлении каждого нового инструмента.
|
||
|
||
## Состав MVP
|
||
|
||
- Поддержка REST для `GET`, `POST`, `PUT`, `PATCH` и `DELETE`.
|
||
- Поддержка GraphQL для `query` и `mutation` на основе шаблонов и переменных.
|
||
- Поддержка только unary-методов gRPC.
|
||
- Загрузка примеров `JSON` для ускоренного создания схем и чернового маппинга.
|
||
- Загрузка `.proto` файлов или descriptor set для обнаружения схемы gRPC.
|
||
- Импорт и экспорт конфигураций операций в `YAML`.
|
||
- Использование `JSONPath` для точечного маппинга вложенных параметров и ответа.
|
||
- Настройка маппинга запроса и ответа через UI.
|
||
- Публикация tools в MCP без пересборки backend.
|
||
|
||
## Структура документации
|
||
|
||
- `docs/architecture.md` - архитектура системы, модули, потоки данных и стек.
|
||
- `docs/module-decomposition.md` - детальная декомпозиция crates и внутренних модулей.
|
||
- `docs/data-model.md` - формальная модель данных и JSON-структуры сущностей.
|
||
- `docs/database-schema.md` - схема БД, связи и versioning конфигураций.
|
||
- `docs/admin-api.md` - HTTP-контракты административного API.
|
||
- `docs/diagrams.md` - структурные диаграммы компонентов, сущностей, БД и потоков.
|
||
- `docs/mcp-interface.md` - транспорт и контракт публикации MCP tools.
|
||
- `docs/testing-strategy.md` - стратегия тестирования до и во время разработки.
|
||
- `docs/runtime-config.md` - конфигурация окружения, storage и секретов.
|
||
- `docs/rust-design.md` - распределение методов, `impl`, `trait` и service-слоя без god-struct.
|
||
- `docs/development-rules.md` - правила разработки, TDD-процесс и git workflow.
|
||
- `docs/rust-code-rules.md` - Rust-specific правила кода, toolchain и linting.
|
||
- `docs/implementation-plan.md` - последовательность модулей и фич по этапам реализации.
|
||
- `docs/protocols/rest.md` - функциональные требования и ограничения для REST.
|
||
- `docs/protocols/graphql.md` - функциональные требования и ограничения для GraphQL.
|
||
- `docs/protocols/grpc.md` - функциональные требования и ограничения для gRPC.
|
||
|
||
## Ключевая идея продукта
|
||
|
||
Система строится вокруг унифицированной сущности `Operation`. Каждая операция описывает:
|
||
|
||
- внешний протокол,
|
||
- целевой endpoint или метод,
|
||
- входную схему,
|
||
- правила маппинга входных данных,
|
||
- параметры выполнения,
|
||
- правила маппинга выходных данных,
|
||
- метаданные MCP tool.
|
||
|
||
За счет этого MCP runtime работает с единой внутренней моделью, а протокольные адаптеры уже выполняют конкретные вызовы REST, GraphQL или gRPC.
|
||
|
||
Для GraphQL это означает, что в MCP публикуется не "универсальный GraphQL endpoint", а конкретная операция с фиксированным шаблоном запроса, фиксированным набором входных параметров и предсказуемой структурой ответа.
|
||
|
||
Для упрощения настройки оператор может загружать примеры входного и выходного `JSON`, а для gRPC - `.proto` или descriptor set. На основе этих артефактов система строит черновую схему и стартовый маппинг, который затем вручную уточняется через `JSONPath`.
|
||
|
||
Конфигурации операций должны импортироваться и экспортироваться в `YAML`, чтобы их можно было переносить между окружениями, хранить в git и редактировать вне UI.
|
||
|
||
## Поддерживаемые протоколы
|
||
|
||
В MVP платформа ориентируется на три основных протокольных сценария интеграции:
|
||
|
||
- REST
|
||
- GraphQL
|
||
- gRPC
|
||
|
||
`SOAP` сознательно не входит в MVP. Он остается актуальным для части корпоративных и государственных интеграций, но требует отдельного адаптера с поддержкой WSDL, XML Schema, SOAP envelope, namespaces и XML-oriented mapping. Для первой версии это слишком большой отдельный пласт сложности.
|