actual-mcp-server 0.5.6 → 0.5.8

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.
@@ -678,4 +724,4 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.5.6 | **Tool Count:** 63 (verified LibreChat-compatible)
+**Version:** 0.5.8 | **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.6",
+    "version": "0.5.8",
     "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

@@ -22,7 +22,7 @@ const InputSchema = z.object({
 });
 const tool = {
     name: 'actual_transactions_uncategorized',
-    description: 'List uncategorized transactions (category is null/unset). Useful for cleanup workflows and rule-suggestion prompts. Defaults to the current month unless a date range is provided. Returns { transactions, count, summary: { totalAmount }, dateRange }.',
+    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 }.',
     inputSchema: InputSchema,
     call: async (args, _meta) => {
         const input = InputSchema.parse(args || {});
@@ -38,17 +38,21 @@ const tool = {
         // 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 off-budget exclusion set.
+        // Fetch accounts to build exclusion set: off-budget + closed accounts.
         const accounts = await adapter.getAccounts();
-        const offBudgetIds = new Set(
+        const excludedAccountIds = new Set(
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         (Array.isArray(accounts) ? accounts : [])
-            .filter((acc) => acc?.offbudget === true)
+            .filter((acc) => acc?.offbudget === true || acc?.closed === true)
             .map((acc) => acc.id));
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const uncategorized = txns.filter(
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        (txn) => txn?.category == null && !offBudgetIds.has(txn?.account));
+        (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);
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const totalAmount = limited.reduce((sum, txn) => {

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.5.6",
+  "version": "0.5.8",
   "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"