CDF Finance MCP

CDF Finance MCP

将 Claude、ChatGPT 和任何 MCP 客户端（OAuth 2.1）连接到你的 CDF Finance 账户——通过自然语言查询并记录你的财务状况。

远程服务： https://mcp.cdf.finance/mcp (Streamable HTTP) · 网站： https://cdf.finance/mcp · 状态： https://status.cdf.finance · 支持： [email protected]

---

简介

面向 CDF Finance 的无状态隔离式 MCP 服务——这是一款个人财务管理应用（账户、银行卡、交易、账单、预算、目标、债务、投资和洞察）。

• 面向用户： 向 Claude/ChatGPT 询问你的财务状况，无需打开应用即可记录交易。
• 面向开发者/审阅者： 代码可审计，不依赖 backend-husk——仅通过 HTTP 调用移动应用已在使用的公共 API。

基于 BUSL-1.1 提供源代码：可审计、可与 CDF Finance 搭配使用，也可贡献代码。将其作为竞品产品投入生产使用需获得商业许可。将于 2030-09-01 转为 Apache-2.0。

示例

你说	会发生什么
“这个月我的工资还剩多少？”	current_month_spending + categories_insights
“我的下一期账单会超出预算吗？”	list_pending_invoices + budget_comparison
“在 Nubank 将一笔 R$ 27,50 的 Uber 车费记为交通费”	list_accounts + list_categories + create_transaction

英语：“How much is left of my salary?” / “Will my next bill fit the budget?” / “Log an Uber ride of R$27.50 on Nubank as Transportation.”

---

架构

与 backend-husk 完全隔离——此服务不导入后端代码。

Claude / ChatGPT (MCP client)
        │  OAuth 2.1 — DCR + PKCE (S256)
        ▼
┌───────────────────────────────┐
│  cdf-mcp-server (este repo)   │  Postgres isolado (Railway)
│  • Authorization Server        │  ├─ oauth_clients / oauth_codes
│  • Resource Server (/mcp)     │  ├─ oauth_tokens (hash SHA-256)
│  • Catálogo declarativo       │  └─ sessions (JWT mobile criptografado
│    ~50 tools → REST           │                AES-256-GCM)
└───────────────┬───────────────┘
                │  HTTPS — Bearer <mobile JWT>
                ▼
        backend-husk (api.vessell.app)
        API pública — mesmo contrato do app mobile

登录流程：

1. 客户端在 /register 执行动态客户端注册。
2. 用户在 /authorize 授权（服务端渲染表单，不涉及第三方）→ 使用 device_id=mcp-<sessionId>、platform=mcp 向 /api/mobile/auth/login 发送 POST 请求。
3. 后端的 access/refresh 会加密后存储在 sessions 中；MCP 客户端仅接收不透明令牌（oauth_tokens）。
4. 每个工具都会通过 getValidAccessToken 自动使用 refresh 刷新 access_token。
5. 会话会作为设备显示在 GET /api/mobile/devices 中，可通过 DELETE /api/mobile/devices/:id 撤销。

为何保持隔离（原始 README）：避免循环依赖，独立部署/扩展（Railway 与后端的 Coolify 分开），并且不受后端更换编程语言影响——仅通过 HTTP 通信。

工具

位于 src/tools/catalog/ 的 100% 声明式目录——每个工具都是 { name, method, path, input(zod) }，由 src/tools/register.ts 执行。后端新增路由 = 新增条目，无需处理程序。

领域	工具（示例）
用户	get_profile、update_profile
账户 / 卡片	list_accounts、create_account、list_cards、current_invoice
类别 / 成本中心	list_categories、create_category、list_cost_centers
交易	list_transactions、create_transaction、confirm_pending_transaction、upcoming_transactions
定期交易 / 账单	list_recurring_transactions、list_invoices、pay_invoice
目标 / 预算 / 债务	list_goals、budget_comparison、create_debt、debt_payoff_simulation
股票 / 投资	list_equities、add_equity_valuation、investments_workspace
洞察 / 分析	cashflow_forecast、spending_projection、networth_projection、categories_insights、behavior_insights、can_afford、analytics_history
标签	list_tags、create_tag

