copilot-money-mcp 2.1.0 → 2.2.0

package/README.md

@@ -17,7 +17,7 @@
 
 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.**
 
-**17 read tools** across spending, investments, budgets, goals, and more — query transactions, accounts, holdings, balances, categories, recurring charges, budgets, goals, and investment performance.
+**14 cache-mode read tools (or 21 in `--live-reads` mode: 8 surviving cache + 13 live), plus up to 17 write tools** — query and modify transactions, accounts, holdings, balances, categories, recurring charges, budgets, goals, and investment performance. See [Tools by Mode](#tools-by-mode) below.
 
 ## Privacy First
 
@@ -32,6 +32,22 @@ We never collect, store, or transmit your data to any server operated by this pr
 >
 > **By using this MCP server with a hosted AI model, you are knowingly sharing your financial data with that AI provider.** Only use this tool if you are comfortable with that trade-off. If you are not, consider waiting for an official Copilot Money integration or using a fully local model.
 
+## Tools by Mode
+
+This server exposes different tools depending on which CLI flags you enable.
+
+| Mode | Flag | What it does | Auth | Network | Tools available |
+|---|---|---|---|---|---|
+| 🟢 Default | _(none)_ | Reads from your local LevelDB cache | ❌ None | 🔌 Zero (offline) | 14 cache-mode read + utility tools |
+| 🌐 Live reads | `--live-reads` | Real-time reads via Copilot's GraphQL API; swaps out 6 cache tools and adds 7 live-only ones | 🔒 Browser session | 🌐 HTTPS per request | 21 read tools (8 cache + 13 live) |
+| ✍️ Writes | `--write` | Adds mutation tools (transactions, tags, categories, budgets, recurrings, splits) | 🔒 Browser session | 🌐 HTTPS per request | +17 write tools (additive to either read mode) |
+
+`--live-reads` and `--write` can be combined.
+
+📖 **See [docs/tools-by-mode.md](docs/tools-by-mode.md)** for the full per-tool inventory with status, caveats, and known limitations (goals, stock splits, response-size caps).
+
+---
+
 ## Quick Start
 
 ### Prerequisites
@@ -95,7 +111,7 @@ Then add to your Claude Desktop configuration (`~/Library/Application Support/Cl
 
 > "What are my top 5 spending categories this year?"
 
-Uses `get_transactions`, `get_categories` with date ranges, text search, and category filters.
+Uses `get_transactions` (or `get_transactions_live` for fresh data via `--live-reads`) and `get_categories` (or `get_categories_live`), with date ranges, text search, and category filters.
 
 ### Account Overview
 
@@ -105,17 +121,17 @@ Uses `get_transactions`, `get_categories` with date ranges, text search, and cat
 
 > "Which bank connections need attention?"
 
-Uses `get_accounts`, `get_balance_history`, `get_connection_status`.
+Uses `get_accounts` (or `get_accounts_live` for fresh balances via `--live-reads`), `get_balance_history` (with optional `get_balance_history_live` per-account live variant), `get_connection_status`, and `get_networth_live` for net-worth-over-time charts.
 
 ### Investment Portfolio
 
 > "What are my current holdings and total returns?"
 
-> "Show me AAPL price history for the past year"
+> "Show me the price history for my largest equity holding over the past year"
 
-> "What's my time-weighted return this quarter?"
+> "What's my current cost basis on META?"
 
-Uses `get_holdings`, `get_investment_prices`, `get_securities`, `get_investment_performance`, `get_twr_returns`.
+Uses `get_holdings` (or `get_holdings_live` for live cost basis), `get_investment_prices` (or `get_investment_prices_live` for live per-security price history).
 
 ### Budgets & Goals
 
@@ -125,7 +141,7 @@ Uses `get_holdings`, `get_investment_prices`, `get_securities`, `get_investment_
 
 > "Show me my goal history over the past 6 months"
 
-Uses `get_budgets`, `get_goals`, `get_goal_history`.
+Uses `get_budgets` (or `get_budgets_live` via `--live-reads`), and `get_goals` / `get_goal_history` (cache-only — Copilot's GraphQL endpoint doesn't expose goal data).
 
 ### Subscriptions & Recurring
 
@@ -133,31 +149,7 @@ Uses `get_budgets`, `get_goals`, `get_goal_history`.
 
 > "How much do I spend on recurring charges per month?"
 
-Uses `get_recurring_transactions`.
-
-## Available Tools
-
-### Read Tools (17)
-
-| Tool | Description |
-|------|-------------|
-| `get_transactions` | Query transactions with filters — date range, category, merchant, amount, account, location, text search, and special types (foreign, refunds, duplicates, HSA-eligible). |
-| `get_accounts` | List all accounts with balances, filter by type (checking, savings, credit, investment). Includes net worth calculation. |
-| `get_categories` | List categories with transaction counts and spending totals. Supports list, tree, and search views. |
-| `get_recurring_transactions` | Identify subscriptions and recurring charges with frequency, cost, and next expected date. |
-| `get_budgets` | Get budgets with spending vs. limit comparisons. |
-| `get_goals` | Get financial goals with target amounts, progress, and monthly contributions. |
-| `get_goal_history` | Monthly progress snapshots for goals with daily data and contribution records. |
-| `get_balance_history` | Daily balance snapshots for accounts over time. Supports daily, weekly, or monthly granularity. |
-| `get_holdings` | Current investment holdings with ticker, quantity, price, cost basis, and total return. |
-| `get_investment_prices` | Historical price data (daily + high-frequency) for stocks, ETFs, mutual funds, and crypto. |
-| `get_investment_splits` | Stock split history with ratios, dates, and multipliers. |
-| `get_investment_performance` | Per-security investment performance data. |
-| `get_twr_returns` | Time-weighted return (TWR) monthly data for investment holdings. |
-| `get_securities` | Security master data — ticker, name, type, price, and identifiers (ISIN/CUSIP). |
-| `get_connection_status` | Bank sync health for linked institutions, including last sync timestamps and errors. |
-| `get_cache_info` | Local cache metadata — date range, transaction count, cache age. |
-| `refresh_database` | Reload data from disk. Cache auto-refreshes every 5 minutes. |
+Uses `get_recurring_transactions` (or `get_recurring_live` via `--live-reads`) and `get_upcoming_recurrings_live` for next-due unpaid items.
 
 ## Configuration
 
@@ -210,6 +202,58 @@ The `period` parameter supports these shortcuts:
 
 `this_month` `last_month` `last_7_days` `last_30_days` `last_90_days` `ytd` `this_year` `last_year`
 
+## Authentication & Optional Modes
+
+Both `--live-reads` and `--write` make authenticated calls to Copilot Money's GraphQL API at `app.copilot.money/api/graphql`. They require a **logged-in browser session** against `app.copilot.money` — the server reads the same Firebase refresh token the web app stores in your browser (Chrome, Arc, Safari, or Firefox).
+
+Default mode requires no authentication and makes zero network requests — reads come from the local LevelDB cache.
+
+### `--live-reads`: real-time reads via GraphQL
+
+```bash
+copilot-money-mcp --live-reads
+```
+
+Replaces 6 cache-mode read tools (`get_transactions`, `get_accounts`, `get_categories`, `get_budgets`, `get_recurring_transactions`, `get_holdings`) with live GraphQL-backed equivalents, and adds 7 net-new ones (`get_tags_live`, `get_networth_live`, `get_upcoming_recurrings_live`, `get_monthly_spend_live`, `get_balance_history_live`, `get_investment_prices_live`, `refresh_cache`).
+
+Use this when:
+- You need transactions the macOS app hasn't pre-fetched yet (the auto-fetch window is typically ~30 days; past that, open the app and scroll back to force the cache to populate, or use `--live-reads` to query the server directly).
+- You want fresh per-security cost basis or balance-over-time data.
+- The macOS app hasn't synced recently.
+
+### `--write`: mutations via GraphQL
+
+```bash
+copilot-money-mcp --write
+```
+
+Adds 17 mutation tools for transactions, tags, categories, recurrings, budgets, and split-transactions. Off by default — the server is read-only unless you opt in.
+
+### Combining both
+
+```bash
+copilot-money-mcp --live-reads --write
+```
+
+Live reads + write tools together — the most common power-user setup.
+
+### Configuring via Claude Desktop / Cursor
+
+Add the flags to the `args` array in your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "copilot-money": {
+      "command": "copilot-money-mcp",
+      "args": ["--live-reads", "--write"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop / Cursor after editing.
+
 ## Known Limitations
 
 ### Local Cache Dependency
@@ -218,6 +262,24 @@ This server reads from Copilot Money's **local Firestore cache**, not the cloud.
 
 **To maximize cached data:** Open the Copilot Money app and browse through your data (transaction history, accounts, budgets) to ensure it has been fetched and cached locally.
 
+### Goals are read-only
+
+`get_goals` and `get_goal_history` work (cache-only), but there are no goal write tools — Copilot's GraphQL endpoint doesn't expose goal mutations. Goal creation, editing, and contributions are mobile-only in Copilot itself, and live in a path our project can't reach without iOS / desktop traffic capture.
+
+### Investment splits are limited to currently-held securities
+
+`get_investment_splits` returns split events (date + adjustment multiplier) for securities you currently hold. Securities you no longer hold eventually fall out of the cache. There's no GraphQL endpoint for splits, so this is the only path.
+
+Also: `get_investment_prices` and `get_investment_prices_live` already return split- and dividend-adjusted prices (Copilot applies Plaid's adjustment factors server-side). You generally don't need raw split events to back-correct prices.
+
+### Live investment prices are ownership-gated
+
+`get_investment_prices_live` only works for securities currently in your linked accounts. Asking for a price series on a ticker you don't own returns an explicit "not in your linked accounts" error.
+
+### Long time-series responses are capped
+
+Time-series live tools (`get_balance_history_live`, `get_networth_live`, `get_investment_prices_live`) cap responses at 500 rows by default to fit the MCP single-tool-result token limit. Pass `max_rows` / `offset` to paginate, or narrow `time_frame` for fewer rows.
+
 ## Troubleshooting
 
 ### Database Not Found