QRTap

qrtap-mcp — AI エージェント向け QRTap

Claude や、MCP 対応アシスタントならどれでも QRTap ワークスペースを操作できる MCP stdio サーバーです。編集可能な QR コードと短縮リンク、公開ページ、ゲストレビュー、予約リクエスト、条件付きリダイレクトを利用できます。

ロシア語版：README.ru.md。

作成した理由

QRTap コードには永続的な短縮リンクが埋め込まれており、そのリンク先はいつまでも編集できます。メニュー、価格表、店の窓、名刺に一度コードを印刷すれば、必要に応じて何度でもリンク先を変更できます。印刷し直す必要はありません。

そのため、この製品はエージェントに適しています。「夏のメニューに QR コードを付けて」「ステッカーのリンク先を新しい価格表にして」「各支店に 1 つずつ、支店分のコードを 120 個発行して」「新しい予約はある？」といった依頼は、どれも 1、2 回のツール呼び出しで済みます。

インストール

npx -y qrtap-mcp        # run the stdio server
npm i -g qrtap-mcp      # or install the qrtap-mcp binary

Node 20 以降があれば、それ以外は必要ありません。このパッケージは 実行時依存関係ゼロ のコンパイル済み JavaScript なので、npx が取得するのは約 22 kB で、すぐにサーバーを起動できます。初回実行時にツールチェーンをダウンロードする必要はありません。MCP 通信には stdin/stdout を使い、ログは stderr にのみ出力します。

設定

変数	意味
QRTAP_API_KEY	必須。 ワークスペースの API キーです。
QRTAP_API_URL	API のベース URL です。デフォルトは https://app.qrtap.kg です。

キーの取得方法。 ワークスペースの所有者は、QRTap の管理画面にある app.qrtap.kg/workspace/api でキーを発行できます。キーは一度だけ表示され、ワークスペース全体の権限を持ちます。いつでもそこで取り消すことができます。無料プランを含むすべてのプランで キーを発行できるため、支払い前に連携を試すことができます。プランによって変わるのは利用枠と一括処理用エンドポイントであり、利用可否ではありません。詳しくは以下の制限とプランと app.qrtap.kg/pricingをご覧ください。

キーはパスワードと同様に扱ってください。プロンプト、リポジトリ、共有ドキュメントには記載せず、MCP クライアントの env ブロックに設定してください。

Claude Desktop

「設定」→「開発者」→「設定を編集」を選択し、claude_desktop_config.json に次を追加します。

{
  "mcpServers": {
    "qrtap": {
      "command": "npx",
      "args": ["-y", "qrtap-mcp"],
      "env": { "QRTAP_API_KEY": "qrtap_key_XXXX" }
    }
  }
}

Claude Code

claude mcp add qrtap --env QRTAP_API_KEY=qrtap_key_XXXX -- npx -y qrtap-mcp

Cursor、Windsurf、VS Code などの MCP クライアント

標準の mcpServers 形式に対応している場所なら、どこでも同じ設定を使用できます。.cursor/mcp.json、プロジェクトのルートにある .mcp.json、またはクライアント独自の設定ファイルに追加してください。

{
  "mcpServers": {
    "qrtap": {
      "command": "npx",
      "args": ["-y", "qrtap-mcp"],
      "env": { "QRTAP_API_KEY": "qrtap_key_XXXX" }
    }
  }
}

ツール

公開 REST API v1 を通じて 20 個のツールを利用できます。読み取り操作は自由に実行しても安全です。公開への影響あり と記された 4 つのツールは、実際の顧客に表示される内容を変更します。各ツールの説明では、先にユーザーへ確認するようエージェントに指示しています。

コードと短縮リンク

ツール	対応先
qrtap_create_code(url, title?, external_ref?, group?, design_template_id?)	POST /api/v1/codes
qrtap_create_codes_bulk(items[])	POST /api/v1/codes/bulk — 最大 500 件、項目ごとの結果を返します
qrtap_list_codes(group?, external_ref?, include_stats?, limit?, offset?)	GET /api/v1/codes
qrtap_get_code(codeId)	GET /api/v1/codes/{id}
qrtap_change_destination(codeId, url) — 公開への影響あり	PATCH /api/v1/codes/{id}
qrtap_code_history(codeId)	GET /api/v1/codes/{id}/history
qrtap_create_short_link(url)	POST /api/v1/codes
qrtap_list_design_templates()	GET /api/v1/design-templates

