copilot-money-mcp 1.1.0 → 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ignacio Hermosilla
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -108,39 +108,16 @@ After installing the MCP server, Claude Desktop will request **one-time approval
 **MCP Tool Call:**
 ```json
 {
-  "tool": "get_spending_by_category",
+  "tool": "get_transactions",
   "arguments": {
+    "category": "food_and_drink",
     "period": "last_month"
   }
 }
 ```
 
-**Response:**
-```json
-{
-  "period": {
-    "start_date": "2025-12-01",
-    "end_date": "2025-12-31"
-  },
-  "total_spending": 1847.32,
-  "category_count": 8,
-  "categories": [
-    {
-      "category": "food_dining",
-      "total_spending": 487.50,
-      "transaction_count": 23
-    },
-    {
-      "category": "groceries",
-      "total_spending": 612.80,
-      "transaction_count": 12
-    }
-  ]
-}
-```
-
 **Claude's Answer:**
-> "Last month you spent $487.50 on dining out across 23 transactions. Your largest spending category was groceries at $612.80. Overall, you spent $1,847.32 across 8 categories."
+> "Last month you spent $487.50 on dining out across 23 transactions. Your largest expense was $67.50 at The Italian Place on January 15th."
 
 ---
 
@@ -152,36 +129,14 @@ After installing the MCP server, Claude Desktop will request **one-time approval
 **MCP Tool Call:**
 ```json
 {
-  "tool": "search_transactions",
+  "tool": "get_transactions",
   "arguments": {
-    "query": "amazon"
+    "merchant": "amazon",
+    "period": "last_30_days"
   }
 }
 ```
 
-**Response:**
-```json
-{
-  "count": 7,
-  "transactions": [
-    {
-      "transaction_id": "txn_abc123",
-      "amount": 47.99,
-      "date": "2026-01-05",
-      "name": "Amazon.com",
-      "category_id": "shopping_online"
-    },
-    {
-      "transaction_id": "txn_def456",
-      "amount": 23.50,
-      "date": "2025-12-28",
-      "name": "Amazon Prime",
-      "category_id": "subscriptions"
-    }
-  ]
-}
-```
-
 **Claude's Answer:**
 > "You made 7 Amazon purchases in the last 30 days, totaling $234.87. The largest was $47.99 on January 5th. You also had a Prime subscription charge of $23.50."
 
