chore: publish clean community baseline
This commit is contained in:
github-ops
@@ -0,0 +1,185 @@
|
||||
# Crank
|
||||
|
||||
|
||||
|
||||
Crank Community — самостоятельная версия Crank для публикации REST API как MCP-инструментов.
|
||||
|
||||
Проект помогает подключать существующие HTTP API к LLM-клиентам без написания отдельного MCP-сервера для каждой интеграции. В Crank можно описать REST-операцию, проверить ее, опубликовать и открыть через MCP.
|
||||
|
||||
## Возможности
|
||||
|
||||
- Создание REST-операций через веб-интерфейс или YAML.
|
||||
- Преобразование входных параметров MCP-инструмента в параметры REST-запроса: путь, query string, заголовки и тело запроса.
|
||||
- Преобразование ответа REST API в структурированный результат MCP-инструмента.
|
||||
- Публикация выбранных операций в MCP-точках доступа конкретных агентов.
|
||||
- Отдельный каталог инструментов для каждого агента.
|
||||
- Хранение черновиков, версий, примеров запросов и ответов, правил преобразования, журналов и статистики в PostgreSQL.
|
||||
- Простая авторизация администратора через email, пароль и сессию браузера.
|
||||
- Хранение секретов и профилей авторизации для внешних REST API.
|
||||
- Развертывание через Docker Compose.
|
||||
|
||||
## Границы Community-версии
|
||||
|
||||
Этот репозиторий содержит только Community-возможности:
|
||||
|
||||
- только REST;
|
||||
- одно самостоятельное развертывание;
|
||||
- простая авторизация администратора;
|
||||
- статические ключи агентов для MCP-доступа;
|
||||
- PostgreSQL как основная база данных;
|
||||
- необязательный Valkey или Redis для служебного кэша;
|
||||
- CI/CD через Gitea Actions.
|
||||
|
||||
## Архитектура
|
||||
|
||||
Основные сущности:
|
||||
|
||||
- `Workspace` — граница данных для операций, агентов, секретов и журналов.
|
||||
- `Operation` — версионируемое описание REST-интеграции.
|
||||
- `Agent` — MCP-точка доступа с ограниченным набором опубликованных операций.
|
||||
|
||||
Рабочий сценарий:
|
||||
|
||||
1. Оператор создает или импортирует REST-операцию.
|
||||
2. Crank проверяет схему входа, схему выхода и правила преобразования данных.
|
||||
3. Оператор выполняет пробный вызов внешнего REST API.
|
||||
4. Операция публикуется.
|
||||
5. Операция привязывается к агенту.
|
||||
6. MCP-клиент вызывает инструмент через `mcp-server`.
|
||||
|
||||
## Структура репозитория
|
||||
|
||||
```text
|
||||
apps/
|
||||
admin-api/ HTTP API для интерфейса, авторизации, операций, агентов, журналов и настроек
|
||||
mcp-server/ MCP-сервер поверх Streamable HTTP
|
||||
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 манифест развертывания Community-версии
|
||||
.env.example пример переменных окружения
|
||||
```
|
||||
|
||||
## Требования
|
||||
|
||||
- Rust toolchain из `rust-toolchain.toml`
|
||||
- Node.js и npm для веб-интерфейса
|
||||
- PostgreSQL
|
||||
- Docker и Docker Compose для развертывания
|
||||
|
||||
## Локальная разработка
|
||||
|
||||
Запустите 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
|
||||
```
|
||||
|
||||
Запустите серверные приложения:
|
||||
|
||||
```bash
|
||||
cargo run -p admin-api
|
||||
cargo run -p mcp-server
|
||||
```
|
||||
|
||||
Соберите веб-интерфейс:
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
Веб-интерфейс:
|
||||
|
||||
```bash
|
||||
cd apps/ui
|
||||
npm ci
|
||||
npm run build
|
||||
npx playwright test
|
||||
```
|
||||
|
||||
Playwright поднимает локальный проверочный стенд с PostgreSQL, `admin-api`, `mcp-server` и сервером веб-интерфейса.
|
||||
|
||||
## Развертывание
|
||||
|
||||
Манифест Community-версии находится в `deploy/community/docker-compose.yml`.
|
||||
|
||||
Для рабочего развертывания нужны:
|
||||
|
||||
- внешний PostgreSQL;
|
||||
- контейнерные образы для `admin-api`, `mcp-server` и `ui`;
|
||||
- секреты и настройки через переменные окружения;
|
||||
- обратный прокси перед портами `3000`, `3001`, `3002`.
|
||||
|
||||
Процесс развертывания в `.gitea/workflows/deploy.yml` собирает образы, читает настройки из OpenBao, записывает `.env` на сервер развертывания и запускает Docker Compose.
|
||||
|
||||
Ключевые переменные окружения:
|
||||
|
||||
- `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`
|
||||
|
||||
Дополнительная документация:
|
||||
|
||||
- [docs/runtime-config.md](docs/runtime-config.md)
|
||||
- [docs/deployment.md](docs/deployment.md)
|
||||
- [docs/mcp-interface.md](docs/mcp-interface.md)
|
||||
|
||||
## MCP
|
||||
|
||||
Crank публикует MCP-точки доступа для отдельных агентов через Streamable HTTP. Каждый агент имеет собственный каталог инструментов, поэтому MCP-клиент видит только REST-инструменты, явно привязанные к этому агенту.
|
||||
|
||||
Типовой сценарий:
|
||||
|
||||
1. Создать REST-операцию.
|
||||
2. Проверить REST-операцию пробным вызовом.
|
||||
3. Опубликовать REST-операцию.
|
||||
4. Привязать операцию к агенту.
|
||||
5. Создать ключ агента.
|
||||
6. Подключить MCP-клиент к точке доступа агента.
|
||||
|
||||
## Английская документация
|
||||
|
||||
Английский вариант README находится в [docs/en/README.md](docs/en/README.md).
|
||||
|
||||
## Лицензия
|
||||
|
||||
MIT
|
||||
Reference in New Issue
Block a user