アナリティクス

ツール	対応先
qrtap_code_stats(codeId, from?, to?)	GET /api/v1/codes/{id}/stats
qrtap_group_stats(group, from?, to?)	GET /api/v1/groups/{group}/stats

スキャンのアナリティクスは匿名で、集計データのみを扱う設計です。総数、日別の推移、デバイスの内訳を確認できます。ボットは除外され、訪問者の IP アドレスやユーザーエージェントは保存されないため、エージェントが個人別の記録を求めても取得できません。

公開ページ（/a/{slug}）

ツール	対応先
qrtap_list_pages()	GET /api/v1/pages
qrtap_get_page(slug)	GET /api/v1/pages/{slug}
qrtap_create_page(content)	POST /api/v1/pages
qrtap_update_page(slug, content)	PATCH /api/v1/pages/{slug}

レビューと予約

ツール	対応先
qrtap_list_reviews(status?)	GET /api/v1/reviews（デフォルトは pending）
qrtap_moderate_review(reviewId, action) — 公開への影響あり	POST /api/v1/reviews/{id}/moderate
qrtap_list_bookings(status?)	GET /api/v1/bookings
qrtap_set_booking_status(bookingId, status) — 公開への影響あり	POST /api/v1/bookings/{id}/status

スマートリンク（条件付きリダイレクト）

ツール	対応先
qrtap_get_smart_rules(codeId)	GET /api/v1/codes/{id}/smart-rules
qrtap_set_smart_rules(codeId, rules) — 公開への影響あり	PUT /api/v1/codes/{id}/smart-rules

エージェントが知っておくべき2つのルール

上書きする前に読み取ってください。 qrtap_update_page と qrtap_set_smart_rules は、ペイロード全体を置き換えます。省略した内容はすべて消去されます。qrtap_get_page ／ qrtap_get_smart_rules で現在の状態を取得し、変更を反映してから、オブジェクト全体を送り返してください。

バッチ処理では external_ref を設定してください。 作成処理は external_ref によって冪等になるため、再試行した呼び出しでは重複を作成せず、既存のコードが返されます。これにより、一部が失敗したバッチを安全に再実行できます。

印刷用アーティファクト

すべてのコードで png_url と svg_url が返されます。印刷業者向けには、PDFを直接リクエストしてください。アーティファクトのエンドポイントにも同じBearerキーが必要です。

curl -H "Authorization: Bearer $QRTAP_API_KEY" \
  "https://app.qrtap.kg/api/v1/codes/$CODE_ID/qr?format=pdf" -o code.pdf

format は png | svg | pdf、size はPNGの幅を設定します（256～3000、印刷用途では約2000）。PNG出力は返される前にデコード検証されます。結果はエージェントが推論できるテキストではなくバイナリファイルであるため、レンダリングはツールとして公開されていません。

すぐに使えるエージェントスキル

印刷し直さずに変更できるメニュー、5分で作成できる専門家のページ、2GIS／Google／Yandexのレビュー用QRコード1つ、コードの一括発行、予約の受信トレイの処理など、よくある作業の手順をまとめたレシピは、リポジトリ内の skills/ にあります。それぞれが、アシスタントに渡せる単独で完結したMarkdownファイルです。

制限とプラン

すべての /api/v1 呼び出しには、ワークスペースのプランによって設定される、1分あたりの制限と1日あたりのクォータという2つの予算が適用されます。

プラン	1分あたり	1日あたり	有効なキー	一括処理とスキャンのWebhook
Free	60	100	1	いいえ
Standard	120	5,000	3	はい
Full	300	50,000	10	はい

無料プランは、開発者やエージェントが購入前に連携を試せるように用意されています。1日100回の呼び出しがあれば、構築やデモには十分ですが、ビジネスの運用には足りません。

予算を超えると、APIは 429 を返し、どちらの上限に達したかを示します。{"error":"rate_limited", "scope":"minute"} の場合は数秒待ち、{"error":"quota_exceeded","scope":"day"} の場合はUTCの午前0時まで待ちます。いずれにも Retry-After と X-RateLimit-Limit ／ -Remaining ／ -Reset ヘッダーが含まれます。ツールの結果にはこれらすべてがそのまま表示されるため、エージェントはリクエストを連続して送り続けず、間隔を空けられます。

どのプランでも、次の2つの呼び出しを優先するとよいでしょう。ループ処理の代わりに qrtap_create_codes_bulk を、コードごとの統計リクエストの代わりに qrtap_list_codes(include_stats=true) を使ってください。

