Jarv

🚀 Jarvis — 個人財務MCPサーバー + エージェント

Notionデータベースをバックエンドとする、個人財務追跡用のモデルコンテキストプロトコル（MCP）サーバーです。自然言語を構造化されたツール呼び出しに変換するLLM（Gemini）ベースのエージェントを備えています。

⚠️ 重要な注意

このプロジェクトは特定のNotionワークスペースに密接に結合されています。 Jarvis Notionサイト

データベースのスキーマ、関係、および数式はNotion内で構成されています。このプロジェクトを使用するには、Notionテンプレートを複製してから進めてください。

🚀 クイックスタート

アーキテクチャ

┌───────────────────────────────────────────────────────────────────┐
│                           USER INPUT                              │
│              "spent $12 on groceries at Trader Joes"              │
└───────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
┌───────────────────────────────────────────────────────────────────┐
│                      AGENT SERVER (port 4000)                     │
│                         POST /chat                                │
│  ┌─────────────────────────────────────────────────────────────┐  │
│  │  Gemini Client (gemini_client.ts) or LLM Provider           │  │
│  │  - Parses natural language → structured action              │  │
│  │  - Infers: action type, amount, category, account, etc.     │  │
│  └─────────────────────────────────────────────────────────────┘  │
│                              │                                    │
│                              ▼                                    │
│  ┌─────────────────────────────────────────────────────────────┐  │
│  │  MCP Client (mcp_client.ts)                                 │  │
│  │  - Calls MCP tools via JSON-RPC                             │  │
│  └─────────────────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
┌───────────────────────────────────────────────────────────────────┐
│                       MCP SERVER (port 3000)                      │
│                         POST /mcp                                 │
│  ┌─────────────────────────────────────────────────────────────┐  │
│  │  Registered Tools (server.ts)                               │  │
│  │  - add_transaction         - get_categories                 │  │
│  │  - add_transactions_batch  - get_uncategorized_transactions │  │
│  │  - set_budget_rule         - update_transaction_category    │  │
│  │  - split_paycheck     - update_transaction_categories_batch │  │
│  └─────────────────────────────────────────────────────────────┘  │
│                              │                                    │
│                              ▼                                    │
│  ┌─────────────────────────────────────────────────────────────┐  │
│  │  Services Layer                                             │  │
│  │  - transactions.ts  (add_transaction, batch)                │  │
│  │  - payments.ts      (create_payment, auto-clear expenses)   │  │
│  │  - categories.ts    (get/update uncategorized)              │  │
│  │  - budgets.ts       (set_budget_rule, split_paycheck)       │  │
│  └─────────────────────────────────────────────────────────────┘  │
│                              │                                    │
│                              ▼                                    │
│  ┌─────────────────────────────────────────────────────────────┐  │
│  │  Notion Layer (notion/client.ts, notion/utils.ts)           │  │
│  │  - API client + DB IDs                                      │  │
│  │  - Category caching + validation                            │  │
│  │  - Account/budget rule lookups                              │  │
│  └─────────────────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
┌───────────────────────────────────────────────────────────────────┐
│                         NOTION DATABASES                          │
│  - Expenses DB       - Income DB        - Payments DB            │
│  - Accounts DB       - Categories DB    - Budget Rules DB        │
└───────────────────────────────────────────────────────────────────┘

💡 使用ヒント

ChatGPT、Claude、または他のMCPをネイティブサポートするLLMクライアントを通じてMCPサーバーを使用する場合、src/agent/ディレクトリ全体は不要です。これらのクライアントはPOST /mcpで直接MCPツールを呼び出します。Geminiベースの解析を備えたスタンドアロンの/chatエンドポイントが必要な場合のみ、エージェントが必要です。

プロジェクト構造

jarvis/
├── src/
│   ├── mcp/                        # MCP Server (port 3000)
│   │   ├── server.ts               # Express + MCP tool registration
│   │   ├── constants.ts            # Shared account enums + validators
│   │   ├── notion/
│   │   │   ├── client.ts           # Notion API client + DB IDs
│   │   │   ├── types.ts            # Typed wrappers for dataSources API
│   │   │   └── utils.ts            # Helpers: category cache, lookups
│   │   └── services/
│   │       ├── transactions.ts     # add_transaction, batch
│   │       ├── payments.ts         # create_payment, auto-clear
│   │       ├── categories.ts       # uncategorized + updates
│   │       └── budgets.ts          # budget rules + paycheck split
│   │
│   └── agent/                      # Agent Server (port 4000)
│       ├── agent_server.ts         # Express /chat endpoint
│       ├── mcp_client.ts           # JSON-RPC client for MCP
│       └── llm/
│           ├── gemini_client.ts    # Gemini prompt + action parser
│           └── claude_prompt.md    # Claude system prompt reference
│
├── package.json
├── tsconfig.json
├── .env                            # Environment variables (not committed)
└── README.md

