clarity-api-mcp

Bun-MCP-Server für den Clarity AI Upscaler. Ein POST-Endpunkt, alle offiziellen Modi.

Funktionen

• Tools: clarity_list_models, clarity_upscale

• Modi: crystal, crystal-video, clarity (creative-Alias), clarity-pro

• Lokale Dateien: werden vor dem Clarity-POST auf eine öffentliche Roh-URL veröffentlicht (uguu, litterbox oder Tailscale Funnel)

• Dropbox-Freigabeseiten und tmpfiles.org-HTML-Seiten werden zu direkten Datei-URLs umgeschrieben

• Bun-nativ: TypeScript ohne Kompilierungsschritt, automatische .env, Bun.file / Bun.write, Bun Shell curl

• Strukturierte MCP-Ausgabe plus Text-Fallback

Voraussetzungen

• Bun >= 1.1

• Ein Clarity-AI-API-Schlüssel von https://clarityai.co/api

Einrichtung

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

Füge deinen Schlüssel in .env ein (diese Datei niemals committen):

CLARITY_API_KEY=your-key-here

Bun lädt .env automatisch. Der Server liest auch die .env dieses Pakets, wenn ein Coding-Agent ihn aus einem anderen Verzeichnis startet.

MCP-Client-Konfiguration

Ersetze den Pfad durch deinen Klon:

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

Der Schlüssel kann in .env oder im MCP-env-Block liegen. Siehe docs/INSTALL.md für Claude-, Cursor-, Codex- und Grok-Snippets.

Tools

clarity_list_models

Gibt jeden Modus, die Parameterliste und den Beispiel-Body von der offiziellen API-Seite zurück.

clarity_upscale

Sendet POST https://api-upscale.clarityai.co mit Authorization: Bearer ….

Eingabe (allgemein)

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 pro Ausgabe-MP, max. 64 MP.

Ausgabe

{
  "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 berechnet 1 Credit = $0.01. Lokale Dateien werden zuerst veröffentlicht, damit Clarity Rohbytes abrufen kann. Verwende publish: "funnel", wenn die Datei auf diesem Rechner bleiben soll (Tailscale Funnel, nicht Serve).

Umgebungsvariablen

Skripte

bun start
bun test
bun run smoke-test
bun run smoke-test -- --live

--live ruft die echte API auf und verbraucht Credits.

Hinweise

• Schreibe außer dem MCP-Transport nichts auf stdout von diesem Prozess. Diagnosen gehen an stderr.

• Der HTTP-Client ist Bun Shell curl, passend zu den offiziellen Beispielen, mit einem Response-Body als stdin.

Lizenz

MIT