qrpaint

qrpaint

絵でもある QR コードです。夕焼けの灯台、カフェのオーニング、ご自身の写真などに、読み取れるコードが描き込まれています。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 を基に、絵に変更を加えた新しいコードを作成します（例：「夜にする」）。元のコードには手を加えず、新しいコードも同じリンク先を開きます。
• 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 — generate_qr_code の style に指定できる見た目の一覧を取得します。

一般的な手順は、generate_qr_code（または generate_qr_code_from_image）を呼び出し、その後、返された ID を使って get_qr_code を呼び出し、ステータスが succeeded になるまで確認することです。通常は 1 分以内に完了します。コードの作成には QRX の利用枠が使われます。残りの枠は get_account で確認できます。

転送の仕組み

各ツール呼び出しでは、ホスト型エンドポイントとの新しいセッションを開始します。まず initialize リクエスト（プロトコルバージョン 2025-03-26）を送信し、返されたセッション ID を notifications/initialized 通知に引き継いだ後、指定された引数をそのまま tools/call リクエストに渡します。応答はプレーンな JSON またはサーバー送信イベントとして届き、どちらも読み取ります。リモートの結果は JSON テキストとして返されます。リモートエラーはリモート側のメッセージとともに通知され、2xx 以外の応答は qrx error: HTTP <status> で失敗し、エンドポイントに到達できない場合は qrx unreachable で失敗します。呼び出しは再試行されません。再試行すると、2 つ目のコードが描画され（料金も発生し）かねないためです。このハンドシェイクは、標準の Streamable HTTP セッションフローを再現したものです。エンドポイント、Bearer 認証、キー未設定時の動作は、元のパッケージで文書化されている設計に基づいています。

キー未設定時のルールを除き、ローカルでの引数検証は行いません。上記のスキーマは、お使いの MCP クライアントが検証に利用できるよう、そのまま提供されます。すべての呼び出しにおける最終的な判断はサービスが行います。

CLI

各ツールは、1 つの 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