Crank

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.

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

mkdir -p crank
cd crank

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

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.

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

openssl rand -hex 32

Запустите Crank:

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:

CRANK_PUBLISH_BIND=0.0.0.0

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

docker compose ps

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

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

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

docker compose down

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

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:

docker compose up -d

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

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

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

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-инструменты, которые явно привязаны к этому агенту.

Рекомендации по названиям, описаниям, схемам, ошибкам и опасным операциям описаны в документе Проектирование MCP-инструментов.

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

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

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

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

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;
• Node.js и npm;
• PostgreSQL;
• Docker, если хотите запускать полный стенд контейнерами.

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

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

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

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

cargo run -p admin-api

MCP-сервер:

cargo run -p mcp-server

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

cd apps/ui
npm ci
npm run dev

Проверки:

just fmt-check
just clippy
just test

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

cd apps/ui
npm ci
npm run build

E2E-проверки:

cd apps/ui
npx playwright test

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

• Настройки запуска
• Развертывание
• MCP-интерфейс
• Английский README

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

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

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

Лицензия

GNU Affero General Public License v3.0 only