セットアップ

1. 前提条件

• Node.js 18+
• API統合機能を持つNotionアカウント
• Gemini APIキー

2. Notionデータベースのセットアップ

以下のスキーマでNotionに6つのデータベースを作成します。

3. 環境変数

env.exampleを.envにコピーし、以下を記入します。

# Notion
NOTION_API_KEY=secret_xxx
EXPENSES_DB_ID=xxx
INCOME_DB_ID=xxx
PAYMENTS_DB_ID=xxx
ACCOUNTS_DB_ID=xxx
CATEGORIES_DB_ID=xxx
BUDGET_RULES_DB_ID=xxx

# Gemini (for Agent)
GEMINI_API_KEY=xxx

# オプション: カスタムポート
PORT=3000           # MCPサーバー
AGENT_PORT=4000     # エージェントサーバー
MCP_BASE_URL=http://localhost:3000

4. インストールと実行

npm install

# ターミナル1: MCPサーバー
npm run mcp

# ターミナル2: エージェントサーバー
npm run agent

✨ 主な機能

• 統一されたadd_transaction: 1つのツールで支出、収入、および支払いを処理します。
• アカウントレベルの残高: クレジットカードの残高は、個々の支出の精算ではなく、総支出から総支払いを差し引いて計算されます。
• 自動支払い精算: 支払いを追加すると、自動的に一致する未精算の支出を精算します（古いものから順）。
• カテゴリ検証: 不明なカテゴリは「その他」に変換されます。
• カテゴリキャッシュ: Notionから取得され、5分間のTTLでキャッシュされます。
• LLM非依存設計: エージェント層はGeminiを任意のLLMに置き換えることができます。
• バッチ操作: 効率的な一括取引とカテゴリの更新が可能です。

💻 使用例

自然言語入力の例（エージェント）

📚 ドキュメント

MCPツールリファレンス

取引

カテゴリ

予算

APIエンドポイント

MCPサーバー (localhost:3000)

POST /mcp
Content-Type: application/json
Accept: application/json, text/event-stream

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "name": "add_transaction",
    "arguments": {
      "amount": 12.34,
      "transaction_type": "expense",
      "account": "sapphire",
      "funding_account": "checkings",
      "category": "groceries",
      "date": "2026-01-10",
      "note": "Trader Joes"
    }
  }
}

エージェントサーバー (localhost:4000)

POST /chat
Content-Type: application/json

{
  "message": "spent $12.34 on groceries at Trader Joes yesterday"
}

レスポンス:

{
  "reply": "added expense of $12.34 to sapphire (category: groceries).",
  "meta": {
    "action": { "action": "add_transaction", "args": {...} },
    "mcp": {...}
  }
}

有効なアカウント

残高モデル

アカウントの残高は、個々の支出のステータスを合計するのではなく、Notionの数式を使用してアカウントレベルの計算によって算出されます。

ledger_balance数式

if(account_type == "credit",
  total_expenses - total_payments_in,
  starting_balance + total_income - total_payments_out - total_expenses
)

• クレジットカード: 未払い残高 = 請求額 - 受け取った支払い額。支払いは、個々の支出が精算されているかどうかに関係なく、即座に残高を全額減少させます。
• デビット/貯蓄アカウント: 残高 = 開始残高 + 収入 - 支払い額 - 直接の支出。

reserved_for_cc (ロールアップ)

funding_account = このアカウントであるクレジットカードの支出のowed_amountを合計します。資金提供アカウント（例: チェッキング）に、未払いのクレジットカードの支出に割り当てられている金額を示します。

available_to_spend (数式)

ledger_balance - reserved_for_cc

支出の精算（調整）

APIを介して支払いが作成されると、payments.tsが自動的に一致する支出を精算します（古いものから順）。これにより、各支出のpaid_amountが設定され、owed_amount（数式: amount - paid_amount）が減少し、それによって資金提供アカウントのreserved_for_ccが減少します。精算は資金提供アカウントの正確性に必要ですが、クレジットカードのledger_balanceには影響しません。

🔧 技術詳細

開発

# 型チェック
npm run typecheck

# MCPサーバーを実行する（ホットリロード）
npm run mcp

# エージェントサーバーを実行する（ホットリロード）
npm run agent

📄 ライセンス

MIT