@@ -200,35 +155,6 @@ After installing the MCP server, Claude Desktop will request **one-time approval
 }
 ```
 
-**Response:**
-```json
-{
-  "count": 3,
-  "total_balance": 12547.83,
-  "accounts": [
-    {
-      "account_id": "acc_checking",
-      "name": "Chase Checking",
-      "account_type": "checking",
-      "current_balance": 3247.50,
-      "mask": "1234"
-    },
-    {
-      "account_id": "acc_savings",
-      "name": "Ally Savings",
-      "account_type": "savings",
-      "current_balance": 8500.33
-    },
-    {
-      "account_id": "acc_credit",
-      "name": "Chase Freedom",
-      "account_type": "credit",
-      "current_balance": 800.00
-    }
-  ]
-}
-```
-
 **Claude's Answer:**
 > "Your total balance across all accounts is $12,547.83. This includes:
 > - Chase Checking: $3,247.50
@@ -237,88 +163,18 @@ After installing the MCP server, Claude Desktop will request **one-time approval
 
 ## Available Tools
 
-The MCP server provides 23 read-only tools for comprehensive financial analysis:
-
-### Core Tools
-
-### 1. `get_transactions`
-Query transactions with flexible filters.
-
-**Parameters:**
-- `period` - Date range shorthand (this_month, last_30_days, ytd, etc.)
-- `start_date` - Start date (YYYY-MM-DD)
-- `end_date` - End date (YYYY-MM-DD)
-- `category` - Filter by category (case-insensitive)
-- `merchant` - Filter by merchant name (case-insensitive)
-- `account_id` - Filter by account ID
-- `min_amount` / `max_amount` - Amount range
-- `limit` - Max results (default: 100)
-
-### 2. `search_transactions`
-Free-text search by merchant name.
-
-**Parameters:**
-- `query` - Search query (required)
-- `limit` - Max results (default: 50)
-
-### 3. `get_accounts`
-List all accounts with balances.
-
-**Parameters:**
-- `account_type` - Filter by type (checking, savings, credit, investment)
-
-### 4. `get_spending_by_category`
-Aggregate spending by category.
-
-**Parameters:**
-- `period` - Date range shorthand
-- `start_date` / `end_date` - Date range
-- `min_amount` - Minimum expense amount
-
-### 5. `get_account_balance`
-Get specific account details.
-
-**Parameters:**
-- `account_id` - Account ID (required)
-
-### Data Quality & Advanced Analysis Tools
-
-### 6. `get_data_quality_report`
-Generate a comprehensive data quality report to identify issues in your financial data that should be corrected in Copilot Money.
-
-This tool helps you find:
-- **Unresolved category IDs** - Transactions with category IDs that can't be mapped to human-readable names
-- **Potential currency conversion issues** - Large amounts with foreign merchant names that may be displaying unconverted foreign currency
-- **Non-unique transaction IDs** - Multiple transactions sharing the same ID
-- **Duplicate accounts** - Accounts with the same name and type that may be duplicates
-- **Suspicious categorizations** - Common miscategorizations (e.g., Uber as Parking, pharmacies as Office Supplies)
-
-**Parameters:**
-- `period` - Date range shorthand (this_month, last_90_days, ytd, etc.)
-- `start_date` / `end_date` - Custom date range
-
-**Use Case:** Run this tool before doing financial analysis to identify data quality issues that could skew your results. It's especially useful after international travel or if you notice unexpected spending totals.
-
-### Other Analysis Tools
-
-The server also provides these additional tools:
-- `get_categories` - List all transaction categories
-- `get_recurring_transactions` - Find subscriptions and recurring payments
-- `get_income` - Track income sources
-- `get_spending_by_merchant` - Merchant spending analysis
-- `compare_periods` - Compare spending across time periods
-- `get_foreign_transactions` - International transactions and FX fees
-- `get_refunds` - Refund transactions
-- `get_duplicate_transactions` - Find duplicate transactions
-- `get_credits` - Credit transactions
-- `get_spending_by_day_of_week` - Spending patterns by day
-- `get_trips` - Travel analysis with location detection
-- `get_transaction_by_id` - Lookup specific transactions
-- `get_top_merchants` - Top merchants by spending
-- `get_unusual_transactions` - Anomaly detection
-- `export_transactions` - Export to CSV or JSON
-- `get_hsa_fsa_eligible` - Healthcare expenses
-- `get_spending_rate` - Spending velocity analysis
+The MCP server provides **8 read-only tools** for querying your financial data:
+
+| Tool | Description |
+|------|-------------|
+| `get_transactions` | Query transactions with filters (date, category, merchant, amount, account, location). Supports period shortcuts, text search, and special types (foreign, refunds, duplicates). |
+| `get_accounts` | List all accounts with balances, optionally filter by type (checking, savings, credit, investment). |
+| `get_categories` | List all transaction categories with human-readable names, transaction counts, and spending totals. Filter by date range. |
+| `get_recurring_transactions` | Identify subscriptions and recurring charges with frequency, monthly cost, and next expected date. Filter by name for detailed view. |
+| `get_budgets` | Get budgets from Copilot's native budget tracking with spending vs. limit comparisons. |
+| `get_goals` | Get financial goals with progress tracking, monthly history, and savings status. |
+| `get_cache_info` | Get information about the local data cache, including date range and transaction count. |
+| `refresh_database` | Refresh the in-memory cache to pick up newly synced data from Copilot Money. Cache auto-refreshes every 5 minutes. |
 
 See tool schemas in Claude Desktop or use the MCP Inspector for complete parameter documentation.
 
@@ -384,7 +240,7 @@ copilot-money-mcp/
 - **Language:** TypeScript 5.3+
 - **Validation:** Zod schemas
 - **Database:** LevelDB (classic-level) + Protocol Buffers
-- **Testing:** Bun test runner (366 tests, 100% passing)
+- **Testing:** Bun test runner (726 tests, 100% passing)
 - **MCP SDK:** @modelcontextprotocol/sdk v1.2
 
 ## Testing
@@ -401,8 +257,8 @@ npm run test:coverage
 ```
 
 **Test Coverage:**
-- ✅ 366 tests passing
-- ✅ 1360+ assertions
+- ✅ 726 tests passing
+- ✅ 1870+ assertions
 - ✅ Core decoder tests
 - ✅ Database abstraction tests
 - ✅ Tool implementation tests
@@ -432,6 +288,40 @@ The `period` parameter supports these shortcuts:
 - `this_year` - Current calendar year
 - `last_year` - Previous calendar year
 
+## Configuration
+
+### Cache TTL
+
+The MCP server caches data in memory for 5 minutes by default. You can configure this via environment variable:
+
+```bash
+# Set cache TTL to 10 minutes
+COPILOT_CACHE_TTL_MINUTES=10 copilot-money-mcp
+
+# Disable caching (always reload from disk)
+COPILOT_CACHE_TTL_MINUTES=0 copilot-money-mcp
+```
+
+You can also manually refresh the cache using the `refresh_database` tool.
+
+## Known Limitations
+
+### Local Cache Size
+
+This MCP server reads from Copilot Money's **local Firestore cache**, not directly from the cloud. The cache typically contains:
+- **~500 recent transactions** (not your full history)
+- Accounts, budgets, goals, and recurring transactions
+- Data synced during recent app usage
+
+**Why this limitation exists:** Copilot Money uses Firebase/Firestore with App Check security, which prevents direct cloud database access. The local cache is an offline copy maintained by the app for performance.
+
+**To maximize cached data:**
+1. Open the Copilot Money app regularly
+2. Scroll through your transaction history to trigger sync
+3. The cache updates when you interact with the app
+
+**What you get:** While you may have thousands of transactions in Copilot Money, only recently accessed/synced data is available locally. This is sufficient for most queries (recent spending, current budgets, recurring charges) but won't include your complete historical data.
+
 ## Troubleshooting
 
 ### Database Not Found