budgety-mcp 0.1.0

package/README.md

@@ -0,0 +1,154 @@
+# Budgety MCP
+
+Budgety (家計簿アプリ) を Claude から操作するための MCP ブリッジ。
+
+Claude → MCP server (Node.js) → macOS `shortcuts` CLI → Shortcuts.app レシピ → Budgety AppIntent → Core Data → CloudKit、という経路で支出の取得・追加を行う。
+
+## できること
+
+| ツール名 | 用途 |
+|---|---|
+| `mcp__budgety__get_expenses` | 期間指定で支出/収入一覧を JSON で取得 |
+| `mcp__budgety__add_expense` | 支出を 1 件追加 (日付・カテゴリ AI 自動分類対応) |
+
+## 前提
+
+- macOS (Mac Catalyst で Budgety が動く環境)
+- Budgety アプリがインストール済み・起動済み (= AppIntent が macOS に登録されている)
+- iCloud に Budgety と同じ Apple ID でサインイン
+- Node.js (v18 以上推奨)
+- Claude Code CLI
+
+## セットアップ
+
+### 1. Budgety を起動
+
+一度起動して AppIntent を macOS に登録させる。終了せず動かしっぱなしで OK。
+
+### 2. Shortcuts.app でレシピを 2 つ作成
+
+#### A. 「支出を取得」
+
+```
+[1] Budgety > 支出を取得
+       期間: ショートカットの入力
+[2] 結果として返す: [1] の出力
+```
+
+#### B. 「クイック支出追加」
+
+```
+[1] ショートカットの入力 から辞書を取得 (= JSON parse)
+[2] 辞書 内の amount の 値を取得
+[3] 辞書 内の title  の 値を取得
+[4] 辞書 内の date   の 値を取得
+[5] Budgety > 支出を追加
+       シート:        家計簿 (固定選択)
+       タイトル:       [3] の出力
+       金額:          [2] の出力
+       カテゴリ:       AI 提案 (= ドロップダウンで選択)
+       日付:          現在の日付 (= 変数バインド)
+       日付テキスト:   [4] の出力 (= ISO8601 文字列を内部で parse)
+       メモ:          (空)
+```
+
+> ⚠ Shortcuts.app で `[4]` の値を「日付」フィールドに直接バインドするとエラーになる。必ず「**日付テキスト (任意)**」フィールドに渡すこと (= AppIntent 内部で文字列 → Date 変換される)。「日付」自体は `現在の日付` 変数固定でフォールバック用。
+
+### 3. MCP server をインストール
+
+```bash
+cd /path/to/budgety-mcp
+npm install
+```
+
+### 4. Claude Code に登録
+
+```bash
+claude mcp add budgety -s user -- node $(pwd)/index.js
+```
+
+### 5. 起動確認
+
+```bash
+claude
+```
+
+Claude セッション内で `mcp__budgety__get_expenses` が使えれば成功。
+
+## 使い方 (Claude への依頼例)
+
+```
+「今月の支出を見せて」              → get_expenses(period: "thisMonth")
+「コーヒー 350 円を追加」           → add_expense(amount: 350, title: "コーヒー")
+「昨日のラーメン 1200 円」          → add_expense(amount: 1200, title: "ラーメン",
+                                                date: "2026-05-09T...")
+「5/3 の焼肉 4200 円」             → add_expense(amount: 4200, title: "焼肉",
+                                                date: "2026-05-03T19:00:00+09:00")
+```
+
+カテゴリは指定しない。AI が title から自動分類する。
+
+## 仕様詳細
+
+### `add_expense`
+
+| パラメータ | 型 | 必須 | 説明 |
+|---|---|---|---|
+| `amount` | number | ✓ | 数字のみ (¥, 円 などは剥がす) |
+| `title` | string | ✓ | 用途・店名・品目 (短く) |
+| `date` | string | × | ISO8601。未指定 = 現在時刻 |
+
+**date の例:**
+- `"2026-05-08T15:00:00Z"` (UTC)
+- `"2026-05-08T19:00:00+09:00"` (JST)
+
+相対日付 (「昨日」「先週月曜」) は **Claude 側で絶対日付に変換してから渡す**。Shortcut は相対表現を理解しない。
+
+### `get_expenses`
+
+| パラメータ | 値 |
+|---|---|
+| `period` | `today` / `yesterday` / `thisWeek` / `thisMonth` / `lastMonth` / `thisYear` / `last30Days` |
+
+## トラブルシューティング
+
+| 症状 | 原因 | 対処 |
+|---|---|---|
+| `shortcut timed out (>8s)` | Shortcut が対話プロンプトでハング | Shortcuts.app で対象 Shortcut の各パラメータを「毎回尋ねる」から固定値/変数に変更 |
+| `shortcut exited code=1` | パラメータの型不整合 (例: 文字列を Date 欄に渡した) | Shortcut の各フィールドのバインド先を確認 |
+| 追加したのに反映されない | iCloud 同期遅延 | 数秒待つ |
+| 日付指定したのに今日になる | 日付テキストが間違ったキーにバインド | Shortcut で `date` キーから値を取り出しているか確認 |
+| 「支出を追加」が `shortcuts list` に出ない | Budgety を起動していない | アプリを起動 |
+
+## アーキテクチャ
+
+```
+Claude
+   ↓ JSON-RPC (stdio)
+budgety-mcp (Node.js)
+   ↓ execFile("shortcuts", ["run", ...])
+macOS Shortcuts CLI
+   ↓ 実行
+Shortcuts.app レシピ (= 「クイック支出追加」)
+   ↓ AppIntent
+Budgety.app (Mac Catalyst)
+   ↓ Core Data
+CloudKit → iPhone / Watch / 他 Mac
+```
+
+## ファイル構成
+
+```
+budgety-mcp/
+├── index.js       # MCP server (Node.js)
+├── package.json
+└── README.md      # このファイル
+```
+
+AppIntent 側のコード (= Budgety リポジトリ内):
+- `Budgety/Intents/AddExpenseIntent.swift`
+- `Budgety/Intents/QuickAddExpenseIntent.swift`
+- `Budgety/Intents/GetExpensesIntent.swift`
+- `Budgety/Intents/ExpensoShortcuts.swift`
+- `Budgety/Intents/ExpenseCategoryEntity.swift`
+- `Budgety/Intents/ExpenseSheetEntity.swift`

