bsodfather a965bc4137
CI / UI Checks (pull_request) Successful in 9s
CI / Rust Checks (pull_request) Failing after 4m10s
CI / Rust Feature Validation (pull_request) Skipped
CI / Frontend E2E (pull_request) Skipped
CI / Community Image Smoke (pull_request) Skipped
CI / Required Checks (pull_request) Failing after 1s
CI / Deploy (pull_request) Skipped
feat(epic3): уведомления об изменении Resource/Prompt каталога MCP (Story 3.19)
Story 3.19 / FR-19 на принятой базе Story 3.18 (`47a6e54`, PR #99): после
commit опубликованного каталога Agent клиент получает
`notifications/resources/list_changed` и/или
`notifications/prompts/list_changed`, обе pinned revisions, а обычное чтение
каталога остаётся авторитетным при потере сигнала. Scope ограничен
list-change: `resources/subscribe`/`unsubscribe` остаются `-32601`, значение
`resources.subscribe` остаётся `false` (одобренный владельцем вариант A).

Публикация переносит только semantic delta Story 3.19 из
`/home/codex/code/crank-worktrees/story31-worktree`
(`1b6db09` + cumulative overlay) на принятый head 3.18, а не копирует
worktree:
- новый `protocol/signals.rs` (watcher, отпечаток каталога, bounded filter,
  revision-correct encoders, bounded legacy stream registry) и
  `protocol/signals_tests.rs` (17 unit oracles);
- `subscriptions/listen` (modern-only dispatch registration) + честные
  `listChanged: true` объявления; `app/endpoint.rs` получает legacy GET
  producer/DELETE retire, `app/dispatch.rs` — modern listen stream;
- ATDD `mcp_signals` 5 сценариев на реальном endpoint/PostgreSQL/artifact
  store; capability inventory и frozen/provenance проекции обновлены
  (`b90b59f3…`, inventory `10ca3538…`);
- `scripts/ci-story-checks.sh`: добавлены 3.19-проверки, записи Story 3.18
  сохранены (гейт не ослаблен).

Принятая правка code-health `206ca78` сохранена: `app/endpoint.rs` 402 строки
(было 381), `app/legacy_dispatch.rs` 731 без изменений, т.е. split не
переписан. Новый ATDD-файл `mcp_signals.rs` до 1138 строк превышал лимит
`scripts/check-rust-code-health.sh`, поэтому его сценарии механически
вынесены в `mcp_signals/scenarios.rs` без изменения проверок.

Наследованный дефект tooling-гейта: `tests/unit/test_validate_capability_inventory.py`
требует, чтобы `Run tooling unit tests` шёл раньше
`scripts/validate-capability-inventory.py`; в принятом `ci.yml` (3.18) шаг
оказался в условном feature-job. Шаг перенесён в обязательный `rust` job перед
проверкой inventory — исполняемый tooling-гейт теперь проверяется там же, где
применяется; ни одна проверка не отключена и не ослаблена.

Проверки на этом коммите: `ci-story-checks.sh` exit 0 — 4/9/1/12/10/3/5(+1
manual ignored)/17 passed; `crank-community-mcp --lib` 102/0; transport 20/0,
mcp_prompts 15/0, revision_matrix::negotiation 23/0, era_isolation 5/0;
`cargo fmt --check` и `cargo clippy -p crank-community-mcp -p mcp-server
--all-targets -D warnings` — 0; `check-rust-code-health.sh` — pass;
capability inventory `status=valid protocol_items=50 revisions=2`;
`python3 -m unittest discover -s tests/unit` — 305 OK.

NOT_RUN (честно, не PASS): полный `just verify`, межкомпонентная интеграция,
нагрузка и квалификация ≥3 реальных клиентов — остаются на собранной фиче 3.20
по validation-policy.md.
2026-10-25 21:00:51 +00:00

Crank

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

Этот вариант удобен для локальной проверки изменений перед отправкой патча.

Как пользоваться

Обычный сценарий:

  1. Зайти в веб-интерфейс.
  2. Создать REST-инструмент.
  3. Описать входные параметры и правила вызова REST API.
  4. Выполнить пробный запрос.
  5. Опубликовать инструмент.
  6. Привязать инструмент к агенту.
  7. Создать ключ агента.
  8. Подключить 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

Документация

Участие в разработке

Перед отправкой pull request нужно согласиться с Contributor License Agreement.

Правила участия описаны в CONTRIBUTING.md.

Лицензия

GNU Affero General Public License v3.0 only

S
Description
No description provided
Readme AGPL-3.0
7.1 MiB
0 Stars 1 Watchers 0 Forks
Languages
Rust 77.7%
JavaScript 12.5%
Python 5.6%
HTML 2%
CSS 1.3%
Other 0.8%