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 サーバーです。CDF Finance は、個人の財務を管理するアプリです（口座、カード、取引、請求書、予算、目標、負債、投資、インサイト）。

• ユーザー向け： Claude／ChatGPT にお金について質問し、アプリを開かずに取引を記録できます。
• 開発者／レビュアー向け： 監査可能なコードで、backend-husk への依存はありません。モバイルアプリがすでに使用している公開 API に HTTP でアクセスするだけです。

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

英語の例：「給料はあといくら残っていますか？」／「次の請求額は予算内に収まりますか？」／「交通費として、Nubank に R$27.50 の Uber 乗車を記録して。」

---

アーキテクチャ

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 で Dynamic Client Registration を行います。
2. ユーザーが /authorize で認可します（サーバーがレンダリングするフォームで、サードパーティは使用しません）。その後、device_id=mcp-<sessionId>、platform=mcp を指定して POST /api/mobile/auth/login を実行します。
3. バックエンドの access/refresh は sessions に暗号化して保存され、MCP クライアントには不透明なトークン（oauth_tokens）のみが渡されます。
4. 各ツールは getValidAccessToken を使って refresh 経由で access_token を自動更新します。
5. セッションは GET /api/mobile/devices でデバイスとして表示され、DELETE /api/mobile/devices/:id で取り消せます。

分離している理由（原文の README より）：循環依存を避け、デプロイとスケーリングを独立して行えるようにし（バックエンドは Coolify、こちらは Railway）、バックエンドの言語変更の影響を受けないようにするためです。HTTP で通信するだけです。

ツール

src/tools/catalog/ にある完全宣言型のカタログです。各ツールは { 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（またはステージング環境）
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 が必須です。
• 不透明トークン — oauth_tokens に保存されるのは SHA-256 のみです。生のトークンは一度だけ渡されます。
• モバイル JWT は sessions 内で AES-256-GCM により暗号化され、クライアントには決して公開されません（src/crypto.ts、src/mcp/http.ts）。
• デバイスごとに分離 — 各セッションは mcp-<id>（src/backend/client.ts:45）で識別され、他のログインに影響を与えずに取り消せます。
• サニタイズ — redactLargeInlineData と redactFields（src/tools/register.ts:19）により、data: URI や機密フィールドが LLM に漏えいするのを防ぎます。

脆弱性は 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 をご覧ください。フォークし、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 がメンテナンス}