actual-mcp-server 0.5.3 → 0.5.5

package/README.md

@@ -1,5 +1,7 @@
 # Actual MCP Server
 
+[![npm version](https://img.shields.io/npm/v/actual-mcp-server)](https://www.npmjs.com/package/actual-mcp-server)
+[![npm downloads](https://img.shields.io/npm/dm/actual-mcp-server)](https://www.npmjs.com/package/actual-mcp-server)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue)](https://www.typescriptlang.org/)
@@ -668,4 +670,4 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.5.2 | **Tool Count:** 62 (verified LibreChat-compatible)
+**Version:** 0.5.5 | **Tool Count:** 62 (verified LibreChat-compatible)

package/dist/package.json

@@ -1,7 +1,7 @@
 {
     "name": "actual-mcp-server",
     "displayName": "Actual MCP Server",
-    "version": "0.5.3",
+    "version": "0.5.5",
     "engines": {
         "node": ">=20.0.0",
         "npm": ">=10.0.0"
@@ -58,13 +58,18 @@
     "dependencies": {
         "@actual-app/api": "^26.4.0",
         "@modelcontextprotocol/sdk": "^1.29.0",
+        "debug": "^4.4.3",
         "dotenv": "^17.4.1",
         "express": "^5.2.1",
+        "jose": "^6.1.3",
         "mcp-auth": "^0.2.0",
         "winston": "^3.18.3",
         "winston-daily-rotate-file": "^5.0.0",
         "zod": "^4.0.0"
     },
+    "optionalDependencies": {
+        "prom-client": "*"
+    },
     "overrides": {
         "ajv": "8.18.0",
         "qs": "6.14.2"
@@ -76,6 +81,7 @@
         "@playwright/test": "^1.59.1",
         "@types/express": "^5.0.3",
         "@types/node": "^25.6.0",
+        "node-fetch": "^3.3.2",
         "tsconfig-paths": "^4.2.0",
         "typescript": "^6.0.2"
     },

package/dist/src/config.js

@@ -32,7 +32,11 @@ export const configSchema = z.object({
 function getConfig() {
     const result = configSchema.safeParse(process.env);
     if (!result.success) {
-        console.error('Invalid or missing environment variables:', result.error.issues);
+        const missing = result.error.issues.map(i => `  • ${i.path.join('.')}`).join('\n');
+        console.error(`\n❌ Missing or invalid environment variables:\n${missing}\n\n` +
+            `Set them in a .env file in the current directory, or export them before running.\n` +
+            `Required: ACTUAL_SERVER_URL, ACTUAL_PASSWORD, ACTUAL_BUDGET_SYNC_ID\n` +
+            `See: https://github.com/agigante80/actual-mcp-server\n`);
         process.exit(1);
     }
     return result.data;

package/dist/src/index.js

@@ -67,32 +67,50 @@ process.on('uncaughtException', (error) => {
 });
 // Minimal early help handling before any side-effectful modules (prevents dotenv from running on --help)
 const argsEarly = process.argv.slice(2);
+// dotenv v17 outputs diagnostic text to stdout by default (console.log).
+// Suppress it unconditionally — in stdio mode stdout is the JSON-RPC channel
+// (non-JSON corrupts the framing), and in other modes the diagnostic is noise.
+process.env.DOTENV_CONFIG_QUIET = 'true';
 // Set MCP_STDIO_MODE before the async IIFE so it is in place when src/logger.ts is first
 // imported. The Winston Console transport reads this env var at construction time to decide
 // whether to route all output to stderr (required in stdio mode — stdout writes corrupt JSON-RPC).
 if (argsEarly.includes('--stdio')) {
     process.env.MCP_STDIO_MODE = 'true';
-    // dotenv v17 outputs diagnostic text to stdout by default (console.log).
-    // In stdio mode stdout is the JSON-RPC channel — any non-JSON output corrupts
-    // the framing and causes MCP clients to close the connection immediately.
-    process.env.DOTENV_CONFIG_QUIET = 'true';
 }
 // Only load dotenv if we're not just showing help
 // dotenv will be loaded inside the async IIFE below via dynamic import
 // to avoid using require() in ESM and to keep the early --help fast exit.
-const usageEarly = `
-Usage: npm run dev -- [--http | --stdio | --test-actual-connection | --test-actual-tools] [--debug] [--help]
+const KNOWN_FLAGS = new Set([
+    '--http', '--stdio', '--test-actual-connection', '--test-mcp-client',
+    '--debug', '--help', '-h', '--version', '-v',
+]);
+const unknownFlags = argsEarly.filter(a => a.startsWith('-') && !KNOWN_FLAGS.has(a));
+if (unknownFlags.length > 0) {
+    console.error(`Unknown option: ${unknownFlags.join(', ')}\nRun \`actual-mcp-server --help\` for usage.`);
+    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' } });
+    const version = pkg.default.version;
+    if (argsEarly.includes('--version') || argsEarly.includes('-v')) {
+        console.log(version);
+    }
+    else {
+        console.log(`actual-mcp-server v${version}
+
+Usage: actual-mcp-server [--http | --stdio | --test-actual-connection] [--debug] [--help]
 
 Options:
   --http                   Start HTTP MCP server
   --stdio                  Start stdio MCP server (for Claude Desktop / local clients)
   --test-actual-connection Test connecting to Actual and exit
-  --test-actual-tools      Test connecting and run all tools, then exit
   --debug                  Enable debug logging
-  --help                   Show this help message
-`;
-if (argsEarly.includes('--help')) {
-    console.log(usageEarly);
+  --version, -v            Print version and exit
+  --help, -h               Show this help message
+
+Docs & source: https://github.com/agigante80/actual-mcp-server`);
+    }
     process.exit(0);
 }
 (async () => {
@@ -112,9 +130,8 @@ if (argsEarly.includes('--help')) {
         console.log('Debug mode enabled: DEBUG=* LOG_LEVEL=debug');
     }
     // dynamic imports to avoid running side effects on module import
-    const [{ connectToActual }, { testAllTools }, { ActualMCPConnection }] = await Promise.all([
+    const [{ connectToActual }, { ActualMCPConnection }] = await Promise.all([
         import('./actualConnection.js'),
-        import('./tests/actualToolsTests.js'),
         import('./lib/ActualMCPConnection.js'),
     ]);
     const [{ startHttpServer }, { startStdioServer }, loggerModule, osModule, utilsModule, actualToolsManagerModule,] = await Promise.all([
@@ -157,12 +174,10 @@ if (argsEarly.includes('--help')) {
     const useHttp = args.includes('--http');
     const useStdio = args.includes('--stdio');
     const useTestActualConnection = args.includes('--test-actual-connection');
-    const useTestActualTools = args.includes('--test-actual-tools');
     const useTestMcpClient = args.includes('--test-mcp-client');
     const SERVER_DESCRIPTION = 'Bridge MCP server exposing Actual finance API to LibreChat.';
     const SERVER_INSTRUCTIONS = 'Welcome to the Actual MCP server. The tools listed here are only the ones currently confirmed and tested, ' +
         'but the server can proxy any API call supported by Actual. As we expand coverage, more tools will be officially exposed.';
-    const usage = usageEarly;
     async function main() {
         // Mutual exclusion — stdio and http are incompatible transports
         if (useHttp && useStdio) {
@@ -179,23 +194,6 @@ if (argsEarly.includes('--help')) {
             logger.info('⚙️  --test-actual-connection specified, connection to Actual Finance successful.');
             process.exit(0);
         }
-        if (useTestActualTools) {
-            logger.info('⚙️  --test-actual-tools specified, connecting and testing all tools...');
-            try {
-                await testAllTools();
-                logger.info('✅ All tool tests completed.');
-            }
-            catch (err) {
-                if (err instanceof Error) {
-                    logger.error('❌ Tool tests failed: %s', err.message);
-                }
-                else {
-                    logger.error('❌ Tool tests failed: %o', err);
-                }
-                process.exit(1);
-            }
-            process.exit(0);
-        }
         // Initialize tools before usage
         await actualToolsManager.initialize();
         // Now get implemented tools after initialization

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "engines": {
     "node": ">=20.0.0",
     "npm": ">=10.0.0"
@@ -58,13 +58,18 @@
   "dependencies": {
     "@actual-app/api": "^26.4.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "debug": "^4.4.3",
     "dotenv": "^17.4.1",
     "express": "^5.2.1",
+    "jose": "^6.1.3",
     "mcp-auth": "^0.2.0",
     "winston": "^3.18.3",
     "winston-daily-rotate-file": "^5.0.0",
     "zod": "^4.0.0"
   },
+  "optionalDependencies": {
+    "prom-client": "*"
+  },
   "overrides": {
     "ajv": "8.18.0",
     "qs": "6.14.2"
@@ -76,6 +81,7 @@
     "@playwright/test": "^1.59.1",
     "@types/express": "^5.0.3",
     "@types/node": "^25.6.0",
+    "node-fetch": "^3.3.2",
     "tsconfig-paths": "^4.2.0",
     "typescript": "^6.0.2"
   },

package/dist/src/tests/actualToolsTests.js

@@ -1,70 +0,0 @@
-// src/tests/actualToolsTests.ts
-import logger from '../logger.js';
-import actualToolsManager from '../actualToolsManager.js';
-// Test data mapping for each tool
-const getTestArgs = (toolName) => {
-    switch (toolName) {
-        case 'actual.accounts.create':
-            return { name: 'Test Account', balance: 1000 };
-        case 'actual.accounts.update':
-            return { id: 'test-account-id', fields: { name: 'Updated Test Account' } };
-        case 'actual.accounts.get.balance':
-            return { id: 'test-account-id' };
-        case 'actual.transactions.create':
-            return { accountId: 'test-account-id', amount: 100, payee: 'Test Payee', date: '2025-11-08' };
-        case 'actual.transactions.get':
-            return { accountId: 'test-account-id', startDate: '2025-11-01', endDate: '2025-11-08' };
-        case 'actual.transactions.import':
-            return { accountId: 'test-account-id', txs: [{ amount: 50, payee: 'Import Test', date: '2025-11-08' }] };
-        case 'actual.categories.create':
-            // Try different field names that might be expected
-            return { name: 'Test Category', group_id: 'fc3825fd-b982-4b72-b768-5b30844cf832', groupId: 'fc3825fd-b982-4b72-b768-5b30844cf832' };
-        case 'actual.payees.create':
-            return { name: 'Test Payee' };
-        case 'actual.budgets.setAmount':
-            // Use an existing category ID (Food category from the budget data)
-            return { month: '2025-11', categoryId: '541836f1-e756-4473-a5d0-6c1d3f06c7fa', amount: 500 };
-        case 'actual.budgets.getMonth':
-            return { month: '2025-11' };
-        // These tools don't require parameters
-        case 'actual.accounts.list':
-        case 'actual.categories.get':
-        case 'actual.payees.get':
-        case 'actual.budgets.getMonths':
-        default:
-            return {};
-    }
-};
-export async function testAllTools() {
-    await actualToolsManager.initialize();
-    const toolNames = actualToolsManager.getToolNames();
-    const results = [];
-    for (const name of toolNames) {
-        try {
-            logger.info(`⚙️  Testing tool: ${name}`);
-            const testArgs = getTestArgs(name);
-            const result = await actualToolsManager.callTool(name, testArgs);
-            logger.info(`✅ Tool ${name} output: ${JSON.stringify(result, null, 2)}`);
-            results.push({ name, success: true });
-        }
-        catch (err) {
-            const message = err && typeof err?.message === 'string' ? err.message : String(err);
-            logger.error(`❌ Tool ${name} test failed: ${message}`);
-            results.push({ name, success: false, error: message });
-        }
-    }
-    // Summary
-    const successful = results.filter(r => r.success).length;
-    const failed = results.filter(r => !r.success).length;
-    logger.info(`\n📊 Test Summary: ${successful} passed, ${failed} failed`);
-    if (failed > 0) {
-        logger.error(`❌ Failed tools:`);
-        results.filter(r => !r.success).forEach(r => {
-            logger.error(`  - ${r.name}: ${r.error}`);
-        });
-        throw new Error(`${failed} tool tests failed`);
-    }
-    else {
-        logger.info(`🎉 All ${successful} tools passed!`);
-    }
-}