# Demo Runbook

## 1. Цель документа

Этот документ фиксирует минимальный воспроизводимый сценарий запуска и демонстрации Crank без знания внутренней структуры кода.

## 2. Предусловия

- доступен `PostgreSQL`;
- заданы `POSTGRES_HOST`, `POSTGRES_PORT`, `POSTGRES_DB`, `POSTGRES_USER`, `POSTGRES_PASSWORD`;
- задан `CRANK_STORAGE_ROOT`;
- доступны `CRANK_ADMIN_BIND` и `CRANK_MCP_BIND`;
- если нужен заполненный demo state без ручного онбординга, задан `CRANK_DEMO_SEED=true`;
- для UI установлен `Node.js`;
- для Rust-части установлен toolchain из `rust-toolchain.toml`.

## 3. Быстрый локальный запуск

### Backend

```bash
cargo run -p admin-api
```

Для предзаполненного demo state:

```bash
CRANK_DEMO_SEED=true cargo run -p admin-api
```

Во втором терминале:

```bash
cargo run -p mcp-server
```

### UI

```bash
cd apps/ui
npm install
npm run dev
```

## 4. Контрольные health endpoints

```bash
curl http://127.0.0.1:3001/health
curl http://127.0.0.1:3002/health
```

Ожидаемо:

- `admin-api` возвращает `{"service":"admin-api","status":"ok"}`
- `mcp-server` возвращает `{"service":"mcp-server","status":"ok"}`

## 5. Demo flow

### REST

1. Создать REST operation через UI или `admin-api`.
2. Выполнить `test-run`.
3. Опубликовать operation.
4. Проверить появление tool в MCP через `tools/list`.
5. Выполнить `tools/call`.

### GraphQL

1. Создать GraphQL operation с фиксированным `query` или `mutation`.
2. Выполнить `test-run`.
3. Экспортировать YAML.
4. Импортировать YAML в режиме `upsert`.
5. Опубликовать operation и вызвать ее через MCP.

### gRPC

1. Создать gRPC operation.
2. Загрузить `descriptor set`.
3. Проверить `grpc/services` discovery summary.
4. Выполнить `test-run`.
5. Экспортировать YAML.
6. Импортировать YAML в режиме `upsert`.
7. Опубликовать operation и вызвать ее через MCP.

## 6. Проверка publish/reload flow

После публикации новой операции `mcp-server` не требует restart.

Проверка:

1. Открыть MCP session.
2. Вызвать `tools/list`.
3. Опубликовать новую operation через `admin-api`.
4. Повторно вызвать `tools/list`.
5. Убедиться, что новый tool появился после refresh interval.

## 7. Проверка YAML roundtrip

YAML roundtrip считается успешным, если:

1. operation экспортируется через `/api/admin/operations/{operation_id}/export`;
2. экспортированный YAML импортируется через `/api/admin/operations/import?mode=upsert`;
3. создается новая версия operation;
4. `test-run` новой версии проходит успешно.

## 8. Что считать готовым demo state

- все три протокола проходят сценарий `create -> test-run -> publish -> MCP call`;
- YAML export/import проходит хотя бы для `REST`, `GraphQL` и `gRPC`;
- `mcp-server` подхватывает published changes без restart;
- ошибки `admin-api` и runtime возвращаются в читаемом виде;
- логи позволяют понять, какая операция создавалась, тестировалась, публиковалась или импортировалась.

## 9. Post-deploy smoke

Если demo запускается не локально, а на staging/production-like стенде, после deploy нужно пройти отдельный checklist:

- [deploy-and-staging-smoke.md](/home/a.tolmachev/code/rust/mcpaas/docs/deploy-and-staging-smoke.md)