qrtap_create_codes_bulk には有料プランが必要です。無料ワークスペースでは、現在のプランとアップグレードURLを含む 402 plan_required が返されます。その場合は、1日のクォータ内で qrtap_create_code をループして実行してください。現在のプラン制限は、プラットフォーム内の API_PLAN_LIMITS という1か所で管理されており、上の表もそれに基づいています。

エラー

API の失敗は、isError: true が設定された通常のツール結果として返されます。HTTP ステータスとレスポンスボディがテキストで含まれるため、エージェントはクラッシュせずに内容を読み取り、説明できます。不明なツール名のみが JSON-RPC エラー（-32602）になります。

ステータス	意味
401	キーがない、無効、または失効しています
402 plan_required	リクエストは有効ですが、プランの対象外です（一括処理、スキャン用 Webhook）
404	お使いのワークスペースに該当するオブジェクトがありません — 別のテナントの ID は意図的に、入力ミスと見分けがつかないようになっています
422	コンテンツが拒否されました：連絡先情報のないページ、または宣伝文句を含む QR キャプション
429	利用枠を使い切りました。scope を確認し、Retry-After に従ってください

ライセンスと利用規約 — 境界について

このパッケージのクライアントコードは MIT ライセンスです。自由に読んだり、フォークしたり、ベンダーとして取り込んだり、ご自身の製品に組み込んだりできます。ライセンスの許諾内容は LICENSE ファイルに記載されているものがすべてです。

このライセンスが適用されるのは、この軽量クライアントのみであり、それ以外は対象外です。QRTap API へのアクセスは別の扱いであり、お使いの QRTap プランと QRTap の利用規約に準拠します。サービス、ホスト型プラットフォーム、およびワークスペース内のデータは引き続き QRTap のものです。クライアントが MIT ライセンスであることは、API の利用資格を意味しません。API アクセスを含むプランの有効なキーが必要であり、通常の制限と利用規約が適用されます。

開発

モノレポでも公開ミラーでも、すべてのコマンドはこのパッケージのディレクトリから実行します：

npm install          # first time only
npm test             # vitest: tool→HTTP mapping and MCP dispatch
npm run typecheck

手動でのスモークテスト — 1 行につき JSON-RPC メッセージを 1 つ入力します：

npm run build    # dist/ must exist first
QRTAP_API_KEY=qrtap_key_XXXX node bin/qrtap-mcp.mjs <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list"}
EOF

公開されるパッケージは dist/ 内のコンパイル済み JavaScript で、実行時依存関係はありません。npx -y qrtap-mcp は約 22 kB をダウンロードし、事前にツールチェーンを取得することなく、通常の Node で起動します。prepack は npm pack および npm publish のたびに dist/ を再ビルドするため、ビルドされていないパッケージや古いパッケージが公開されることはありません。

npm run build     # tsc -p tsconfig.build.json → dist/

TypeScript のソースはリポジトリ内の src/ にあります（MIT ライセンス。下記参照）が、tarball には含まれていません。MCP stdio プロトコルは src/server.ts に直接実装されています。tsc はモジュール指定子を書き換えないため、インポートには明示的な .js 拡張子を付けています。これにより、出力された ESM が通常の Node で解決されます。

このリポジトリについて

これは qrtap-mcp npm パッケージの公開ソースです。サーバー、テスト、エージェントスキルが含まれています。QRTap プラットフォームのその他の部分（Web アプリ、API、データベース）は非公開で、プライベートリポジトリに置かれているため、このリポジトリの履歴は最初のコミットではなく、最初の公開リリースから始まっています。

意図的に含めていないテストが 1 つあります。plan-limits.test.ts はプラットフォームのデータベースパッケージからプラン一覧を読み込み、この README に記載された数値が実際の販売内容と一致するかを検証します。両方のリポジトリが揃っている環境でしか実行できないため、プライベートリポジトリに置いています。

サーバー、スキル、ドキュメントに関する Issue やプルリクエストは歓迎します。

リンク

• API リファレンスとキー — app.qrtap.kg/developers
• OpenAPI 仕様 — app.qrtap.kg/openapi.json
• プランと制限 — app.qrtap.kg/pricing
• Issue — github.com/IlyaShurf/qrtap-mcp/issues

MIT © 2026 QRTap（ИП Шуренков И.П.、Kyrgyz Republic）