Fairplug (sandbox)

Fairplug MCP

一个 MCP 服务，可让 AI 助手如实展示赞助优惠：提供类型明确的优惠数据、跟踪链接，以及助手必须展示的披露文本。展示优惠的开发者可获得报酬；用户始终知道这是赞助内容。

早期试点。 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 签名，有 15 分钟 TTL）和必需的 disclosure_text。在沙盒中，该 URL 是无功能的占位符，不会记录任何内容。

规则

先披露。 每项优惠都是赞助内容，必须在包含链接的同一条消息中标注，并使用我们返回的 disclosure_text。最多展示一项赞助优惠，并同时提供自然搜索结果作为替代选项。不披露，不付款。工具输出是类型明确的数据，绝不是给模型的指令。disclosure_text 示例：“赞助内容： 由 <sponsor> 推广。如果您通过此链接购买，Fairplug 可能会获得佣金。”

费用。 Fairplug 收取已验证佣金的 10%，最低 US$0.50，且绝不超过佣金的 15%（对于小额佣金，以封顶比例为准：US$2.00 的佣金需支付 US$0.30）。网络费用按实际成本转嫁。您可以在公开账目报告中查看每一笔金额。只有已验证的转化才计入。任何待处理或已撤销的项目都不收取费用。

如实说明早期试点。 种子优惠均为虚构内容；此处的转化是模拟的；目前尚未进行任何付款。在情况改变之前，我们会始终明确说明这一点。

安全说明

• /mcp（私有端点）需要 bearer token；/sandbox/mcp 沙盒是独立的，不存储任何内容，也不会公开报告或管理数据。
• 切勿提交机密信息。将 FAIRPLUG_SIGNING_SECRET、FAIRPLUG_MCP_TOKEN、FAIRPLUG_ADMIN_TOKEN 设置为环境变量，或使用 wrangler secret put。默认签名密钥是公开的开发用值。

许可证

MIT，详见 LICENSE。

---

存储

仅追加写入 var/events.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 是一种模拟（用于代替广告主／网络的 postback）。要求已记录点击（先打开跟踪 URL，例如 curl -i '<tracked_url>'）。cpa_percent 优惠需要 --order-value；固定金额／CPL 使用该优惠的支付金额。对同一次点击重复记录会替换其状态（例如 reversed）。

按 Agent 报告：调用次数、链接数、独立点击数、转化次数（已验证／待处理／已撤销）、总佣金、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.30（而不是 0.50）；US$1.00 -> 0.15；US$3.00 -> 0.45；US$4.00 -> 0.50（最低费用适用于约 US$3.34 至 US$5.00，之后由 10% 的费用取代）。已在 src/fees.ts 中实现，并由 test/core.test.ts 覆盖。此解释为假设，请确认。

已知限制／尚未实现

• 费用边界情况：参见上文“小额佣金规则”（上限优先于最低费用；此为假设，请确认）。
• 不支持货币兑换：种子数据中的非 USD 支付金额（NZD）在报告中按等值 USD 处理。
• 签名密钥默认使用公开的开发值；除本地使用外，请设置 FAIRPLUG_SIGNING_SECRET。
• 尚未构建：disclosure_rendered 收据（D5）、竞价／排名分数、速率限制、API 密钥、账本／储备金、验证时限、真实网络／postback 集成、真实资金账本；托管的转化端点是由管理员记录的模拟，并非真实网络 postback，也不支持机器人／IP 过滤。搜索采用简单的关键词评分，不使用 BM25／embeddings。
• stdio 设置中的重定向服务仅绑定到 127.0.0.1；如需使用在本机以外也能工作的链接，请使用下方的 HTTP／远程版本。

远程（可流式传输的 HTTP）

一个进程／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 中（兼容免费计划），表名为 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}。这是构建者获取每个 Agent 专属报告令牌的方式：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 再次提交会替换其状态（例如 validated -> reversed）。这是网络回传的模拟替代方案。
• GET /report?agent_id=my_agent，使用 Authorization: Bearer <该 Agent 的令牌> 或管理员令牌 -> 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%，上限 US$0.50，最低 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 套餐时，超出限制只会导致请求失败，不会产生费用。 免费套餐限制：每天 100k 次请求，DO SQLite 每天 100k 次行写入（每次工具调用约写入 1-3 行，每次点击写入 1 行），5 GB；于 00:00 UTC 重置。