crank/README.md

# Crank

![Crank](./Crank.png)

Crank - это свободная платформа для создания MCP-инструментов из REST API эндпоинтов.

Сервис ставится на собственный сервер, подключается к PostgreSQL и дает веб-интерфейс, в котором можно описать REST API, проверить вызов, опубликовать его как инструмент и подключить к MCP-клиенту.

## Что умеет Crank

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

## Быстрый запуск через Docker

Требования:

- Docker;
- Docker Compose;
- свободные порты `3000`, `3001`, `3002`;
- 4 ГБ RAM или больше для комфортной сборки образов.

Склонируйте репозиторий:

```bash
git clone https://github.com/bsodfather/crank-community.git crank
cd crank
```

Подготовьте настройки:

```bash
cp .env.example .env
```

Откройте [`.env.example`](./.env.example) и перенесите нужные значения в `.env`.

Минимально нужно заменить:

- `POSTGRES_PASSWORD`;
- `CRANK_MASTER_KEY`;
- `CRANK_SESSION_SECRET`;
- `CRANK_PASSWORD_PEPPER`;
- `CRANK_BOOTSTRAP_ADMIN_EMAIL`;
- `CRANK_BOOTSTRAP_ADMIN_PASSWORD`;
- `CRANK_BASE_URL`.

Секреты можно сгенерировать так:

```bash
openssl rand -hex 32
```

Запустите Crank:

```bash
docker compose up -d --build
```

После запуска:

- веб-интерфейс: `http://localhost:3000`;
- HTTP API панели управления: `http://localhost:3001`;
- MCP-сервер: `http://localhost:3002`.

По умолчанию порты публикуются только на `127.0.0.1`. Это удобно, если перед Crank стоит nginx, Caddy или другой обратный прокси. Если нужно открыть порты наружу напрямую, укажите в `.env`:

```env
CRANK_PUBLISH_BIND=0.0.0.0
```

Проверить состояние контейнеров:

```bash
docker compose ps
```

Посмотреть журналы:

```bash
docker compose logs -f admin-api mcp-server ui
```

Остановить сервис:

```bash
docker compose down
```

## Запуск с внешним PostgreSQL

Корневой [`docker-compose.yml`](./docker-compose.yml) поднимает PostgreSQL рядом с приложением. Для сервера, где база уже есть отдельно, используйте манифест из [`deploy/community/docker-compose.yml`](./deploy/community/docker-compose.yml):

```bash
cp deploy/community/.env.example deploy/community/.env
docker compose -f deploy/community/docker-compose.yml --env-file deploy/community/.env up -d --build
```

В этом варианте в `deploy/community/.env` нужно указать параметры вашей базы:

- `POSTGRES_HOST`;
- `POSTGRES_PORT`;
- `POSTGRES_DB`;
- `POSTGRES_USER`;
- `POSTGRES_PASSWORD`.

Если используется PgBouncer, укажите его адрес в `POSTGRES_HOST` и порт в `POSTGRES_PORT`.

## Как пользоваться

Обычный сценарий:

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

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

## Что входит в эту версию

Этот репозиторий содержит открытую версию Crank:

- REST API как источник инструментов;
- MCP через Streamable HTTP;
- веб-интерфейс администратора;
- простая авторизация администратора;
- ключи агентов для доступа к MCP;
- PostgreSQL как основное хранилище;
- необязательный Valkey или Redis для служебного кэша.

## Структура проекта

```text
apps/
  admin-api/      HTTP API для веб-интерфейса
  mcp-server/     MCP-сервер
  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      запуск с внешним PostgreSQL
  .env.example            пример настроек для серверного запуска
```

## Разработка

Для разработки нужны:

- Rust toolchain из [`rust-toolchain.toml`](./rust-toolchain.toml);
- Node.js и npm;
- PostgreSQL;
- Docker, если хотите запускать полный стенд контейнерами.

Быстрее всего поднять окружение так же, как для обычного запуска:

```bash
cp .env.example .env
docker compose up -d postgres
```

Приложения читают настройки из переменных окружения. Можно использовать `.env` через свое окружение разработки, `direnv`, IDE или любой другой привычный способ загрузки переменных.

Сервер панели управления:

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

MCP-сервер:

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

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

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

Проверки:

```bash
just fmt-check
just clippy
just test
```

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

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

E2E-проверки:

```bash
cd apps/ui
npx playwright test
```

## Документация

- [Настройки запуска](docs/runtime-config.md)
- [Развертывание](docs/deployment.md)
- [MCP-интерфейс](docs/mcp-interface.md)
- [Английский README](docs/en/README.md)

## Лицензия

MIT