Fairplug (sandbox)

Fairplug MCP

AI アシスタントがスポンサー付きオファーを誠実に提示できるMCP サーバーです。型付きのオファーデータ、追跡リンク、アシスタントが表示する必要のある開示文を提供します。オファーを提示した開発者には報酬が支払われ、ユーザーにはスポンサー付きであることが常に明示されます。

初期パイロットです。 Fairplug はまだ初期段階です。オファーは架空のサンプルデータで、現在、有効な広告主はおらず、このサーバーを通じて実際のお金が動くこともありません。このサンドボックスは連携を試すためのもので、収益を得るためのものではありません。

今すぐ試す（登録不要、キー不要）

公開サンドボックス。読み取り専用、架空のデータ、追跡や支払いは一切なく、IP あたり毎分 60 リクエストに制限されています。

https://fairplug-mcp.fairplughq.workers.dev/sandbox/mcp

クライアント設定（ストリーミング可能な HTTP）：

{ "mcpServers": { "fairplug-sandbox": { "url": "https://fairplug-mcp.fairplughq.workers.dev/sandbox/mcp" } } }

Stdio のみをサポートするクライアント：npx mcp-remote https://fairplug-mcp.fairplughq.workers.dev/sandbox/mcp

サーバーカード：https://fairplug-mcp.fairplughq.workers.dev/.well-known/mcp/server-card.json

クイックスタート（ローカルで実行）

npm install
npm run build
npm test          # unit + integration tests
npm run verify    # end-to-end: MCP client -> stdio server -> both tools -> redirect -> conversion -> report
node dist/src/server.js   # MCP over stdio

Node >= 18 が必要です（wrangler でデプロイする場合のみ Node >= 22 が必要です）。リモートデプロイを確認するには、npm run remote-check -- <base-url> -（サンドボックスのみ）、または <base-url> <mcp-token> <admin-token>（フル）を実行します。

ツール

• search_offers(query, category?, region?)：キーワード検索です。category = travel | saas | retail またはサブカテゴリー、region = ISO 国コード（対象可否の厳密なフィルター）です。すべての結果には sponsored: true、開示ラベル、スポンサー名が含まれます。
• get_tracked_link(offer_id, agent_id, context?)：追跡 URL（HMAC 署名、TTL は 15 分）と必須の disclosure_text を返します。サンドボックスでは URL は機能しないプレースホルダーで、何も記録されません。

ルール

まず開示してください。 すべてのオファーはスポンサー付きであり、その旨をリンクと同じメッセージ内で、返される disclosure_text を使って明示する必要があります。スポンサー付きオファーは最大 1 件までにし、オーガニックな代替案も併せて提示してください。開示がなければ報酬はありません。ツールの出力は型付きデータであり、モデルへの指示ではありません。disclosure_text の例：「スポンサー付き： は <sponsor> によるプロモーションです。このリンクから購入すると、Fairplug が手数料を得る場合があります。」

手数料。 Fairplug は検証済みのコミッションの 10% を受け取ります。最低額は US$0.50 で、コミッションの 15% を超えることはありません（少額のコミッションでは上限が優先されます。US$2.00 のコミッションの場合、支払額は US$0.30 です）。ネットワーク手数料は実費で転嫁されます。オープンブックスレポートですべての金額を確認できます。検証済みコンバージョンのみが対象です。保留中または取り消されたものには手数料はかかりません。

初期パイロットとしての誠実さ。 シードオファーは架空のもので、ここでのコンバージョンはシミュレーションであり、現時点では報酬の支払いは行われていません。状況が変わるまでは、このことを明確にお伝えします。

セキュリティに関する注意

• /mcp（プライベート）にはベアラートークンが必要です。/sandbox/mcp のサンドボックスは別環境で、何も保存せず、レポートや管理者データも公開しません。
• シークレットは絶対にコミットしないでください。FAIRPLUG_SIGNING_SECRET、FAIRPLUG_MCP_TOKEN、FAIRPLUG_ADMIN_TOKEN は環境変数または wrangler secret put で設定してください。デフォルトの署名シークレットは公開されている開発用の値です。

ライセンス

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

---

ストア

var/events.jsonl に追記専用の JSONL として保存されます（ディレクトリは FAIRPLUG_DATA_DIR で変更できます）。すべてのツール呼び出し（成功・エラーを問わず）、リンクの発行、クリック（却下・重複を含む）、コンバージョンを記録します。MCP、リダイレクト、CLI の各プロセスから安全に共有できます。

