YNAB MCP スターター

読み取り専用のYNAB MCPサーバーのための、本番環境スタイルのTypeScriptスターターリポジトリです。

このスターターは意図的に小さく、明示的な構成になっています：

• Node.js 18以上

• 厳格なコンパイラ設定のTypeScript

• Zodで検証されたツールの入力と出力

• リトライとタイムアウト処理を備えた読み取り専用のYNAB APIクライアント

• YNABレスポンスをモック化したユニットテスト

• MCPトランスポートの接続先を示す明確なTODOマーカー

このリポジトリに含まれるもの

src/
  clients/   YNAB API client, environment config, and error types
  schemas/   strict Zod schemas for tool contracts
  server/    MCP server composition and transport TODO placeholders
  tools/     read-only business logic for each YNAB capability
  types/     shared API and service types
tests/       unit tests with mocked API responses

実装済みの読み取り専用機能：

• 予算の一覧表示

• 口座の一覧表示

• カテゴリの一覧表示

• 最近の取引の一覧表示

• 未分類の取引の検索

• カテゴリ別の月間支出

書き込みアクセスは意図的に実装されていません。

Related MCP server: MCP Server Starter

セットアップ

1. 依存関係をインストールします：

npm install

2. 環境変数のサンプルファイルをコピーします：

cp .env.example .env

3. .env にYNABトークンを設定します：

YNAB_TOKEN=your-token-here

4. ローカル開発モードを実行します：

npm run dev

スクリプト

• npm run build TypeScriptを dist/ にコンパイルします

• npm run dev ファイル監視付きでスターターのエントリポイントを実行します

• npm run lint ESLintを実行します

• npm run test Vitestでユニットテストを実行します

• npm run typecheck TypeScriptを非出力モードで実行します

MCPの接続

このリポジトリにはサーバー構成レイヤーが含まれていますが、まだ特定のトランスポートに固定されていません。

以下のファイルの TODO コメントを確認してください：

• src/server/index.ts

• src/server/registerTools.ts

ここで行うべきことは以下の通りです：

1. MCPサーバーのインスタンス化

2. ツール定義とスキーマの登録

3. stdio、SSE、またはその他のトランスポートの接続

4. 構造化ログと運用フックの追加

セキュリティ上の注意

• このスターターは、環境変数に YNAB_TOKEN 個人アクセストークンを必要とします。

• ソースファイル、テスト、プロンプト、ログにトークンをハードコードしないでください。

• トークンは読み取り専用の運用用途に限定し、漏洩した場合はローテーションしてください。

• 本番環境では、取引メモやその他の機密性の高い財務メタデータが含まれる可能性があるため、生のYNAB APIレスポンスをログに記録しないでください。

• このスターターはYNAB APIに対して GET リクエストのみを実行します。書き込みエンドポイントは実装されていません。

設計上の注意

• YNABクライアントは、リトライ、タイムアウト処理、エラーの正規化を一元管理します。

• ツールモジュールはHTTPの詳細から分離されており、小さなサービスインターフェース上で動作します。

• Zodスキーマは、ツールの入力と出力の両方を検証し、早期に不整合を検出します。

• 金額は、YNABのミリ単位と人間が読みやすい10進数の両方で公開されます。

• カテゴリ別の月間支出は、リクエストされた月の流出額のみをカウントします。

プロンプトの例

• "List my YNAB budgets."

• "Show the accounts in budget budget-id-123."

• "List categories for budget budget-id-123."

• "Show the most recent 20 transactions in budget budget-id-123."

• "Find uncategorized transactions in budget budget-id-123 since 2026-04-01."

• "Summarize monthly spend by category for budget budget-id-123 in 2026-04."

テスト

テストはYNAB APIレスポンスをモック化しているため、ライブトークンなしで動作を検証できます：

npm run test

本番環境向けの強化案

• リクエスト相関IDと構造化ログの追加

• リトライ、レート制限、レイテンシに関するメトリクスの追加

• モック化されたHTTPレイヤーに対する統合テストの追加

• MCPクライアントがより大きな結果セットを期待する場合のページネーション制御の追加

• デプロイ用にローカルの .env ファイルではなく、シークレットマネージャーの統合を追加