a.tolmachev
155 lines
8.6 KiB
Markdown
155 lines
8.6 KiB
Markdown
# Crank
|
|
|
|
|
|
|
|
Crank - платформа для публикации внешних API в виде MCP tools без написания отдельного backend-кода под каждую интеграцию. Целевая модель проекта строится вокруг связки `workspace -> agent -> operations`.
|
|
|
|
## Цели
|
|
|
|
- Разработать MCP server на Rust.
|
|
- Поддержать динамическое добавление интеграций через UI или конфигурацию.
|
|
- Обеспечить единый сценарий работы оператора для REST, GraphQL, gRPC, WebSocket и SOAP.
|
|
- Нормализовать внешние протоколы в единую внутреннюю модель операции.
|
|
- Ограничивать набор tools на уровне конкретного агента, а не отдавать один глобальный каталог.
|
|
- Поддержать workspace-изоляцию, platform access и observability.
|
|
|
|
## Целевая модель продукта
|
|
|
|
- `Workspace` как tenant boundary.
|
|
- `Operation` как интеграционный контракт.
|
|
- `Agent` как curated MCP surface для LLM.
|
|
- Поддержка REST для `GET`, `POST`, `PUT`, `PATCH` и `DELETE`.
|
|
- Поддержка GraphQL для `query` и `mutation`.
|
|
- Поддержка unary и bounded server-streaming для gRPC.
|
|
- Поддержка WebSocket upstream integrations в bounded execution modes.
|
|
- Поддержка SOAP/WSDL enterprise integrations.
|
|
- Поддержка controlled streaming modes поверх MCP `Streamable HTTP`.
|
|
- Platform API keys и membership layer.
|
|
- Observability: invocation logs, usage aggregates, latency/error metrics.
|
|
- Импорт и экспорт operation-конфигураций в `YAML`.
|
|
- Использование `JSONPath` для точечного маппинга.
|
|
|
|
## Структура документации
|
|
|
|
- `docs/architecture.md` - целевая архитектура системы.
|
|
- `docs/as-is-to-be.md` - переход `as is -> to be`, page-by-page gap analysis и архитектурные конфликты.
|
|
- `docs/backend-gap-plan.md` - конкретный backend-план: сущности, API, БД и порядок реализации.
|
|
- `docs/operations-workspace-contracts.md` - точные `workspace-scoped` контракты для экранов `Operations` и `Wizard`.
|
|
- `docs/alpine-ui-integration-plan.md` - постраничный план подключения нового Alpine UI к реальному backend.
|
|
- `docs/module-decomposition.md` - декомпозиция crates и модулей.
|
|
- `docs/data-model.md` - целевая модель данных.
|
|
- `docs/database-schema.md` - целевая схема БД.
|
|
- `docs/admin-api.md` - целевые HTTP-контракты административного API.
|
|
- `docs/diagrams.md` - диаграммы компонентов, сущностей и БД.
|
|
- `docs/mcp-interface.md` - модель MCP transport и agent-scoped publishing.
|
|
- `docs/testing-strategy.md` - стратегия тестирования.
|
|
- `docs/manual-regression-checklist.md` - post-integration regression baseline и ручной smoke checklist.
|
|
- `docs/runtime-config.md` - конфигурация окружения.
|
|
- `docs/deployment.md` - деплой, reverse proxy и CI/CD.
|
|
- `docs/deploy-and-staging-smoke.md` - канонический post-deploy smoke pass для staging/production-like окружения.
|
|
- `docs/authenticated-staging-pass.md` - browser-authenticated pass для UI flows, secrets, wizard и protocol smoke на стенде.
|
|
- `docs/staging-regression-notes.md` - журнал реальных замечаний и результатов post-deploy проверок на стенде.
|
|
- `docs/demo-runbook.md` - демонстрационный сценарий.
|
|
- `docs/public-smoke-targets.md` - готовые публичные upstream-сервисы и payload-ы для smoke-проверки MCP.
|
|
- `docs/secrets-auth-plan.md` - целевая модель upstream secrets, auth profiles и пошаговый план реализации.
|
|
- `docs/streaming-mcp-plan.md` - целевая модель MCP transport streaming, upstream streaming и поэтапный план реализации.
|
|
- `docs/streaming-admin-api.md` - точные HTTP-контракты и DTO для streaming configuration, sessions и jobs.
|
|
- `docs/streaming-runtime-design.md` - функция-за-функцией разложенная streaming runtime architecture.
|
|
- `docs/streaming-ui-contract.md` - точный UI-контракт для streaming configuration и test flows.
|
|
- `docs/protocol-capability-matrix.md` - capability matrix по всем protocol families и execution modes.
|
|
- `docs/streaming-implementation-spec.md` - execution-oriented план реализации по срезам, файлам, тестам и DoD.
|
|
- `docs/rust-design.md` - правила распределения поведения в Rust.
|
|
- `docs/development-rules.md` - правила разработки и workflow.
|
|
- `docs/rust-code-rules.md` - Rust-specific coding rules.
|
|
- `docs/implementation-plan.md` - порядок перехода от текущего состояния к целевой модели.
|
|
- `docs/protocols/rest.md` - требования и ограничения для REST.
|
|
- `docs/protocols/graphql.md` - требования и ограничения для GraphQL.
|
|
- `docs/protocols/grpc.md` - требования и ограничения для gRPC.
|
|
- `docs/protocols/websocket.md` - требования и ограничения для WebSocket.
|
|
- `docs/protocols/soap.md` - требования и ограничения для SOAP.
|
|
|
|
## Ключевая идея продукта
|
|
|
|
Система строится вокруг трех уровней:
|
|
|
|
- `Workspace` - граница данных и доступа команды.
|
|
- `Agent` - curated MCP endpoint для конкретного сценария LLM.
|
|
- `Operation` - низкоуровневый интеграционный контракт.
|
|
|
|
`Operation` описывает:
|
|
|
|
- внешний протокол;
|
|
- целевой endpoint или метод;
|
|
- входную схему;
|
|
- правила маппинга входных данных;
|
|
- параметры выполнения;
|
|
- правила маппинга выходных данных;
|
|
- метаданные MCP tool.
|
|
|
|
`Agent` собирает ограниченный набор опубликованных операций в одну MCP-поверхность. Именно это решает проблему, когда один агент теряется в слишком большом наборе tools.
|
|
|
|
## CI/CD статус
|
|
|
|
В репозитории настроены:
|
|
|
|
- `CI` для Rust, UI и deployment manifests;
|
|
- `CD`, который после успешного `CI` на `main` собирает versioned images, пушит их в `GHCR` и деплоит Community через `deploy/community/docker-compose.yml`;
|
|
- containerized Community deployment через `deploy/community/docker-compose.yml`.
|
|
|
|
## Поддерживаемые протоколы
|
|
|
|
В целевой модели платформа ориентируется на:
|
|
|
|
- REST
|
|
- GraphQL
|
|
- gRPC
|
|
- WebSocket
|
|
- SOAP
|
|
|
|
Все пять протокольных семейств входят в целевой product scope. Разница только в очередности реализации.
|
|
|
|
## Frontend e2e
|
|
|
|
Для UI настроен Playwright-контур, который поднимает локальный стек:
|
|
|
|
- `postgres` в отдельном Docker-контейнере;
|
|
- `admin-api` и `mcp-server` через `cargo run`;
|
|
- `apps/ui` через локальный Node static+proxy server для e2e;
|
|
- `CRANK_DEMO_SEED=true` для предсказуемых demo-данных.
|
|
|
|
Локальный запуск:
|
|
|
|
```bash
|
|
cd apps/ui
|
|
npm ci
|
|
npm run build
|
|
npm run e2e:install
|
|
npm run e2e
|
|
```
|
|
|
|
Или через `just`:
|
|
|
|
```bash
|
|
just ui-e2e
|
|
```
|
|
|
|
Для post-deploy smoke:
|
|
|
|
```bash
|
|
just staging-smoke https://<domain>
|
|
```
|
|
|
|
Для browser-authenticated smoke на реальном стенде:
|
|
|
|
```bash
|
|
export CRANK_STAGING_ADMIN_EMAIL=owner@example.com
|
|
export CRANK_STAGING_ADMIN_PASSWORD=secret
|
|
just authenticated-staging-smoke https://<domain>
|
|
```
|
|
|
|
Чтобы быстро подготовить запись для `docs/staging-regression-notes.md`:
|
|
|
|
```bash
|
|
just staging-note-block <domain> <deploy-sha> "codex + operator"
|
|
```
|