# Ship Receipt MCP

Ship Receipt MCP lets an AI assistant print a **launch receipt** (visits, signups, revenue, cost, and an honest verdict) as a 1200×675 PNG, right inside the chat. It runs the same renderer as the [Ship Receipt website](https://ship-receipt.kevinnsue507.workers.dev), on your machine.

- **No account. No API key. No network calls.** Numbers are self-reported, rendered locally, and never stored or sent.
- Works with any MCP client (Claude Desktop, Cursor, Claude Code, VS Code, and others).

## Demo

[Watch the demo](docs/ship-receipt-mcp-demo.mp4): an assistant calls `generate_receipt` and the PNG comes back in the chat.

## Tools

| Tool | What it does | Annotations |
|---|---|---|
| `generate_receipt` | Renders the receipt PNG and returns it inline (image) plus verdict/headline (text + structured output). | `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false` |
| `describe_ship_receipt` | Explains fields, paper styles, languages and privacy. | read-only |

`generate_receipt` inputs: `project` (≤40 chars), `days` (1–9999), `visits`, `signups`, `revenue`, `cost`, `currency` (`$`/`€`/`£`), `note` (≤120 chars, optional), `theme` (`thermal`/`midnight`/`riso`), `lang` (`en`/`es`), `example` (bool).

Verdicts: PROFITABLE · PRE-REVENUE · TUITION PAID · BREAK-EVEN · EXPERIMENT.

## Install

Install from a clone of this repository. Node.js 18 or newer is required. Use the absolute path to `src/server.mjs` in the client config.

```bash
git clone https://github.com/kdnsue/ship-receipt-mcp.git
cd ship-receipt-mcp
npm install
node src/server.mjs
```

### Claude Desktop

Edit the desktop config:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "ship-receipt": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/ship-receipt-mcp/src/server.mjs"]
    }
  }
}
```

Replace the path with the clone on your machine, then restart Claude Desktop. `generate_receipt` and `describe_ship_receipt` show up as tools.

### Cursor

For one project, add `.cursor/mcp.json` at the project root. For every project, use `~/.cursor/mcp.json`.

```json
{
  "mcpServers": {
    "ship-receipt": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/ship-receipt-mcp/src/server.mjs"]
    }
  }
}
```

Reload MCP servers from Cursor Settings after saving the file.

## Remote (Streamable HTTP)

```bash
PORT=8787 node src/server.mjs --http     # POST http://host:8787/mcp , GET /health
docker build -t ship-receipt-mcp . && docker run -p 8787:8787 ship-receipt-mcp
```

Stateless, no auth (public, read-only tool, no user data).

## Environment variables (all optional)

| Var | Default | Purpose |
|---|---|---|
| `SHIP_RECEIPT_OUTPUT_DIR` | unset | Also save each PNG to this folder (stdio use) |
| `SHIP_RECEIPT_URL` | `https://ship-receipt.kevinnsue507.workers.dev` | Link to the web tool shown in the reply |
| `SHIP_RECEIPT_SITE_LABEL` | `Ship Receipt` | Watermark text printed on the receipt |
| `PORT` | `8787` | HTTP mode port |

## Test

```bash
npm test     # real MCP client over stdio AND Streamable HTTP: list tools, 3 receipts, PNG validity, bad input
npx @modelcontextprotocol/inspector --cli node src/server.mjs --method tools/list
```

## Privacy

See [PRIVACY.md](PRIVACY.md). Short version: the server does not log, store, or transmit the numbers you give it. Rendering stays on the machine that runs the server. A PNG is written to disk only if you set `SHIP_RECEIPT_OUTPUT_DIR`.

Support is through [GitHub Issues](https://github.com/kdnsue/ship-receipt-mcp/issues).

## License

MIT. Copyright (c) 2026 Kevin Daniel. See [LICENSE](LICENSE).

Fonts (JetBrains Mono, Space Grotesk, Instrument Serif) are under the SIL Open Font License.