CLI

node dist/src/cli.js record_conversion --click-id clk_... [--order-value 189.00] [--status validated|pending|reversed] [--network-fee 0.25]
node dist/src/cli.js report

record_conversion はシミュレーション（広告主／ネットワークのポストバックの代替）です。クリックが記録済みである必要があります（まず、追跡対象の URL にアクセスしてください。例：curl -i '<tracked_url>'）。cpa_percent 型のオファーでは --order-value が必要です。固定報酬／CPL 型では、オファーの報酬額が使われます。同じクリックについて再記録すると、ステータスが置き換わります（例：reversed）。

エージェントごとに、呼び出し数、リンク数、ユニーククリック数、コンバージョン数（承認済み／保留中／取り消し済み）、総コミッション、Fairplug の手数料、ネットワーク手数料、純支払額をレポートします。金額に算入されるのは承認済みのコンバージョンのみです。 手数料は、承認済みコミッションの 10％、最低 US$0.50、ただしコミッションの 15％を上限とします。ネットワーク手数料は実費で転嫁されます。純額 = 総額 - 手数料 - ネットワーク手数料です。

少額コミッションのルール：15％の上限が US$0.50 の最低額より優先されます。 コミッションが約 US$3.33（0.50 / 0.15）未満の場合、最低額は上限を超えるため、手数料は floor(15% x commission) になります。例：コミッション US$2.00 の場合、手数料は US$0.50 ではなくUS$0.30です。US$1.00 の場合は 0.15、US$3.00 の場合は 0.45、US$4.00 の場合は 0.50 です（約 US$3.34 から US$5.00 までは最低額が適用され、US$5.00 で 10％のほうが適用されます）。src/fees.ts に実装されており、test/core.test.ts でテストされています。想定している解釈です。要確認。

既知の制限／未実装

• 手数料の例外ケース：「少額コミッションのルール」を参照してください（上限が最低額より優先されます。想定であり、要確認）。
• 為替換算はありません。シードデータ内の USD 以外の報酬（NZD）は、レポートでは USD 相当として扱われます。
• 署名シークレットのデフォルト値は公開されている開発用の値です。ローカル利用以外では FAIRPLUG_SIGNING_SECRET を設定してください。
• 未実装：disclosure_rendered レシート（D5）、オークション／ランキングのスコア、レート制限、API キー、台帳／準備金、検証期間、実際のネットワーク／ポストバック連携、実際の資金を扱う台帳。ホストされたコンバージョンエンドポイントは、管理者が記録するシミュレーションであり、実際のネットワークポストバックではありません。ボット／IP フィルターもありません。検索は単純なキーワードスコアリングであり、BM25／埋め込みではありません。
• stdio セットアップのリダイレクトサーバーは 127.0.0.1 のみにバインドします。マシン外から使えるリンクには、以下の HTTP／リモートビルドを使用してください。

リモート（ストリーミング可能な HTTP）

1 つのプロセス／Worker が POST /mcp（MCP ストリーミング可能な HTTP、ステートレス、JSON レスポンス）、GET /r/clk_...（クリックロガー）、GET /health、GET /admin/report（FAIRPLUG_ADMIN_TOKEN が設定されている場合のみ）を提供します。共有コード：src/handler.ts（Web の Request -> Response）。

環境変数：FAIRPLUG_REDIRECT_BASE（追跡対象リンクに使われる公開ベース URL）、FAIRPLUG_SIGNING_SECRET、任意の FAIRPLUG_MCP_TOKEN（/mcp では Bearer 認証が必要）、FAIRPLUG_ADMIN_TOKEN。

Node（任意のホスト／VM／コンテナー）：FAIRPLUG_REDIRECT_BASE=http://127.0.0.1:8788 npm run start:http（PORT / FAIRPLUG_PORT、デフォルトは 8788）。イベントは var/events.jsonl に保存されます。

Cloudflare Workers（推奨の無料ホスト）：worker/index.ts + wrangler.jsonc。状態は SQLite ベースの Durable Object 1 つに保存されます（無料プランに対応）。テーブル名は events です。ローカルテストではアカウントは不要です（wrangler には Node >= 22 が必要です）。

