actual-mcp-server 0.5.0

package/dist/src/tools/transactions_update.js

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+const InputSchema = z.object({
+    id: z.string().optional().describe('Transaction ID to update (optional for smoke tests, required for actual usage)'),
+    fields: z.object({
+        account: z.string().nullable().optional().describe('Account ID'),
+        date: z.string().nullable().optional().describe('Transaction date (YYYY-MM-DD)'),
+        amount: z.number().nullable().optional().describe('Amount in cents (e.g., 1000 = $10.00)'),
+        payee: z.string().nullable().optional().describe('Payee ID or name'),
+        payee_name: z.string().nullable().optional().describe('Payee name (alternative to payee ID)'),
+        imported_payee: z.string().nullable().optional().describe('Original imported payee name'),
+        category: z.string().nullable().optional().describe('Category ID'),
+        notes: z.string().nullable().optional().describe('Transaction notes'),
+        imported_id: z.string().nullable().optional().describe('Original imported transaction ID'),
+        transfer_id: z.string().nullable().optional().describe('Transfer transaction ID if this is a transfer'),
+        cleared: z.boolean().nullable().optional().describe('Whether transaction is cleared'),
+        reconciled: z.boolean().nullable().optional().describe('Whether transaction is reconciled'),
+    }).describe('Fields to update'),
+});
+const tool = {
+    name: 'actual_transactions_update',
+    description: 'Update an existing transaction in Actual Budget. Provide the transaction ID and the fields you want to update.',
+    inputSchema: InputSchema,
+    call: async (args, _meta) => {
+        const input = InputSchema.parse(args || {});
+        // For smoke tests, return early if no id provided
+        if (!input.id) {
+            return { success: true };
+        }
+        await adapter.updateTransaction(input.id, input.fields);
+        return { success: true };
+    },
+};
+export default tool;

package/dist/src/tools/transactions_update_batch.js

@@ -0,0 +1,60 @@
+/**
+ * actual_transactions_update_batch
+ *
+ * Batch-update multiple transactions in one call.
+ *
+ * Concept and implementation adapted from the ZanzyTHEbar fork:
+ * https://github.com/ZanzyTHEbar/actual-mcp-server/blob/main/src/tools/transactions_update_batch.ts
+ * Credit: ZanzyTHEbar (https://github.com/ZanzyTHEbar)
+ *
+ * Adapted for this project's conventions:
+ * - No wrapToolCall — uses direct call() pattern
+ * - Returns a plain BatchResult object (no { result } wrapper)
+ */
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+const FieldsSchema = z.object({
+    account: z.string().nullable().optional().describe('Account ID'),
+    date: z.string().nullable().optional().describe('Transaction date (YYYY-MM-DD)'),
+    amount: z.number().nullable().optional().describe('Amount in cents (e.g., -1000 = -$10.00)'),
+    payee: z.string().nullable().optional().describe('Payee ID'),
+    payee_name: z.string().nullable().optional().describe('Payee name (alternative to payee ID)'),
+    imported_payee: z.string().nullable().optional().describe('Original imported payee name'),
+    category: z.string().nullable().optional().describe('Category ID'),
+    notes: z.string().nullable().optional().describe('Transaction notes'),
+    cleared: z.boolean().nullable().optional().describe('Whether transaction is cleared'),
+});
+const UpdateItemSchema = z.object({
+    id: z.string().describe('Transaction ID to update'),
+    fields: FieldsSchema.describe('Fields to update for this transaction'),
+});
+const InputSchema = z.object({
+    updates: z.array(UpdateItemSchema)
+        .min(1)
+        .max(100)
+        .describe('Array of {id, fields} objects. Maximum 100 per batch.'),
+});
+const tool = {
+    name: 'actual_transactions_update_batch',
+    description: `Update multiple transactions in a single call. Accepts up to 100 {id, fields} pairs. Each update is applied independently — partial failures are reported per-item so you know exactly which succeeded and which failed.
+
+Returns: { succeeded: [{id}], failed: [{id, error}], total, successCount, failureCount }
+
+Example: { updates: [{ id: "txn-uuid-1", fields: { category: "cat-uuid" } }, { id: "txn-uuid-2", fields: { notes: "Reimbursement" } }] }`,
+    inputSchema: InputSchema,
+    call: async (args, _meta) => {
+        const input = InputSchema.parse(args || {});
+        // Single adapter call — all updates share one init/sync/shutdown cycle (fixes issue #79).
+        // Calling adapter.updateTransaction() in a loop would trigger N separate budget sessions.
+        const { succeeded, failed } = await adapter.updateTransactionBatch(input.updates);
+        const result = {
+            succeeded,
+            failed,
+            total: input.updates.length,
+            successCount: succeeded.length,
+            failureCount: failed.length,
+        };
+        return result;
+    },
+};
+export default tool;

package/dist/src/utils.js

