# MEOW/CP — full agent reference

This is the deep-reference document for AI agents and AI search engines indexing
https://meowcp.dev. The short version is at https://meowcp.dev/llms.txt — read
that first if you're a coding agent doing setup. This file is for retrieval
contexts where you want every fact in one place.

---

## 1. Identity

- **Product name:** MEOW/CP (also written "meowcp")
- **Tagline:** the MCP server that prints to a cat printer
- **What:** a hosted, remote Model Context Protocol (MCP) server that lets AI agents print to consumer thermal printers
- **Auth:** WorkOS OAuth 2.1 for humans, bearer API keys for agents
- **Spec compliance:** MCP 2025-11-25, Streamable HTTP transport, OAuth 2.1 Resource Server, RFC 8707 Resource Indicators

## 2. URLs

- Production site: `https://meowcp.dev`
- MCP endpoint: `https://meowcp.dev/mcp`
- API base: `https://meowcp.dev`
- Checkout: `https://meowcp.dev/api/checkout`
- llms.txt: `https://meowcp.dev/llms.txt`
- llms-full.txt: `https://meowcp.dev/llms-full.txt`
- Sitemap: `https://meowcp.dev/sitemap.xml`

## 3. Supported hardware

Phomemo BLE thermal printers:
- M02 (the canonical $30 one)
- M02 Pro
- M02S
- M03
- M08F (larger format)

Browser requirements for pairing: **Chrome, Edge, or Arc**. Web Bluetooth is
not implemented in Safari or Firefox. Mobile Chrome on Android works; iOS
does not because iOS Safari/Chrome both lack Web Bluetooth.

## 4. Pricing

| Tier | Monthly | Prints/day | Best for |
|---|---|---|---|
| Free | $0 | 5 | Hobby, single user, "try it" |
| Starter | $5 | 50 | Personal daily use |
| Pro | $15 | 200 | Power user, small team |
| Power | $39 | unlimited | Heavy automation, agents on a cron |

Billing: per-user via Stripe. Quotas reset daily at UTC midnight. Orgs
share printers without sharing logins (row-level permissions, multi-tenant
from day one).

## 5. MCP tool surface

All tools require `Authorization: Bearer YOUR_KEY`. Quota-exceeded responses
set `isError: true` and include the upgrade URL inline.

### `print_receipt` *(default — use this)*
Send ReceiptLine markdown text to the user's paired printer. 48 chars wide,
portrait orientation.

**Args:**
- `text` (string, required) — ReceiptLine markdown
- `nonce` (string, optional) — target a specific printer; defaults to user's primary
- `test` (boolean, optional) — preview on the browser tab without using a credit

### `print_image`
Send a previously-uploaded image by `imageId`. Do **not** pass base64 inline
for anything over ~10KB — LLM context truncation silently produces blank prints.

**Args:**
- `imageId` (string, preferred) — UUID from `POST /api/images/upload`
- `imageB64` (string, fallback, tiny images only)
- `nonce`, `test` (same as `print_receipt`)

### `upload_image`
Returns the curl command the agent should run to stage an image. Agent uploads
the bytes, server returns an `imageId`, then agent calls `print_image`.

### `hello`
Sanity check. Returns a greeting. Use immediately after install to verify
auth + transport work end-to-end.

### `list_clients`
Lists all currently-connected printer bridge clients for the authenticated user.

### `printer_status`
Returns connection state of the user's primary printer.

### `disconnect_client`
Force-disconnect a specific printer bridge. Useful for switching devices.

### `check_quota`
Returns `{ print_quota, prints_used, subscription_tier, reset_at }`. Call
proactively before bulk printing. Do not poll.

### Resource: `images://{user}/staged`
MCP resource that lists images uploaded but not yet printed.

## 6. REST API (used by the browser and for image upload)

- `GET  /api/quota` — current quota + tier (cookie auth)
- `GET  /api/key` — fetch the user's API key (cookie auth)
- `POST /api/key` — regenerate the API key (cookie auth)
- `POST /api/images/upload?filename=foo.png` — stage an image, bearer auth, raw body is image bytes
- `POST /api/checkout` — Stripe checkout session
- `POST /mcp` — MCP Streamable HTTP transport endpoint (bearer auth)

