Bancadia MCP

Bancadia MCP

一个 Model Context Protocol 服务，可让 MCP 客户端（Claude、其他 LLM Agent 等）通过结构化筛选条件查询 Bancadia 的企业存款账户产品注册表（仅限美国）。

它作为 Cloudflare Worker 运行，基于 Hono，通过 JSON-RPC 2.0（Streamable HTTP 传输）提供 MCP 服务，底层由 Supabase（Postgres）支持，并配有 Upstash Redis 缓存和速率限制层。

端点

方法	路径	用途	身份验证
GET	/health	存活检查	无
GET	/.well-known/mcp	公共发现信息／清单（服务信息和工具列表）	无
POST	/	JSON-RPC 2.0 端点 — initialize、tools/list、tools/call	会话；tools/call 还需要 bearer 令牌
GET	/	独立 SSE 流（服务端发起的消息、保持连接）	会话
DELETE	/	终止会话	会话

MCP 会话生命周期

1. 使用 method: "initialize" 调用 POST / — 无需身份验证。响应头中会返回 Mcp-Session-Id；后续每个请求都必须在 Mcp-Session-Id 请求头中传回该值。
2. 使用 method: "tools/list" 调用 POST / — 需要会话，无需 bearer 令牌。返回工具清单。
3. 使用 method: "tools/call" 调用 POST / — 需要会话和 Authorization: Bearer <token>。每个令牌均适用滑动窗口速率限制（成功响应和 429 响应中都会包含 X-RateLimit-* 响应头）。

默认情况下，响应为普通 JSON；如果请求的 Accept 标头包含 text/event-stream，则响应为 Server-Sent Events。

如需用于生产环境，请从 Bancadia 开发者门户获取 bearer 令牌 — 完整 API 文档请参阅 bancadia.com/docs。

可用工具

工具	用途
query_business_checking	筛选企业支票账户列表（费用、实体类型、州、RTP 通道、集成、APY 等）
get_business_checking_listing	根据 listing_slug 获取单个列表的完整详情 — 费用和功能，包括按套餐等级划分的明细

如需查看每个工具参数的完整 JSON Schema，请参阅 src/lib/tools.ts；也可以直接查询 GET /.well-known/mcp 或 tools/list。

application_url 归因标签

tools/call 返回的每个 application_url 都是绝对 https://bancadia.com/go/... 链接，并附有归因参数：src=mcp 和 qr=<request_id>。其中 request_id 是每次 tools/call 仅生成一次的 UUID，也会写入该调用对应的每条 query_match_events 记录（因此可以将 /go 点击与显示该链接的工具调用关联起来）。存储的 URL 中已有的参数绝不会被覆盖。每个工具都会添加 qr；如果某个工具没有记录 query_match_events，或者没有返回任何列表，就没有可供关联的记录。主机前缀和标签都在同一层处理：src/lib/urls.ts 中的 applyApplicationUrlHost，由 src/index.ts 调用。

**客户端和 Agent 应原样传递 application_url，包括其查询字符串。**移除这些参数会导致该点击的归因信息丢失。

入门

npm install
cp .dev.vars.example .dev.vars   # fill in Supabase + Upstash credentials
npm run dev                      # wrangler dev — local server

wrangler.toml [vars] 提供非机密默认值（测试用的 Supabase/Upstash URL、会话 TTL、允许的源），供 npm run dev 和测试套件共用；实际机密存放在 .dev.vars 中（已加入 git 忽略）。

命令

npm run dev               # wrangler dev — local server
npm test                  # vitest run (runs inside workerd via @cloudflare/vitest-pool-workers)
npm run lint              # tsc --noEmit
npm run deploy:staging    # wrangler deploy --env staging
npm run deploy:production # wrangler deploy --env production

运行单个测试文件：

npx vitest run src/__tests__/query-business-checking.test.ts

环境

• staging — bancadia-mcp-staging，已启用 workers.dev。CI 会在每次向 main 推送或提交 PR 时自动部署。
• production — bancadia-mcp-production，路由至 mcp.bancadia.com/*。通过 npm run deploy:production 手动部署。

每个环境的机密通过 wrangler secret put <KEY> --env <environment> 设置，绝不会提交到版本库。

架构

如需了解代码库的详细指南，包括请求流程、身份验证/会话/速率限制设计，以及查询处理器所依托的 Supabase 混合架构（基础表 + 按产品类型划分的详情表），请参阅 CLAUDE.md。