actual-mcp-server 0.5.8 → 0.6.1

package/README.md

@@ -296,7 +296,7 @@ For Claude Desktop (stdio), restart Claude after upgrading.
 | `actual_accounts_reopen` | Reopen closed account |
 | `actual_accounts_get_balance` | Get account balance at a date |
 
-### Transactions (12)
+### Transactions (13)
 
 **Standard (6)**
 
@@ -309,6 +309,12 @@ For Claude Desktop (stdio), restart Claude after upgrading.
 | `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 |
@@ -724,4 +730,4 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.5.8 | **Tool Count:** 63 (verified LibreChat-compatible)
+**Version:** 0.6.1 | **Tool Count:** 63 (verified LibreChat-compatible)

package/dist/package.json

@@ -1,7 +1,7 @@
 {
     "name": "actual-mcp-server",
     "displayName": "Actual MCP Server",
-    "version": "0.5.8",
+    "version": "0.6.1",
     "engines": {
         "node": ">=20.0.0",
         "npm": ">=10.0.0"

package/dist/src/lib/actual-adapter.js

@@ -385,7 +385,8 @@ export async function importTransactions(accountId, txs) {
 }
 export async function createTransfer(params) {
     observability.incrementToolCall('actual.transfers.create').catch(() => { });
-    return queueWriteOperation(async () => {
+    // ── Phase 1: validate + write ─────────────────────────────────────────────
+    const writeResult = await queueWriteOperation(async () => {
         if (params.from_account === params.to_account) {
             return { success: false, error: 'from_account and to_account must be different accounts.' };
         }
@@ -411,16 +412,30 @@ export async function createTransfer(params) {
             payee: transferPayee.id,
             ...(params.notes !== undefined && { notes: params.notes }),
         };
-        const result = await withConcurrency(() => retry(() => rawAddTransactions(params.from_account, [sourceTx], { runTransfers: true }), { retries: 2, backoffMs: 200 }));
-        let from_id = null;
-        if (Array.isArray(result) && result.length > 0 && typeof result[0] === 'string' && result[0] !== 'ok') {
-            from_id = result[0];
-        }
-        else if (result && typeof result === 'object' && 'id' in result) {
-            from_id = result.id;
-        }
-        return { success: true, from_id, to_id: null };
+        await withConcurrency(() => retry(() => rawAddTransactions(params.from_account, [sourceTx], { runTransfers: true }), { retries: 2, backoffMs: 200 }));
+        return { success: true };
     });
+    if (!writeResult.success)
+        return writeResult;
+    // ── Phase 2: read-back in a fresh session (after write has synced) ────────
+    // A new withActualApi session downloads the budget from the server, which
+    // reflects the synced write, guaranteeing transfer_id is fully committed.
+    try {
+        return await withActualApi(async () => {
+            const txns = await withConcurrency(() => retry(() => rawGetTransactions(params.from_account, params.date, params.date), { retries: 2, backoffMs: 200 }));
+            // Find the most recently created transfer matching our amount.
+            // imported_id is not synced via Actual Budget CRDT, so we sort by
+            // sort_order descending and take the newest matching transfer instead.
+            const tx = (txns ?? [])
+                .filter((t) => t.amount === -Math.abs(params.amount) && t.transfer_id != null)
+                .sort((a, b) => (b.sort_order ?? 0) - (a.sort_order ?? 0))[0];
+            return { success: true, from_id: tx?.id ?? null, to_id: tx?.transfer_id ?? null };
+        });
+    }
+    catch {
+        // Transfer was created; IDs just can't be retrieved right now.
+        return { success: true, from_id: null, to_id: null };
+    }
 }
 export async function getTransactions(accountId, startDate, endDate) {
     return withActualApi(async () => {

package/dist/src/tools/transactions_uncategorized.js

@@ -1,70 +1,115 @@
 /**
  * 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';
 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)'),
+    startDate: CommonSchemas.date.optional().describe('Start date in YYYY-MM-DD format (default: all-time)'),
     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.',
+        'Default date range is all-time (2000-01-01 to today); pass startDate/endDate to narrow.',
+        '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 || {});
         const today = new Date();
-        const firstDayOfMonth = new Date(today.getFullYear(), today.getMonth(), 1);
-        const startDate = input.startDate || firstDayOfMonth.toISOString().split('T')[0];
+        const startDate = input.startDate || '2000-01-01';
         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,7 +1,7 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.5.8",
+  "version": "0.6.1",
   "engines": {
     "node": ">=20.0.0",
     "npm": ">=10.0.0"