clarity-api-mcp

用于 Clarity AI 放大器的 Bun MCP 服务器。一个 POST 端点，覆盖所有官方模式。

功能

• 工具：clarity_list_models、clarity_upscale

• 模式：crystal、crystal-video、clarity（creative 别名）、clarity-pro

• 本地文件：在 Clarity POST 之前发布到原始公开 URL（uguu、litterbox 或 Tailscale Funnel）

• Dropbox 分享页面和 tmpfiles.org HTML 页面会被改写为直接文件 URL

• Bun 原生：TypeScript 无需编译步骤，自动加载 .env，Bun.file / Bun.write，Bun Shell curl

• 结构化 MCP 输出，外加文本回退

要求

• Bun >= 1.1

• 从 https://clarityai.co/api 获取一个 Clarity AI API 密钥

设置

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

将你的密钥放入 .env（切勿提交此文件）：

CLARITY_API_KEY=your-key-here

Bun 会自动加载 .env。当编码代理从其他目录启动本服务器时，它也会读取此包的 .env。

MCP 客户端配置

将路径替换为你克隆的仓库路径：

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

密钥可以放在 .env 中，也可以放在 MCP 的 env 块中。有关 Claude、Cursor、Codex 和 Grok 的配置片段，请参阅 docs/INSTALL.md。

工具

clarity_list_models

返回官方 API 页面中的全部模式、参数列表和示例请求体。

clarity_upscale

发送 POST https://api-upscale.clarityai.co，携带 Authorization: Bearer …。

输入（通用）

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。每个输出 MP $0.03，上限 64 MP。

输出

{
  "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 按 1 积分 = $0.01 收费。本地文件会先被发布，以便 Clarity 获取原始字节。如果文件需要保留在本机上（Tailscale Funnel，而非 Serve），请使用 publish: "funnel"。

环境变量

脚本

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

--live 会调用真实 API 并消耗积分。

说明

• 除 MCP 传输外，此进程不得向 stdout 写入内容。诊断信息输出到 stderr。

• HTTP 客户端是 Bun Shell 的 curl，与官方示例一致，Response 正文作为 stdin。

许可证

MIT