Recovery delivery of the accumulated, TL-accepted Epic 3 work that had never been
committed to Git (stories 3.6-3.17, see the crank board). Story 3.18 is not accepted
yet and is deliberately excluded: its logging surface, its capability registration,
its oracle projections and its tests are not part of this tree.
Accepted scope
- 3.6 typed static Resource Drafts; 3.7 publication and exact binding of static
Resource Versions; 3.8 MCP discovery/read and revocation of static Resources;
- 3.9 Resource import/export in API and UI plus TLS dependency maintenance;
3.10 REST-backed Resource templates; 3.11 shared REST read runtime and the MCP
revision/capability foundation;
- 3.12 parameterised Prompt Drafts with preview; 3.13 Prompt publication and exact
version binding to Agents; 3.14 MCP prompts; 3.15 Prompt import/export;
- 3.16 composite Prompts with published Resources (dependency content scan plus
dynamic read through the accepted 3.11 runtime, admin preview and MCP prompts/get);
- 3.17 bounded MCP completion suggestions from typed published schemas and the
resources/list admission fix for bound template publications.
Accepted evidence being reused (unchanged code paths)
- 3.16 candidate: core 7, admin-api 22, registry 4, mcp-server 4, UI 6; one final
`just verify` run 1651 passed / 0 failed / 2 ignored.
- 3.17 candidate: full run 1672 passed / 0 failed / 2 ignored, QA targeted reruns and
a real MCP Inspector 2.12.0 client smoke.
Delivery engineering in this commit
- CI: one event per change (feature branches are gated by their pull request, push
runs only on main), story events run the changed packages, the full workspace suite
stays the feature/release gate; no cache/sharding without a measured runner check.
- Release: the packaged archives, checksums and SBOM are now uploaded to the Gitea
release entry of the tag instead of dying with the runner workspace.
Not included on purpose: Story 3.18 work, build caches, runtime databases, local
credentials and scratch evidence.
Refs: crank kanban t_e39d7263; baseline 1b6db09bd1.
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.
Создайте рабочую папку:
mkdir -p crank
cd crank
Скачайте compose-файл и пример настроек:
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.
Секреты можно сгенерировать так:
openssl rand -hex 32
Запустите Crank:
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:
CRANK_PUBLISH_BIND=0.0.0.0
Проверить состояние контейнеров:
docker compose ps
Посмотреть журналы:
docker compose logs -f admin-api mcp-server ui
Остановить сервис:
docker compose down
Обновить Crank до свежих образов:
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:
docker compose up -d
Если используется PgBouncer, укажите его адрес в POSTGRES_HOST и порт в POSTGRES_PORT.
Запуск из исходников
Если нужно собрать образы самостоятельно, клонируйте репозиторий и используйте корневой docker-compose.yml:
git clone https://github.com/bsodfather/crank-community.git crank
cd crank
cp .env.example .env
docker compose up -d --build
Этот вариант удобен для локальной проверки изменений перед отправкой патча.
Как пользоваться
Обычный сценарий:
- Зайти в веб-интерфейс.
- Создать REST-инструмент.
- Описать входные параметры и правила вызова REST API.
- Выполнить пробный запрос.
- Опубликовать инструмент.
- Привязать инструмент к агенту.
- Создать ключ агента.
- Подключить MCP-клиент к адресу агента.
Каждый агент имеет свой каталог инструментов. MCP-клиент видит только те REST-инструменты, которые явно привязаны к этому агенту.
Рекомендации по названиям, описаниям, схемам, ошибкам и опасным операциям описаны в документе Проектирование MCP-инструментов.
Что входит в эту версию
Этот репозиторий содержит открытую версию Crank:
- REST API как источник инструментов;
- MCP через Streamable HTTP;
- веб-интерфейс администратора;
- простая авторизация администратора;
- ключи агентов для доступа к MCP;
- PostgreSQL как основное хранилище;
- необязательный Valkey или Redis для служебного кэша.
Текущие и целевые возможности фиксируются в
docs/capability-inventory.json. Статус
implemented означает реализованный flow; planned, gap и blocked не
считаются готовностью. MCP Resources, Prompts, фоновые Tasks и встроенные Load
Runs сейчас перечислены только как planned target и не выдаются за работающие
возможности этой версии.
Проверенный snapshot текущих UI, Admin API и MCP flows находится в
docs/capability-baseline/manifest.json.
Он связывает inventory, обязательные surfaces, taxonomy, manual checklist и
sanitized results точными SHA-256. Полный baseline pass требует сочетания
implemented + automated + pass; skipped, flaky, not-run и manual-only не
становятся pass.
Структура проекта
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; - Node.js и npm;
- PostgreSQL, если запускаете сервисы вручную;
- Docker для полного стенда и Rust-тестов с временной PostgreSQL.
Быстрее всего поднять окружение так же, как для обычного запуска:
git clone https://github.com/bsodfather/crank-community.git crank
cd crank
cp .env.example .env
docker compose up -d postgres
Приложения читают настройки из переменных окружения. Можно использовать .env через свое окружение разработки, direnv, IDE или любой другой привычный способ загрузки переменных.
Rust-тесты сами поднимают временный PostgreSQL через Testcontainers. Отдельно запускать тестовую БД или задавать URL тестовой базы не нужно.
Сервер панели управления:
cargo run -p admin-api
MCP-сервер:
cargo run -p mcp-server
Веб-интерфейс:
cd apps/ui
npm ci
npm run dev
Проверки:
just fmt-check
just clippy
just test
Сборка веб-интерфейса:
cd apps/ui
npm ci
npm run build
E2E-проверки:
cd apps/ui
npx playwright test
Документация
- Документация
- Введение
- Установка
- Первый инструмент
- Веб-интерфейс
- MCP-интерфейс
- Admin API
- Практические API-примеры
- Production checklist
- Troubleshooting
- Настройки запуска
- Machine schema runtime-конфигурации
- Английский README
- Capability Inventory
- Capability Baseline
Участие в разработке
Перед отправкой pull request нужно согласиться с Contributor License Agreement.
Правила участия описаны в CONTRIBUTING.md.
Лицензия
GNU Affero General Public License v3.0 only
