qrpaint

qrpaint

二维码也可以是一幅画：夕阳下的灯塔、咖啡馆遮阳篷，或你自己的照片——其中绘有可扫描的二维码。qrpaint 是托管 QRX 服务的轻量转发客户端。它在本地提供 9 个工具，并将每次调用原样转发给服务，由服务绘制图片、检查二维码是否仍可扫描，并返回带有专属短链接的二维码。

由于绘图由托管服务完成，此软件包本身不包含任何渲染逻辑。它包含的是服务契约：服务公开服务器卡中列出的准确工具清单和架构、每次调用所经历的会话握手，以及必须先提供 API 密钥才会发送任何内容的规则。

配置

• QRX_API_KEY（工具调用必需）——你的 QRX API 密钥，每次请求都会通过 Authorization: Bearer <key> 发送到托管端点。没有此密钥，服务器仍会启动并列出工具，但所有调用都会失败并显示 QRX_API_KEY is not set，且不会发出任何请求。
• QRX_MCP_URL（可选）——托管 MCP 端点。默认为 https://qrx.codes/mcp。

工具

• generate_qr_code——根据 prompt（图片应呈现的内容）和 destination 链接开始生成新的艺术二维码；还可以选择使用 list_styles 提供的 style。图片绘制期间会立即返回二维码 ID。
• generate_qr_code_from_image——将二维码融入你已有的图片中。图片通过一次性附加的 image 文件、公开的 imageUrl 或 imageBase64 传入，并附上 destination。
• vary_qr_code——根据现有二维码的 id 生成新二维码，并通过 change 指定图片变化（“把它改成夜景”）。原二维码不会改变，新二维码仍指向同一目标地址。
• get_qr_code——通过 id 获取二维码状态、完成后的图片和短链接；如果二维码仍在绘制中，wait（0–25 秒，默认 25 秒）可让请求等待。
• list_qr_codes——按创建时间从新到旧列出你的二维码，并通过 limit（1–100，默认 20）和 cursor 分页。
• change_qr_code_destination——将现有链接二维码的目标地址改为新的 destination；已印制的副本会立即指向新地址。
• get_account——获取已连接账户的套餐，以及今日剩余的二维码额度。
• get_profile——查看已连接的 QRX 账户。
• list_styles——查看可作为 style 传给 generate_qr_code 的外观样式。

典型工作流是调用 generate_qr_code（或 generate_qr_code_from_image），然后使用返回的 ID 调用 get_qr_code，直到状态变为 succeeded——通常不到一分钟。生成二维码会计入你的 QRX 额度；get_account 会显示剩余额度。

转发工作方式

每次工具调用都会与托管端点建立一个新会话：先发送 initialize 请求（协议版本 2025-03-26），再将返回的会话 ID 放入 notifications/initialized 通知，最后发送带有原样参数的 tools/call 请求。响应以普通 JSON 或服务器发送事件的形式返回，两种格式都会读取。远程结果以 JSON 文本返回。远程错误会显示远程消息；非 2xx 响应会以 qrx error: HTTP <status> 失败；无法访问端点时会以 qrx unreachable 失败。调用不会重试——重试可能会多生成一个二维码（并产生额外费用）。此握手是对标准 Streamable HTTP 会话流程的复现；端点、Bearer 身份验证和缺少密钥时的行为，均为原软件包文档中说明的设计。

除缺少密钥这一规则外，本地不进行参数验证：上述架构会原样提供给 MCP 客户端进行验证，而每次调用均以服务自身的判断为准。

CLI

每个工具都是一个子命令，接收一个 JSON 参数字符串：

export QRX_API_KEY="<your key>"
npx @reneturcios/qrpaint generate_qr_code '{"prompt":"a lighthouse on a cliff at sunset","destination":"https://example.com/menu"}'
npx @reneturcios/qrpaint get_qr_code '{"id":"abc123"}'
npx @reneturcios/qrpaint list_qr_codes '{"limit":10}'
npx @reneturcios/qrpaint vary_qr_code '{"id":"abc123","change":"make it night time"}'
npx @reneturcios/qrpaint change_qr_code_destination '{"id":"abc123","destination":"https://example.com/new-menu"}'
npx @reneturcios/qrpaint get_account '{}'
npx @reneturcios/qrpaint list_styles '{}'
npx @reneturcios/qrpaint --version

输出为远程结果的 JSON 文本。退出码：成功时为 0，错误结果时为 1（包括缺少密钥、远程错误或上游故障），用法错误时为 2。

MCP 服务

npx -y @reneturcios/qrpaint mcp

MCP 客户端配置（通过客户端的环境变量提供密钥）：

{
  "mcpServers": {
    "qrpaint": {
      "command": "npx",
      "args": ["-y", "@reneturcios/qrpaint", "mcp"],
      "env": {
        "QRX_API_KEY": "<your key>"
      }
    }
  }
}

Docker

docker run -i -e QRX_API_KEY="<your key>" ghcr.io/cloudcorprecords/qrpaint
docker run --rm -e QRX_API_KEY="<your key>" ghcr.io/cloudcorprecords/qrpaint list_styles '{}'

Development

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (fake fetch only, no network)
npm run dev     # run the CLI from source

License

MIT — Copyright (c) 2026 Rene Turcios