crank/README.md

# Crank

![Crank](./crank-community.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`;
- доступ к опубликованным Docker-образам Crank.

Создайте рабочую папку:

```bash
mkdir -p crank
cd crank
```

Скачайте compose-файл и пример настроек:

```bash
curl -fsSLo docker-compose.yml https://git.itexp.me/bsodfather/crank/raw/branch/main/deploy/community/docker-compose.images.yml
curl -fsSLo .env.example https://git.itexp.me/bsodfather/crank/raw/branch/main/deploy/community/.env.images.example
cp .env.example .env
```

Откройте скачанный `.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 --profile local-db up -d
```

Если registry требует авторизацию, сначала выполните `docker login git.itexp.me`.

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

- веб-интерфейс: `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
```

Обновить Crank до свежих образов:

```bash
docker compose --profile local-db pull
docker compose --profile local-db up -d
```

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

Если PostgreSQL уже запущен отдельно, профиль `local-db` не нужен.

В `.env` укажите параметры вашей базы:

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

Затем запустите только приложения Crank:

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

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

## Запуск из исходников

Если нужно собрать образы самостоятельно, клонируйте репозиторий и используйте корневой [`docker-compose.yml`](./docker-compose.yml):

```bash
git clone https://github.com/bsodfather/crank-community.git crank
cd crank
cp .env.example .env
docker compose up -d --build
```

Этот вариант удобен для локальной проверки изменений перед отправкой патча.

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

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

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
  docker-compose.images.yml запуск готовых образов без исходников
  .env.example            пример настроек для серверного запуска из исходников
  .env.images.example     пример настроек для запуска готовых образов
```

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

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

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

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

```bash
git clone https://github.com/bsodfather/crank-community.git crank
cd crank
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)

## Участие в разработке

Перед отправкой pull request нужно согласиться с [Contributor License Agreement](CLA.md).

Правила участия описаны в [CONTRIBUTING.md](CONTRIBUTING.md).

## Лицензия

GNU Affero General Public License v3.0 only