docs: add public smoke configs for mcp checks

2026-04-05 22:40:52 +03:00
parent 0bd47d9944
commit 627023ffcc
10 changed files with 566 additions and 6 deletions
@@ -0,0 +1,169 @@
+# Public Smoke Targets
+
+Этот документ фиксирует три публичных upstream-сервиса, которые можно использовать для ручной проверки `REST`, `GraphQL` и `gRPC` operation в Crank без поднятия своих тестовых backend-ов.
+
+Все примеры ниже уже сверены с реальными публичными endpoint-ами и дублируются готовыми payload-файлами в [examples/mcp-smoke](/home/a.tolmachev/code/rust/mcpaas/examples/mcp-smoke).
+
+## 1. Источники
+
+- REST: Open-Meteo Weather Forecast API  
+  `https://open-meteo.com/en/docs`
+- GraphQL: Countries GraphQL API  
+  `https://github.com/trevorblades/countries/blob/main/README.md`  
+  Playground / endpoint: `https://countries.trevorblades.com/`
+- gRPC: grpcb.in  
+  `https://grpcb.in/`  
+  Public proto: `https://raw.githubusercontent.com/moul/pb/master/addsvc/addsvc.proto`
+
+## 2. Готовые operation payload-ы
+
+- REST: [rest-open-meteo.operation.json](/home/a.tolmachev/code/rust/mcpaas/examples/mcp-smoke/rest-open-meteo.operation.json)
+- REST test input: [rest-open-meteo.test-input.json](/home/a.tolmachev/code/rust/mcpaas/examples/mcp-smoke/rest-open-meteo.test-input.json)
+- GraphQL: [graphql-countries.operation.json](/home/a.tolmachev/code/rust/mcpaas/examples/mcp-smoke/graphql-countries.operation.json)
+- GraphQL test input: [graphql-countries.test-input.json](/home/a.tolmachev/code/rust/mcpaas/examples/mcp-smoke/graphql-countries.test-input.json)
+- gRPC: [grpc-grpcb-add.operation.json](/home/a.tolmachev/code/rust/mcpaas/examples/mcp-smoke/grpc-grpcb-add.operation.json)
+- gRPC test input: [grpc-grpcb-add.test-input.json](/home/a.tolmachev/code/rust/mcpaas/examples/mcp-smoke/grpc-grpcb-add.test-input.json)
+- gRPC proto reference: [grpc-grpcb-addsvc.proto](/home/a.tolmachev/code/rust/mcpaas/examples/mcp-smoke/grpc-grpcb-addsvc.proto)
+
+## 3. Как использовать
+
+### 3.1. Через UI
+
+1. Создай operation вручную в `Wizard`.
+2. Подставь значения из соответствующего `*.operation.json`.
+3. Для `gRPC` можно либо:
+   - просто использовать готовый `descriptor_set_b64` из JSON payload;
+   - либо отдельно загрузить `.proto` из [grpc-grpcb-addsvc.proto](/home/a.tolmachev/code/rust/mcpaas/examples/mcp-smoke/grpc-grpcb-addsvc.proto).
+4. На шаге теста используй `*.test-input.json`.
+
+### 3.2. Через admin-api
+
+Пример для `ws_default`:
+
+```bash
+curl -sS -X POST \
+  https://rmcp.itexp.me/api/admin/workspaces/ws_default/operations \
+  -H 'content-type: application/json' \
+  -b cookie.txt \
+  --data @examples/mcp-smoke/rest-open-meteo.operation.json
+```
+
+Потом test-run:
+
+```bash
+curl -sS -X POST \
+  https://rmcp.itexp.me/api/admin/workspaces/ws_default/operations/<operation_id>/test-runs \
+  -H 'content-type: application/json' \
+  -b cookie.txt \
+  --data '{
+    "version": 1,
+    "input": '"$(cat examples/mcp-smoke/rest-open-meteo.test-input.json)"'
+  }'
+```
+
+Логин перед этим:
+
+```bash
+curl -sS -c cookie.txt \
+  -H 'content-type: application/json' \
+  -X POST https://rmcp.itexp.me/api/auth/login \
+  --data '{"email":"<your-email>","password":"<your-password>"}'
+```
+
+## 4. Что именно проверяют примеры
+
+### 4.1. REST: Open-Meteo
+
+- Protocol: `REST`
+- Endpoint: `https://api.open-meteo.com/v1/forecast`
+- Проверка:
+  - query mapping
+  - fixed query defaults
+  - JSON response extraction
+
+Ожидаемый upstream response shape:
+
+```json
+{
+  "timezone": "Europe/Moscow",
+  "current": {
+    "time": "2026-04-05T22:30",
+    "temperature_2m": 3.4,
+    "wind_speed_10m": 8.3
+  }
+}
+```
+
+### 4.2. GraphQL: Countries
+
+- Protocol: `GraphQL`
+- Endpoint: `https://countries.trevorblades.com/`
+- Проверка:
+  - fixed GraphQL query
+  - variable mapping
+  - `response_path`
+  - nested array extraction
+
+Ожидаемый upstream query:
+
+```graphql
+query GetCountry($code: ID!) {
+  country(code: $code) {
+    code
+    name
+    capital
+    emoji
+    currency
+    languages {
+      code
+      name
+    }
+  }
+}
+```
+
+### 4.3. gRPC: grpcb.in / addsvc.Add.Sum
+
+- Protocol: `gRPC`
+- Endpoint: `http://grpcb.in:9000`
+- Service: `addsvc.Add`
+- Method: `Sum`
+- Проверка:
+  - descriptor-backed unary gRPC call
+  - `request.grpc.*` mapping
+  - protobuf JSON response normalization
+  - `to_number` transform from protobuf `int64` string
+
+Проверенный реальный вызов:
+
+```bash
+docker run --rm fullstorydev/grpcurl:latest \
+  -plaintext \
+  -d '{"a":7,"b":5}' \
+  grpcb.in:9000 \
+  addsvc.Add/Sum
+```
+
+Ожидаемый ответ:
+
+```json
+{
+  "v": "12"
+}
+```
+
+## 5. Практическая рекомендация
+
+Для первого smoke pass используй именно эти три operation:
+
+- `weather_current_open_meteo`
+- `country_lookup_countries`
+- `grpcb_add_sum`
+
+Этого достаточно, чтобы проверить весь путь:
+
+- create operation
+- test-run
+- publish
+- bind to agent
+- MCP call через `workspace + agent`