# simplesat-mcp

MCP server for **Simplesat** (CSAT/NPS customer feedback survey
platform). Exposes the Simplesat **V1 API**'s answer search as an MCP
tool.

> Naming note: Simplesat has two generations of integration in MSPbots —
> a legacy 2021-era integration (`subjectCode=SIMPLESAT`, `GET
> /api/answers/`, a `token` field) and the current one this server
> targets (`subjectCode=SIMPLESATV1`, `POST /api/v1/answers/search`, an
> `apiKey` field). Only the current V1 API is covered here.

## Overview

- Stateless HTTP service. No credentials are ever persisted — each request
  supplies its own API key via a header, used only for the lifetime of
  that single request.
- Supports concurrent requests; per-request credential isolation is done via
  Python `contextvars`, not a global/shared client instance.
- Entry points: `POST /mcp` (MCP protocol) and `GET /health` (health check).
- Default port: `8080` (configurable via `MCP_HTTP_PORT`).

## Authentication

Simplesat uses a single static API key — no login or token exchange:

```
X-Simplesat-Token: <api key>
```

Already fully stateless by the vendor's own design; nothing is cached
across MCP calls.

### HEADER 授权参数说明

| Header | 类型 | 是否必填 | 默认值 | 枚举值 | 字段描述 | Example |
|---|---|---|---|---|---|---|
| `X-Simplesat-Api-Key` | string | 是 | 无 | 无 | Simplesat API Key（Account Settings -> API Keys 生成），原样转发为上游 `X-Simplesat-Token` 请求头 | `ssat_170927_a1b2c3d4e5f6g7h8i9j0` |

Missing the header returns `401`:
```json
{
  "error": "Missing credentials",
  "message": "This server requires the X-Simplesat-Api-Key header",
  "required_headers": ["X-Simplesat-Api-Key"],
  "optional_headers": []
}
```

An invalid key surfaces as a tool-level structured error envelope (e.g.
`{"error":{"code":"unauthorized","message":"Invalid Token.","retryable":false}}`),
not an HTTP-level error from this server — see the error envelope format
under **Tool List** below.

## Environment Variables

| Variable | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| `MCP_HTTP_PORT` | int | 否 | `8080` | HTTP 监听端口 |
| `MCP_HTTP_HOST` | string | 否 | `0.0.0.0` | HTTP 监听地址 |
| `SIMPLESAT_BASE_URL` | string | 否 | `https://api.simplesat.io` | Simplesat API 基础 URL |

## MCP Endpoint

- `POST /mcp` — MCP protocol (streamable HTTP transport)
- `GET /health` — health check, pure local probe (does not depend on the Simplesat API), returns `{"status": "ok"}`

## Tool List

| Tool | 功能 | 参数 |
|---|---|---|
| `simplesat_search_answers` | 搜索问卷调查回答（CSAT/NPS 评分与评论），只读 | `page`、`page_size`（默认/上限 100，见下）、`start_date`、`end_date`、`filter_key`、`filter_values`、`filter_comparison`（均可选） |

- `page_size` is clamped server-side to Simplesat's own documented maximum of
  **100** records per page (stricter than it might otherwise be) — values
  above 100 are silently capped rather than rejected upstream.
- Responses are compact JSON (no pretty-printing, `ensure_ascii=False`), and
  are truncated with `truncated`/`original_count` markers if a result would
  exceed ~20,000 characters.
- Errors are returned as a structured envelope, not a plain string:
  `{"error": {"code": "...", "message": "...", "retryable": true|false}}`.
  `code` is one of `not_configured` / `unauthorized` / `not_found` /
  `invalid_argument` / `rate_limited` / `upstream_error`.

## 测试示例

```bash
# Health check
curl -s http://localhost:8080/health

# Call a tool via the MCP protocol (streamable HTTP) — requires an
# initialize handshake first per the MCP spec; abbreviated example below
# shows the tool-call request body only:
curl -s -X POST http://localhost:8080/mcp \
  -H "X-Simplesat-Api-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: <session-id-from-initialize>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "simplesat_search_answers",
      "arguments": {}
    }
  }'
```

**Live-verified** (2026-07-31) against a real Simplesat account:
`simplesat_search_answers` called end-to-end through this running server
with the real API key returned `200` and the vendor's correctly-shaped
response (`{"next": null, "previous": null, "count": 0, "answers": []}`)
— this particular test account has zero survey answers recorded yet,
confirmed as a genuine empty result (not an auth failure) since the
response shape exactly matches the vendor's documented schema. A
separate test with a deliberately invalid API key correctly surfaced
the structured error envelope
`{"error":{"code":"unauthorized","message":"Invalid Token.","retryable":false}}`,
confirming the auth failure path works as expected (re-verified 2026-08-19
after the error format was changed from a plain string to this structured
envelope).

## API Reference

- Public, no login required: https://developer.simplesat.io/api (full V1
  API reference, including the Search Answers operation used here)

## Known Gaps

- **Scope is exactly the 1 method MSPbots' current integration uses**
  (`Search answers`) — the Simplesat V1 API also covers Customers, Team
  members, Responses, Surveys, and Questions, plus `Get answer by ID` and
  `Update answer by ID`; those are out of scope here.
- **`simplesat_search_answers` could not be verified with non-empty
  results** — the test account has zero recorded survey answers. Auth
  and request-shape correctness were confirmed via (1) a 200 response
  matching the vendor's exact documented response schema, and (2) a
  separate invalid-key test correctly returning a 403 `Invalid Token`
  error.
- **The `filter_key`/`filter_values`/`filter_comparison` parameters
  expose only a single filter object** — the vendor's API technically
  accepts an array of filter objects for compound filtering, but MSPbots'
  own usage of this integration sends no filters at all, so this server
  keeps the tool signature simple rather than exposing arbitrary
  multi-filter arrays.