# CheckSlip MCP

A **remote MCP server** (Streamable HTTP) for verifying Thai bank transfer
slips. It exposes MCP tools over HTTP so any MCP-compatible client (Claude,
Cursor, VS Code, Gemini CLI, Codex CLI, …) can verify a slip's amount,
receiver, transfer date, and detect duplicate usage.

- **Website:** <https://thaibankslip.com>
- **MCP endpoint:** `https://thaibankslip.com/mcp`
- **Connect guides (per client):** <https://thaibankslip.com/docs>

## Get started

1. Create a merchant account at <https://thaibankslip.com/merchant/register>
   (free trial tokens included). Copy your **API Key** — it is shown once.
2. Add the MCP server to your client using the endpoint
   `https://thaibankslip.com/mcp` (step-by-step for each client at
   [/docs](https://thaibankslip.com/docs)).
3. When your client opens the sign-in page, enter your **Merchant Name** and
   **API Key**. That's it — the `check_slip` tool is now available to your AI
   agent.

## Endpoints

- `POST /mcp` — MCP Streamable HTTP (initialize + requests). Requires a valid
  OAuth access token (`Authorization: Bearer <token>`).
- `GET /mcp` — MCP server-to-client stream (requires an active session)
- `DELETE /mcp` — terminate an MCP session
- `GET /health` — `{ "ok": true, "name": "CheckSlip MCP", "version": "1.0.0" }`
- `GET /` — basic server info
- OAuth (public): `GET /.well-known/oauth-protected-resource`,
  `GET /.well-known/oauth-authorization-server`, `POST /register` (DCR),
  `GET|POST /authorize`, `POST /token`

## Authentication (OAuth 2.1)

The `/mcp` endpoint is protected by an OAuth 2.1 Authorization Code flow with
PKCE, designed for MCP clients like Claude's custom connector:

1. The client reads `/.well-known/oauth-protected-resource` (advertised via the
   `WWW-Authenticate` header on a `401`) to discover the authorization server.
2. It registers dynamically via `POST /register` (DCR), then opens `/authorize`
   in a browser.
3. You sign in with your **Merchant Name** and **API Key**. On success an
   authorization code is redirected back.
4. The client exchanges the code at `/token` (verifying PKCE) for a short-lived
   access token plus a rotating refresh token — all handled automatically by
   your MCP client.

## MCP tools

### `check_slip`

Verifies a slip via a slip image, a QR payload, or a transaction reference.

Input:

```json
{
  "slip_image_base64": "base64 PNG/JPEG (optional)",
  "qr_payload": "string (optional)",
  "transaction_ref": "string (optional)",
  "expected_amount": "number > 0 (optional)",
  "expected_receiver_name": "string (optional)",
  "expected_receiver_account_last4": "4 digits (optional)",
  "expected_transfer_date": "YYYY-MM-DD (optional)",
  "order_id": "string (optional)",
  "mark_as_used": "boolean (default false)"
}
```

At least one of `slip_image_base64`, `qr_payload`, or `transaction_ref` is
required. When only `slip_image_base64` is given (raw base64 or a
`data:image/...;base64,` data URL), the server decodes the QR code from the
image and uses it as the QR payload. The result is
returned as JSON text content with `status` one of
`verified | failed | duplicate | provider_error | config_error`.

Comparison rules:

- Amount: exact numeric match.
- Receiver name: case-insensitive, whitespace-trimmed.
- Receiver account last 4: digits only.
- Date: compares the `YYYY-MM-DD` part of the slip's transfer datetime.
- Fields you don't pass are omitted from `checks` (not reported as `false`).

When `mark_as_used` is `true` and all checks pass, the slip's transaction id is
recorded so future checks of the same slip return `status: "duplicate"`.

### `slip_checker_status`

Returns configuration/health without exposing secrets (provider readiness,
duplicate-detection scope, your remaining token balance, auth configuration).

## Tokens & pricing

1 token = 1 slip check. New merchants get free trial tokens; buy more from
your dashboard at <https://thaibankslip.com/merchant> (Stripe Checkout, THB).
See all packages at <https://thaibankslip.com/#pricing>.

## Warning

This server verifies slips through a provider API, never from the picture alone.
When you pass `slip_image_base64`, the server only reads the slip's QR code from
the image and forwards that QR payload to the provider; the rest of the image is
not trusted. Slips without a readable QR code must be supplied as a `qr_payload`
or `transaction_ref` instead.