package/index.js

@@ -0,0 +1,210 @@
+#!/usr/bin/env node
+//
+// Budgety MCP Bridge
+//
+// Exposes Budgety's data to Claude via MCP. Internally calls macOS `shortcuts`
+// CLI which runs the `Budgety で支出を取得` AppShortcut → returns JSON to Claude.
+//
+// Setup:
+//   1. Install Budgety on iPhone, sign in to iCloud
+//   2. On Mac, ensure Shortcuts.app has "Budgety で支出を取得" available
+//      (auto-synced via iCloud once Budgety iOS App Intent is registered)
+//   3. claude mcp add budgety -s user -- node /Users/ishinotento/budgety-mcp/index.js
+//   4. Restart Claude Code: claude -c
+//
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+    CallToolRequestSchema,
+    ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { writeFile, readFile, unlink } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const exec = promisify(execFile);
+
+const SHORTCUT_NAME_GET_EXPENSES = "支出を取得";
+const SHORTCUT_NAME_ADD_EXPENSE = "クイック支出追加";
+
+const server = new Server(
+    {
+        name: "budgety-mcp",
+        version: "0.1.0",
+    },
+    {
+        capabilities: {
+            tools: {},
+        },
+    }
+);
+
+// MARK: Tools
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: "get_expenses",
+            description:
+                "Get expense / income records from Budgety for a specified period. Returns structured JSON with date, amount, category, sheet, etc. Useful for analyzing spending patterns.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    period: {
+                        type: "string",
+                        enum: [
+                            "today",
+                            "yesterday",
+                            "thisWeek",
+                            "thisMonth",
+                            "lastMonth",
+                            "thisYear",
+                            "last30Days",
+                        ],
+                        default: "thisMonth",
+                        description: "Period to fetch expenses for",
+                    },
+                },
+            },
+        },
+        {
+            name: "add_expense",
+            description: [
+                "Record an expense in Budgety (the user's family expense tracking app).",
+                "Use this whenever the user mentions a purchase, payment, or expense in conversation",
+                "(e.g. 'コーヒー 350 円', 'lunch was 1200 yen', 'add yesterday's groceries').",
+                "",
+                "Behavior:",
+                "- Saves to the user's primary sheet (家計簿).",
+                "- Currency = sheet's default (JPY for Japan).",
+                "- Category is auto-classified by AI from the title — DO NOT pass a category.",
+                "",
+                "Date handling (IMPORTANT):",
+                "- Resolve relative dates ('yesterday', '昨日', '先週月曜', etc.) to an absolute",
+                "  ISO8601 string BEFORE calling. The shortcut does not understand relative dates.",
+                "- Format: 'YYYY-MM-DDTHH:MM:SSZ' (UTC) or 'YYYY-MM-DDTHH:MM:SS+09:00' (JST).",
+                "- Omit `date` to record at the current moment.",
+                "- If the user mentions a date but not a time, use 12:00 local time as a sensible default.",
+            ].join("\n"),
+            inputSchema: {
+                type: "object",
+                properties: {
+                    amount: {
+                        type: "number",
+                        description:
+                            "Amount as a plain number. Strip currency symbols (¥, $, 円) before passing.",
+                    },
+                    title: {
+                        type: "string",
+                        description:
+                            "Short label for the expense (店名・品目). Keep it concise — no need for full sentences.",
+                    },
+                    date: {
+                        type: "string",
+                        description: [
+                            "ISO8601 date-time string. Optional — defaults to now.",
+                            "Examples:",
+                            "  '2026-05-03T19:30:00Z'      (UTC)",
+                            "  '2026-05-03T19:30:00+09:00' (JST)",
+                            "Resolve relative dates ('yesterday', '昨日') to absolute before passing.",
+                        ].join("\n"),
+                    },
+                },
+                required: ["amount", "title"],
+            },
+        },
+    ],
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const name = req.params.name;
+    const args = req.params.arguments ?? {};
+    try {
+        if (name === "get_expenses") {
+            const period = args.period ?? "thisMonth";
+            const json = await runShortcutWithInput(
+                SHORTCUT_NAME_GET_EXPENSES,
+                period
+            );
+            return {
+                content: [{ type: "text", text: json }],
+            };
+        }
+        if (name === "add_expense") {
+            // date は常に送る (= 未指定なら現在時刻の ISO8601)。Shortcut 側は
+            // 「日付を取得」アクションで text → Date に変換する前提。
+            const dateISO = args.date && typeof args.date === "string"
+                ? args.date
+                : new Date().toISOString();
+            const payload = JSON.stringify({
+                amount: args.amount,
+                title: args.title ?? "",
+                date: dateISO,
+            });
+            const result = await runShortcutWithInput(
+                SHORTCUT_NAME_ADD_EXPENSE,
+                payload
+            );
+            return {
+                content: [{ type: "text", text: result || "OK" }],
+            };
+        }
+        throw new Error(`Unknown tool: ${name}`);
+    } catch (err) {
+        return {
+            isError: true,
+            content: [
+                {
+                    type: "text",
+                    text: `${err.message ?? err}\n\nHint: ensure the shortcut is set up in Shortcuts.app on this Mac (signed into the same iCloud as Budgety).`,
+                },
+            ],
+        };
+    }
+});
+
+async function runShortcutWithInput(name, input) {
+    const inputPath = join(tmpdir(), `budgety-mcp-in-${Date.now()}.txt`);
+    const outputPath = join(tmpdir(), `budgety-mcp-out-${Date.now()}.txt`);
+    await writeFile(inputPath, input ?? "", "utf-8");
+    try {
+        // 8 秒以上かかったら shortcut が対話プロンプトでハングしている可能性大なので abort
+        const child = execFile("shortcuts", [
+            "run",
+            name,
+            "--input-path", inputPath,
+            "--output-path", outputPath,
+        ]);
+        const promise = new Promise((resolve, reject) => {
+            child.on("exit", (code) => code === 0 ? resolve() : reject(new Error(`shortcut exited code=${code}`)));
+            child.on("error", reject);
+        });
+        const timeout = new Promise((_, reject) =>
+            setTimeout(() => {
+                try { child.kill("SIGKILL"); } catch {}
+                reject(new Error("shortcut timed out (>8s) - probably waiting for user input. Configure the shortcut in Shortcuts.app to skip prompts."));
+            }, 8000)
+        );
+        await Promise.race([promise, timeout]);
+    } finally {
+        try { await unlink(inputPath); } catch {}
+    }
+    let result = "";
+    try {
+        result = await readFile(outputPath, "utf-8");
+    } catch {
+        result = "";
+    }
+    try { await unlink(outputPath); } catch {}
+    // 空 output は許容 (= shortcut 末尾に出力アクションがない場合の正常終了)。
+    // 本物の失敗は execFile の exit code 非 0 / timeout で既に throw されている。
+    return result;
+}
+
+// MARK: Run
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "budgety-mcp",
+  "version": "0.1.0",
+  "description": "MCP bridge to control Budgety (家計簿アプリ) from Claude via macOS Shortcuts.",
+  "type": "module",
+  "main": "index.js",
+  "bin": { "budgety-mcp": "./index.js" },
+  "files": [
+    "index.js",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node index.js"
+  },
+  "keywords": [
+    "mcp",
+    "claude",
+    "budgety",
+    "expense",
+    "shortcuts",
+    "macos"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "darwin"
+  ],
+  "license": "MIT",
+  "author": "Tento Ishino",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  }
+}