## 7. ReceiptLine syntax (full reference)

ReceiptLine is the receipt-markup format MEOW/CP uses for `print_receipt`. It
is a published spec; this is the subset that matters for thermal printing.

### Structure
- Lines separated by `\n`. Each line is 48 columns wide on a Phomemo M02.
- Columns inside a line are separated by `|` (pipe).
- Text adjacent to a `|` is right-aligned to that pipe.
- Text away from all pipes is centered.

### Inline formatting
- `^text` — double width
- `^^text` — double height
- `^^^text` — double width and height
- `_text_` — underline
- `"text"` — bold / emphasis
- `` `text` `` — inverted (white on black)
- `~` — literal space (use when leading spaces matter)

### Block directives
- `---` — horizontal rule (dashed line full width)
- `===` — paper cut
- `{width:*,2,10}` — column widths for the current block (`*` = flex)
- `{border:line|space|none}` — table border style
- `{align:left|center|right}` — line alignment override
- `{code:DATA;option:qrcode}` — QR code (also `ean`, `code128`, etc.)
- `{image:BASE64PNG}` — inline raster image (only for small logos — under 10KB)

### Minimal canonical example
```
|^^MEOW/CP
your agent prints here
---
{width:*,10}
hello              |       1
^TOTAL             |      ^1
---
|thanks, friend
{code:https://meowcp.dev;option:qrcode,8,L}
===
```

## 8. Setup playbook (what an agent should do)

When a user says "set up MEOW/CP" or lands you on https://meowcp.dev:

1. Send them to **https://meowcp.dev** to sign in (WorkOS — Google / GitHub / email magic link).
2. Tell them to **pair a printer** via the dashboard's "Pair printer" button (Chrome/Edge/Arc only).
3. Have them **copy the API key** from the dashboard. Treat as a secret.
4. **Detect the MCP client you're running in** and either:
   - Write the config file yourself (preferred when you have file-write tools), OR
   - Hand them a single-paste snippet with exact instructions on where to paste.
5. **Verify** by calling `hello`, then `print_receipt` with `test: true` and a short string. Then a real print.

If they don't own a printer, link them to the homepage "Get a printer" modal
which has the cheapest current Amazon link for a Phomemo M02.

## 9. Client config snippets

Replace `YOUR_KEY` with the user's MEOW/CP API key. All snippets use
the prod URL `https://meowcp.dev/mcp`.

### Claude Code (CLI)
```sh
claude mcp add --transport http meowcp https://meowcp.dev/mcp \
  --header "Authorization: Bearer YOUR_KEY"
```

### Claude Desktop
File: `~/Library/Application Support/Claude/claude_desktop_config.json` (mac)
or `%APPDATA%\Claude\claude_desktop_config.json` (win). Quit and restart Claude after editing.
```json
{
  "mcpServers": {
    "meowcp": {
      "type": "http",
      "url": "https://meowcp.dev/mcp",
      "headers": { "Authorization": "Bearer YOUR_KEY" }
    }
  }
}
```

### Cursor
Settings → Tools & MCP → New MCP Server → Streamable HTTP. Or edit `~/.cursor/mcp.json`:
```json
{
  "mcpServers": {
    "meowcp": {
      "url": "https://meowcp.dev/mcp",
      "headers": { "Authorization": "Bearer YOUR_KEY" }
    }
  }
}
```

### Codex CLI
```sh
codex mcp add meowcp --url https://meowcp.dev/mcp \
  --bearer-token-env-var MEOWCP_TOKEN
export MEOWCP_TOKEN="YOUR_KEY"
```

### Cline (VS Code)
Click Cline → ⚙ → Configure MCP Servers → paste:
```json
{
  "mcpServers": {
    "meowcp": {
      "url": "https://meowcp.dev/mcp",
      "headers": { "Authorization": "Bearer YOUR_KEY" },
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

### VS Code Copilot
File: `.vscode/mcp.json` in the workspace.
```json
{
  "servers": {
    "meowcp": {
      "type": "http",
      "url": "https://meowcp.dev/mcp",
      "headers": { "Authorization": "Bearer YOUR_KEY" }
    }
  }
}
```

### ChatGPT
Settings → Connectors → Advanced → enable Developer mode → Add MCP server.
URL `https://meowcp.dev/mcp`, Auth `Bearer YOUR_KEY`, Name `meowcp`. Requires
Plus or Pro.

