actual-mcp-server 0.5.0

package/dist/src/lib/ActualConnectionPool.js

@@ -0,0 +1,343 @@
+/**
+ * Connection Pool for Actual Budget API
+ *
+ * Manages separate Actual Budget connections for each MCP session.
+ * Each connection has its own lifecycle (init -> operations -> shutdown).
+ * This ensures proper data persistence according to Actual Budget's API design.
+ *
+ * NOTE: Since @actual-app/api is a singleton module, this implementation
+ * supports sequential session handling (one active session at a time).
+ * For true concurrent multi-session support, the Actual Budget API would
+ * need to support multiple instances or we'd need request queuing.
+ */
+import api from '@actual-app/api';
+import logger from '../logger.js';
+import config from '../config.js';
+import path from 'path';
+import os from 'os';
+import fs from 'fs';
+const DEFAULT_DATA_DIR = path.resolve(os.homedir() || '.', '.actual');
+class ActualConnectionPool {
+    connections = new Map();
+    cleanupInterval = null;
+    IDLE_TIMEOUT; // Configurable via SESSION_IDLE_TIMEOUT_MINUTES env var (default: 5 minutes)
+    CLEANUP_INTERVAL; // Check frequency (default: 2 minutes)
+    MAX_CONCURRENT_SESSIONS; // Configurable via MAX_CONCURRENT_SESSIONS env var (default: 1)
+    sharedConnection = null;
+    initializationPromise = null;
+    constructor() {
+        // Read from environment variable or default to 15
+        // @actual-app/api is a singleton, so concurrent sessions cause conflicts
+        this.MAX_CONCURRENT_SESSIONS = parseInt(process.env.MAX_CONCURRENT_SESSIONS || '15', 10);
+        // Configurable idle timeout (in minutes)
+        const idleTimeoutMinutes = parseInt(process.env.SESSION_IDLE_TIMEOUT_MINUTES || '5', 10);
+        this.IDLE_TIMEOUT = idleTimeoutMinutes * 60 * 1000;
+        // Cleanup runs at half the idle timeout (or 2 minutes minimum)
+        this.CLEANUP_INTERVAL = Math.max(Math.floor(this.IDLE_TIMEOUT / 5), 2 * 60 * 1000);
+        logger.info(`[ConnectionPool] Max concurrent sessions: ${this.MAX_CONCURRENT_SESSIONS}`);
+        logger.info(`[ConnectionPool] Session idle timeout: ${idleTimeoutMinutes} minutes`);
+        logger.info(`[ConnectionPool] Cleanup interval: ${Math.floor(this.CLEANUP_INTERVAL / 1000)}s`);
+        // Initialize asynchronously (force close stale connections, then start cleanup timer)
+        // Store the promise so callers can await it if needed
+        this.initializationPromise = this.initialize();
+    }
+    /**
+     * Async initialization: force close stale connections, then start cleanup timer
+     * This ensures cleanup completes before any connections are accepted
+     */
+    async initialize() {
+        // Force close any stale connections from previous instance
+        await this.forceCloseStaleConnections();
+        // Start periodic cleanup of idle connections
+        this.startCleanupTimer();
+        logger.info('[ConnectionPool] Initialization complete, ready to accept connections');
+    }
+    /**
+     * Wait for connection pool initialization to complete
+     * Should be called before accepting any connections
+     */
+    async waitForInitialization() {
+        if (this.initializationPromise) {
+            await this.initializationPromise;
+        }
+    }
+    /**
+     * Check if connection pool has completed initialization
+     * Returns true if pool is ready to accept connections
+     */
+    isInitialized() {
+        return this.initializationPromise !== null && this.cleanupInterval !== null;
+    }
+    /**
+     * Check if a session has an active connection
+     */
+    hasConnection(sessionId) {
+        const conn = this.connections.get(sessionId);
+        return conn?.initialized ?? false;
+    }
+    /**
+     * Check if we can accept a new session (under the concurrent limit)
+     * Returns true if limit not reached, false otherwise
+     */
+    canAcceptNewSession() {
+        const activeConnections = Array.from(this.connections.values()).filter(c => c.initialized).length;
+        return activeConnections < this.MAX_CONCURRENT_SESSIONS;
+    }
+    /**
+     * Get or create a connection for an MCP session
+     */
+    async getConnection(sessionId) {
+        let conn = this.connections.get(sessionId);
+        if (conn && conn.initialized) {
+            conn.lastActivity = Date.now();
+            logger.debug(`[ConnectionPool] Reusing connection for session: ${sessionId}`);
+            return;
+        }
+        // Check concurrent session limit
+        const activeConnections = Array.from(this.connections.values()).filter(c => c.initialized).length;
+        if (activeConnections >= this.MAX_CONCURRENT_SESSIONS) {
+            const errorMsg = `[ConnectionPool] Max concurrent sessions (${this.MAX_CONCURRENT_SESSIONS}) reached. Active: ${activeConnections}. Please close some connections or wait for idle sessions to timeout.`;
+            logger.warn(errorMsg);
+            throw new Error(errorMsg);
+        }
+        // Create new connection for this session
+        logger.info(`[ConnectionPool] Creating Actual connection for session: ${sessionId} (${activeConnections + 1}/${this.MAX_CONCURRENT_SESSIONS})`);
+        const SERVER_URL = config.ACTUAL_SERVER_URL;
+        const PASSWORD = config.ACTUAL_PASSWORD;
+        const BUDGET_SYNC_ID = config.ACTUAL_BUDGET_SYNC_ID;
+        const BUDGET_PASSWORD = process.env.ACTUAL_BUDGET_PASSWORD;
+        // Use shared data directory so changes persist across sessions
+        // This is critical - all sessions must share the same database to avoid data loss
+        const DATA_DIR = config.MCP_BRIDGE_DATA_DIR || DEFAULT_DATA_DIR;
+        if (!fs.existsSync(DATA_DIR)) {
+            fs.mkdirSync(DATA_DIR, { recursive: true });
+        }
+        try {
+            await api.init({
+                dataDir: DATA_DIR,
+                serverURL: SERVER_URL,
+                password: PASSWORD,
+            });
+            logger.info(`[ConnectionPool] Downloading budget for session: ${sessionId}`);
+            if (BUDGET_PASSWORD) {
+                const apiWithOptions = api;
+                await apiWithOptions.downloadBudget(BUDGET_SYNC_ID, { password: BUDGET_PASSWORD });
+            }
+            else {
+                await api.downloadBudget(BUDGET_SYNC_ID);
+            }
+            conn = {
+                sessionId,
+                initialized: true,
+                lastActivity: Date.now(),
+                dataDir: DATA_DIR
+            };
+            this.connections.set(sessionId, conn);
+            logger.info(`[ConnectionPool] Connection ready for session: ${sessionId}`);
+        }
+        catch (err) {
+            logger.error(`[ConnectionPool] Failed to initialize connection for session ${sessionId}:`, err);
+            // Clean up the failed connection attempt
+            // Try to shutdown the API to leave it in a clean state for the next attempt
+            try {
+                const maybeApi = api;
+                if (typeof maybeApi.shutdown === 'function') {
+                    await maybeApi.shutdown();
+                    logger.debug(`[ConnectionPool] Cleaned up failed connection for session: ${sessionId}`);
+                }
+            }
+            catch (cleanupErr) {
+                logger.debug(`[ConnectionPool] Error during cleanup (ignoring): ${cleanupErr}`);
+            }
+            // Ensure this session is not in the connections map
+            this.connections.delete(sessionId);
+            throw err;
+        }
+    }
+    /**
+     * Get or create the shared/fallback connection (for backward compatibility)
+     */
+    async getSharedConnection() {
+        if (this.sharedConnection?.initialized) {
+            this.sharedConnection.lastActivity = Date.now();
+            return;
+        }
+        logger.info('[ConnectionPool] Creating shared Actual connection');
+        const SERVER_URL = config.ACTUAL_SERVER_URL;
+        const PASSWORD = config.ACTUAL_PASSWORD;
+        const BUDGET_SYNC_ID = config.ACTUAL_BUDGET_SYNC_ID;
+        const BUDGET_PASSWORD = process.env.ACTUAL_BUDGET_PASSWORD;
+        const DATA_DIR = config.MCP_BRIDGE_DATA_DIR || DEFAULT_DATA_DIR;
+        if (!fs.existsSync(DATA_DIR)) {
+            fs.mkdirSync(DATA_DIR, { recursive: true });
+        }
+        try {
+            await api.init({
+                dataDir: DATA_DIR,
+                serverURL: SERVER_URL,
+                password: PASSWORD,
+            });
+            if (BUDGET_PASSWORD) {
+                const apiWithOptions = api;
+                await apiWithOptions.downloadBudget(BUDGET_SYNC_ID, { password: BUDGET_PASSWORD });
+            }
+            else {
+                await api.downloadBudget(BUDGET_SYNC_ID);
+            }
+            this.sharedConnection = {
+                sessionId: 'shared',
+                initialized: true,
+                lastActivity: Date.now(),
+                dataDir: DATA_DIR
+            };
+            logger.info('[ConnectionPool] Shared connection ready');
+        }
+        catch (err) {
+            logger.error('[ConnectionPool] Failed to initialize shared connection:', err);
+            throw err;
+        }
+    }
+    /**
+     * Shutdown connection for a specific session
+     */
+    async shutdownConnection(sessionId) {
+        const conn = this.connections.get(sessionId);
+        if (!conn || !conn.initialized) {
+            return;
+        }
+        logger.info(`[ConnectionPool] Shutting down connection for session: ${sessionId}`);
+        try {
+            const maybeApi = api;
+            if (typeof maybeApi.shutdown === 'function') {
+                await maybeApi.shutdown();
+            }
+            conn.initialized = false;
+            this.connections.delete(sessionId);
+            // NOTE: We do NOT delete the data directory because it's shared across all sessions
+            // Deleting it would cause data loss for other active sessions
+            logger.info(`[ConnectionPool] Connection shutdown complete for session: ${sessionId}`);
+        }
+        catch (err) {
+            logger.error(`[ConnectionPool] Error shutting down connection for session ${sessionId}:`, err);
+        }
+    }
+    /**
+     * Shutdown the shared connection
+     */
+    async shutdownSharedConnection() {
+        if (!this.sharedConnection?.initialized) {
+            return;
+        }
+        logger.info('[ConnectionPool] Shutting down shared connection');
+        try {
+            const maybeApi = api;
+            if (typeof maybeApi.shutdown === 'function') {
+                await maybeApi.shutdown();
+            }
+            this.sharedConnection.initialized = false;
+            this.sharedConnection = null;
+            logger.info('[ConnectionPool] Shared connection shutdown complete');
+        }
+        catch (err) {
+            logger.error('[ConnectionPool] Error shutting down shared connection:', err);
+        }
+    }
+    /**
+     * Force close any stale connections from previous server instance
+     * This ensures clean state on restart
+     */
+    async forceCloseStaleConnections() {
+        try {
+            logger.info('[ConnectionPool] Force closing any stale connections from previous instance');
+            // Try to shutdown the API if it was left initialized
+            const maybeApi = api;
+            if (typeof maybeApi.shutdown === 'function') {
+                await maybeApi.shutdown();
+                logger.info('[ConnectionPool] Successfully closed stale API connection');
+            }
+        }
+        catch (err) {
+            // Ignore errors - connection may not have been initialized
+            logger.debug('[ConnectionPool] No stale connections to close (or already closed)');
+        }
+        // Clear any connection state
+        this.connections.clear();
+        this.sharedConnection = null;
+    }
+    /**
+     * Start periodic cleanup of idle connections
+     */
+    startCleanupTimer() {
+        this.cleanupInterval = setInterval(() => {
+            this.cleanupIdleConnections();
+        }, this.CLEANUP_INTERVAL);
+    }
+    /**
+     * Clean up idle connections that haven't been used recently
+     */
+    async cleanupIdleConnections() {
+        const now = Date.now();
+        const connectionsToRemove = [];
+        for (const [sessionId, conn] of this.connections.entries()) {
+            if (now - conn.lastActivity > this.IDLE_TIMEOUT) {
+                connectionsToRemove.push(sessionId);
+            }
+        }
+        if (connectionsToRemove.length > 0) {
+            logger.info(`[ConnectionPool] Cleaning up ${connectionsToRemove.length} idle connections`);
+            for (const sessionId of connectionsToRemove) {
+                await this.shutdownConnection(sessionId);
+            }
+        }
+    }
+    /**
+     * Shutdown all connections and stop cleanup timer
+     */
+    async shutdownAll() {
+        logger.info('[ConnectionPool] Shutting down all connections');
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+            this.cleanupInterval = null;
+        }
+        // Shutdown all session connections
+        const shutdownPromises = [];
+        for (const sessionId of this.connections.keys()) {
+            shutdownPromises.push(this.shutdownConnection(sessionId));
+        }
+        // Shutdown shared connection
+        if (this.sharedConnection?.initialized) {
+            shutdownPromises.push(this.shutdownSharedConnection());
+        }
+        await Promise.all(shutdownPromises);
+        logger.info('[ConnectionPool] All connections shut down');
+    }
+    /**
+     * Get idle timeout in minutes
+     */
+    getIdleTimeoutMinutes() {
+        return Math.floor(this.IDLE_TIMEOUT / 60000);
+    }
+    /**
+     * Get connection statistics
+     */
+    getStats() {
+        const now = Date.now();
+        const sessions = Array.from(this.connections.entries()).map(([id, conn]) => ({
+            sessionId: id, // Return full session ID so session_close can use it
+            lastActivity: new Date(conn.lastActivity),
+            idleMinutes: Math.floor((now - conn.lastActivity) / 60000)
+        }));
+        return {
+            totalSessions: this.connections.size,
+            activeSessions: Array.from(this.connections.values()).filter(c => c.initialized).length,
+            maxConcurrent: this.MAX_CONCURRENT_SESSIONS,
+            sharedConnection: this.sharedConnection?.initialized || false,
+            sessions
+        };
+    }
+}
+// Export singleton instance
+export const connectionPool = new ActualConnectionPool();
+// NOTE: Process shutdown handlers are managed by the server (httpServer.ts)
+// to ensure proper cleanup order. The connection pool should NOT have its own SIGTERM/SIGINT handlers
+// as they would call process.exit() and prevent the server's cleanup from running.

