Affitor

@affitor/mcp

一个适用于 Affitor 的 Model Context Protocol (MCP) stdio 服务。

它将 Affitor 的联盟跟踪功能作为 MCP 工具提供，因此 AI Agent（包括 Claude Desktop、Cursor 以及任何其他 MCP 客户端）可以直接通过工具调用报告点击、潜在客户、销售和退款，并查询集成就绪状态。

在底层，它封装了整合后的服务客户端 @affitor/sdk/server（Affitor 类）。身份验证使用你的程序 API 密钥，通过 AFFITOR_API_KEY 环境变量提供。

将其添加到 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"
      }
    }
  }
}

重启客户端后，Agent 即可使用 affitor 工具。

环境变量

变量	必需	说明
AFFITOR_API_KEY	是	你的 Affitor 程序 API 密钥（Bearer）。仅限服务端使用，切勿将其提供给浏览器。
AFFITOR_API_URL	否	API 基础 URL 覆盖值。默认为 https://api.affitor.com。
AFFITOR_MCP_WRITE	否	设置为 1，以注册两个会涉及资金变动的工具：affitor_track_sale 和 affitor_track_refund。默认关闭，因此探索工具的 Agent 无法创建真实销售或撤销佣金。

如果未设置 AFFITOR_API_KEY，服务会向 stderr 输出清晰的提示并退出。

工具

每个工具都带有 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。报告退款（省略金额表示全额退款 → 佣金已冲销；部分退款 → 已退款）。通过 invoiceId 实现幂等。testMode 表示试运行。
affitor_track_click	报告点击（通常在浏览器端执行；公开，无需客户信息）。
affitor_get_integration_plan	返回适用于某个技术栈的确定性支付跟踪集成计划——安装、结账元数据代码片段、trackSale 代码片段及其注入位置，以及验证步骤。纯操作——读取权威的 @affitor/recipes 注册表；无需 SDK 客户端、网络或副作用。Agent 应遵循此计划，而不是猜测接口约定。
affitor_run_verification	通过 Affitor 的真实归因流水线触发合成的点击 → 潜在客户 → 销售验证链（使用隔离的 is_test 行）。这是 Agent 的验证步骤：运行此工具，然后轮询 affitor_readiness，直到 integration_verified 为 true。频率限制为 每个程序每小时 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