QR for Agent

QR for Agent

AI エージェント向けに構築された、QR コードのサービスとしての API です。REST API または MCP（37 個のツール）を介して、動的 QR コードをプログラムから作成、更新、追跡できます。

QR コードは短縮 URL（/r/:shortId）を参照し、いつでも転送先を変更できます。QR コードの画像は変わりませんが、スキャンすると新しい転送先に移動します。マルチテナントを前提に設計されており、詳細なスキャン分析機能を備えています。

ライブ API： api.qrforagent.com  |  サイト： qrforagent.com  |  MCP： qr-for-agent

機能

• 動的 QR コード — 画像を再生成せずに転送先 URL を変更できます
• 11 種類の QR コード — URL、vCard、WiFi、メール、SMS、電話、イベント、テキスト、位置情報、ソーシャル、アプリストア
• カスタムスタイル — ドット形状（四角、角丸、ドット、クラシックな角丸）、コーナースタイル、色、グラデーション、ロゴの埋め込み、CTA テキスト付きフレーム
• SVG と PNG — ベクター形式とビットマップ形式で出力できます
• 詳細な分析機能 — デバイスの種類、ブラウザー、OS、国、都市、リファラー、日別スキャン数
• リアルタイムの Webhook — HMAC-SHA256 署名付きペイロードと配信ログ
• UTM トラッキング — 転送先 URL に UTM パラメーターを自動追加します
• GTM サポート — Google Tag Manager スニペットを含む中間ページ
• 条件付きリダイレクト — デバイス、OS、国、言語、時間帯、または A/B 分割によるルーティング
• カスタムドメイン — Pro ユーザーは独自のドメインで短縮 URL をブランド化できます（qr.yourbrand.com/r/abc123）
• 有効期限とスケジュール設定 — QR コードを自動で期限切れにするか、URL の切り替えをスケジュールできます
• コンバージョントラッキング — スキャン後のイベント（購入、登録）を追跡するトラッキングピクセルと API、および ROI 分析
• フレームとテンプレート — CTA テキスト付きの QR コード装飾フレーム（banner_top、banner_bottom、rounded）
• 一括操作 — 1 回のリクエストで最大 50 個の QR コードを作成、更新、削除できます。または CSV アップロードで最大 500 個まで対応します（Pro）
• マルチテナント — 各 API キーからは、そのキー自身のデータのみを参照できます
• MCP サーバー — Claude Desktop、Cursor など向けに 37 個のツールを備えた qr-for-agent
• プラン別の使用量上限 — Free（QR コード 10 個、月間スキャン数 1,000 件）と Pro（月額 19 ドル、無制限）
• セルフサービス登録 — メールアドレスを使った POST /api/register。クレジットカードは不要です
• Stripe 連携 — チェックアウト、請求ポータル、Webhook によるプラン管理
• OpenAPI ドキュメント — /documentation にある Swagger UI
• AI による検出に対応 — /.well-known/ai-plugin.json と /.well-known/mcp.json
• オープンソース — MIT ライセンス。Docker を使ってセルフホストできます

クイックスタート

git clone https://github.com/benswel/qr-for-agent-api.git
cd qr-for-agent-api
npm install
npm run dev

初回起動時に API キーが自動生成され、コンソールに表示されます。

curl -X POST http://localhost:3100/api/qr \
  -H "Content-Type: application/json" \
  -H "X-API-Key: qr_YOUR_KEY_HERE" \
  -d '{"target_url": "https://example.com", "label": "My first QR"}'

API エンドポイント

QR コード管理（X-API-Key が必要）

メソッド	パス	説明
POST	/api/qr	QR コードを作成します（11 種類、カスタムスタイル対応）
GET	/api/qr	すべての QR コードを一覧表示します（ページネーション対応）
GET	/api/qr/:shortId	QR コードの詳細を取得します
PATCH	/api/qr/:shortId	転送先 URL、ラベル、UTM、GTM、リダイレクトルールを更新します
DELETE	/api/qr/:shortId	QR コードとその分析データを削除します
GET	/api/qr/:shortId/image	QR コード画像をダウンロードします（保存済みのスタイルで再生成）
POST	/api/qr/bulk	最大 50 個の QR コードを作成します（全件成功または全件失敗）
PATCH	/api/qr/bulk	最大 50 個の QR コードを更新します（一部成功に対応）
DELETE	/api/qr/bulk	最大 50 個の QR コードを削除します（一部成功に対応）
POST	/api/qr/bulk/csv	CSV から最大 500 個の QR コードを作成します（Pro のみ）

