hermes_dev 3b5fcc51cc
CI / UI Checks (pull_request) Successful in 9s
CI / Rust Checks (pull_request) Successful in 20m41s
CI / Rust Feature Validation (pull_request) Skipped
CI / Frontend E2E (pull_request) Skipped
CI / Community Image Smoke (pull_request) Skipped
CI / Required Checks (pull_request) Successful in 1s
CI / Deploy (pull_request) Skipped
fix(ui): pin npm build stage to TLS 1.2 on the CI host uplink
The CI host uplink (192.168.1.108) drops TLS 1.3 ClientHello carrying the
hybrid X25519MLKEM768 key share, so registry.npmjs.org is unreachable from
the seeded node:22-alpine build stage while the same host answers over TLS
1.2. RUN npm ci hung until the build was cancelled.

Cap only the UI build stage at TLS 1.2 via NODE_OPTIONS=--tls-max-v1.2.
Certificates, SRI and the lockfile are untouched; no mirror, fallback or
cache-substituted packages. Remove the line once TLS 1.3 works from the CI
host again.
2026-10-30 09:56:19 +00:00

Crank

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 для служебного кэша.

Текущие и целевые возможности фиксируются в docs/capability-inventory.json. Статус implemented означает реализованный flow; planned, gap и blocked не считаются готовностью. MCP Resources, Prompts, фоновые Tasks и встроенные Load Runs сейчас перечислены только как planned target и не выдаются за работающие возможности этой версии.

Проверенный snapshot текущих UI, Admin API и MCP flows находится в docs/capability-baseline/manifest.json. Он связывает inventory, обязательные surfaces, taxonomy, manual checklist и sanitized results точными SHA-256. Полный baseline pass требует сочетания implemented + automated + pass; skipped, flaky, not-run и manual-only не становятся pass.

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

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 для полного стенда и Rust-тестов с временной PostgreSQL.

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

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

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

Rust-тесты сами поднимают временный PostgreSQL через Testcontainers. Отдельно запускать тестовую БД или задавать URL тестовой базы не нужно.

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

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

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

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

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

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

Лицензия

GNU Affero General Public License v3.0 only

S
Description
No description provided
Readme AGPL-3.0
7.1 MiB
0 Stars 1 Watchers 0 Forks
Languages
Rust 77.7%
JavaScript 12.5%
Python 5.6%
HTML 2%
CSS 1.3%
Other 0.8%