# 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`.

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

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

```bash
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:

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

Соберите UI:

```bash
cd apps/ui
npm ci
npm run build
```

## Проверки

Rust:

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

UI:

```bash
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/runtime-config.md)
- [docs/deployment.md](docs/deployment.md)
- [docs/mcp-interface.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](docs/en/README.md).

## Лицензия

MIT