有意不在范围内的功能（与后端一致）：admin、Stripe/pagamentos、webhooks、S3/anexos、/api/ai/*。

只读模式： MCP_TOOLS_MODE=readonly 仅公开 readOnly:true 的工具——非常适合精选目录。

---

快速开始

cp .env.example .env   # preencha DATABASE_URL, TOKEN_ENCRYPTION_KEY, SESSION_SECRET
npm install
npm run db:migrate
npm run dev            # http://localhost:8090

使用 MCP Inspector 测试：

npx @modelcontextprotocol/inspector
# Transport: Streamable HTTP → http://localhost:8090/mcp

环境变量

变量	必填	说明
PUBLIC_URL	是	此服务的公开 URL（用于 OAuth 元数据）。请在首次部署之前生成域名
PORT	否	默认值 8090
BACKEND_API_URL	是	https://api.vessell.app（或 staging）
DATABASE_URL	是	此服务专用的 Postgres
TOKEN_ENCRYPTION_KEY	是	32 字节 base64：node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
SESSION_SECRET	是	用于 /authorize Cookie 的长随机字符串
MCP_SERVICE_TOKEN	否	服务间密钥（backend-husk → MCP，通过 X-CDF-User-Token）。若未设置，则仅支持 OAuth
MCP_TOOLS_MODE	否	full（默认值）或 readonly
OPENAI_APPS_CHALLENGE_TOKEN	否	OpenAI 域名验证
ALLOWED_ORIGINS	否	/authorize 的 CORS——默认值为 https://claude.ai,https://chatgpt.com

请参阅带注释的 .env.example。

部署（Railway）

1. 运行 railway init，或在控制面板中连接仓库。
2. 添加 Postgres 插件（注入 DATABASE_URL）。
3. 配置上述环境变量——请先在 Settings → Networking 中生成域名。
4. 部署：Dockerfile → node dist/index.js（railway.json 已配置）。
5. 运行迁移：railway run npm run db:migrate。
6. 在 Claude.ai/ChatGPT 中将连接器指向 https://<seu-dominio>.up.railway.app/mcp——DCR/OAuth 会自动完成。

---

安全

• 所有 authorization_code 流程都必须使用 PKCE S256。
• 不透明令牌——仅持久化 SHA-256（oauth_tokens），原始令牌只会交付一次。
• 加密的移动端 JWT——使用 AES-256-GCM 存储在 sessions 中，绝不会暴露给客户端（src/crypto.ts、src/mcp/http.ts）。
• 设备隔离——每个会话使用 mcp-<id>（src/backend/client.ts:45），可单独撤销，不影响其他登录。
• 清理——redactLargeInlineData + redactFields（src/tools/register.ts:19）可避免向大模型泄露 data: URI 和敏感字段。

请通过 SECURITY.md 报告漏洞——请勿公开创建 issue：发送邮件至 [email protected]，主题为 [SECURITY]。

合规 — Anthropic 目录（第 4.A 节）

此连接器不会转移资金/加密货币/资产，也不会代表用户执行付款——它只会读取并记录个人财务管理中的账目，与应用中的操作相同。所有写入操作都必须在对话中明确提出请求。

• 如需精选列表，请使用 MCP_TOOLS_MODE=readonly。
• 书面例外申请（第 4.A 节本身已有规定）：docs/4a-exception-request.md。
• 供审核者使用的测试账号： [email protected] / 123456（示例数据）。

贡献

请参阅 CONTRIBUTING.md——fork、创建 feat/... 分支、运行 npm run build，并提交已在后端验证路径的 PR。贡献即表示你根据 BUSL-1.1 授予许可。

许可证

源代码可用的 BUSL-1.1——可自由用于 CDF Finance、个人用途、学术用途和贡献。禁止将其作为竞争性财务管理产品用于生产环境（托管/代管）。将于 2030-09-01 转为 Apache-2.0。

商业咨询：[email protected]。

---

_{基于 Model Context Protocol 构建 · 由 Vessell CDF Finance 维护}