Benefits City

Benefits City — an AI Agent City プロジェクト

手作業で検証した米国の銀行口座開設ボーナスとクレジットカード入会ボーナスを、 2 つの方法で提供します。

対象	インターフェース	方法
人間	サーバーでレンダリングされるサイト：ランディングページ、フィルター可能な一覧、ボーナス詳細ページ、エージェント向けドキュメント	npm start → /、/bonuses、/bonuses/:id、/agents
エージェント	MCP サーバー — Streamable HTTP（POST /mcp）と stdio で利用できる 6 つのツール	npm start → /mcp · npm run mcp
エージェント	JSON フィード + llms.txt	/api/bonuses.json、/api/bonuses/:id、/api/stats、/llms.txt
運用者	CLI。MCP と同じデータとロジックを使用し、標準出力に JSON を出力	npm run cli -- …

1 つのデータベースと、2 つの主要なインターフェース。ランディングページのライブ統計は実データから計算されるため、古くなることはありません。

インストールと実行

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（再実行可能なアップサート）、npm run typecheck。

エージェント向け：MCP 経由で接続

Streamable HTTP — MCP 対応のあらゆるクライアント（Claude、Claude Code、Muse など）で利用できます。 API キーは不要です（/auth.md を参照）。

POST {PUBLIC_URL}/mcp

Claude Code の場合、1 行で設定できます：

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 は無効なパラメーター名を示し、404 は不明または期限切れの ID に対して返されます）。

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 を実行します。

エージェントとのやり取りの例：

# 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"] })

シェル経由でも同様に実行できます（パイプ処理では 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（bool）、disclosure_url が渡されます。並び順はボーナス額の降順（同額の場合は ID 順）で、コミッションの影響を受けることはありません（テストで保証）。期限切れの特典は返されません。 エラー形式は {"error":{"type","message","code?","param?"}} です。

ツール定義は src/mcp-tools.ts にあり、stdio サーバーと Streamable HTTP トランスポートで共有されるため、契約にずれが生じることはありません。（ステートレス HTTP は SDK のパターンに従い、リクエストごとに新しいサーバーとトランスポートを使用します。）

データスキーマ（レコードごと）

id（ケバブケース） · bank_or_issuer · product_name · bonus_type（bank_account | credit_card | savings | brokerage）· bonus_amount_usd（銀行口座：広告に掲載されたボーナス額。クレジットカード：ポイント／マイルのボーナスの推定 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（構造化データ、nullable）· affiliate_url（入力専用 — /go/:id で使用。公開されません）。

「今日」は米国東部時間の暦日です。有効期限が 9/30 の特典は、9/30 ET の終日提供されます。

シードデータの出典

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 は、期限切れ／変更あり／ 金額不一致のオファーを確認キューに報告します。人またはエージェントが seed-data/ を編集してください。 詳しくはREFRESH_PLAN.mdをご覧ください。
• 単一ノードの JSON ストア（data/bonuses.json、アトミック書き込み）です。この規模なら問題ありません。 同時に書き込むプロセスが発生した場合は、Postgres/SQLite に移行してください。

デプロイ

このアプリは Railway でのデプロイに対応しています（start スクリプト、PORT を尊重、 engines: node >= 20、ネイティブ依存関係は1つ（better-sqlite3、ビルド済みバイナリ）、 prestart で DB にデータを投入）。リバースプロキシ経由で 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