# clarity-api-mcp

Bun MCP server for the [Clarity AI](https://clarityai.co/api) upscaler. One POST endpoint, every official mode.

## Features

- Tools: `clarity_list_models`, `clarity_upscale`
- Modes: `crystal`, `crystal-video`, `clarity` (`creative` alias), `clarity-pro`
- Local files: published to a raw public URL (`uguu`, `litterbox`, or Tailscale Funnel) before the Clarity POST
- Dropbox share pages and tmpfiles.org HTML pages are rewritten to direct file URLs
- Bun-native: TypeScript with no compile step, automatic `.env`, `Bun.file` / `Bun.write`, Bun Shell `curl`
- Structured MCP output plus a text fallback

## Requirements

- [Bun](https://bun.sh) >= 1.1
- A Clarity AI API key from https://clarityai.co/api

## Setup

```bash
git clone https://github.com/thomastraum/clarity-api-mcp.git
cd clarity-api-mcp
bun install
cp .env.example .env
```

Put your key in `.env` (never commit this file):

```
CLARITY_API_KEY=your-key-here
```

Bun loads `.env` automatically. The server also reads this package's `.env` when a coding agent starts it from another directory.

## MCP client config

Replace the path with your clone:

```json
{
  "mcpServers": {
    "clarity-api": {
      "command": "bun",
      "args": ["/absolute/path/to/clarity-api-mcp/src/index.ts"]
    }
  }
}
```

The key can live in `.env` or in the MCP `env` block. See [docs/INSTALL.md](docs/INSTALL.md) for Claude, Cursor, Codex, and Grok snippets.

## Tools

### `clarity_list_models`

Returns every mode, parameter list, and example body from the official API page.

### `clarity_upscale`

Sends `POST https://api-upscale.clarityai.co` with `Authorization: Bearer …`.

**Input (common)**

| Field | Notes |
| --- | --- |
| `mode` | `crystal` \| `crystal-video` \| `clarity` \| `creative` \| `clarity-pro` |
| `image` | Public image URL **or local file** (all image modes) |
| `video` | Public video URL **or local file** (`crystal-video`) |
| `publish` | `uguu` (default) \| `litterbox` \| `funnel` \| `none` — how to expose a local file as raw bytes |
| `webhook` | Optional. Result is POSTed here instead of returned |
| `output_path` | Optional local file or directory to save the result |
| `include_raw_response` | Optional debug flag |

**Crystal** — `scale_factor` 1–200, `creativity` 0–10, `output_format` jpg/png, `target_megapixels` 0.001–1500

**Crystal Video** — `scale_factor` 1–200

**Clarity** — `creativity` / `resemblance` / `dynamic` / `fractality` −10–10, `scale_factor` 2–16, `style` default/portrait/anime, `postprocessing` none/sharpen, `prompt`

**Clarity Pro** — `creativity` −10–10, `scale_factor` 2/4/8/16, `output_format` png/jpg. $0.03 per output MP, max 64 MP.

**Output**

```json
{
  "mode": "crystal",
  "requested_mode": "crystal",
  "url": "https://…",
  "credit_cost": 3,
  "cost_usd": 0.03,
  "balance": 97,
  "webhook": null,
  "saved_to": "/path/to/out.jpg",
  "published_url": "https://a.uguu.se/…",
  "published_via": "uguu",
  "note": null
}
```

Clarity charges 1 credit = $0.01. Local files are published first so Clarity can fetch raw bytes. Use `publish: "funnel"` if the file should stay on this machine (Tailscale Funnel, not Serve).

## Environment variables

| Name | Default | Purpose |
| --- | --- | --- |
| `CLARITY_API_KEY` | — | Required (or `CAI_API_KEY`) |
| `CLARITY_BASE_URL` | `https://api-upscale.clarityai.co` | Override the endpoint |
| `CLARITY_TIMEOUT` | `300000` | curl timeout in ms |
| `CLARITY_OUTPUT_DIR` | — | Auto-save results when `output_path` is omitted |
| `CLARITY_PUBLISH` | `uguu` | Default publisher for local files |
| `CLARITY_LITTERBOX_TIME` | `1h` | litterbox TTL (`1h` / `12h` / `24h` / `72h`) |

## Scripts

```bash
bun start
bun test
bun run smoke-test
bun run smoke-test -- --live
```

`--live` calls the real API and spends credits.

## Notes

- Do not write to stdout from this process except the MCP transport. Diagnostics go to stderr.
- The HTTP client is Bun Shell `curl`, matching the official examples, with a `Response` body as stdin.

## License

MIT