chore: publish clean community baseline

README.md

@@ -0,0 +1,191 @@
+# 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