# Waffo Pancake MCP Server

A **Cloudflare Worker** Model Context Protocol (MCP) server for Waffo Pancake payment operations. This server enables AI assistants like Grok Bot and Cursor to create checkout sessions, list products, retrieve orders, and process refunds through natural language commands.

**Production Deployment:** The test Worker `pancake-mcp` on workers.dev tracks this official repository.

## What This Is

This is a **hosted MCP server** deployed as a Cloudflare Worker that exposes Waffo Pancake payment APIs through 4 tools. It is **not** a marketplace plugin. It provides a Streamable HTTP endpoint at `/mcp` with Bearer token authentication that AI assistants can connect to for payment operations.

## Features

### 4 MCP Tools

1. **createCheckoutSession** - Create a checkout session and get a checkoutUrl
2. **listProducts** - List all stores and their products (one-time and subscription)
3. **getOrder** - Look up orders by Waffo order ID or your business reference
4. **createRefund** - Create refund tickets for payments (requires X-MCP-Refund-Token)

### Security

- **Bearer Token Authentication**: All `/mcp` requests require `Authorization: Bearer <MCP_AUTH_TOKEN>`
- **Refund Authorization**: `createRefund` tool requires additional `X-MCP-Refund-Token` header
- **Health Checks**: `/` and `/health` endpoints work without authentication

## Prerequisites

