feat: harden demo flows and observability

2026-03-25 21:31:54 +03:00
parent 1a6d7c5ddc
commit 2d3abb9f3d
7 changed files with 320 additions and 13 deletions
@@ -0,0 +1,105 @@
+# Demo Runbook
+
+## 1. Цель документа
+
+Этот документ фиксирует минимальный воспроизводимый сценарий запуска и демонстрации MCPaaS без знания внутренней структуры кода.
+
+## 2. Предусловия
+
+- доступен `PostgreSQL`;
+- задан `MCPAAS_DATABASE_URL`;
+- задан `MCPAAS_STORAGE_ROOT`;
+- доступны `MCPAAS_ADMIN_BIND` и `MCPAAS_MCP_BIND`;
+- для UI установлен `Node.js`;
+- для Rust-части установлен toolchain из `rust-toolchain.toml`.
+
+## 3. Быстрый локальный запуск
+
+### Backend
+
+```bash
+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 возвращаются в читаемом виде;
+- логи позволяют понять, какая операция создавалась, тестировалась, публиковалась или импортировалась.