giftcardshop-mcp

# @giftcardshop/mcp

MCP server that lets AI agents browse the giftcardshop catalog and buy gift
cards with Lightning - no account, no signup. The agent pays a Lightning
invoice and receives a single-view reveal link with the code.

Read tools work against the live public API with no key. `create_order` is
early access: it needs the shared `GCS_INTERNAL_SECRET` (request one at
https://giftcardshop.org/contact); without it the read tools still work and
`create_order` reports that it is not configured.

## Tools

| Tool | Kind | Backed by |
|------|------|-----------|
| `list_brands` | read | `GET /v1/brands` |
| `search_products` | read | `GET /v1/products` |
| `get_product` | read | `GET /v1/products/:id` (variants + denominations) |
| `get_order_status` | read | `GET /v1/orders/:id` (payment state + reveal availability) |
| `create_order` | write | `POST /internal/agent-orders` (HMAC) -> Lightning invoice |

Read tools pass the API JSON through verbatim. `create_order` returns
`{ orderId, invoiceId, invoiceUrl, bolt11?, sats?, total, currency, expiresAt }`.

## Run

```bash
# read-only (browsing works, create_order reports "not configured")
npx @giftcardshop/mcp

# with checkout enabled
GCS_INTERNAL_SECRET=<64-hex> npx @giftcardshop/mcp
```

Claude Desktop / any MCP client (stdio):

```json
{
  "mcpServers": {
    "giftcardshop": {
      "command": "npx",
      "args": ["-y", "@giftcardshop/mcp"],
      "env": { "GCS_INTERNAL_SECRET": "<64-hex>" }
    }
  }
}
```

## Config

| Env | Default | Purpose |
|-----|---------|---------|
| `GCS_API_BASE` | `https://api.giftcardshop.org` | public API base |
| `GCS_INTERNAL_SECRET` | (unset) | 64-hex HMAC secret; enables `create_order`. Unset = read-only. |

## Checkout (create_order)

`create_order` POSTs to `POST /internal/agent-orders`, HMAC-signed with
`GCS_INTERNAL_SECRET` (header `x-internal-sig`), and returns a Lightning
invoice. Pay it, then poll `get_order_status` for the single-view reveal
link. No Nostr identity and no partner account required.

## Roadmap

- L402 (Lightning HTTP 402) so an agent pays per-call without a human step.
- A hosted remote MCP over HTTP, so there is nothing to install.
- A btcrecharge MCP for mobile top-ups (same shape).