# PerlerBeadAI MCP Server

**Model Context Protocol server for fuse bead pattern tools** — let AI clients (Claude Code, Cursor, Claude Desktop, Codex, etc.) convert images into bead patterns, generate AI pattern art, look up bead colors, match colors across brands, and estimate bead costs.

```
Server URL: https://perlerbeadai.com/wp-json/pba/v1/mcp
Transport:  Streamable HTTP (JSON-RPC 2.0)
Auth:       Bearer token (free account required)
```

## Tools

| Tool | Description | Rate Limit |
|------|-------------|-----------|
| `pba_convert` | Convert an image (URL or base64) into a bead pattern — color-quantized grid, per-color bead counts, rendered chart PNG. Supports 4 brands (Perler, Hama, Artkal-S, Artkal-C), boards 2–120 beads. | 30/min per key |
| `pba_generate` | Generate bead-pattern-style art from a text prompt (gpt-image-2, ~1–4 min). Two-step: submit with prompt → poll with `job_id` every ~15s. Result opens directly in the AI editor. Uses your account quota (3 free/day + credits). | 1/15s per key |
| `pba_color_chart` | Full color chart for a brand — Perler (103), Hama (92), Artkal-S (199), Artkal-C (174). Each entry: code, name, hex. | 60/min per key |
| `pba_convert_color` | Find nearest bead colors across brands for a brand+code or any hex, using **CIEDE2000** (ΔE grades: excellent <2, good <4, approximate <7, poor ≥7). | 60/min per key |
| `pba_estimate_cost` | Turn per-color bead counts (e.g. from `pba_convert`) into bag counts and reference cost estimates. | 60/min per key |

## Quick Start

### 1. Get an API key

Register a free account at [perlerbeadai.com](https://perlerbeadai.com/register/) (5 bonus credits included), then open your [account page](https://perlerbeadai.com/account/) → **API Keys & MCP** card and click **Create key**. Copy the key (`pba_uk_…`) — it's shown only once.

### 2. Add to your AI client

**Claude Code:**

```bash
claude mcp add --transport http perlerbeadai \
  https://perlerbeadai.com/wp-json/pba/v1/mcp \
  --header "Authorization: Bearer pba_uk_…"
```

**Cursor / Claude Desktop:**

```json
{
  "mcpServers": {
    "perlerbeadai": {
      "url": "https://perlerbeadai.com/wp-json/pba/v1/mcp",
      "headers": {
        "Authorization": "Bearer pba_uk_…"
      }
    }
  }
}
```

Cursor: Settings → MCP → Add server. Claude Desktop: `claude_desktop_config.json`. Restart after saving.

**Codex (OpenAI CLI):**

```toml
[mcp_servers.perlerbeadai]
url = "https://perlerbeadai.com/wp-json/pba/v1/mcp"
http_headers = { "Authorization" = "Bearer pba_uk_…" }
```

## Example Usage

### Convert an image to a bead pattern

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "pba_convert",
    "arguments": {
      "imageUrl": "https://example.com/photo.jpg",
      "width": 29,
      "brand": "perler",
      "maxColors": 25
    }
  }
}
```

Returns the bead grid (`cells[y][x]`), palette with hex/code/name/count, and a rendered chart PNG URL.

### Generate AI pattern art

```json
// Step 1 — submit
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "pba_generate",
    "arguments": { "prompt": "a cute black cat with green eyes" }
  }
}
// → returns { "status": "pending", "job_id": "550e8400-…" }

// Step 2 — poll (repeat every ~15s until status=done)
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "pba_generate",
    "arguments": { "job_id": "550e8400-…" }
  }
}
// → returns { "status": "done", "imageUrl": "https://…", "editorUrl": "https://…" }
```

### Match a hex color to nearest bead colors

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "pba_convert_color",
    "arguments": { "hex": "#FF6B8A", "targetBrand": "hama", "top": 3 }
  }
}
```

## OAuth 2.1 PKCE

OAuth 2.1 with PKCE (S256) is also supported for client-side apps:

- **Discovery:** `GET /.well-known/oauth-authorization-server/wp-json/pba/v1/mcp`
- **Authorize:** `/wp-json/pba/v1/oauth/authorize`
- **Token:** `/wp-json/pba/v1/oauth/token`

### Verify a key

```bash
curl -H "Authorization: Bearer YOUR_KEY" \
  https://perlerbeadai.com/wp-json/pba/v1/key/whoami
```

## Server Implementation

The MCP server is implemented as a WordPress REST API handler. The reference implementation is in `server/pbai-mcp.php`.

Key features:
- **JSON-RPC 2.0** over Streamable HTTP
- **SSRF-safe** image fetching (public-IP validation, DNS check, redirect limit, Content-Type verification)
- **CIEDE2000** color distance math (full implementation ported from Python reference)
- **GD-based** chart rendering (bead-grid PNG generation)
- **Rate limiting** per API key with WordPress transients
- **Audit logging** (JSONL, key-hashed, per-month)
- **OAuth 2.1 PKCE** (S256, single-use codes, token cleanup)

## Security

- API keys are SHA256-hashed at rest; raw keys are never stored
- SSRF protection: public-IP-only DNS validation, port 80/443 only, max 2 redirects, 10MB limit
- Image type verification via `getimagesizefromstring()` (PNG/JPEG/WebP/GIF only)
- IP-term filtering on AI prompts (copyrighted characters/brands rejected)
- Keys are revocable and regenerable instantly from the account page
- All calls are audit-logged (hashed key ID, timestamp, tool, latency)
- Uses `hash_equals()` for timing-safe key comparison

## Pricing

- **Free tier:** 3 AI generations per day, unlimited for reference tools (convert, color chart, color matching, cost estimate)
- **Credits:** $0.50/generation beyond the free tier. Credits never expire — [top up here](https://perlerbeadai.com/pricing/#credits)
- **Reference prices** in `pba_estimate_cost` are planning estimates, not live shop prices

## Links

- [MCP Documentation](https://perlerbeadai.com/mcp/)
- [Pattern Editor](https://perlerbeadai.com/perler-bead-pattern-generator/)
- [AI Generator](https://perlerbeadai.com/ai-pattern-generator/)
- [Color Chart](https://perlerbeadai.com/colors/)
- [Free Patterns](https://perlerbeadai.com/patterns/)

## License

MIT — see [LICENSE](LICENSE).

---

Made with ❤️ by [PerlerBeadAI](https://perlerbeadai.com) — free fuse bead pattern maker & AI generator.