# Bonus Pink MCP Server

Remote MCP server that lets Bonus Pink sub-accounts operate their loyalty program from any AI agent (Claude, Cursor, etc.): issue cards, add/subtract points, stamps and visits, redeem rewards, send push/SMS, read statistics — 84 tools for sub-accounts, plus 24 agency-only tools that appear automatically when connected with the Bonus Pink agency key.

Stateless Cloudflare Worker. Your API key travels with each request and is never stored on the server.

**End-user guide for sub-accounts: [USAGE.md](USAGE.md)** — getting an API key, connecting each client, example prompts, troubleshooting.

## Connect (sub-accounts)

Get your API key from the Bonus Pink dashboard (Settings → Integrations / API).

**Claude Code**

```sh
claude mcp add --transport http bonuspink https://mcp.bonuspink.com \
  --header "Authorization: Bearer YOUR_API_KEY"
```

**claude.ai / clients without custom headers** — put the key in the URL instead:

```
https://mcp.bonuspink.com/k/YOUR_API_KEY
```

**Generic MCP JSON (Cursor, etc.)**

```json
{
  "mcpServers": {
    "bonuspink": {
      "url": "https://mcp.bonuspink.com",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}
```

Then ask your agent things like: *"Find the card for customer jane@example.com and add 50 points"* or *"How much revenue did we do last month?"*

## Development

```sh
npm install
npm run gen      # openapi.json → src/tools.gen.mjs (108 tools)
npm test         # generator sanity check
npm run dev      # local server on :8787
npm run deploy   # gen + test + wrangler deploy
```

To refresh the API surface: re-download the spec and regenerate.

```sh
curl -s https://api.digitalwallet.cards/api/v2/docs/json -o openapi.json && npm run gen && npm test
```

## How it works

- `scripts/gen-tools.mjs` generates one MCP tool per OpenAPI operation (path + query + body merged into one flat input schema). Marketplace endpoints are excluded (separate `X-App-Token` auth, not for sub-accounts).
- `src/index.ts` is a stateless JSON-RPC handler: `initialize`, `tools/list`, `tools/call`, `ping`. It proxies calls to `https://api.digitalwallet.cards` with the caller's `X-API-Key` and passes API responses (including errors) through verbatim so the agent can self-correct.
- Agency detection: one probe of `GET /api/v2/profile/agency` per key (cached in-memory). Agency-only tools (companies, white-label branding, tariffs) are hidden from sub-account keys and return an error if called anyway.

## Custom domain

`mcp.bonuspink.com` is attached via `routes` in `wrangler.jsonc` (custom_domain). The workers.dev URL also still works: https://bonus-pink-mcp.mecaca.workers.dev