# Crank

![Crank](./Crank.png)

Crank - платформа для публикации внешних API в виде MCP tools без написания отдельного backend-кода под каждую интеграцию. Целевая модель проекта строится вокруг связки `workspace -> agent -> operations`.

## Цели

- Разработать MCP server на Rust.
- Поддержать динамическое добавление интеграций через UI или конфигурацию.
- Обеспечить единый сценарий работы оператора для REST, GraphQL и gRPC.
- Нормализовать внешние протоколы в единую внутреннюю модель операции.
- Ограничивать набор tools на уровне конкретного агента, а не отдавать один глобальный каталог.
- Поддержать workspace-изоляцию, platform access и observability.

## Целевая модель продукта

- `Workspace` как tenant boundary.
- `Operation` как интеграционный контракт.
- `Agent` как curated MCP surface для LLM.
- Поддержка REST для `GET`, `POST`, `PUT`, `PATCH` и `DELETE`.
- Поддержка GraphQL для `query` и `mutation`.
- Поддержка только unary-методов gRPC.
- 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/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/runtime-config.md` - конфигурация окружения.
- `docs/deployment.md` - деплой, reverse proxy и CI/CD.
- `docs/demo-runbook.md` - демонстрационный сценарий.
- `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.

## Ключевая идея продукта

Система строится вокруг трех уровней:

- `Workspace` - граница данных и доступа команды.
- `Agent` - curated MCP endpoint для конкретного сценария LLM.
- `Operation` - низкоуровневый интеграционный контракт.

`Operation` описывает:

- внешний протокол;
- целевой endpoint или метод;
- входную схему;
- правила маппинга входных данных;
- параметры выполнения;
- правила маппинга выходных данных;
- метаданные MCP tool.

`Agent` собирает ограниченный набор опубликованных операций в одну MCP-поверхность. Именно это решает проблему, когда один агент теряется в слишком большом наборе tools.

## CI/CD статус

В репозитории настроены:

- `CI` для Rust, UI container и deployment artifacts;
- `CD`, который запускается после успешного `CI` на `main` или вручную;
- containerized deployment через `docker compose`.

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

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

- REST
- GraphQL
- gRPC

`SOAP` сознательно не входит в текущий scope.