qrcanvas

qrcanvas

qrcanvas は、ホスト型の Hovercode MCP サーバーへの小規模なローカルブリッジです。このサーバーは、Hovercode ワークスペース内の QR コード、短縮リンク、 ランディングページ、フォームを管理します。エージェントから QR コードを作成できます。静的なものはもちろん、リンク先を編集可能な状態に保ち、 スキャン数を追跡できる動的なものも作成できます。色、 パターン、目の形、フレーム、ロゴを使ってスタイルを設定し、 コードを一括生成したり、PDF をコードで包んだり、 レンダリング済みの画像をダウンロードしたりできます。同じワークスペース内で、短縮リンク、 種類別のブロックから構成されるランディングページ、回答を読み戻せる フォームも管理できます。これらはフォルダーやタグで整理でき、 スキャンやリンクの分析情報で効果を測定できます。

このブリッジ自体はワークスペースのデータを保持しません。 ライブエンドポイントから取得したとおりのツール一覧をローカルで返し、 各ツール呼び出しを上流に転送して、返された内容をそのまま返します。 取得済みの 36 個のツールはすべて、この再構築版に含まれています。 提供するのはご自身のワークスペースに対する CRUD 操作です。支払い、 請求、送信を行うツールはありません。

ツール

ワークスペースと QR コード：

• list_workspaces — このアカウントがアクセスできるワークスペースを一覧表示します。 現在のワークスペースには印が付いています。必須引数はありません。
• set_workspace — 現在のワークスペースを切り替えます。 必須：workspace。
• create_qr_code — QR コードを作成し、詳細とレンダリング済みの PNG を取得します。 必須：qr_data。
• create_qr_codes_bulk — 複数のコードを一度に作成します。 必須：items。
• create_pdf_qr — PDF 用の QR コードを作成します。必須引数はありません。
• list_qr_codes — コードを一覧表示し、検索します。必須引数はありません。
• get_qr_code / update_qr_code / delete_qr_code — コードを 1 つ読み取り、変更、または削除します。必須：id。
• download_qr — コードのレンダリング済み画像をダウンロードします。 必須：id。
• get_qr_activity — 1 つのコードのスキャン状況を取得します。 必須：id。
• get_analytics — ワークスペースの分析情報を取得します。必須引数はありません。

ページとフォーム：

• build_page — 順序付けされたブロックからランディングページを作成して公開します。 必須：title、blocks。
• create_page — ページを作成します。必須：title。
• get_page / update_page / delete_page — ページを 1 つ読み取り、 変更、または削除します。必須：id。
• list_pages — ページを一覧表示します。必須引数はありません。
• list_block_types — ページの作成に使うブロックの種類を一覧表示します。必須引数はありません。
• create_form — フォームを作成します。必須：title、 fields。
• update_form — フォームを変更します。必須：id。
• list_forms — フォームを一覧表示します。必須引数はありません。
• get_form — フォームを 1 つ読み取ります。必須：id。
• get_form_responses — フォームの回答を読み取ります。 必須：id。

短縮リンクと組織管理：

• create_short_link — 短縮リンクを作成します。 必須：link。
• get_short_link / update_short_link / delete_short_link — リンクを 1 つ読み取り、変更、または削除します。 必須：id。
• list_short_links — リンクを一覧表示し、検索します。必須引数はありません。
• get_short_link_activity — 1 つのリンクのクリック状況を取得します。 必須：id。
• list_templates — デザインテンプレートを一覧表示します。必須引数はありません。
• list_folders — フォルダーを一覧表示します。必須引数はありません。
• create_folder — フォルダーを作成します。必須： name。
• update_folder / delete_folder — フォルダーの名前変更、移動、または削除を行います。必須：id。
• list_tags — タグを一覧表示します。必須引数はありません。

設定

• HOVERCODE_MCP_URL（任意）— 上流エンドポイントを上書きします。デフォルトは https://hovercode.com/mcp/ です。（この上書き用フックは、 この再構築版独自のものであることを明示しています。）
• HOVERCODE_API_TOKEN（任意）— 設定すると、すべての上流リクエストに Hovercode API トークンを含む Authorization: Bearer <token> ヘッダーが付与され、OAuth ブラウザー フローがスキップされます。未設定の場合、キーのヘッダーは送信されません。 （環境変数名は元のレジストリレコードに基づいています。レコード上のリモートにはヘッダーが指定されていないため、Bearer ヘッダー形式は 再構築版独自のものであることを明示しています。元の機能はキーなしで取得されました。）

転送の仕組み

最初のツール呼び出しで、クライアントは上流にストリーミング可能な HTTP セッションを開きます。まず JSON-RPC の initialize リクエスト（protocolVersion 2025-03-26、clientInfo 名 qrcanvas）を送り、続いて notifications/initialized 通知を送り、その後、呼び出し元の引数を変更せずに含めた tools/call リクエストを送ります。上流が initialize に Mcp-Session-Id ヘッダーを付けて応答すると、その値は セッションの後続の各リクエストに付与され、プロセスの存続期間中 再利用されます。応答は通常の JSON またはサーバー送信イベントとして 届く場合があり、どちらも読み取られます。

上流からの成功結果は、上流が設定した isError フラグも含め、 そのまま返されます。失敗（JSON-RPC エラー、2xx 以外のステータス、 読み取り不能な応答、または完了できないリクエスト）は、 テキストが qrcanvas error: で始まる isError 結果として返されます （この形式は、この再構築版独自のラベル付き再現です）。

CLI

各ツールは、JSON 引数文字列を受け取るサブコマンドとしても実行できます。

npx @reneturcios/qrcanvas list_workspaces '{}'
npx @reneturcios/qrcanvas create_qr_code '{"qr_data":"https://example.com","dynamic":true}'
npx @reneturcios/qrcanvas create_short_link '{"link":"https://example.com/a/very/long/path"}'
npx @reneturcios/qrcanvas get_qr_code '{"id":"qr_123"}'
npx @reneturcios/qrcanvas --version

終了コード：成功時は 0、isError 結果の場合は 1、使用方法に誤りがある場合は 2 です。

MCP サーバー

npx -y @reneturcios/qrcanvas mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "qrcanvas": {
      "command": "npx",
      "args": ["-y", "@reneturcios/qrcanvas", "mcp"]
    }
  }
}

Docker

docker run -i ghcr.io/cloudcorprecords/qrcanvas
docker run --rm ghcr.io/cloudcorprecords/qrcanvas --version

コンテナのデフォルトコマンドは mcp です。そのため、最初の形式は stdio MCP サーバーとして動作し、その他の引数は通常どおり CLI に渡されます。

開発

npm install
npm run build
npm test
npm run dev

テストスイートは、スタブ化された JSON-RPC 上流のみを対象に実行されます。実際のネットワーク呼び出しは行われません。

ライセンス

MIT — LICENSE を参照してください。