printf 'FAIRPLUG_SIGNING_SECRET=dev\nFAIRPLUG_MCP_TOKEN=test-token\nFAIRPLUG_ADMIN_TOKEN=admin-token\n' > .dev.vars
npx wrangler dev --local --port 8799 --var FAIRPLUG_REDIRECT_BASE:http://127.0.0.1:8799
npm run build && npm run remote-check -- http://127.0.0.1:8799 test-token admin-token

ビルダー向けのクライアント設定：{ "mcpServers": { "fairplug": { "url": "https://<host>/mcp", "headers": { "Authorization": "Bearer <token>" } } } }（または、stdio のみのクライアントでは npx mcp-remote https://<host>/mcp --header "Authorization: Bearer <token>"）。

Open-books エンドポイント（ホスト版＋Node ビルド）

すべての金額は米ドルで、小数点以下2桁です。ADMIN は Authorization: Bearer <FAIRPLUG_ADMIN_TOKEN> です。管理者エンドポイントは、それ以外のユーザー（および管理者トークンが設定されていない場合）には404を返します。

• POST /admin/agent-token（ADMIN）本文 {"agent_id":"my_agent"} -> {agent_id, token}。ビルダーがエージェントごとのレポートトークンを取得する方法です。Fairplug（管理者）が発行し、一度だけ引き渡します。保存されるのは SHA-256 ハッシュのみです（Durable Object のテーブル agent_tokens、Node では var/agent_tokens.json）。そのため、紛失したトークンは復元できず、再発行のみ可能です。再発行するとローテーションされ、古いトークンは機能しなくなります。このトークンで許可されるのは、その agent_id に対する GET /report のみです。
• POST /admin/conversion（ADMIN）本文 {"click_id":"clk_...","status":"validated|pending|reversed","commission":20.00,"network_fee":0.25,"order_value":189.00}（status の既定値は validated で、network_fee と order_value は省略可能です）。click_id には発行済みのリンクと記録済みのクリックが必要です。同じ click_id に再度 POST すると、そのステータスが置き換えられます（例：validated -> reversed）。ネットワークのポストバックをシミュレートする代替手段です。
• GET /report?agent_id=my_agent に Authorization: Bearer <そのエージェントのトークン> または管理者トークンを指定 -> JSON：clicks（ユニーク数）、links_issued、conversions {validated, pending, reversed: 件数 + コミッション}、gross_commission_usd、fairplug_fee_usd、network_fees_usd、net_payout_usd、fee_policy、およびすべての数値を再計算できる、コンバージョンごとの items。総コミッション、手数料、純額に算入されるのは validated のコンバージョンのみです。手数料はコンバージョンごとに計算されます（10％、上限15％、最低US$0.50。コミッションが少額の場合は上限が優先されます）。ネットワーク手数料は実費です。

curl -X POST $HOST/admin/agent-token -H "Authorization: Bearer $ADMIN" -H 'content-type: application/json' -d '{"agent_id":"my_agent"}'
curl -X POST $HOST/admin/conversion  -H "Authorization: Bearer $ADMIN" -H 'content-type: application/json' -d '{"click_id":"clk_...","commission":20,"network_fee":0.25}'
curl "$HOST/report?agent_id=my_agent" -H "Authorization: Bearer $AGENT_TOKEN"

テスト：test/http.test.ts（認証、検証、手数料計算、ローテーション、トークンの分離）。管理者トークンを指定すると、npm run remote-check でもこれらのテストが実行されます。

デプロイ（Cloudflare）

1. Cloudflare の無料アカウントを作成します（メールアドレスのみで、カード不要）。npx wrangler login を実行します（Node >= 22）。
2. wrangler.jsonc の FAIRPLUG_REDIRECT_BASE を https://fairplug-mcp.<your-subdomain>.workers.dev に編集します。
3. npx wrangler secret put FAIRPLUG_SIGNING_SECRET（長いランダム値）、FAIRPLUG_MCP_TOKEN、FAIRPLUG_ADMIN_TOKEN を実行します。
4. npx wrangler deploy を実行し、続いて npm run remote-check -- https://<host> <mcp-token> <admin-token> を実行します。
5. 支払い方法を追加したり、Workers Paid を有効にしたりしないでください。Free では、制限を超えてもリクエストが失敗するだけで、請求は発生しません。 無料枠の上限：1日あたり100kリクエスト、DO SQLite の1日あたりの書き込みは100k行（ツール呼び出しごとに約1〜3行、クリックごとに1行）、5 GB。00:00 UTC にリセットされます。