package/dist/src/lib/ActualMCPConnection.js

@@ -0,0 +1,125 @@
+// lib/ActualMCPConnection.ts
+import { EventEmitter } from 'events';
+import * as actual from '@actual-app/api';
+import actualToolsManager from '../actualToolsManager.js';
+import adapter from './actual-adapter.js';
+import { z } from 'zod';
+/**
+ * MCPConnection implementation for Actual Finance bridge.
+ */
+export class ActualMCPConnection extends EventEmitter {
+    name;
+    capabilities;
+    constructor() {
+        super();
+        this.name = 'actual';
+        this.capabilities = {
+            tools: { listChanged: true },
+            resources: { listChanged: false },
+            prompts: { listChanged: false },
+            models: { listChanged: false },
+            logging: { listChanged: false },
+        };
+        // Re-emit adapter notifications as connection-level 'progress' events
+        try {
+            adapter.notifications.on('progress', (token, payload) => {
+                this.emit('progress', { token, payload });
+            });
+        }
+        catch (e) {
+            // ignore if adapter doesn't expose notifications yet
+        }
+    }
+    /** Called by the MCP client to fetch current capabilities */
+    async fetchCapabilities() {
+        // If actualToolsManager is not ready, return demo tools
+        let tools;
+        try {
+            const toolNames = actualToolsManager.getToolNames();
+            tools = toolNames.map((name) => {
+                const tool = actualToolsManager.getTool(name);
+                if (!tool) {
+                    throw new Error(`Tool not found: ${name}`);
+                }
+                // Add examples if present on the tool
+                return {
+                    name: tool.name,
+                    title: tool.name,
+                    description: tool.description,
+                    inputSchema: tool.inputSchema ? z.toJSONSchema(tool.inputSchema) : { type: 'object' },
+                };
+            });
+        }
+        catch (e) {
+            // fallback to demo tools
+            tools = [
+                {
+                    name: 'search.docs',
+                    title: 'Search Documents',
+                    description: 'Search a small demo document store',
+                    inputSchema: {
+                        type: 'object',
+                        properties: { query: { type: 'string' } },
+                        required: ['query'],
+                    },
+                    examples: [{ query: 'budget' }],
+                },
+                {
+                    name: 'math.add',
+                    title: 'Add Numbers',
+                    description: 'Add two numbers',
+                    inputSchema: {
+                        type: 'object',
+                        properties: { a: { type: 'number' }, b: { type: 'number' } },
+                        required: ['a', 'b'],
+                    },
+                    examples: [{ a: 2, b: 3 }],
+                },
+            ];
+        }
+        return {
+            tools: {
+                listChanged: true,
+                list: tools,
+            },
+            resources: false,
+            prompts: false,
+            models: false,
+            logging: false,
+            serverInstructions: 'This server exposes Actual Finance tools via MCP. You must provide ACTUAL_SERVER_URL, ACTUAL_PASSWORD, and ACTUAL_BUDGET_SYNC_ID as environment variables.'
+        };
+    }
+    /** Executes a tool requested by the client */
+    async executeTool(toolName, params) {
+        // If actualToolsManager is not ready, support demo tools
+        if (actualToolsManager && typeof actualToolsManager.callTool === 'function') {
+            // Call the tool - let errors propagate to client
+            return await actualToolsManager.callTool(toolName, params);
+        }
+        switch (toolName) {
+            case 'search.docs': {
+                // Example: bridge to Actual API (demo)
+                if (params && typeof params === 'object' && 'query' in params) {
+                    const query = params['query'];
+                    if (typeof query === 'string') {
+                        return { result: await actual.searchDocuments(query) };
+                    }
+                }
+                throw new Error('Invalid params for search.docs');
+            }
+            case 'math.add': {
+                if (params && typeof params === 'object' && 'a' in params && 'b' in params) {
+                    const p = params;
+                    return { result: p.a + p.b };
+                }
+                throw new Error('Invalid params for math.add');
+            }
+            default:
+                throw new Error(`Unknown tool: ${toolName}`);
+        }
+    }
+    /** Optional shutdown logic */
+    close() {
+        this.removeAllListeners();
+    }
+}