chore: publish clean community baseline
This commit is contained in:
github-ops
@@ -0,0 +1,269 @@
|
||||
# Crank
|
||||
|
||||
|
||||
|
||||
Crank - это свободная платформа для создания MCP-инструментов из REST API эндпоинтов.
|
||||
|
||||
Сервис ставится на собственный сервер, подключается к PostgreSQL и дает веб-интерфейс, в котором можно описать REST API, проверить вызов, опубликовать его как инструмент и подключить к MCP-клиенту.
|
||||
|
||||
## Что умеет Crank
|
||||
|
||||
- Создавать REST-инструменты через веб-интерфейс или YAML.
|
||||
- Принимать параметры от MCP-клиента и подставлять их в путь, query string, заголовки или тело REST-запроса.
|
||||
- Преобразовывать ответ REST API в структурированный результат для MCP-клиента.
|
||||
- Публиковать только выбранные инструменты для конкретного агента.
|
||||
- Хранить версии, черновики, примеры запросов и ответов, секреты, журналы вызовов и статистику в PostgreSQL.
|
||||
- Работать с простой авторизацией администратора: email, пароль и браузерная сессия.
|
||||
- Запускаться через Docker Compose.
|
||||
|
||||
## Быстрый запуск через Docker
|
||||
|
||||
Требования:
|
||||
|
||||
- Docker;
|
||||
- Docker Compose;
|
||||
- свободные порты `3000`, `3001`, `3002`;
|
||||
- доступ к опубликованным Docker-образам Crank.
|
||||
|
||||
Создайте рабочую папку:
|
||||
|
||||
```bash
|
||||
mkdir -p crank
|
||||
cd crank
|
||||
```
|
||||
|
||||
Скачайте compose-файл и пример настроек:
|
||||
|
||||
```bash
|
||||
curl -fsSLo docker-compose.yml https://git.itexp.me/bsodfather/crank/raw/branch/main/deploy/community/docker-compose.images.yml
|
||||
curl -fsSLo .env.example https://git.itexp.me/bsodfather/crank/raw/branch/main/deploy/community/.env.images.example
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
Откройте скачанный `.env.example` и перенесите нужные значения в `.env`.
|
||||
|
||||
Минимально нужно заменить:
|
||||
|
||||
- `POSTGRES_PASSWORD`;
|
||||
- `CRANK_MASTER_KEY`;
|
||||
- `CRANK_SESSION_SECRET`;
|
||||
- `CRANK_PASSWORD_PEPPER`;
|
||||
- `CRANK_BOOTSTRAP_ADMIN_EMAIL`;
|
||||
- `CRANK_BOOTSTRAP_ADMIN_PASSWORD`;
|
||||
- `CRANK_BASE_URL`.
|
||||
|
||||
Секреты можно сгенерировать так:
|
||||
|
||||
```bash
|
||||
openssl rand -hex 32
|
||||
```
|
||||
|
||||
Запустите Crank:
|
||||
|
||||
```bash
|
||||
docker compose --profile local-db up -d
|
||||
```
|
||||
|
||||
Если registry требует авторизацию, сначала выполните `docker login git.itexp.me`.
|
||||
|
||||
После запуска:
|
||||
|
||||
- веб-интерфейс: `http://localhost:3000`;
|
||||
- HTTP API панели управления: `http://localhost:3001`;
|
||||
- MCP-сервер: `http://localhost:3002`.
|
||||
|
||||
По умолчанию порты публикуются только на `127.0.0.1`. Это удобно, если перед Crank стоит nginx, Caddy или другой обратный прокси. Если нужно открыть порты наружу напрямую, укажите в `.env`:
|
||||
|
||||
```env
|
||||
CRANK_PUBLISH_BIND=0.0.0.0
|
||||
```
|
||||
|
||||
Проверить состояние контейнеров:
|
||||
|
||||
```bash
|
||||
docker compose ps
|
||||
```
|
||||
|
||||
Посмотреть журналы:
|
||||
|
||||
```bash
|
||||
docker compose logs -f admin-api mcp-server ui
|
||||
```
|
||||
|
||||
Остановить сервис:
|
||||
|
||||
```bash
|
||||
docker compose down
|
||||
```
|
||||
|
||||
Обновить Crank до свежих образов:
|
||||
|
||||
```bash
|
||||
docker compose --profile local-db pull
|
||||
docker compose --profile local-db up -d
|
||||
```
|
||||
|
||||
## Запуск с внешним PostgreSQL
|
||||
|
||||
Если PostgreSQL уже запущен отдельно, профиль `local-db` не нужен.
|
||||
|
||||
В `.env` укажите параметры вашей базы:
|
||||
|
||||
- `POSTGRES_HOST`;
|
||||
- `POSTGRES_PORT`;
|
||||
- `POSTGRES_DB`;
|
||||
- `POSTGRES_USER`;
|
||||
- `POSTGRES_PASSWORD`.
|
||||
|
||||
Затем запустите только приложения Crank:
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
Если используется PgBouncer, укажите его адрес в `POSTGRES_HOST` и порт в `POSTGRES_PORT`.
|
||||
|
||||
## Запуск из исходников
|
||||
|
||||
Если нужно собрать образы самостоятельно, клонируйте репозиторий и используйте корневой [`docker-compose.yml`](./docker-compose.yml):
|
||||
|
||||
```bash
|
||||
git clone https://github.com/bsodfather/crank-community.git crank
|
||||
cd crank
|
||||
cp .env.example .env
|
||||
docker compose up -d --build
|
||||
```
|
||||
|
||||
Этот вариант удобен для локальной проверки изменений перед отправкой патча.
|
||||
|
||||
## Как пользоваться
|
||||
|
||||
Обычный сценарий:
|
||||
|
||||
1. Зайти в веб-интерфейс.
|
||||
2. Создать REST-инструмент.
|
||||
3. Описать входные параметры и правила вызова REST API.
|
||||
4. Выполнить пробный запрос.
|
||||
5. Опубликовать инструмент.
|
||||
6. Привязать инструмент к агенту.
|
||||
7. Создать ключ агента.
|
||||
8. Подключить MCP-клиент к адресу агента.
|
||||
|
||||
Каждый агент имеет свой каталог инструментов. MCP-клиент видит только те REST-инструменты, которые явно привязаны к этому агенту.
|
||||
|
||||
## Что входит в эту версию
|
||||
|
||||
Этот репозиторий содержит открытую версию Crank:
|
||||
|
||||
- REST API как источник инструментов;
|
||||
- MCP через Streamable HTTP;
|
||||
- веб-интерфейс администратора;
|
||||
- простая авторизация администратора;
|
||||
- ключи агентов для доступа к MCP;
|
||||
- PostgreSQL как основное хранилище;
|
||||
- необязательный Valkey или Redis для служебного кэша.
|
||||
|
||||
## Структура проекта
|
||||
|
||||
```text
|
||||
apps/
|
||||
admin-api/ HTTP API для веб-интерфейса
|
||||
mcp-server/ MCP-сервер
|
||||
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 запуск с внешним PostgreSQL
|
||||
docker-compose.images.yml запуск готовых образов без исходников
|
||||
.env.example пример настроек для серверного запуска из исходников
|
||||
.env.images.example пример настроек для запуска готовых образов
|
||||
```
|
||||
|
||||
## Разработка
|
||||
|
||||
Для разработки нужны:
|
||||
|
||||
- Rust toolchain из [`rust-toolchain.toml`](./rust-toolchain.toml);
|
||||
- Node.js и npm;
|
||||
- PostgreSQL;
|
||||
- Docker, если хотите запускать полный стенд контейнерами.
|
||||
|
||||
Быстрее всего поднять окружение так же, как для обычного запуска:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/bsodfather/crank-community.git crank
|
||||
cd crank
|
||||
cp .env.example .env
|
||||
docker compose up -d postgres
|
||||
```
|
||||
|
||||
Приложения читают настройки из переменных окружения. Можно использовать `.env` через свое окружение разработки, `direnv`, IDE или любой другой привычный способ загрузки переменных.
|
||||
|
||||
Сервер панели управления:
|
||||
|
||||
```bash
|
||||
cargo run -p admin-api
|
||||
```
|
||||
|
||||
MCP-сервер:
|
||||
|
||||
```bash
|
||||
cargo run -p mcp-server
|
||||
```
|
||||
|
||||
Веб-интерфейс:
|
||||
|
||||
```bash
|
||||
cd apps/ui
|
||||
npm ci
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Проверки:
|
||||
|
||||
```bash
|
||||
just fmt-check
|
||||
just clippy
|
||||
just test
|
||||
```
|
||||
|
||||
Сборка веб-интерфейса:
|
||||
|
||||
```bash
|
||||
cd apps/ui
|
||||
npm ci
|
||||
npm run build
|
||||
```
|
||||
|
||||
E2E-проверки:
|
||||
|
||||
```bash
|
||||
cd apps/ui
|
||||
npx playwright test
|
||||
```
|
||||
|
||||
## Документация
|
||||
|
||||
- [Настройки запуска](docs/runtime-config.md)
|
||||
- [Развертывание](docs/deployment.md)
|
||||
- [MCP-интерфейс](docs/mcp-interface.md)
|
||||
- [Английский README](docs/en/README.md)
|
||||
|
||||
## Участие в разработке
|
||||
|
||||
Перед отправкой pull request нужно согласиться с [Contributor License Agreement](CLA.md).
|
||||
|
||||
Правила участия описаны в [CONTRIBUTING.md](CONTRIBUTING.md).
|
||||
|
||||
## Лицензия
|
||||
|
||||
GNU Affero General Public License v3.0 only
|
||||
Reference in New Issue
Block a user