分析（X-API-Key が必要）

メソッド	パス	説明
GET	/api/analytics/:shortId	スキャン統計を取得します。デバイス、ブラウザー、OS、国、都市別の内訳とコンバージョンを確認できます

変換（X-API-Key が必要）

メソッド	パス	説明
POST	/api/conversions	所有する QR コードのコンバージョンイベントを記録します
GET	/api/conversions/:shortId	コンバージョンの統計（合計、イベント別、日別、最近のデータ）を取得します

Webhook（X-API-Key が必要）

メソッド	パス	説明
POST	/api/webhooks	Webhook エンドポイントを登録します（HMAC シークレットを返します）
GET	/api/webhooks	すべての Webhook を一覧表示します
DELETE	/api/webhooks/:id	Webhook を削除します

カスタムドメイン（X-API-Key が必要、Pro のみ）

メソッド	パス	説明
GET	/api/domain	現在のカスタムドメインと DNS のステータスを取得します
PUT	/api/domain	カスタムドメインを設定します
DELETE	/api/domain	カスタムドメインを削除します

アカウント（X-API-Key が必要）

メソッド	パス	説明
GET	/api/usage	現在の使用状況とクォータ
POST	/api/stripe/checkout	Stripe Checkout セッションを作成します（Pro にアップグレード）
POST	/api/stripe/portal	Stripe の請求ポータルを開きます

パブリック（認証不要）

メソッド	パス	説明
POST	/api/register	セルフサービスで API キーを登録します（レート制限あり）
GET	/r/:shortId	ターゲット URL にリダイレクトします（スキャンを記録）
GET	/t/:shortId	コンバージョントラッキングピクセル（1×1 GIF を返します）
GET	/i/:shortId	QR 画像を提供します（キャッシュ可能）
GET	/health	ヘルスチェック
GET	/documentation	Swagger UI
GET	/.well-known/ai-plugin.json	AI プラグインマニフェスト
GET	/.well-known/mcp.json	MCP 検出マニフェスト

管理者（X-Admin-Secret ヘッダーが必要）

メソッド	パス	説明
GET	/api/admin/keys	登録済みのすべての API キーを一覧表示します
GET	/api/admin/stats	ダッシュボードの指標

認証

