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 и деплоит через docker compose pull;
• containerized deployment через docker compose.

Поддерживаемые протоколы

В целевой модели платформа ориентируется на:

• 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-данных.

Локальный запуск:

cd apps/ui
npm ci
npm run e2e:install
npm run e2e

Или через just:

just ui-e2e

Для post-deploy smoke:

just staging-smoke https://<domain>

Для browser-authenticated smoke на реальном стенде:

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:

just staging-note-block <domain> <deploy-sha> "codex + operator"