- Node.js 20+ (for local development)
- Cloudflare account (free tier works)
- Waffo Pancake merchant account
- API credentials from [Dashboard → API & Development](https://pancake.waffo.ai/merchant/dashboard/integration)

## Setup

### 1. Get Your API Credentials

1. Go to [Waffo Pancake Dashboard → API & Development](https://pancake.waffo.ai/merchant/dashboard/integration)
2. Copy your **Merchant ID** (MER_xxx format) from the top of the page
3. Create an API Key if you don't have one:
   - Click **API Keys** section
   - Click **Create API Key**
   - Download your **private key** (PEM file) - this is only shown once!

### 2. Install Dependencies

```bash
npm install
```

### 3. Set Secrets (for Local Development)

Create a `.dev.vars` file in the project root (Wrangler's local secrets file):

```bash
# Required: Your Waffo Merchant ID
WAFFO_MERCHANT_ID=YOUR_MERCHANT_ID

# Required: Base64 encoded RSA private key
# Encode your key: cat private.pem | base64 | tr -d '\n'
WAFFO_PRIVATE_KEY_BASE64=YOUR_BASE64_ENCODED_PRIVATE_KEY

# Optional: Environment (defaults to test)
WAFFO_ENVIRONMENT=test

# Optional: Default store ID for listProducts and refunds
WAFFO_STORE_ID=YOUR_STORE_ID

# Required: MCP authentication token for /mcp endpoint
MCP_AUTH_TOKEN=YOUR_MCP_AUTH_TOKEN

# Required: Separate refund authorization token
MCP_REFUND_TOKEN=YOUR_MCP_REFUND_TOKEN
```

**Important:** 
- `.dev.vars` is for local development only (gitignored)
- Never commit secrets to git - use YOUR_* placeholders in examples
- For production, use `wrangler secret put` (see Deployment section)

### 4. Run Locally

```bash
npm run dev
```

The Worker will start at `http://127.0.0.1:8787` with the MCP endpoint at `http://127.0.0.1:8787/mcp`.

## Adding MCP URL to AI Assistants

### Cursor

1. Open Cursor Settings
2. Go to **Features** → **MCP** 
3. Click **Add MCP URL**
4. Enter your deployed Workers URL: `https://pancake-mcp.<account>.workers.dev/mcp`
5. Save

### Grok Bot

1. Open Grok Bot settings
2. Go to **Integrations** → **MCP Servers**
3. Click **Add Server**
4. Enter your deployed Workers URL: `https://pancake-mcp.<account>.workers.dev/mcp`
5. Save

**Note:** Replace `<account>` with your Cloudflare Workers subdomain.

## Usage Examples

Once connected, you can use natural language commands:

```
"charge $9.99 for the monthly subscription"
"list all my products"
"look up order ORD_abc123"
"refund payment PAY_xyz789 for $29.99 USD because customer requested cancellation"
```

### Example: Create Checkout Session

**Command:**
```
"create a checkout for product PROD_4cWAslE1GKkGeaOMl9Vbmy, charge $29.99 USD"
```

**Tool Call:**
```json
{
  "name": "createCheckoutSession",
  "arguments": {
    "productId": "PROD_4cWAslE1GKkGeaOMl9Vbmy",
    "productType": "onetime",
    "currency": "USD",
    "priceSnapshot": {
      "amount": "29.99",
      "taxCategory": "digital_goods"
    }
  }
}
```

**Response:**
```json
{
  "sessionId": "cs_550e8400-e29b-41d4-a716-446655440000",
  "checkoutUrl": "https://checkout.waffo.ai/...",
  "expiresAt": "2026-09-03T13:35:00.000Z"
}
```

### Example: List Products

**Command:**
```
"show me all my products"
```

**Response:**
```json
{
  "stores": [
    {
      "id": "STO_abc123",
      "name": "My Store",
      "status": "active",
      "onetimeProducts": [
        {
          "id": "PROD_xyz789",
          "name": "E-Book",
          "prices": {
            "USD": { "amount": "29.00", "taxCategory": "digital_goods" }
          },
          "status": "active"
        }
      ],
      "subscriptionProducts": [
        {
          "id": "PROD_def456",
          "name": "Pro Monthly",
          "billingPeriod": "monthly",
          "prices": {
            "USD": { "amount": "9.99", "taxCategory": "saas" }
          },
          "status": "active"
        }
      ]
    }
  ]
}
```

### Example: Get Order

**Command:**
```
"look up order ORD_7J3K5L8M2N4P6Q9R"
```

**Response:**
```json
{
  "order": {
    "type": "onetime",
    "id": "ORD_7J3K5L8M2N4P6Q9R",
    "buyerEmail": "customer@example.com",
    "status": "completed",
    "currency": "USD",
    "priceSnapshot": {
      "subtotal": "29.00",
      "taxAmount": "2.32",
      "total": "31.32"
    }
  },
  "payments": [
    {
      "id": "PAY_abc123",
      "status": "succeeded",
      "refundStatus": "not_refunded"
    }
  ]
}
```

### Example: Create Refund

**Command:**
```
"refund payment PAY_abc123 for $29.00 USD because customer wasn't satisfied"
```

**Response:**
```json
{
  "data": {
    "ticketId": "RFT_xyz789",
    "status": "pending",
    "requestedAmount": {
      "amount": "29.00",
      "currency": "USD"
    }
  }
}
```

## Tool Schemas

### 1. createCheckoutSession

Creates a checkout session for a product.

**Parameters:**
- `productId` (required): Product ID in Short ID format (e.g., PROD_xxx)
- `productType` (required): "onetime" or "subscription"
- `currency` (required): ISO 4217 currency code (USD, EUR, GBP, HKD, JPY, CNY)
- `buyerEmail` (optional): Pre-fill customer's email
- `successUrl` (optional): Redirect URL after payment
- `priceSnapshot` (optional): Override pricing
  - `amount`: Display format string (e.g., "29.00")
  - `taxCategory`: "saas", "digital_goods", "software", etc.
  - `taxIncluded`: boolean
- `metadata` (optional): Custom key-value pairs

**Returns:**
- `sessionId`: Checkout session ID
- `checkoutUrl`: URL to redirect customer for payment
- `expiresAt`: ISO 8601 expiration timestamp

### 2. listProducts

Lists all stores and their products.

**Parameters:**
- `storeId` (optional): Filter by specific store ID

**Returns:**
- Array of stores with their one-time and subscription products
- Each product includes: id, name, prices, status, billingPeriod (subscriptions)

### 3. getOrder

Look up an order by Waffo order ID or your business reference.

**Parameters:**
- `orderId` (optional): Waffo order ID (ORD_xxx)
- `orderMerchantExternalId` (optional): Your business order reference

**Note:** Provide either `orderId` OR `orderMerchantExternalId`, not both.

**Returns:**
- Order details (type, status, buyer email, amounts)
- Related payments array

### 4. createRefund

Create a refund ticket for a payment. **Requires X-MCP-Refund-Token header.**

**Parameters:**
- `paymentId` (required): Payment ID to refund (PAY_xxx)
- `reason` (required): Refund reason (e.g., "Customer request")
- `amount` (required): Refund amount as string (e.g., "29.00")
- `currency` (required): ISO 4217 currency code
- `buyerEmail` (optional): Buyer email (will be looked up from payment if not provided)

**Authorization:**
- Requires `Authorization: Bearer YOUR_MCP_AUTH_TOKEN` (same as all /mcp requests)
- **Additionally** requires `X-MCP-Refund-Token: YOUR_MCP_REFUND_TOKEN` header

**Returns:**
- Refund ticket details including status and ticket ID

**Warning:** Refunds are auto-approved and processed immediately. This action is irreversible.

## Deployment

### Cloudflare Workers Deployment

The test Worker `pancake-mcp.workers.dev` tracks this repository.

1. **Build the Worker:**
```bash
npm run build
```

2. **Set Production Secrets:**
```bash
# Waffo API credentials
npx wrangler secret put WAFFO_MERCHANT_ID
# Enter: YOUR_MERCHANT_ID

npx wrangler secret put WAFFO_PRIVATE_KEY_BASE64
# Enter: YOUR_BASE64_ENCODED_PRIVATE_KEY

npx wrangler secret put WAFFO_ENVIRONMENT
# Enter: prod (or test)

npx wrangler secret put WAFFO_STORE_ID
# Enter: YOUR_STORE_ID (optional, for default store)

# MCP authentication tokens
npx wrangler secret put MCP_AUTH_TOKEN
# Enter: YOUR_MCP_AUTH_TOKEN

npx wrangler secret put MCP_REFUND_TOKEN
# Enter: YOUR_MCP_REFUND_TOKEN
```

3. **Deploy:**
```bash
npx wrangler deploy
```

Your MCP server will be available at:
```
https://pancake-mcp.<your-account>.workers.dev/mcp
```

### Authentication

**All `/mcp` requests require Bearer token:**
```http
Authorization: Bearer YOUR_MCP_AUTH_TOKEN
```

**Refund operations require additional header:**
```http
X-MCP-Refund-Token: YOUR_MCP_REFUND_TOKEN
```

### Health Check

The Worker includes health check endpoints:
- `/` - Returns server info and status (no auth)
- `/health` - Returns `{"status": "ok"}` (no auth)

### Environment-Specific Keys

**Important:** Use separate API keys for test and production:
- **Test keys**: Use in development with `WAFFO_ENVIRONMENT=test`
- **Production keys**: Use in deployed Workers with `WAFFO_ENVIRONMENT=prod`

Get both from Dashboard → API & Development

## Security

### Best Practices

1. **Never commit private keys** - Always use environment variables
2. **Use test environment** during development
3. **Rotate keys** if compromised
4. **Use base64 encoding** for deployment platforms
5. **Set up HTTPS** for production deployments
6. **Validate requests** from AI assistants if exposing publicly

### Private Key Management

Your private key is the most sensitive credential. Protect it:

- ❌ Don't put in source code
- ❌ Don't commit to git
- ❌ Don't share in logs or error messages
- ✅ Store in environment variables
- ✅ Use secrets management (Railway/Fly/Workers secrets)
- ✅ Rotate if exposed

## API Integration Details

### Authentication

The server uses RSA-SHA256 signing for all Waffo API requests:
- Merchant ID is sent via `X-Merchant-Id` header
- Timestamp is sent via `X-Timestamp` header
- Request signature is sent via `X-Signature` header

The `@waffo/pancake-ts` SDK handles signing automatically.

### GraphQL Queries

The server uses Waffo's GraphQL API for read operations:
- Uses `String!` for ID variables (not `ID!`)
- Accesses results via `result.data`
- Read-only operations

### Amount Format

All amounts are **display strings**, not cents:
- ✅ "29.00" for $29.00
- ✅ "9.99" for $9.99
- ❌ 2900 (cents)

## Troubleshooting

### "Unauthorized" Error

- Check `WAFFO_MERCHANT_ID` matches your dashboard
- Verify private key is complete (including BEGIN/END markers)
- Ensure no extra whitespace in credentials
- Try base64 encoding: `cat private.pem | base64 | tr -d '\n'`

### "Product not found"

- Verify product ID format (PROD_xxx)
- Check if product is active in your environment
- For production, ensure product is published

### "Store not found"

- Verify store ID (STO_xxx format)
- Check you have at least one store created
- Confirm store is active

### Connection Issues

- Verify Worker is running locally (`npm run dev`)
- Check correct URL in AI assistant settings
- For production: ensure Worker is deployed (`npx wrangler deploy`)
- Check Wrangler logs: `npx wrangler tail`

## Development

### Project Structure

```
.
├── src/
│   └── index.ts          # Main MCP server (Cloudflare Worker entry point)
├── dist/                 # Compiled output (generated)
├── wrangler.toml         # Cloudflare Workers configuration
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── .dev.vars.example     # Example local secrets (create .dev.vars)
└── README.md            # This file
```

### Build

```bash
npm run build
```

Compiles TypeScript to `dist/` directory.

### Type Check

```bash
npm run typecheck
```

Validates TypeScript types without building.

## Links

- [Waffo Pancake Dashboard](https://pancake.waffo.ai/)
- [Waffo Documentation](https://docs.waffo.ai/)
- [Waffo API Reference](https://docs.waffo.ai/api-reference/introduction.md)
- [MCP Specification](https://modelcontextprotocol.io/)
- [@waffo/pancake-ts SDK](https://www.npmjs.com/package/@waffo/pancake-ts)

## Support

- Waffo Dashboard: https://pancake.waffo.ai/
- Documentation: https://docs.waffo.ai/
- AI Integration Guide: https://docs.waffo.ai/integrate/ai-integration.md

## License

MIT