Benefits City

Benefits City — 一个 AI Agent City 项目

经人工核实的美国银行开户奖励和信用卡申请奖励，提供两种方式：

受众	界面	使用方式
人类	服务端渲染的网站：落地页、可筛选浏览、奖励详情页、Agent 文档	npm start → /、/bonuses、/bonuses/:id、/agents
Agent	MCP 服务 — 通过 Streamable HTTP（POST /mcp）和 stdio 提供 6 个工具	npm start → /mcp · npm run mcp
Agent	JSON 数据源 + llms.txt	/api/bonuses.json、/api/bonuses/:id、/api/stats、/llms.txt
运营者	CLI，使用与 MCP 相同的数据和逻辑，JSON 输出到 stdout	npm run cli -- …

一个数据库，两种一等界面。落地页上的实时统计数据根据真实数据计算，不会过时。

安装与运行

cd ~/workspace/bank-bonus-agent
npm install                    # builds better-sqlite3 (metrics); with --ignore-scripts run `npm rebuild better-sqlite3`
npm run build                  # tsc -> dist/
npm run test                   # tsc + node:test suite (dist/tests)
npm run freshness              # daily source check -> data/review-queue.json (see REFRESH_PLAN.md)
npm start                      # prestart seeds data/bonuses.json, then serves on PORT (default 3000)

实用环境变量：

变量	默认值	说明
PORT	3000	监听端口（Railway 会注入自己的端口）
BASE_PATH	""	挂载到子路径下，例如 /benefits — 所有链接、资源和表单都会相应调整
PUBLIC_URL	派生值	文档和 llms.txt 使用的规范公开 URL，例如 https://aiagentscity.com/benefits
BONUS_DB_PATH	data/bonuses.json	覆盖 JSON 存储位置

其他命令：npm run mcp（stdio MCP 服务）、npm run cli -- …、npm run seed（可重复运行的 upsert）、npm run typecheck。

面向 Agent：通过 MCP 连接

Streamable HTTP — 任何兼容 MCP 的客户端（Claude、Claude Code、Muse 等），无需 API 密钥（参见 /auth.md）：

POST {PUBLIC_URL}/mcp

Claude Code，一行命令：

claude mcp add --transport http benefits-city https://aiagentscity.com/benefits/mcp

发现入口：/server.json（MCP 注册表清单，也位于 /.well-known/mcp.json）、/.well-known/agent.json、/.well-known/mcp/server-card.json（根据实时工具列表生成）、/openapi.json（OpenAPI 3.1）、/auth.md、/llms.txt、/skill.md（也作为 skill://benefits-city/benefits-city/SKILL.md MCP 资源提供）、/docs（/agents 的别名）以及 /changelog（另有 /changelog.json、/feed.xml；数据位于 changelog/changelog.json）。

与 MCP 工具功能一致的 REST 接口：GET /api/search、/api/expiring、/api/compare?ids=a,b、/api/bonuses/:id、/api/bonuses.json、/api/stats — 使用相同的筛选条件和公开数据格式，错误格式为 {"error":{"type","message","code?","param?"}}（400 会指出错误参数；未知或已过期的 ID 返回 404）。

Claude Code / Claude Desktop 配置（通过 mcp-remote）：

{
  "mcpServers": {
    "benefits-city": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://aiagentscity.com/benefits/mcp"]
    }
  }
}

本地 stdio（可自托管）：运行 npm run build 后执行 node dist/mcp-server.js。

Agent 交互示例：

# Which checking bonuses pay $400+ and don't require direct deposit?
search_bonuses({ "bonus_type": "bank_account", "min_bonus_amount_usd": 400,
                 "direct_deposit_required": false })

# Full terms for one offer
get_bonus({ "id": "chase-total-checking-400" })

# What's expiring in the next 2 weeks?
expiring_soon({ "days": 14 })

# Head-to-head
compare_bonuses({ "ids": ["bmo-checking-600", "sofi-checking-savings-400"] })

也可通过 shell 使用（通过管道传输时，请直接使用 node dist/cli.js — npm run 会打印横幅）：

node dist/cli.js search --type bank_account --state TX --min 300 --pretty
node dist/cli.js get chase-total-checking-400 --pretty
node dist/cli.js expiring --days 30
node dist/cli.js compare bmo-checking-600 sofi-checking-savings-400

通过 HTTP：

curl localhost:3000/api/bonuses.json | jq '.[].id'
curl localhost:3000/api/bonuses/us-bank-smartly-checking-450
curl localhost:3000/api/stats | jq '{total_offers, total_bonus_usd}'
curl localhost:3000/llms.txt

工具契约

工具	输入	输出
search_bonuses	bonus_type?（bank_account|credit_card|savings|brokerage）、state?（2 位字母代码；全国范围始终匹配）、min_bonus_amount_usd?、direct_deposit_required?、query?（银行／产品子字符串）、limit?（1–100，默认值为 25）	奖励记录数组，按奖励金额从高到低排列
get_bonus	id	完整记录，或带类型的 not_found 错误
expiring_soon	days?（1–365，默认值为 30）	记录中注明的到期日期在指定时间范围内的记录，按到期时间从近到远排列。不包含未注明到期日期的优惠
compare_bonuses	ids（2–4 个）	{ bonuses: [...], summary: { highest_bonus_usd, earliest_expiry } }，或列出未知 id 的带类型 not_found 错误
benefits_api_docs	—	Markdown 文档：工具、字段、排序保证、错误格式
benefits_examples	—	可运行的示例调用 {title, tool, arguments}

