Crank

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.

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

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 и задайте переменные окружения:

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

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

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

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

cd apps/ui
npm ci
npm run build

Проверки

Rust:

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

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

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/deployment.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.

Лицензия

MIT