actual-mcp-server 0.5.7 → 0.6.0

package/README.md

@@ -47,6 +47,7 @@ Most Actual Budget MCP implementations are simple stdio bridges designed for sin
 ## Table of Contents
 
 - [Quick Start](#quick-start)
+- [Upgrading](#upgrading)
 - [Available Tools](#available-tools)
 - [Configuration](#configuration)
 - [Multi-Budget Switching](#multi-budget-switching)
@@ -234,6 +235,51 @@ See [docs/guides/MCP_CLIENTS_SETUP.md](docs/guides/MCP_CLIENTS_SETUP.md) for all
 
 ---
 
+## Upgrading
+
+### Docker (Option A)
+
+```bash
+docker pull ghcr.io/agigante80/actual-mcp-server:latest
+docker stop actual-mcp-server-backend
+docker rm actual-mcp-server-backend
+# Re-run the original docker run command with the same flags and volumes
+```
+
+Also available on Docker Hub: `docker pull agigante80/actual-mcp-server:latest`
+
+### Docker Compose (Option B)
+
+```bash
+docker compose pull
+docker compose --profile production up -d
+```
+
+### npm / cloned repo (Option C)
+
+```bash
+git pull
+npm install
+npm run build
+# Then restart the server
+```
+
+### npx / stdio (Options C & D)
+
+If you run `npx actual-mcp-server` without a globally installed version, npx fetches the latest from the registry automatically. But if you previously installed it globally (`npm install -g actual-mcp-server`), the global install takes precedence — you must upgrade it explicitly:
+
+```bash
+# Upgrade the global install
+npm install -g actual-mcp-server
+
+# Or force the registry version without touching your global install
+npx actual-mcp-server@latest --http
+```
+
+For Claude Desktop (stdio), restart Claude after upgrading.
+
+---
+
 ## Available Tools
 
 **63 tools** across 12 categories. All tools use the `actual_<category>_<action>` naming convention.
@@ -250,7 +296,7 @@ See [docs/guides/MCP_CLIENTS_SETUP.md](docs/guides/MCP_CLIENTS_SETUP.md) for all
 | `actual_accounts_reopen` | Reopen closed account |
 | `actual_accounts_get_balance` | Get account balance at a date |
 
-### Transactions (12)
+### Transactions (13)
 
 **Standard (6)**
 
@@ -263,6 +309,12 @@ See [docs/guides/MCP_CLIENTS_SETUP.md](docs/guides/MCP_CLIENTS_SETUP.md) for all
 | `actual_transactions_update` | Update a transaction |
 | `actual_transactions_delete` | Delete a transaction |
 
+**Utility (1)**
+
+| Tool | Description |
+|------|-------------|
+| `actual_transactions_uncategorized` | Summary of uncategorized transactions (totalCount, totalAmount, per-account breakdown); pass `includeTransactions:true` for paginated rows |
+
 **Exclusive ActualQL-powered (6)** — unique to this MCP server
 
 | Tool | Description |
@@ -678,4 +730,4 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.5.7 | **Tool Count:** 63 (verified LibreChat-compatible)
+**Version:** 0.6.0 | **Tool Count:** 63 (verified LibreChat-compatible)

package/dist/package.json

@@ -1,12 +1,13 @@
 {
     "name": "actual-mcp-server",
     "displayName": "Actual MCP Server",
-    "version": "0.5.7",
+    "version": "0.6.0",
     "engines": {
         "node": ">=20.0.0",
         "npm": ">=10.0.0"
     },
-    "description": "MCP server with 62 tools for AI-driven financial management with Actual Budget — HTTP and stdio transports, LibreChat, Claude Desktop, Cursor, VS Code, Gemini CLI",
+    "description": "MCP server with 63 tools for AI-driven financial management with Actual Budget — HTTP and stdio transports, LibreChat, Claude Desktop, Cursor, VS Code, Gemini CLI",
+    "homepage": "https://github.com/agigante80/actual-mcp-server#readme",
     "repository": {
         "type": "git",
         "url": "https://github.com/agigante80/actual-mcp-server"

package/dist/src/index.js

@@ -89,6 +89,22 @@ if (unknownFlags.length > 0) {
     console.error(`Unknown option: ${unknownFlags.join(', ')}\nRun \`actual-mcp-server --help\` for usage.`);
     process.exit(1);
 }
+// Early transport mode check — before dotenv and dynamic imports.
+// Without this, the config validation error fires first and confuses users who
+// simply forgot to pass --http or --stdio.
+if (!argsEarly.includes('--http') &&
+    !argsEarly.includes('--stdio') &&
+    !argsEarly.includes('--test-actual-connection') &&
+    !argsEarly.includes('--test-mcp-client') &&
+    !argsEarly.includes('--help') && !argsEarly.includes('-h') &&
+    !argsEarly.includes('--version') && !argsEarly.includes('-v')) {
+    console.error('No transport mode specified.\n\n' +
+        'Usage:\n' +
+        '  actual-mcp-server --http        # HTTP server (LibreChat / LobeChat / multi-user)\n' +
+        '  actual-mcp-server --stdio       # stdio transport (Claude Desktop / Claude Code)\n\n' +
+        'Run actual-mcp-server --help for all options.\n');
+    process.exit(1);
+}
 if (argsEarly.includes('--help') || argsEarly.includes('-h') ||
     argsEarly.includes('--version') || argsEarly.includes('-v')) {
     const pkg = await import('../package.json', { with: { type: 'json' } });

package/dist/src/tools/transactions_uncategorized.js

@@ -1,15 +1,13 @@
 /**
  * actual_transactions_uncategorized
  *
- * List transactions that have no category assigned.
+ * Returns a summary of uncategorized transactions by default (totalCount, totalAmount,
+ * per-account breakdown). Pass includeTransactions:true to also receive a paginated
+ * transaction list with limit/offset/hasMore.
  *
  * Concept and implementation adapted from the ZanzyTHEbar fork:
  * https://github.com/ZanzyTHEbar/actual-mcp-server/blob/main/src/tools/transactions_uncategorized.ts
  * Credit: ZanzyTHEbar (https://github.com/ZanzyTHEbar)
- *
- * Adapted for this project's conventions:
- * - No wrapToolCall — uses direct call() pattern
- * - Returns { transactions, count, summary, dateRange } matching the search_by_* shape
  */
 import { z } from 'zod';
 import adapter from '../lib/actual-adapter.js';
@@ -17,12 +15,30 @@ import { CommonSchemas } from '../lib/schemas/common.js';
 const InputSchema = z.object({
     startDate: CommonSchemas.date.optional().describe('Start date in YYYY-MM-DD format (default: first day of current month)'),
     endDate: CommonSchemas.date.optional().describe('End date in YYYY-MM-DD format (default: today)'),
-    accountId: CommonSchemas.accountId.optional().describe('Filter by specific account ID (optional)'),
-    limit: z.number().optional().default(500).describe('Maximum number of transactions to return (default: 500)'),
+    accountId: CommonSchemas.accountId.optional().describe('Filter to a specific account ID (optional)'),
+    includeTransactions: z.boolean().optional().default(false).describe('When true, include paginated transaction rows in the response (default: false)'),
+    limit: z.number().int().min(1).max(1000).optional().default(50).describe('Max transactions per page when includeTransactions is true (default: 50, max: 1000)'),
+    offset: z.number().int().min(0).optional().default(0).describe('Pagination start index when includeTransactions is true (default: 0)'),
 });
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function isUncategorized(txn, excludedAccountIds) {
+    return (txn?.category == null &&
+        txn?.transfer_id == null &&
+        txn?.is_parent !== true &&
+        txn?.starting_balance_flag !== true &&
+        !excludedAccountIds.has(txn?.account));
+}
 const tool = {
     name: 'actual_transactions_uncategorized',
-    description: 'List uncategorized transactions (category is null/unset). Excludes transfers, split-transaction parents, opening balance entries, off-budget accounts, and closed accounts — matching Actual Budget\'s own Uncategorized view. Defaults to the current month unless a date range is provided. Returns { transactions, count, summary: { totalAmount }, dateRange }.',
+    description: [
+        'Get uncategorized transactions summary and optional paginated list.',
+        'Default response: { totalCount, totalAmount, byAccount: [{accountId, accountName, count, totalAmount}], dateRange }.',
+        'Pass includeTransactions:true to also receive transactions[], count, hasMore, offset, limit.',
+        'Use limit (default 50, max 1000) and offset for pagination.',
+        'Excludes: transfers, split-transaction parents, opening balance entries, off-budget accounts, and closed accounts.',
+        'When accountId is provided, all fields are scoped to that account.',
+        'Note: the legacy summary.totalAmount field has been removed — totalAmount is now at the top level.',
+    ].join(' '),
     inputSchema: InputSchema,
     call: async (args, _meta) => {
         const input = InputSchema.parse(args || {});
@@ -31,40 +47,69 @@ const tool = {
         const startDate = input.startDate || firstDayOfMonth.toISOString().split('T')[0];
         const endDate = input.endDate || today.toISOString().split('T')[0];
         const accountId = input.accountId ?? undefined;
-        // Fetch transactions first. When accountId is undefined, rawGetTransactions does
-        // a full table scan (no account filter) — this reliably returns newly written
-        // transactions even across separate WAL sessions in CI Docker. Filtering by
-        // accountId uses a SQLite index that can lag across sessions.
+        // Full table scan when no accountId — reliably returns newly written transactions
+        // across separate WAL sessions in CI Docker. Filtering by accountId uses an index
+        // that can lag across sessions.
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const txnRaw = await adapter.getTransactions(accountId, startDate, endDate);
         const txns = Array.isArray(txnRaw) ? txnRaw : [];
-        // Fetch accounts to build exclusion set: off-budget + closed accounts.
+        // Fetch accounts for exclusion set (off-budget + closed) and name lookup.
+        // Two separate withActualApi sessions is intentional for a read-only tool —
+        // keeps each call isolated. If latency becomes a concern, both could be merged
+        // into a single withActualApi using the raw API directly.
         const accounts = await adapter.getAccounts();
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const accountList = Array.isArray(accounts) ? accounts : [];
         const excludedAccountIds = new Set(
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        (Array.isArray(accounts) ? accounts : [])
+        accountList
             .filter((acc) => acc?.offbudget === true || acc?.closed === true)
             .map((acc) => acc.id));
+        const accountNameMap = new Map(
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const uncategorized = txns.filter(
+        accountList.map((acc) => [acc.id, acc.name]));
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        (txn) => txn?.category == null &&
-            txn?.transfer_id == null &&
-            txn?.is_parent !== true &&
-            txn?.starting_balance_flag !== true &&
-            !excludedAccountIds.has(txn?.account));
-        const limited = uncategorized.slice(0, input.limit ?? 500);
+        const uncategorized = txns.filter((txn) => isUncategorized(txn, excludedAccountIds));
+        const totalCount = uncategorized.length;
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const totalAmount = limited.reduce((sum, txn) => {
-            const amount = typeof txn?.amount === 'number' ? txn.amount : 0;
-            return sum + amount;
+        const totalAmount = uncategorized.reduce((sum, txn) => {
+            return sum + (typeof txn?.amount === 'number' ? txn.amount : 0);
         }, 0);
-        return {
-            transactions: limited,
-            count: limited.length,
-            summary: { totalAmount },
+        // Per-account breakdown — one entry per on-budget open account with ≥1 uncategorized txn
+        const byAccountMap = new Map();
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        for (const txn of uncategorized) {
+            const acctId = txn?.account;
+            if (!acctId)
+                continue;
+            const entry = byAccountMap.get(acctId) ?? { count: 0, totalAmount: 0 };
+            entry.count += 1;
+            entry.totalAmount += typeof txn?.amount === 'number' ? txn.amount : 0;
+            byAccountMap.set(acctId, entry);
+        }
+        const byAccount = Array.from(byAccountMap.entries()).map(([acctId, data]) => ({
+            accountId: acctId,
+            accountName: accountNameMap.get(acctId) ?? acctId,
+            count: data.count,
+            totalAmount: data.totalAmount,
+        }));
+        const result = {
+            totalCount,
+            totalAmount,
+            byAccount,
             dateRange: { startDate, endDate },
         };
+        if (input.includeTransactions) {
+            const limit = input.limit ?? 50;
+            const offset = input.offset ?? 0;
+            const page = uncategorized.slice(offset, offset + limit);
+            result.transactions = page;
+            result.count = page.length;
+            result.hasMore = offset + page.length < totalCount;
+            result.offset = offset;
+            result.limit = limit;
+        }
+        return result;
     },
 };
 export default tool;

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.5.7",
+  "version": "0.6.0",
   "engines": {
     "node": ">=20.0.0",
     "npm": ">=10.0.0"
   },
-  "description": "MCP server with 62 tools for AI-driven financial management with Actual Budget — HTTP and stdio transports, LibreChat, Claude Desktop, Cursor, VS Code, Gemini CLI",
+  "description": "MCP server with 63 tools for AI-driven financial management with Actual Budget — HTTP and stdio transports, LibreChat, Claude Desktop, Cursor, VS Code, Gemini CLI",
+  "homepage": "https://github.com/agigante80/actual-mcp-server#readme",
   "repository": {
     "type": "git",
     "url": "https://github.com/agigante80/actual-mcp-server"