MCP／CLI／数据源返回的每条记录均由 toPublic()（src/links.ts）处理：不会公开原始 affiliate_url；使用方会获得 apply_url（我们的 /go/:id 跟踪链接）、 sponsored（布尔值）和 disclosure_url。排序按奖励金额降序（金额相同时按 id 排序），且 绝不会受到佣金影响（由测试强制保证）。不会返回已过期的优惠。 错误使用 {"error":{"type","message","code?","param?"}} 格式。

工具定义位于 src/mcp-tools.ts，由 stdio 服务和 Streamable HTTP 传输共用，以确保契约不会出现偏差。（无状态 HTTP 遵循 SDK 模式：每个请求创建一个全新的服务和传输。）

数据架构（每条记录）

id（kebab-case） · bank_or_issuer · product_name · bonus_type（bank_account | credit_card | savings | brokerage） · bonus_amount_usd（银行账户：公布的奖励；信用卡：积分／里程奖励的预估美元价值——估值依据注明在 requirements 中） · bonus_points · annual_fee_usd · requirements[]（通俗易懂的资格条件步骤） · min_deposit_usd · direct_deposit_required · expiry_date（YYYY-MM-DD，null = 未注明截止日期） · states_available（"nationwide" 或州代码数组） · application_url · source_url（确认当前条款的来源） · last_verified_date · verification（issuer_page = 已获取发行方自己的页面；aggregator_consensus = 至少 3 个可靠的列表信息一致；另含 verified_at 和 sources[]） · status（active | expired | needs_review） · offer_history[] · eligibility（结构化，可为 null） · affiliate_url（仅作输入——供 /go/:id 使用，绝不公开）。

“今天”指美国东部时区的日历日期：有效期至 9/30 的优惠会在东部时间 9/30 全天提供。

初始数据来源

共 33 条记录（15 条银行账户、17 条信用卡、1 条储蓄）。基础数据集于 2026-09-20 在线核实；在 2026-09-30（D-1518），对即将到期且影响最大的记录进行了 再次核实，从发行方页面新增了 4 条优惠，并有意排除无法核实的说法。 每条记录都包含 source_url、verification 和 last_verified_date；没有任何内容是捏造的。 详见 REFRESH_PLAN.md。

已知注意事项：Chase 和 Wells Fargo 没有找到官方优惠页面的原文 URL，因此 application_url 指向确认条款的页面；BMO 的记录在两个 URL 字段中都使用了 Doctor of Credit 页面。之后可替换为真实的银行 URL／联盟链接。

刻意保留为占位内容的部分

• application_url = 官方申请页面，而非联盟链接。 用户自行注册银行的联盟计划；获批后替换 URL（src/site.ts 中标记为 AFFILIATE_PLACEHOLDER；还要更新披露页面的“当前状态”部分）。
• 刷新仅检测并提交审核，不会自动发布。 npm run freshness 会将已过期、已变更或金额不匹配的优惠报告到审核队列；由人工或 Agent 编辑 seed-data/ — 参见 REFRESH_PLAN.md。
• 单节点 JSON 存储（data/bonuses.json，原子写入）。目前的规模下足够；如果将来出现并发写入者，则迁移到 Postgres/SQLite。

部署

此应用已适配 Railway（start 脚本、遵循 PORT、engines: node >= 20、一个原生依赖项（better-sqlite3，预构建二进制文件）、prestart 会填充数据库）。它通过反向代理部署在 aiagentscity.com/benefits，使用 BASE_PATH=/benefits。简明步骤： RAILWAY_DEPLOY.md。

目录结构

src/
  web-server.ts   site + feeds + /mcp (Streamable HTTP) + /api/stats  [npm start]
  site.ts         server-rendered pages: landing, browse, detail, agents, about/disclosure/contact
  stats.ts        live stats computed from the real data
  mcp-tools.ts    MCP tool definitions (shared by stdio + HTTP)
  mcp-server.ts   MCP server (stdio) — `npm run mcp`
  cli.ts          operator CLI (JSON on stdout)
  db.ts           JSON data store + query functions (search/get/expiring/list)
  compare.ts      shared compare logic (MCP + CLI)
  seed.ts         seed loader (validates, upserts AND prunes: seed-data/*.json is the source of truth)
  types.ts        Bonus schema types
  links.ts        apply-URL resolution, toPublic() shaping, disclosure wording
  meta.ts         version constants, server.json + auth.md builders
  freshness.ts    pure source-page classifier (blocked is not dead)
  freshness-cli.ts  daily check runner -> data/review-queue.json (`--canary` proves it can go red)
  tests/          node:test suite (npm run test)
skill/            product skill served over MCP (skill://benefits-city/benefits-city/SKILL.md)
seed-data/        researched offers (bank-account, credit-card, savings, brokerage JSON files)
data/             bonuses.json (generated by npm run seed / prestart; gitignored)
public/assets/    site.css (no build step)
public/llms.txt   static reference copy (server generates the live one per-host)
screenshots/      headless-Chromium captures of the pages
REFRESH_PLAN.md   how the feed stays fresh
RAILWAY_DEPLOY.md foolproof Railway + reverse-proxy steps