crank/README.md

# Crank

![Crank](./Crank.png)

Crank Community — самостоятельная версия Crank для публикации REST API как MCP-инструментов.

Проект помогает подключать существующие HTTP API к LLM-клиентам без написания отдельного MCP-сервера для каждой интеграции. В Crank можно описать REST-операцию, проверить ее, опубликовать и открыть через MCP.

## Возможности

- Создание REST-операций через веб-интерфейс или YAML.
- Преобразование входных параметров MCP-инструмента в параметры REST-запроса: путь, query string, заголовки и тело запроса.
- Преобразование ответа REST API в структурированный результат MCP-инструмента.
- Публикация выбранных операций в MCP-точках доступа конкретных агентов.
- Отдельный каталог инструментов для каждого агента.
- Хранение черновиков, версий, примеров запросов и ответов, правил преобразования, журналов и статистики в PostgreSQL.
- Простая авторизация администратора через email, пароль и сессию браузера.
- Хранение секретов и профилей авторизации для внешних REST API.
- Развертывание через Docker Compose.

## Границы Community-версии

Этот репозиторий содержит только Community-возможности:

- только REST;
- одно самостоятельное развертывание;
- простая авторизация администратора;
- статические ключи агентов для MCP-доступа;
- PostgreSQL как основная база данных;
- необязательный Valkey или Redis для служебного кэша;
- CI/CD через Gitea Actions.

## Архитектура

Основные сущности:

- `Workspace` — граница данных для операций, агентов, секретов и журналов.
- `Operation` — версионируемое описание REST-интеграции.
- `Agent` — MCP-точка доступа с ограниченным набором опубликованных операций.

Рабочий сценарий:

1. Оператор создает или импортирует REST-операцию.
2. Crank проверяет схему входа, схему выхода и правила преобразования данных.
3. Оператор выполняет пробный вызов внешнего REST API.
4. Операция публикуется.
5. Операция привязывается к агенту.
6. MCP-клиент вызывает инструмент через `mcp-server`.

## Структура репозитория

```text
apps/
  admin-api/      HTTP API для интерфейса, авторизации, операций, агентов, журналов и настроек
  mcp-server/     MCP-сервер поверх Streamable HTTP
  ui/             веб-интерфейс

crates/
  crank-core/             общая доменная модель
  crank-registry/         работа с PostgreSQL
  crank-runtime/          выполнение REST-операций, преобразование данных, кэш, лимиты
  crank-adapter-rest/     REST-адаптер
  crank-community-auth/   пароли и сессии
  crank-community-mcp/    прикладной слой MCP
  crank-mapping/          преобразование данных через JSONPath
  crank-schema/           нормализация и проверка схем

deploy/community/
  docker-compose.yml      манифест развертывания Community-версии
  .env.example            пример переменных окружения
```

## Требования

- Rust toolchain из `rust-toolchain.toml`
- Node.js и npm для веб-интерфейса
- PostgreSQL
- Docker и Docker Compose для развертывания

## Локальная разработка

Запустите PostgreSQL и задайте переменные окружения:

```bash
export POSTGRES_HOST=127.0.0.1
export POSTGRES_PORT=5432
export POSTGRES_DB=crank
export POSTGRES_USER=crank
export POSTGRES_PASSWORD=crank
export CRANK_MASTER_KEY=0000000000000000000000000000000000000000000000000000000000000000
export CRANK_SESSION_SECRET=dev-session-secret
export CRANK_PASSWORD_PEPPER=dev-password-pepper
export CRANK_BOOTSTRAP_ADMIN_EMAIL=owner@crank.local
export CRANK_BOOTSTRAP_ADMIN_PASSWORD=change-me-admin-password
export CRANK_BOOTSTRAP_ADMIN_DISPLAY_NAME="Crank Owner"
export CRANK_STORAGE_ROOT=.tmp/storage
export CRANK_BASE_URL=http://127.0.0.1:3000
```

Запустите серверные приложения:

```bash
cargo run -p admin-api
cargo run -p mcp-server
```

Соберите веб-интерфейс:

```bash
cd apps/ui
npm ci
npm run build
```

## Проверки

Rust:

```bash
cargo fmt --all --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace --all-targets
```

Веб-интерфейс:

```bash
cd apps/ui
npm ci
npm run build
npx playwright test
```

Playwright поднимает локальный проверочный стенд с PostgreSQL, `admin-api`, `mcp-server` и сервером веб-интерфейса.

## Развертывание

Манифест Community-версии находится в `deploy/community/docker-compose.yml`.

Для рабочего развертывания нужны:

- внешний PostgreSQL;
- контейнерные образы для `admin-api`, `mcp-server` и `ui`;
- секреты и настройки через переменные окружения;
- обратный прокси перед портами `3000`, `3001`, `3002`.

Процесс развертывания в `.gitea/workflows/deploy.yml` собирает образы, читает настройки из OpenBao, записывает `.env` на сервер развертывания и запускает Docker Compose.

Ключевые переменные окружения:

- `POSTGRES_HOST`, `POSTGRES_PORT`, `POSTGRES_DB`, `POSTGRES_USER`, `POSTGRES_PASSWORD`
- `CRANK_MASTER_KEY`
- `CRANK_SESSION_SECRET`
- `CRANK_PASSWORD_PEPPER`
- `CRANK_BOOTSTRAP_ADMIN_EMAIL`
- `CRANK_BOOTSTRAP_ADMIN_PASSWORD`
- `CRANK_BASE_URL`
- `CRANK_PUBLISH_BIND`

Дополнительная документация:

- [docs/runtime-config.md](docs/runtime-config.md)
- [docs/deployment.md](docs/deployment.md)
- [docs/mcp-interface.md](docs/mcp-interface.md)

## MCP

Crank публикует MCP-точки доступа для отдельных агентов через Streamable HTTP. Каждый агент имеет собственный каталог инструментов, поэтому MCP-клиент видит только REST-инструменты, явно привязанные к этому агенту.

Типовой сценарий:

1. Создать REST-операцию.
2. Проверить REST-операцию пробным вызовом.
3. Опубликовать REST-операцию.
4. Привязать операцию к агенту.
5. Создать ключ агента.
6. Подключить MCP-клиент к точке доступа агента.

## Английская документация

Английский вариант README находится в [docs/en/README.md](docs/en/README.md).

## Лицензия

MIT