@@ -0,0 +1,63 @@
+import os from 'os';
+export function getLocalIp() {
+    const interfaces = os.networkInterfaces();
+    for (const name of Object.keys(interfaces)) {
+        for (const iface of interfaces[name]) {
+            if (iface.family === 'IPv4' && !iface.internal) {
+                return iface.address;
+            }
+        }
+    }
+    return '127.0.0.1';
+}
+// new: transport logging helpers (enabled when --debug or DEBUG/MCP_BRIDGE_DEBUG_TRANSPORT set)
+export function shouldDebugTransport() {
+    const argvDebug = process.argv.slice(2).includes('--debug');
+    const envDebug = Boolean(process.env.DEBUG) || process.env.MCP_BRIDGE_DEBUG_TRANSPORT === 'true' || process.env.LOG_LEVEL === 'debug';
+    return argvDebug || envDebug;
+}
+/**
+ * Log transport-level request/response objects when debug is enabled.
+ * - prefix: short label like "HTTP REQ" / "HTTP RES"
+ * - obj: any serializable data (headers, body, meta)
+ *
+ * This uses console.debug (falls through to console if no structured logger available).
+ */
+export function logTransport(prefix, obj) {
+    if (!shouldDebugTransport())
+        return;
+    const ts = new Date().toISOString();
+    let payload;
+    try {
+        payload = JSON.stringify(obj, replacer, 2);
+    }
+    catch {
+        try {
+            payload = String(obj);
+        }
+        catch {
+            payload = '[unserializable payload]';
+        }
+    }
+    // prefer console.debug so existing debug tooling (DEBUG env) can capture it
+    // format similar to other logs: "<iso> debug: [TRANSPORT] prefix: <json>"
+    // eslint-disable-next-line no-console
+    console.debug(`${ts} debug: [TRANSPORT] ${prefix}: ${payload}`);
+}
+// Helper replacer to avoid throwing on circular refs and to truncate very large buffers
+function replacer(_key, value) {
+    // Limit Buffer/Uint8Array printing
+    if (value instanceof Uint8Array || (typeof Buffer !== 'undefined' && value instanceof Buffer)) {
+        const buf = value;
+        const len = buf.length ?? 0;
+        const preview = Array.prototype.slice.call(buf, 0, 64);
+        return { _type: 'Buffer', length: len, preview };
+    }
+    if (value instanceof Uint8Array) {
+        const buf = value;
+        const len = buf.length;
+        const preview = Array.prototype.slice.call(buf, 0, 64);
+        return { _type: 'Uint8Array', length: len, preview };
+    }
+    return value;
+}

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "actual-mcp-server",
+  "displayName": "Actual MCP Server",
+  "version": "0.5.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",
+  "main": "dist/src/index.js",
+  "bin": {
+    "actual-mcp-server": "./bin/actual-mcp-server.js"
+  },
+  "files": [
+    "bin/",
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "dev": "npm run build && node scripts/register-tsconfig-paths.js -- --debug",
+    "start": "node dist/src/index.js",
+    "verify-tools": "npm run build && node scripts/verify-tools.js",
+    "check:coverage": "node scripts/list-actual-api-methods.mjs",
+    "direct-sync": "node scripts/direct-sync/bank-sync-direct.mjs",
+    "test:unit-js": "node tests/unit/transactions_create.test.js && node tests/unit/generated_tools.smoke.test.js && node tests/unit/schema_validation.test.js && node tests/unit/auth-acl.test.js && node tests/unit/bug76.test.js && node tests/unit/budgets_setAmount.test.js && node tests/unit/transactions_uncategorized.test.js",
+    "test:adapter": "npm run build && node dist/src/tests_adapter_runner.js",
+    "test:e2e": "npx playwright test",
+    "test:e2e:docker": "./tests/e2e/run-docker-e2e.sh",
+    "test:e2e:docker:smoke": "./tests/e2e/run-docker-e2e.sh smoke",
+    "test:e2e:docker:full": "./tests/e2e/run-docker-e2e.sh full",
+    "test:all": "npm run test:adapter && npm run test:unit-js && npm run test:e2e:docker:smoke",
+    "test:mcp-client": "npm run build && node scripts/register-tsconfig-paths.js -- --http --test-mcp-client",
+    "test:integration": "MCP_TEST_LEVEL=sanity node tests/manual/index.js",
+    "test:integration:sanity": "MCP_TEST_LEVEL=sanity node tests/manual/index.js",
+    "test:integration:smoke": "MCP_TEST_LEVEL=smoke node tests/manual/index.js",
+    "test:integration:normal": "MCP_TEST_LEVEL=normal node tests/manual/index.js",
+    "test:integration:extended": "MCP_TEST_LEVEL=extended node tests/manual/index.js",
+    "test:integration:full": "MCP_TEST_LEVEL=full node tests/manual/index.js",
+    "test:integration:cleanup": "MCP_TEST_LEVEL=cleanup node tests/manual/index.js",
+    "deploy:full": "bash scripts/deploy-and-test.sh full",
+    "deploy:smoke": "bash scripts/deploy-and-test.sh smoke",
+    "docs:sync": "node scripts/version-bump.js sync",
+    "version:current": "cat VERSION",
+    "version:dev": "node scripts/version-dev.js",
+    "version:bump": "node scripts/version-bump.js",
+    "version:check": "node scripts/version-check.js",
+    "release:major": "npm run version:bump -- major",
+    "release:minor": "npm run version:bump -- minor",
+    "release:patch": "npm run version:bump -- patch"
+  },
+  "dependencies": {
+    "@actual-app/api": "^26.4.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "dotenv": "^17.4.1",
+    "express": "^5.2.1",
+    "mcp-auth": "^0.2.0",
+    "winston": "^3.18.3",
+    "winston-daily-rotate-file": "^5.0.0",
+    "zod": "^4.0.0"
+  },
+  "overrides": {
+    "ajv": "8.18.0",
+    "qs": "6.14.2"
+  },
+  "comments": {
+    "security-overrides": "ajv>=8.18.0 (CVE alert #21), qs>=6.14.2 (alert #17)"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.59.1",
+    "@types/express": "^5.0.3",
+    "@types/node": "^25.6.0",
+    "tsconfig-paths": "^4.2.0",
+    "typescript": "^6.0.2"
+  },
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "actual-budget",
+    "actual-finance",
+    "librechat",
+    "claude-desktop",
+    "cursor",
+    "budget",
+    "finance",
+    "ai"
+  ],
+  "author": "agigante80"
+}