github-ops
192 lines
6.1 KiB
Markdown
192 lines
6.1 KiB
Markdown
# 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
|