copilot-money-mcp 2.0.0 → 2.0.1

package/README.md

@@ -4,17 +4,14 @@
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js 18+](https://img.shields.io/badge/node-18+-green.svg)](https://nodejs.org/)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
-[![Tests](https://img.shields.io/badge/tests-1400+-brightgreen.svg)](https://github.com/ignaciohermosillacornejo/copilot-money-mcp)
-[![Tools](https://img.shields.io/badge/tools-17-blue.svg)](https://github.com/ignaciohermosillacornejo/copilot-money-mcp)
+[![TypeScript](https://img.shields.io/badge/TypeScript-6.0-blue.svg)](https://www.typescriptlang.org/)
+[![Tests](https://github.com/ignaciohermosillacornejo/copilot-money-mcp/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/ignaciohermosillacornejo/copilot-money-mcp/actions/workflows/test.yml)
+[![codecov](https://codecov.io/gh/ignaciohermosillacornejo/copilot-money-mcp/branch/main/graph/badge.svg)](https://codecov.io/gh/ignaciohermosillacornejo/copilot-money-mcp)
 
 ## Disclaimer
 
 **This is an independent, community-driven project and is not affiliated with, endorsed by, or associated with Copilot Money or its parent company in any way.** This tool was created by an independent developer to enable AI-powered queries of locally cached data. "Copilot Money" is a trademark of its respective owner.
 
-> [!NOTE]
-> **Write tools are temporarily unavailable.** Copilot Money has restricted direct Firestore writes from third-party clients. The 18 write tools in this repo still exist as source, but the published CLI runs read-only. A replacement write path is being evaluated. Reads are unaffected.
-
 ## Overview
 
 An [MCP](https://modelcontextprotocol.io/) server that gives AI assistants access to your Copilot Money personal finance data. It reads from the locally cached Firestore database (LevelDB + Protocol Buffers) on your Mac. **Reads are 100% local with zero network requests.**
@@ -161,12 +158,6 @@ Uses `get_recurring_transactions`.
 | `get_cache_info` | Local cache metadata — date range, transaction count, cache age. |
 | `refresh_database` | Reload data from disk. Cache auto-refreshes every 5 minutes. |
 
-### Write Tools — temporarily unavailable
-
-Copilot Money has restricted direct Firestore writes from third-party clients, so the 18 write tools (`update_transaction`, `create_budget`, `create_goal`, `update_recurring`, etc.) no longer succeed against the live backend. The code still lives in `src/` and the tool schemas are preserved for reference and future work, but the published `copilot-money-mcp` CLI runs in read-only mode. Passing `--write` prints a notice and still starts read-only.
-
-A replacement write path (via Copilot Money's GraphQL web API) is being evaluated; progress will be tracked in the repo issues.
-
 ## Configuration
 
 ### Cache TTL

package/dist/cli.js

@@ -27840,6 +27840,7 @@ class StdioServerTransport {
 }
 
 // src/core/database.ts
+import { randomUUID } from "crypto";
 import { existsSync, readdirSync } from "fs";
 import { homedir } from "os";
 import { join } from "path";
@@ -29765,6 +29766,8 @@ function processRecurring(fields, docId) {
   }
 }
 function processBudget(fields, docId) {
+  if (fields.size === 0)
+    return null;
   const budgetId = getString(fields, "budget_id") ?? docId;
   const budgetData = {
     budget_id: budgetId
@@ -31553,6 +31556,81 @@ class CopilotDatabase {
     Object.assign(txn, fields);
     return true;
   }
+  patchCachedBudget(categoryId, amount, month) {
+    if (!this._budgets)
+      return false;
+    const monthKey = month ?? (() => {
+      const d = new Date;
+      return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}`;
+    })();
+    const existing = this._budgets.find((b) => b.category_id === categoryId);
+    if (existing) {
+      existing.amounts = { ...existing.amounts ?? {}, [monthKey]: amount };
+    } else {
+      this._budgets.push({
+        budget_id: randomUUID(),
+        category_id: categoryId,
+        amounts: { [monthKey]: amount }
+      });
+    }
+    return true;
+  }
+  patchCachedTagUpsert(tag) {
+    if (!this._tags)
+      return;
+    const idx = this._tags.findIndex((t) => t.tag_id === tag.tag_id);
+    if (idx >= 0) {
+      Object.assign(this._tags[idx], tag);
+    } else {
+      this._tags.push(tag);
+    }
+  }
+  patchCachedTagDelete(tagId) {
+    if (!this._tags)
+      return false;
+    const before = this._tags.length;
+    this._tags = this._tags.filter((t) => t.tag_id !== tagId);
+    return this._tags.length < before;
+  }
+  patchCachedCategoryUpsert(category) {
+    if (!this._userCategories)
+      return;
+    const idx = this._userCategories.findIndex((c) => c.category_id === category.category_id);
+    if (idx >= 0) {
+      Object.assign(this._userCategories[idx], category);
+    } else {
+      this._userCategories.push(category);
+    }
+    this._categoryNameMap = null;
+  }
+  patchCachedCategoryDelete(categoryId) {
+    if (!this._userCategories)
+      return false;
+    const before = this._userCategories.length;
+    this._userCategories = this._userCategories.filter((c) => c.category_id !== categoryId);
+    if (this._userCategories.length < before) {
+      this._categoryNameMap = null;
+      return true;
+    }
+    return false;
+  }
+  patchCachedRecurringUpsert(recurring) {
+    if (!this._recurring)
+      return;
+    const idx = this._recurring.findIndex((r) => r.recurring_id === recurring.recurring_id);
+    if (idx >= 0) {
+      Object.assign(this._recurring[idx], recurring);
+    } else {
+      this._recurring.push(recurring);
+    }
+  }
+  patchCachedRecurringDelete(recurringId) {
+    if (!this._recurring)
+      return false;
+    const before = this._recurring.length;
+    this._recurring = this._recurring.filter((r) => r.recurring_id !== recurringId);
+    return this._recurring.length < before;
+  }
   getCacheLoadedAt() {
     return this._cacheLoadedAt;
   }
@@ -32569,14 +32647,6 @@ var CREATE_RECURRING = `mutation CreateRecurring($input: CreateRecurringInput!)
   createRecurring(input: $input) {
     __typename
     ...RecurringFields
-    rule {
-      __typename
-      ...RecurringRuleFields
-    }
-    payments {
-      __typename
-      ...RecurringPaymentFields
-    }
   }
 }
 
@@ -32602,21 +32672,6 @@ fragment RecurringFields on Recurring {
   state
   name
   id
-}
-
-fragment RecurringRuleFields on RecurringRule {
-  __typename
-  nameContains
-  minAmount
-  maxAmount
-  days
-}
-
-fragment RecurringPaymentFields on RecurringPayment {
-  __typename
-  amount
-  isPaid
-  date
 }`;
 var EDIT_RECURRING = `mutation EditRecurring($id: ID!, $input: EditRecurringInput!) {
   editRecurring(id: $id, input: $input) {
@@ -32624,14 +32679,6 @@ var EDIT_RECURRING = `mutation EditRecurring($id: ID!, $input: EditRecurringInpu
     recurring {
       __typename
       ...RecurringFields
-      rule {
-        __typename
-        ...RecurringRuleFields
-      }
-      payments {
-        __typename
-        ...RecurringPaymentFields
-      }
     }
   }
 }
@@ -32658,21 +32705,6 @@ fragment RecurringFields on Recurring {
   state
   name
   id
-}
-
-fragment RecurringRuleFields on RecurringRule {
-  __typename
-  nameContains
-  minAmount
-  maxAmount
-  days
-}
-
-fragment RecurringPaymentFields on RecurringPayment {
-  __typename
-  amount
-  isPaid
-  date
 }`;
 var DELETE_RECURRING = `mutation DeleteRecurring($deleteRecurringId: ID!) {
   deleteRecurring(id: $deleteRecurringId)
@@ -32803,20 +32835,8 @@ async function editRecurring(client, args) {
   const changed = {};
   if ("state" in args.input)
     changed.state = recurring.state;
-  if ("rule" in args.input && recurring.rule) {
-    const serverRule = recurring.rule;
-    const stringRule = {};
-    if ("nameContains" in serverRule)
-      stringRule.nameContains = serverRule.nameContains;
-    if ("minAmount" in serverRule && serverRule.minAmount !== undefined) {
-      stringRule.minAmount = String(serverRule.minAmount);
-    }
-    if ("maxAmount" in serverRule && serverRule.maxAmount !== undefined) {
-      stringRule.maxAmount = String(serverRule.maxAmount);
-    }
-    if ("days" in serverRule)
-      stringRule.days = serverRule.days;
-    changed.rule = stringRule;
+  if ("rule" in args.input && args.input.rule) {
+    changed.rule = { ...args.input.rule };
   }
   return { id: recurring.id, changed };
 }
@@ -33856,23 +33876,32 @@ class CopilotMoneyTools {
   async getBudgets(options = {}) {
     const { active_only = false } = options;
     const allBudgets = await this.db.getBudgets(active_only);
+    const now = new Date;
+    const currentMonth = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, "0")}`;
+    const effectiveAmount = (b) => {
+      const override = b.amounts?.[currentMonth];
+      return override !== undefined ? override : b.amount;
+    };
+    const nonTombstone = allBudgets.filter((b) => b.category_id !== undefined || b.amount !== undefined || b.amounts !== undefined);
     const categoryMap2 = await this.getUserCategoryMap();
-    const budgets = allBudgets.filter((b) => {
+    const budgets = nonTombstone.filter((b) => {
       if (!b.category_id)
         return true;
       return categoryMap2.has(b.category_id) || isKnownPlaidCategory(b.category_id);
     });
     let totalBudgeted = 0;
     for (const budget of budgets) {
-      if (budget.amount) {
-        const monthlyAmount = budget.period === "yearly" ? budget.amount / 12 : budget.period === "weekly" ? budget.amount * 4.33 : budget.period === "daily" ? budget.amount * 30 : budget.amount;
+      const amt = effectiveAmount(budget);
+      if (amt) {
+        const monthlyAmount = budget.period === "yearly" ? amt / 12 : budget.period === "weekly" ? amt * 4.33 : budget.period === "daily" ? amt * 30 : amt;
         totalBudgeted += monthlyAmount;
       }
     }
     const enrichedBudgets = await Promise.all(budgets.map(async (b) => ({
       budget_id: b.budget_id,
       name: b.name,
-      amount: b.amount,
+      amount: effectiveAmount(b),
+      ...b.amounts ? { amounts: b.amounts } : {},
       period: b.period,
       category_id: b.category_id,
       category_name: b.category_id ? await this.resolveCategoryName(b.category_id) : undefined,
@@ -34079,6 +34108,13 @@ class CopilotMoneyTools {
           isExcluded: args.is_excluded ?? false
         }
       });
+      this.db.patchCachedCategoryUpsert({
+        category_id: result.id,
+        name: result.name,
+        color: result.colorName,
+        emoji: args.emoji,
+        excluded: args.is_excluded ?? false
+      });
       return {
         success: true,
         category_id: result.id,
@@ -34154,6 +34190,15 @@ class CopilotMoneyTools {
         isReviewed: "reviewed"
       };
       const updated = Object.keys(result.changed).map((k) => graphqlToApiName[k] ?? k);
+      const patch = {};
+      if ("category_id" in args && args.category_id !== undefined)
+        patch.category_id = args.category_id;
+      if ("note" in args && args.note !== undefined)
+        patch.user_note = args.note;
+      if ("tag_ids" in args && args.tag_ids !== undefined)
+        patch.tag_ids = args.tag_ids;
+      if (Object.keys(patch).length > 0)
+        this.db.patchCachedTransaction(transaction_id, patch);
       return {
         success: true,
         transaction_id: result.id,
@@ -34224,6 +34269,9 @@ class CopilotMoneyTools {
       }
       throw error48;
     }
+    for (const id of transaction_ids) {
+      this.db.patchCachedTransaction(id, { user_reviewed: reviewed });
+    }
     return {
       success: true,
       reviewed_count,
@@ -34239,6 +34287,11 @@ class CopilotMoneyTools {
       const result = await createTag(client, {
         input: { name: args.name.trim(), colorName }
       });
+      this.db.patchCachedTagUpsert({
+        tag_id: result.id,
+        name: result.name,
+        color_name: result.colorName
+      });
       return {
         success: true,
         tag_id: result.id,
@@ -34255,6 +34308,7 @@ class CopilotMoneyTools {
     const client = this.getGraphQLClient();
     try {
       const result = await deleteTag(client, { id: args.tag_id });
+      this.db.patchCachedTagDelete(args.tag_id);
       return { success: true, tag_id: result.id, deleted: true };
     } catch (e) {
       if (e instanceof GraphQLError)
@@ -34278,6 +34332,16 @@ class CopilotMoneyTools {
     }
     try {
       const result = await editCategory(client, { id: args.category_id, input });
+      const patch = { category_id: args.category_id };
+      if (args.name !== undefined)
+        patch.name = args.name;
+      if (args.color_name !== undefined)
+        patch.color = args.color_name;
+      if (args.emoji !== undefined)
+        patch.emoji = args.emoji;
+      if (args.is_excluded !== undefined)
+        patch.excluded = args.is_excluded;
+      this.db.patchCachedCategoryUpsert(patch);
       return {
         success: true,
         category_id: result.id,
@@ -34293,6 +34357,7 @@ class CopilotMoneyTools {
     const client = this.getGraphQLClient();
     try {
       const result = await deleteCategory(client, { id: args.category_id });
+      this.db.patchCachedCategoryDelete(args.category_id);
       return { success: true, category_id: result.id, deleted: true };
     } catch (e) {
       if (e instanceof GraphQLError)
@@ -34319,6 +34384,7 @@ class CopilotMoneyTools {
         amount: args.amount,
         month: args.month
       });
+      this.db.patchCachedBudget(args.category_id, parseFloat(args.amount), args.month);
       return {
         success: true,
         category_id: result.categoryId,
@@ -34343,6 +34409,10 @@ class CopilotMoneyTools {
         id: args.recurring_id,
         input: { state: args.state }
       });
+      this.db.patchCachedRecurringUpsert({
+        recurring_id: args.recurring_id,
+        state: args.state.toLowerCase()
+      });
       return { success: true, recurring_id: result.id, state: args.state };
     } catch (e) {
       if (e instanceof GraphQLError)
@@ -34354,6 +34424,7 @@ class CopilotMoneyTools {
     const client = this.getGraphQLClient();
     try {
       const result = await deleteRecurring(client, { id: args.recurring_id });
+      this.db.patchCachedRecurringDelete(args.recurring_id);
       return { success: true, recurring_id: result.id, deleted: true };
     } catch (e) {
       if (e instanceof GraphQLError)
@@ -34373,6 +34444,12 @@ class CopilotMoneyTools {
     }
     try {
       const result = await editTag(client, { id: args.tag_id, input });
+      const patch = { tag_id: args.tag_id };
+      if (args.name !== undefined)
+        patch.name = args.name;
+      if (args.color_name !== undefined)
+        patch.color_name = args.color_name;
+      this.db.patchCachedTagUpsert(patch);
       return { success: true, tag_id: result.id, updated: Object.keys(result.changed) };
     } catch (e) {
       if (e instanceof GraphQLError)
@@ -34404,6 +34481,12 @@ class CopilotMoneyTools {
           }
         }
       });
+      this.db.patchCachedRecurringUpsert({
+        recurring_id: result.id,
+        name: result.name,
+        state: result.state.toLowerCase(),
+        frequency: result.frequency
+      });
       return {
         success: true,
         recurring_id: result.id,
@@ -34439,6 +34522,17 @@ class CopilotMoneyTools {
     }
     try {
       const result = await editRecurring(client, { id: args.recurring_id, input });
+      const patch = { recurring_id: args.recurring_id };
+      if (args.state !== undefined) {
+        patch.state = args.state.toLowerCase();
+      }
+      if (args.rule?.name_contains !== undefined)
+        patch.match_string = args.rule.name_contains;
+      if (args.rule?.min_amount !== undefined)
+        patch.min_amount = parseFloat(args.rule.min_amount);
+      if (args.rule?.max_amount !== undefined)
+        patch.max_amount = parseFloat(args.rule.max_amount);
+      this.db.patchCachedRecurringUpsert(patch);
       return { success: true, recurring_id: result.id, updated: Object.keys(result.changed) };
     } catch (e) {
       if (e instanceof GraphQLError)
@@ -34895,7 +34989,7 @@ function createToolSchemas() {
     },
     {
       name: "get_budgets",
-      description: "Get budgets from Copilot's native budget tracking. " + "Retrieves user-defined spending limits and budget rules stored in the app. " + "Returns budget details including amounts, periods (monthly/yearly/weekly), " + "category associations, and active status. Calculates total budgeted amount as monthly equivalent. " + "Sync note: after `set_budget` writes, budget changes can take significantly longer " + "to reflect in this read than other collections (transactions/tags/categories/recurrings " + "sync in seconds; budgets may take minutes). Do not assume a fresh `set_budget` is " + "immediately observable here — poll with `refresh_database` or verify directly in the " + "Copilot app. Per-month overrides written via `set_budget(month=...)` are not surfaced " + "in this view; only the all-months default `amount` is returned.",
+      description: "Get budgets from Copilot's native budget tracking. " + "Returns the current-month effective budget per category plus the full " + "`amounts` map of per-month overrides for history lookups. For parent " + "categories, the returned `amount` is the resolved total (children + " + "rollovers) that Copilot displays in the Budgets view. Totals use the " + "current-month effective amount.",
       inputSchema: {
         type: "object",
         properties: {
@@ -35016,7 +35110,7 @@ function createToolSchemas() {
     },
     {
       name: "get_balance_history",
-      description: "Get daily balance snapshots for accounts over time. Returns current_balance, " + "available_balance, and limit per day. Requires a granularity parameter (daily, weekly, " + "or monthly) to control response size. Weekly and monthly modes downsample by keeping " + "the last data point per period. Filter by account_id and date range.",
+      description: "Get daily balance snapshots for accounts over time. Each entry returns current_balance, " + "available_balance, limit, account_id, and account_name. The response also includes an " + "`accounts` array listing the distinct account IDs in the paginated page. Requires a " + "granularity parameter (daily, weekly, or monthly) to control response size. Weekly and " + "monthly modes downsample by keeping the last data point per period. Filter by " + "account_id and date range.",
       inputSchema: {
         type: "object",
         properties: {
@@ -35215,7 +35309,7 @@ function createWriteToolSchemas() {
     },
     {
       name: "review_transactions",
-      description: "Mark one or more transactions as reviewed (or unreviewed). " + "Accepts an array of transaction_ids. Writes directly to Copilot Money via GraphQL.",
+      description: "Mark one or more transactions as reviewed (or unreviewed). " + "Accepts an array of transaction_ids. Writes are issued via GraphQL in parallel with " + "a cap of 5 in flight at a time. On the first GraphQL error, new writes stop, in-flight " + "writes settle, and the error is thrown with a `reviewed_count` reflecting how many " + "succeeded before the failure (partial success is possible).",
       inputSchema: {
         type: "object",
         properties: {
@@ -35249,11 +35343,7 @@ function createWriteToolSchemas() {
           },
           color_name: {
             type: "string",
-            description: 'Optional color name (e.g. "blue", "red")'
-          },
-          hex_color: {
-            type: "string",
-            description: 'Optional hex color code (e.g. "#FF5733")'
+            description: 'Optional palette token from Copilot (e.g. "PURPLE2", "OLIVE1", "RED1"). ' + 'Defaults to "PURPLE2" when omitted. See existing tags for valid values.'
           }
         },
         required: ["name"]
@@ -35373,7 +35463,7 @@ function createWriteToolSchemas() {
     },
     {
       name: "set_budget",
-      description: 'Set the monthly budget amount for a category. amount="0" clears the budget. ' + 'Pass month="YYYY-MM" for a single-month override; omit for the all-months default. ' + 'Note: if the user has disabled "Enable budgeting" or "Enable rollover" in ' + "Copilot → Settings → General, the budget write still succeeds on the server, but " + "the value will not appear in the Copilot UI until those toggles are re-enabled. " + 'Rollover behavior also depends on the "Rollover categories" selection in the same ' + "settings pane, which is not writable through this tool. " + "Sync delay: successful writes may not be visible via `get_budgets` for minutes — " + "budget docs sync on a slower cadence than other collections. Do not retry the write " + "just because the read does not reflect it yet.",
+      description: 'Set the monthly budget amount for a category. amount="0" clears the budget. ' + 'Pass month="YYYY-MM" for a single-month override; omit for the all-months default. ' + 'Note: if the user has disabled "Enable budgeting" or "Enable rollover" in ' + "Copilot → Settings → General, the budget write still succeeds on the server, but " + "the value will not appear in the Copilot UI until those toggles are re-enabled. " + 'Rollover behavior also depends on the "Rollover categories" selection in the same ' + "settings pane, which is not writable through this tool.",
       inputSchema: {
         type: "object",
         properties: {
@@ -35444,7 +35534,7 @@ function createWriteToolSchemas() {
     },
     {
       name: "update_tag",
-      description: "Update an existing tag. Provide tag_id (required) and at least one of name, " + "color_name, or hex_color. Only the specified fields are updated. " + "Writes directly to Copilot Money via GraphQL.",
+      description: "Update an existing tag. Provide tag_id (required) and at least one of name or " + "color_name. Only the specified fields are updated. " + "Writes directly to Copilot Money via GraphQL.",
       inputSchema: {
         type: "object",
         properties: {
@@ -35458,11 +35548,7 @@ function createWriteToolSchemas() {
           },
           color_name: {
             type: "string",
-            description: 'New color name (e.g. "blue", "red")'
-          },
-          hex_color: {
-            type: "string",
-            description: 'New hex color code (e.g. "#FF5733")'
+            description: 'New palette token from Copilot (e.g. "PURPLE2", "OLIVE1", "RED1"). ' + "See existing tags for valid values."
           }
         },
         required: ["tag_id"]
@@ -36009,6 +36095,7 @@ Usage:
 Options:
   --db-path <path>    Path to LevelDB database (default: Copilot Money's default location)
   --timeout <ms>      Decode timeout in milliseconds (default: 90000 = 90 seconds)
+  --write             Enable write tools (sends authenticated requests to Copilot Money's GraphQL API)
   --verbose, -v       Enable verbose logging
   --help, -h          Show this help message
 
@@ -36038,9 +36125,6 @@ function configureLogging(verbose) {
 async function main() {
   const { dbPath, verbose, timeoutMs, writeFlagSeen } = parseArgs();
   configureLogging(verbose);
-  if (writeFlagSeen) {
-    console.error("[copilot-money-mcp] --write is temporarily unavailable: Copilot Money " + "has restricted direct Firestore writes from third-party clients. " + "Starting in read-only mode. Status: " + "https://github.com/ignaciohermosillacornejo/copilot-money-mcp/issues");
-  }
   try {
     if (verbose) {
       console.log("Starting Copilot Money MCP Server...");
@@ -36049,8 +36133,11 @@ async function main() {
       } else {
         console.log("Using default Copilot Money database location");
       }
+      if (writeFlagSeen) {
+        console.log("Write tools enabled (--write)");
+      }
     }
-    await runServer(dbPath, timeoutMs, false);
+    await runServer(dbPath, timeoutMs, writeFlagSeen);
   } catch (error48) {
     console.error("Server error:", error48);
     process.exit(1);

package/dist/decode-worker.js

@@ -15171,6 +15171,8 @@ function processRecurring(fields, docId) {
   }
 }
 function processBudget(fields, docId) {
+  if (fields.size === 0)
+    return null;
   const budgetId = getString(fields, "budget_id") ?? docId;
   const budgetData = {
     budget_id: budgetId

package/dist/server.js

@@ -27839,6 +27839,7 @@ class StdioServerTransport {
 }
 
 // src/core/database.ts
+import { randomUUID } from "crypto";
 import { existsSync, readdirSync } from "fs";
 import { homedir } from "os";
 import { join } from "path";
@@ -29764,6 +29765,8 @@ function processRecurring(fields, docId) {
   }
 }
 function processBudget(fields, docId) {
+  if (fields.size === 0)
+    return null;
   const budgetId = getString(fields, "budget_id") ?? docId;
   const budgetData = {
     budget_id: budgetId
@@ -31552,6 +31555,81 @@ class CopilotDatabase {
     Object.assign(txn, fields);
     return true;
   }
+  patchCachedBudget(categoryId, amount, month) {
+    if (!this._budgets)
+      return false;
+    const monthKey = month ?? (() => {
+      const d = new Date;
+      return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}`;
+    })();
+    const existing = this._budgets.find((b) => b.category_id === categoryId);
+    if (existing) {
+      existing.amounts = { ...existing.amounts ?? {}, [monthKey]: amount };
+    } else {
+      this._budgets.push({
+        budget_id: randomUUID(),
+        category_id: categoryId,
+        amounts: { [monthKey]: amount }
+      });
+    }
+    return true;
+  }
+  patchCachedTagUpsert(tag) {
+    if (!this._tags)
+      return;
+    const idx = this._tags.findIndex((t) => t.tag_id === tag.tag_id);
+    if (idx >= 0) {
+      Object.assign(this._tags[idx], tag);
+    } else {
+      this._tags.push(tag);
+    }
+  }
+  patchCachedTagDelete(tagId) {
+    if (!this._tags)
+      return false;
+    const before = this._tags.length;
+    this._tags = this._tags.filter((t) => t.tag_id !== tagId);
+    return this._tags.length < before;
+  }
+  patchCachedCategoryUpsert(category) {
+    if (!this._userCategories)
+      return;
+    const idx = this._userCategories.findIndex((c) => c.category_id === category.category_id);
+    if (idx >= 0) {
+      Object.assign(this._userCategories[idx], category);
+    } else {
+      this._userCategories.push(category);
+    }
+    this._categoryNameMap = null;
+  }
+  patchCachedCategoryDelete(categoryId) {
+    if (!this._userCategories)
+      return false;
+    const before = this._userCategories.length;
+    this._userCategories = this._userCategories.filter((c) => c.category_id !== categoryId);
+    if (this._userCategories.length < before) {
+      this._categoryNameMap = null;
+      return true;
+    }
+    return false;
+  }
+  patchCachedRecurringUpsert(recurring) {
+    if (!this._recurring)
+      return;
+    const idx = this._recurring.findIndex((r) => r.recurring_id === recurring.recurring_id);
+    if (idx >= 0) {
+      Object.assign(this._recurring[idx], recurring);
+    } else {
+      this._recurring.push(recurring);
+    }
+  }
+  patchCachedRecurringDelete(recurringId) {
+    if (!this._recurring)
+      return false;
+    const before = this._recurring.length;
+    this._recurring = this._recurring.filter((r) => r.recurring_id !== recurringId);
+    return this._recurring.length < before;
+  }
   getCacheLoadedAt() {
     return this._cacheLoadedAt;
   }
@@ -32568,14 +32646,6 @@ var CREATE_RECURRING = `mutation CreateRecurring($input: CreateRecurringInput!)
   createRecurring(input: $input) {
     __typename
     ...RecurringFields
-    rule {
-      __typename
-      ...RecurringRuleFields
-    }
-    payments {
-      __typename
-      ...RecurringPaymentFields
-    }
   }
 }
 
@@ -32601,21 +32671,6 @@ fragment RecurringFields on Recurring {
   state
   name
   id
-}
-
-fragment RecurringRuleFields on RecurringRule {
-  __typename
-  nameContains
-  minAmount
-  maxAmount
-  days
-}
-
-fragment RecurringPaymentFields on RecurringPayment {
-  __typename
-  amount
-  isPaid
-  date
 }`;
 var EDIT_RECURRING = `mutation EditRecurring($id: ID!, $input: EditRecurringInput!) {
   editRecurring(id: $id, input: $input) {
@@ -32623,14 +32678,6 @@ var EDIT_RECURRING = `mutation EditRecurring($id: ID!, $input: EditRecurringInpu
     recurring {
       __typename
       ...RecurringFields
-      rule {
-        __typename
-        ...RecurringRuleFields
-      }
-      payments {
-        __typename
-        ...RecurringPaymentFields
-      }
     }
   }
 }
@@ -32657,21 +32704,6 @@ fragment RecurringFields on Recurring {
   state
   name
   id
-}
-
-fragment RecurringRuleFields on RecurringRule {
-  __typename
-  nameContains
-  minAmount
-  maxAmount
-  days
-}
-
-fragment RecurringPaymentFields on RecurringPayment {
-  __typename
-  amount
-  isPaid
-  date
 }`;
 var DELETE_RECURRING = `mutation DeleteRecurring($deleteRecurringId: ID!) {
   deleteRecurring(id: $deleteRecurringId)
@@ -32802,20 +32834,8 @@ async function editRecurring(client, args) {
   const changed = {};
   if ("state" in args.input)
     changed.state = recurring.state;
-  if ("rule" in args.input && recurring.rule) {
-    const serverRule = recurring.rule;
-    const stringRule = {};
-    if ("nameContains" in serverRule)
-      stringRule.nameContains = serverRule.nameContains;
-    if ("minAmount" in serverRule && serverRule.minAmount !== undefined) {
-      stringRule.minAmount = String(serverRule.minAmount);
-    }
-    if ("maxAmount" in serverRule && serverRule.maxAmount !== undefined) {
-      stringRule.maxAmount = String(serverRule.maxAmount);
-    }
-    if ("days" in serverRule)
-      stringRule.days = serverRule.days;
-    changed.rule = stringRule;
+  if ("rule" in args.input && args.input.rule) {
+    changed.rule = { ...args.input.rule };
   }
   return { id: recurring.id, changed };
 }
@@ -33855,23 +33875,32 @@ class CopilotMoneyTools {
   async getBudgets(options = {}) {
     const { active_only = false } = options;
     const allBudgets = await this.db.getBudgets(active_only);
+    const now = new Date;
+    const currentMonth = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, "0")}`;
+    const effectiveAmount = (b) => {
+      const override = b.amounts?.[currentMonth];
+      return override !== undefined ? override : b.amount;
+    };
+    const nonTombstone = allBudgets.filter((b) => b.category_id !== undefined || b.amount !== undefined || b.amounts !== undefined);
     const categoryMap2 = await this.getUserCategoryMap();
-    const budgets = allBudgets.filter((b) => {
+    const budgets = nonTombstone.filter((b) => {
       if (!b.category_id)
         return true;
       return categoryMap2.has(b.category_id) || isKnownPlaidCategory(b.category_id);
     });
     let totalBudgeted = 0;
     for (const budget of budgets) {
-      if (budget.amount) {
-        const monthlyAmount = budget.period === "yearly" ? budget.amount / 12 : budget.period === "weekly" ? budget.amount * 4.33 : budget.period === "daily" ? budget.amount * 30 : budget.amount;
+      const amt = effectiveAmount(budget);
+      if (amt) {
+        const monthlyAmount = budget.period === "yearly" ? amt / 12 : budget.period === "weekly" ? amt * 4.33 : budget.period === "daily" ? amt * 30 : amt;
         totalBudgeted += monthlyAmount;
       }
     }
     const enrichedBudgets = await Promise.all(budgets.map(async (b) => ({
       budget_id: b.budget_id,
       name: b.name,
-      amount: b.amount,
+      amount: effectiveAmount(b),
+      ...b.amounts ? { amounts: b.amounts } : {},
       period: b.period,
       category_id: b.category_id,
       category_name: b.category_id ? await this.resolveCategoryName(b.category_id) : undefined,
@@ -34078,6 +34107,13 @@ class CopilotMoneyTools {
           isExcluded: args.is_excluded ?? false
         }
       });
+      this.db.patchCachedCategoryUpsert({
+        category_id: result.id,
+        name: result.name,
+        color: result.colorName,
+        emoji: args.emoji,
+        excluded: args.is_excluded ?? false
+      });
       return {
         success: true,
         category_id: result.id,
@@ -34153,6 +34189,15 @@ class CopilotMoneyTools {
         isReviewed: "reviewed"
       };
       const updated = Object.keys(result.changed).map((k) => graphqlToApiName[k] ?? k);
+      const patch = {};
+      if ("category_id" in args && args.category_id !== undefined)
+        patch.category_id = args.category_id;
+      if ("note" in args && args.note !== undefined)
+        patch.user_note = args.note;
+      if ("tag_ids" in args && args.tag_ids !== undefined)
+        patch.tag_ids = args.tag_ids;
+      if (Object.keys(patch).length > 0)
+        this.db.patchCachedTransaction(transaction_id, patch);
       return {
         success: true,
         transaction_id: result.id,
@@ -34223,6 +34268,9 @@ class CopilotMoneyTools {
       }
       throw error48;
     }
+    for (const id of transaction_ids) {
+      this.db.patchCachedTransaction(id, { user_reviewed: reviewed });
+    }
     return {
       success: true,
       reviewed_count,
@@ -34238,6 +34286,11 @@ class CopilotMoneyTools {
       const result = await createTag(client, {
         input: { name: args.name.trim(), colorName }
       });
+      this.db.patchCachedTagUpsert({
+        tag_id: result.id,
+        name: result.name,
+        color_name: result.colorName
+      });
       return {
         success: true,
         tag_id: result.id,
@@ -34254,6 +34307,7 @@ class CopilotMoneyTools {
     const client = this.getGraphQLClient();
     try {
       const result = await deleteTag(client, { id: args.tag_id });
+      this.db.patchCachedTagDelete(args.tag_id);
       return { success: true, tag_id: result.id, deleted: true };
     } catch (e) {
       if (e instanceof GraphQLError)
@@ -34277,6 +34331,16 @@ class CopilotMoneyTools {
     }
     try {
       const result = await editCategory(client, { id: args.category_id, input });
+      const patch = { category_id: args.category_id };
+      if (args.name !== undefined)
+        patch.name = args.name;
+      if (args.color_name !== undefined)
+        patch.color = args.color_name;
+      if (args.emoji !== undefined)
+        patch.emoji = args.emoji;
+      if (args.is_excluded !== undefined)
+        patch.excluded = args.is_excluded;
+      this.db.patchCachedCategoryUpsert(patch);
       return {
         success: true,
         category_id: result.id,
@@ -34292,6 +34356,7 @@ class CopilotMoneyTools {
     const client = this.getGraphQLClient();
     try {
       const result = await deleteCategory(client, { id: args.category_id });
+      this.db.patchCachedCategoryDelete(args.category_id);
       return { success: true, category_id: result.id, deleted: true };
     } catch (e) {
       if (e instanceof GraphQLError)
@@ -34318,6 +34383,7 @@ class CopilotMoneyTools {
         amount: args.amount,
         month: args.month
       });
+      this.db.patchCachedBudget(args.category_id, parseFloat(args.amount), args.month);
       return {
         success: true,
         category_id: result.categoryId,
@@ -34342,6 +34408,10 @@ class CopilotMoneyTools {
         id: args.recurring_id,
         input: { state: args.state }
       });
+      this.db.patchCachedRecurringUpsert({
+        recurring_id: args.recurring_id,
+        state: args.state.toLowerCase()
+      });
       return { success: true, recurring_id: result.id, state: args.state };
     } catch (e) {
       if (e instanceof GraphQLError)
@@ -34353,6 +34423,7 @@ class CopilotMoneyTools {
     const client = this.getGraphQLClient();
     try {
       const result = await deleteRecurring(client, { id: args.recurring_id });
+      this.db.patchCachedRecurringDelete(args.recurring_id);
       return { success: true, recurring_id: result.id, deleted: true };
     } catch (e) {
       if (e instanceof GraphQLError)
@@ -34372,6 +34443,12 @@ class CopilotMoneyTools {
     }
     try {
       const result = await editTag(client, { id: args.tag_id, input });
+      const patch = { tag_id: args.tag_id };
+      if (args.name !== undefined)
+        patch.name = args.name;
+      if (args.color_name !== undefined)
+        patch.color_name = args.color_name;
+      this.db.patchCachedTagUpsert(patch);
       return { success: true, tag_id: result.id, updated: Object.keys(result.changed) };
     } catch (e) {
       if (e instanceof GraphQLError)
@@ -34403,6 +34480,12 @@ class CopilotMoneyTools {
           }
         }
       });
+      this.db.patchCachedRecurringUpsert({
+        recurring_id: result.id,
+        name: result.name,
+        state: result.state.toLowerCase(),
+        frequency: result.frequency
+      });
       return {
         success: true,
         recurring_id: result.id,
@@ -34438,6 +34521,17 @@ class CopilotMoneyTools {
     }
     try {
       const result = await editRecurring(client, { id: args.recurring_id, input });
+      const patch = { recurring_id: args.recurring_id };
+      if (args.state !== undefined) {
+        patch.state = args.state.toLowerCase();
+      }
+      if (args.rule?.name_contains !== undefined)
+        patch.match_string = args.rule.name_contains;
+      if (args.rule?.min_amount !== undefined)
+        patch.min_amount = parseFloat(args.rule.min_amount);
+      if (args.rule?.max_amount !== undefined)
+        patch.max_amount = parseFloat(args.rule.max_amount);
+      this.db.patchCachedRecurringUpsert(patch);
       return { success: true, recurring_id: result.id, updated: Object.keys(result.changed) };
     } catch (e) {
       if (e instanceof GraphQLError)
@@ -34894,7 +34988,7 @@ function createToolSchemas() {
     },
     {
       name: "get_budgets",
-      description: "Get budgets from Copilot's native budget tracking. " + "Retrieves user-defined spending limits and budget rules stored in the app. " + "Returns budget details including amounts, periods (monthly/yearly/weekly), " + "category associations, and active status. Calculates total budgeted amount as monthly equivalent. " + "Sync note: after `set_budget` writes, budget changes can take significantly longer " + "to reflect in this read than other collections (transactions/tags/categories/recurrings " + "sync in seconds; budgets may take minutes). Do not assume a fresh `set_budget` is " + "immediately observable here — poll with `refresh_database` or verify directly in the " + "Copilot app. Per-month overrides written via `set_budget(month=...)` are not surfaced " + "in this view; only the all-months default `amount` is returned.",
+      description: "Get budgets from Copilot's native budget tracking. " + "Returns the current-month effective budget per category plus the full " + "`amounts` map of per-month overrides for history lookups. For parent " + "categories, the returned `amount` is the resolved total (children + " + "rollovers) that Copilot displays in the Budgets view. Totals use the " + "current-month effective amount.",
       inputSchema: {
         type: "object",
         properties: {
@@ -35015,7 +35109,7 @@ function createToolSchemas() {
     },
     {
       name: "get_balance_history",
-      description: "Get daily balance snapshots for accounts over time. Returns current_balance, " + "available_balance, and limit per day. Requires a granularity parameter (daily, weekly, " + "or monthly) to control response size. Weekly and monthly modes downsample by keeping " + "the last data point per period. Filter by account_id and date range.",
+      description: "Get daily balance snapshots for accounts over time. Each entry returns current_balance, " + "available_balance, limit, account_id, and account_name. The response also includes an " + "`accounts` array listing the distinct account IDs in the paginated page. Requires a " + "granularity parameter (daily, weekly, or monthly) to control response size. Weekly and " + "monthly modes downsample by keeping the last data point per period. Filter by " + "account_id and date range.",
       inputSchema: {
         type: "object",
         properties: {
@@ -35214,7 +35308,7 @@ function createWriteToolSchemas() {
     },
     {
       name: "review_transactions",
-      description: "Mark one or more transactions as reviewed (or unreviewed). " + "Accepts an array of transaction_ids. Writes directly to Copilot Money via GraphQL.",
+      description: "Mark one or more transactions as reviewed (or unreviewed). " + "Accepts an array of transaction_ids. Writes are issued via GraphQL in parallel with " + "a cap of 5 in flight at a time. On the first GraphQL error, new writes stop, in-flight " + "writes settle, and the error is thrown with a `reviewed_count` reflecting how many " + "succeeded before the failure (partial success is possible).",
       inputSchema: {
         type: "object",
         properties: {
@@ -35248,11 +35342,7 @@ function createWriteToolSchemas() {
           },
           color_name: {
             type: "string",
-            description: 'Optional color name (e.g. "blue", "red")'
-          },
-          hex_color: {
-            type: "string",
-            description: 'Optional hex color code (e.g. "#FF5733")'
+            description: 'Optional palette token from Copilot (e.g. "PURPLE2", "OLIVE1", "RED1"). ' + 'Defaults to "PURPLE2" when omitted. See existing tags for valid values.'
           }
         },
         required: ["name"]
@@ -35372,7 +35462,7 @@ function createWriteToolSchemas() {
     },
     {
       name: "set_budget",
-      description: 'Set the monthly budget amount for a category. amount="0" clears the budget. ' + 'Pass month="YYYY-MM" for a single-month override; omit for the all-months default. ' + 'Note: if the user has disabled "Enable budgeting" or "Enable rollover" in ' + "Copilot → Settings → General, the budget write still succeeds on the server, but " + "the value will not appear in the Copilot UI until those toggles are re-enabled. " + 'Rollover behavior also depends on the "Rollover categories" selection in the same ' + "settings pane, which is not writable through this tool. " + "Sync delay: successful writes may not be visible via `get_budgets` for minutes — " + "budget docs sync on a slower cadence than other collections. Do not retry the write " + "just because the read does not reflect it yet.",
+      description: 'Set the monthly budget amount for a category. amount="0" clears the budget. ' + 'Pass month="YYYY-MM" for a single-month override; omit for the all-months default. ' + 'Note: if the user has disabled "Enable budgeting" or "Enable rollover" in ' + "Copilot → Settings → General, the budget write still succeeds on the server, but " + "the value will not appear in the Copilot UI until those toggles are re-enabled. " + 'Rollover behavior also depends on the "Rollover categories" selection in the same ' + "settings pane, which is not writable through this tool.",
       inputSchema: {
         type: "object",
         properties: {
@@ -35443,7 +35533,7 @@ function createWriteToolSchemas() {
     },
     {
       name: "update_tag",
-      description: "Update an existing tag. Provide tag_id (required) and at least one of name, " + "color_name, or hex_color. Only the specified fields are updated. " + "Writes directly to Copilot Money via GraphQL.",
+      description: "Update an existing tag. Provide tag_id (required) and at least one of name or " + "color_name. Only the specified fields are updated. " + "Writes directly to Copilot Money via GraphQL.",
       inputSchema: {
         type: "object",
         properties: {
@@ -35457,11 +35547,7 @@ function createWriteToolSchemas() {
           },
           color_name: {
             type: "string",
-            description: 'New color name (e.g. "blue", "red")'
-          },
-          hex_color: {
-            type: "string",
-            description: 'New hex color code (e.g. "#FF5733")'
+            description: 'New palette token from Copilot (e.g. "PURPLE2", "OLIVE1", "RED1"). ' + "See existing tags for valid values."
           }
         },
         required: ["tag_id"]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "copilot-money-mcp",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "MCP server for Copilot Money — query personal finances locally (17 read tools) and manage them via Copilot's GraphQL API (13 write tools, opt-in with --write)",
   "keywords": [
     "mcp",
@@ -63,6 +63,7 @@
     "fix": "bun run lint:fix && bun run format",
     "clean": "rm -rf dist coverage .bun-build",
     "pack:mcpb": "bun run scripts/pack-mcpb.ts",
+    "pack:mcpb:write": "bun run scripts/sync-manifest.ts -- --write && bun run scripts/pack-mcpb.ts -- --write",
     "prepublishOnly": "bun run clean && bun run build && bun test",
     "prepare": "husky"
   },