crank/README.md

Crank

Crank Community — self-hosted платформа для публикации REST API как MCP tools.

Проект решает практическую задачу: описать внешний REST endpoint, проверить его, опубликовать и отдать LLM-клиентам через MCP без написания отдельного MCP server для каждой интеграции.

Возможности

• Создание REST operations через UI или YAML.
• Маппинг MCP input в query/body/header параметры REST-запроса.
• Маппинг REST response в структурированный output MCP tool.
• Публикация выбранных operations в agent-scoped MCP endpoints.
• Черновики, версии, samples, mappings, logs и usage в PostgreSQL.
• Простая авторизация через bootstrap admin user и browser session.
• PostgreSQL-backed secrets и auth profiles для upstream REST API.
• Docker Compose deployment.

Scope Community

Этот репозиторий содержит только Community-возможности:

• только REST protocol;
• один самостоятельный self-hosted deployment;
• простая admin-аутентификация;
• статические agent API keys для MCP-доступа;
• PostgreSQL как системная БД;
• optional Valkey/Redis для runtime coordination;
• Gitea Actions workflow для CI/CD.

Репозиторий фокусируется только на перечисленном scope.

Архитектура

Основные сущности:

• Workspace — граница данных для operations, agents, secrets и logs.
• Operation — версионируемый REST integration contract.
• Agent — MCP surface, который публикует ограниченный набор operations.

Рабочий flow:

1. Оператор создает или импортирует REST operation.
2. Crank валидирует schema и mapping.
3. Оператор выполняет test call к upstream REST API.
4. Operation публикуется.
5. Agent открывает published operation как MCP tool.
6. MCP client вызывает tool через mcp-server.

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

apps/
  admin-api/      HTTP API для UI, auth, operations, agents, logs и settings
  mcp-server/     Agent-scoped MCP Streamable HTTP server
  ui/             Static web UI

crates/
  crank-core/             Общая domain model
  crank-registry/         PostgreSQL persistence
  crank-runtime/          REST execution, mapping, cache, limits
  crank-adapter-rest/     REST adapter
  crank-community-auth/   Password hashing и sessions
  crank-community-mcp/    MCP application layer
  crank-mapping/          JSONPath mapping
  crank-schema/           Schema normalization и validation

deploy/community/
  docker-compose.yml      Production-like Community deployment
  .env.example            Runtime env template

Требования

• Rust toolchain из rust-toolchain.toml
• Node.js и npm для UI
• PostgreSQL
• Docker и Docker Compose для deployment

Локальная разработка

Запустите 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

Запустите backend:

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

Соберите UI:

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

UI:

cd apps/ui
npm ci
npm run build
npx playwright test

Playwright поднимает локальный test stack с PostgreSQL, admin-api, mcp-server и UI test server.

Deployment

Community manifest находится в deploy/community/docker-compose.yml.

Production-like deployment ожидает:

• внешний PostgreSQL;
• container images для admin-api, mcp-server и ui;
• runtime secrets через environment variables;
• reverse proxy перед портами 3000, 3001, 3002.

Gitea workflow .gitea/workflows/deploy.yml собирает images, читает runtime configuration из OpenBao, пишет .env на deployment host и запускает Docker Compose.

Ключевые runtime variables:

• 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

Полная operational-документация:

• docs/runtime-config.md
• docs/deployment.md
• docs/mcp-interface.md

MCP

Crank публикует agent-scoped MCP endpoints через Streamable HTTP. Каждый agent имеет собственный published tool catalog, поэтому MCP client видит только REST tools, явно привязанные к этому agent.

Типовой сценарий:

1. Создать REST operation.
2. Протестировать operation.
3. Опубликовать operation.
4. Привязать operation к agent.
5. Создать agent API key.
6. Подключить MCP client к agent endpoint.

Английская документация

English README: docs/en/README.md.

Лицензия

MIT