すべての /api/* エンドポイントには X-API-Key ヘッダーが必要です。

• 形式：qr_ + 32 文字のランダム文字列
• 自動生成：キーがない場合、初回起動時に生成されます
• マルチテナント：各キーからは、そのキーが所有する QR コードのみを参照できます
• キーの作成：npm run key:create "my-label"
• キーの一覧表示：npm run key:list

パブリックエンドポイント（/r/*、/i/*、/health、/documentation、/.well-known/*）には認証は不要です。

MCP サーバー

npm で qr-for-agent として公開されています。AI エージェントが QR コードをネイティブに管理するための 37 個のツールを提供します。

npx qr-for-agent

Claude Desktop / Cursor

MCP 設定（claude_desktop_config.json または .cursor/mcp.json）に追加します：

{
  "mcpServers": {
    "qr-for-agent": {
      "command": "npx",
      "args": ["-y", "qr-for-agent"],
      "env": {
        "API_KEY": "your-api-key",
        "BASE_URL": "https://api.qrforagent.com"
      }
    }
  }
}

利用可能なツール（37）

ツール	説明
create_qr_code	カスタムスタイルを任意で指定してURLのQRコードを作成します
get_qr_code	短縮IDでQRコードの詳細を取得します
update_qr_destination	QRコードのリダイレクト先を変更します
list_qr_codes	ページネーションを使ってすべてのQRコードを一覧表示します
delete_qr_code	QRコードとその分析データを削除します
get_qr_analytics	スキャン数と内訳を取得します
bulk_create_qr_codes	一度に最大50個のQRコードを作成します
bulk_update_qr_codes	一度に最大50個のQRコードを更新します
bulk_delete_qr_codes	一度に最大50個のQRコードを削除します
create_vcard_qr	vCard連絡先のQRコードを作成します
create_wifi_qr	WiFi認証情報のQRコードを作成します
create_email_qr	メール（mailto:）のQRコードを作成します
create_sms_qr	SMSのQRコードを作成します
create_phone_qr	電話発信のQRコードを作成します
create_event_qr	カレンダーイベントのQRコードを作成します
create_text_qr	プレーンテキストのQRコードを作成します
create_location_qr	地理的位置情報のQRコードを作成します
create_social_qr	ソーシャルメディアリンクのQRコードを作成します
create_app_store_qr	アプリストアへスマートリダイレクトするQRコードを作成します
update_vcard_qr	vCardのQRコードを更新します
update_wifi_qr	WiFiのQRコードを更新します
update_social_qr	ソーシャルメディアのQRコードを更新します
update_app_store_qr	アプリストアのQRコードを更新します
create_webhook	Webhookエンドポイントを登録します
list_webhooks	登録済みのすべてのWebhookを一覧表示します
delete_webhook	Webhookを削除します
register	APIキーを登録します
get_usage	現在の使用量とクォータを取得します
upgrade_to_pro	Stripe Checkoutセッションを作成します
manage_billing	Stripeの請求ポータルを開きます
set_utm_params	QRコードにUTMトラッキングパラメーターを設定します
set_redirect_rules	QRコードに条件付きリダイレクトルールを設定します
set_custom_domain	カスタムドメインを設定または削除します（Pro）
get_custom_domain	現在のカスタムドメインとDNSの状態を取得します
bulk_create_from_csv	CSVデータから最大500個のQRコードを作成します（Pro）
record_conversion	スキャン後のコンバージョンイベントを記録します
get_conversions	QRコードのコンバージョン統計を取得します

設定

.env.exampleを.envにコピーして編集します。

変数	デフォルト	説明
PORT	3100	HTTPポート
HOST	0.0.0.0	バインドアドレス
BASE_URL	http://localhost:3100	公開URL（短縮URLで使用）
DATABASE_URL	./data/qr-agent.db	SQLiteファイルのパス
SHORT_ID_LENGTH	8	生成される短縮IDの長さ
ADMIN_SECRET	(なし)	管理者エンドポイント用のシークレット（X-Admin-Secretヘッダー）
STRIPE_SECRET_KEY	(なし)	Stripe APIシークレットキー
STRIPE_WEBHOOK_SECRET	(なし)	Stripe Webhook署名シークレット
STRIPE_PRICE_ID	(なし)	ProプランのStripe Price ID

データベース

Drizzle ORMを使用したSQLiteです。テーブルは6つあります。

• api_keys — ラベル、メールアドレス、プラン（free/pro）、Stripe ID、カスタムドメインを含むキーの保存
• qr_codes — QRコードのメタデータ、ターゲットURL、タイプ／type_data、スタイルオプション、UTM、GTM、リダイレクトルール、有効期限／スケジュール
• scan_events — スキャンの追跡：タイムスタンプ、ユーザーエージェント、リファラー、IP、デバイス、ブラウザー、OS、国、都市
• webhooks — APIキーごとのWebhookエンドポイント、HMACシークレット、購読イベント
• webhook_deliveries — 配信ログ：ステータス、レスポンスコード、エラーメッセージ
• conversion_events — コンバージョンの追跡：イベント名、値、メタデータ、リファラー、IP、タイムスタンプ

npm run db:generate   # Generate migration from schema changes
npm run db:migrate    # Apply pending migrations
npm run db:studio     # Open Drizzle Studio (web UI)

マイグレーションはサーバーの起動時に自動実行されます。

デプロイ

Docker

docker compose up -d

データベースはDockerボリュームに保存されます。

Railway

このプロジェクトにはrailway.tomlとマルチステージのDockerfileが含まれています。GitHubリポジトリをRailwayに接続すると、/healthでのヘルスチェックとともにビルドとデプロイが自動的に行われます。

テスト

すべてのエンドポイント、認証、マルチテナント分離、QR タイプ、Webhook、一括操作、カスタムドメイン、フレーム、変換、CSV アップロード、分析を対象とする、195 件の統合テストがあります。

npm test           # Run all tests
npm run test:watch # Watch mode

スクリプト

スクリプト	説明
npm run dev	自動リロード付きで開発サーバーを起動します
npm run build	TypeScript をコンパイルします
npm start	本番サーバーを実行します
npm test	テストスイートを実行します
npm run test:watch	ウォッチモードでテストを実行します
npm run key:create	API キーを作成します
npm run key:list	API キーを一覧表示します
npm run db:generate	マイグレーションを生成します
npm run db:migrate	マイグレーションを実行します
npm run db:studio	Drizzle Studio を開きます

ライセンス

MIT