Affitor

@affitor/mcp

Affitor 用の Model Context Protocol（MCP）stdio サーバーです。

Affitor のアフィリエイト追跡機能を MCP ツールとして公開するため、Claude Desktop、Cursor などの MCP クライアントを使う AI エージェントは、クリック、リード、売上、返金を報告したり、連携の準備状況を確認したりできます。これらの操作は、ツール呼び出しとして直接実行できます。

内部では、統合版サーバークライアント @affitor/sdk/server（Affitor クラス）をラップしています。認証には、AFFITOR_API_KEY 環境変数で指定するプログラム API キーを使用します。

MCP クライアントに追加する

クライアントの MCP サーバー設定に、以下を追加します（Claude Desktop の場合は claude_desktop_config.json、Cursor の場合は .cursor/mcp.json など）。

{
  "mcpServers": {
    "affitor": {
      "command": "npx",
      "args": ["-y", "@affitor/mcp"],
      "env": {
        "AFFITOR_API_KEY": "your_program_key"
      }
    }
  }
}

クライアントを再起動すると、affitor ツールをエージェントが利用できるようになります。

環境変数

変数	必須	説明
AFFITOR_API_KEY	はい	Affitor のプログラム API キー（Bearer）です。サーバー側でのみ使用し、ブラウザーに含めないでください。
AFFITOR_API_URL	いいえ	API のベース URL を上書きします。デフォルトは https://api.affitor.com です。
AFFITOR_MCP_WRITE	いいえ	1 に設定すると、金銭に関わる 2 つのツール affitor_track_sale と affitor_track_refund を登録します。デフォルトでは無効です。そのため、ツールを調べているエージェントが実際の売上を作成したり、コミッションを取り消したりすることはありません。

AFFITOR_API_KEY が設定されていない場合、サーバーは標準エラー出力に明確なメッセージを表示して終了します。

ツール

各ツールには MCP アノテーション（readOnlyHint、destructiveHint、idempotentHint）が付与されているため、クライアントは書き込み前に確認できます。affitor_track_sale と affitor_track_refund は破壊的としてマークされており、AFFITOR_MCP_WRITE=1 の場合にのみ利用できます。

ツール	説明
affitor_readiness	このプログラムの統合／オンボーディングの準備状況を確認します。5 つのゲートの判定、ブロッカー、次のアクションを返します。integration_verified が true になるまでポーリングしてください。
affitor_track_lead	リード／登録を報告します。顧客をクリックに紐付けるため、その後の売上は customerExternalId のみでアトリビューションできます。
affitor_track_sale	AFFITOR_MCP_WRITE=1 が必要です。売上を報告します。testMode が true でない限り、実際の売上とコミッションを作成します。アトリビューションは customerExternalId（リード時に紐付け済み）を使って解決します。
affitor_track_refund	AFFITOR_MCP_WRITE=1 が必要です。返金を報告します（amount を省略すると全額返金となり、コミッションが取り消されます。一部返金の場合は返金額として処理されます）。invoiceId による冪等性があります。testMode はドライランです。
affitor_track_click	クリックを報告します（通常はブラウザー側で実行します。公開されており、顧客情報は不要です）。
affitor_get_integration_plan	スタックに応じた決定論的な決済トラッキング統合プランを返します。インストール方法、チェックアウトのメタデータスニペット、trackSale スニペットとその挿入箇所、検証手順が含まれます。純粋関数 — 正規の @affitor/recipes レジストリを読み取ります。SDK クライアント、ネットワーク、または副作用はありません。エージェントは契約を推測せず、これに従います。
affitor_run_verification	合成的なクリック → リード → 売上の検証チェーンを、Affitor の実際のアトリビューションパイプラインに通して実行します（分離された is_test 行）。エージェントの証明手順です。これを実行し、integration_verified が true になるまで affitor_readiness をポーリングします。1 プログラムあたり 1 時間に 10 回までに制限されています。rate_limited の結果が返された場合は、retry_after_seconds の秒数だけ待ってください。連続してリクエストしないでください。

入力

affitor_readiness

• forceRecheck?: boolean — キャッシュされた判定ではなく、サーバー側で新たに再確認するよう強制します。

affitor_track_lead（customerExternalId / clickId のいずれかが必須）

• customerExternalId?: string — 独自のユーザー ID。クリックにこの顧客を紐付けます。
• clickId?: string — Affitor のクリック ID（affitor_click_id Cookie から取得）。
• email?: string
• testMode?: boolean — テストリードを記録します（is_test）。

affitor_track_sale（customerExternalId / clickId のいずれかが必須）

• customerExternalId?: string — 独自のユーザー ID。アトリビューションを解決します（リード時に紐付け済みであれば、clickId は不要です）。
• clickId?: string
• amount: number — セールス金額。整数のセント単位です（例：4999 = $49.99）。
• invoiceId: string — 冪等性キー（請求書 / 取引 ID）。
• currency?: string — ISO 通貨コード（デフォルトは USD）。
• saleType?: "payment" | "subscription"
• isRecurring?: boolean
• subscriptionId?: string
• subscriptionInterval?: "monthly" | "quarterly" | "annual"
• testMode?: boolean — テストセールを記録します（is_test、コミッションなし）。取引 ID として test_<invoiceId> が送信されるため、同じ請求書の実際のセールをブロックしません。

affitor_track_refund

• invoiceId: string — セールの冪等性キー（affitor_track_sale に渡した invoiceId）。
• refundAmountCents?: number — 整数のセント単位です。省略（または 0）すると全額返金となり、コミッションが取り消されます。一部返金の場合は返金済みとして処理されます。
• refundReason?: string
• testMode?: boolean — ドライランです。送信される予定の返金内容を返し、何も呼び出しません（API にはテスト返金機能がありません）。

affitor_track_click（すべて任意）

• affiliateUrl?: string
• pageUrl?: string
• referrerUrl?: string
• existingClickId?: string

affitor_get_integration_plan

• framework: "next-app" | "next-pages" | "fastify" | "express" | "node" | "unknown" — 検出されたアプリのフレームワークです。trackSale の挿入先を決定します。
• provider?: "stripe" | "polar" | "lemonsqueezy" | "paddle" | "unknown" — 検出された決済プロバイダーです（デフォルトは stripe）。
• mode?: "stripe_connect" | "s2s" — 決済トラッキングモードです（デフォルトは stripe_connect）。stripe_connect は、Connect がセールスを自動取得するモードです（メタデータのみで、trackSale はありません）。s2s は、Webhook に trackSale を挿入するモードです。{ steps, recipe } を返します。

affitor_run_verification（入力なし）

• 合成検証チェーンを実行し、解析済みの結果を返します。レート制限時は例外をスローするのではなく、{ http_status: 429, retry_after_seconds, … } を返します。待機してから再試行してください。

各ツールは、Affitor API の JSON ペイロードをテキストコンテンツとして返します。リクエストが失敗した場合（エラーがスローされた場合、または { ok: false } のエンベロープが返された場合）、ツールはメッセージを含む MCP エラー結果を返します。

ライセンス

MIT