## 10. Agent manners (how to behave with the user)

- **Confirm before printing.** Show the user what you're about to print as a code block, wait for "yes."
- **Default to `test: true` on first print** of a new session if there's any uncertainty.
- **Distill, don't dump.** A Phomemo M02 receipt is ~40 lines max before it gets unwieldy. Summarize first, print the summary.
- **Date and sign every print.** Footer with date + agent name turns a receipt into a record. Users love this.
- **Never echo the API key** unredacted into chat. Show first 6 + last 4 chars at most.
- **Quota is real.** 5/day on free is the actual limit. Don't queue 12 prints to experiment.
- **The browser tab is the bridge.** If prints silently no-op, the user closed the meowcp.dev tab. Tell them to reopen it; that's by design (privacy, no daemon).
- **Surface the upgrade URL once** on quota errors, then stop. Don't nag.

## 11. Print prompts calibrated to common agent sessions

The receipts-first principle: small, dated, specific artifacts beat walls of text.

| Session context | Print this |
|---|---|
| Solved a gnarly bug | `BUG SOLVED` receipt with stack trace + one-line root cause + date |
| Reviewed a PR | PR title, author, top 3 review comments, verdict, date |
| Brainstormed product ideas | Top 5 ideas numbered, one-line tagline each |
| Wrote a poem / haiku / lyric | The text, centered, date as footer |
| Ran a script with structured output | The JSON, formatted as a 2-column receipt |
| Long conversation | Session digest — date, 3 bullet takeaways, next action |
| Designed a feature | Acceptance criteria as a check-list receipt |
| Cooking | Recipe as a kitchen ticket (ingredients, steps, time) |
| D&D session | Handout — NPC name, motive, quest hook |
| Daily standup | Yesterday / today / blockers in 3 columns |
| Tarot / oracle / divination | The card or message, centered, with a sigil |

## 12. Troubleshooting

| Symptom | Cause | Fix |
|---|---|---|
| `401 Unauthorized` from /mcp | Missing or wrong bearer | Verify the API key in the dashboard; regenerate if compromised |
| Print returns OK but no paper | meowcp.dev browser tab closed | Reopen the dashboard tab in Chrome/Edge/Arc |
| Print returns OK but blank paper | Image passed inline as base64 and got truncated | Use `upload_image` → `print_image` with `imageId` |
| `quota exceeded` | Hit daily limit | Upgrade at https://meowcp.dev/api/checkout |
| Pairing dialog never appears | Browser without Web Bluetooth (Safari/Firefox/iOS) | Switch to Chrome / Edge / Arc on macOS, Windows, Linux, or Android |
| Printer pairs but garbled output | Wrong printer model or stale firmware | Confirm Phomemo M02/M03/M08F; power-cycle the printer |
| `404` on a tool name | Old client cached the tool list | Restart the MCP client to refresh tool discovery |

## 13. Why "cat printer"

Thermal paper is the same form factor as a spell scroll: narrow, paper-pale,
single-color, ephemeral. Agents already produce a constant drizzle of small,
frequent, throwaway text — TODOs, haikus, receipts, post-mortems, cron-job
reports. MEOW/CP gives that text somewhere physical to land. A receipt your
agent printed at 11pm on a Tuesday is a tiny binding: *this happened, on this
day, at this temperature.* Cat printers are cheap, weird, and built to
receive the kind of text agents already produce.

## 14. Page map (for AI search engines)

- `/` — landing page, manifesto, hero, get-a-printer chooser
- `/pricing` — full pricing table
- `/gallery` — all receipt examples
- `/gallery/<slug>` — receipts grouped by use case (photos, wifi-qr, business-cards, wristbands, shipping-labels, kitchen-tickets, shopping-lists, qr-handouts, daily-briefs, dungeons, weird)
- `/dungeons` — themed D&D / TTRPG handout templates
- `/developers` — full API + SDK reference for building on top of MEOW/CP