crank/docs/public-smoke-targets.md

# 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`