actual-mcp-server 0.5.0

package/dist/src/observability.js

@@ -0,0 +1,58 @@
+// Lightweight observability wrapper. Uses prom-client when installed; otherwise no-ops.
+// Lightweight observability wrapper. Uses prom-client when installed; otherwise no-ops.
+let registry = null;
+let counter = null;
+async function init() {
+    if (registry)
+        return { registry, counter };
+    try {
+        // Dynamically import prom-client. When present we adapt to its runtime API.
+        const prom = await import('prom-client');
+        // prom.register implements metrics()
+        registry = prom.register;
+        // Create a Counter if available (some versions export Counter class)
+        if (typeof prom.Counter === 'function') {
+            try {
+                // prom.Counter may be a class; construct via known options shape
+                const CounterClass = prom.Counter;
+                counter = new CounterClass({ name: 'actual_tool_calls_total', help: 'Total tool calls', labelNames: ['tool'] });
+            }
+            catch {
+                counter = { inc: (_labels, _v) => { } };
+            }
+        }
+        else {
+            // fallback: try to use prom.register.getSingleMetric or similar; if not present, noop
+            counter = {
+                inc: (_labels, _v) => { },
+            };
+        }
+        return { registry, counter };
+    }
+    catch (e) {
+        // prom-client not installed; provide a noop implementation
+        registry = null;
+        counter = {
+            inc: (_labels, _v) => { },
+        };
+        return { registry, counter };
+    }
+}
+export async function incrementToolCall(toolName) {
+    const { counter } = await init();
+    try {
+        counter?.inc({ tool: toolName }, 1);
+    }
+    catch (e) { /* noop */ }
+}
+export async function getMetricsText() {
+    const { registry } = await init();
+    if (!registry)
+        return null;
+    // registry.metrics may be sync or async depending on prom-client version
+    const m = registry.metrics();
+    if (typeof m === 'string')
+        return m;
+    return await m;
+}
+export default { incrementToolCall, getMetricsText };

package/dist/src/prompts/showLargeTransactions.js

@@ -0,0 +1,6 @@
+// Example prompt: show recent large transactions
+export const showLargeTransactions = {
+    name: 'showLargeTransactions',
+    description: 'Show recent transactions over a specified amount',
+    template: 'Show me all transactions over $100 in the last month.'
+};

package/dist/src/resources/accountsSummary.js

@@ -0,0 +1,13 @@
+// Example resource: summary of all accounts
+import api from '@actual-app/api';
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const { getAccounts } = api;
+export async function accountsSummary() {
+    const accounts = await getAccounts();
+    return accounts.map((a) => {
+        // access via optional chaining in case generated types are partial at runtime
+        const name = a?.name;
+        const balance = a?.balance;
+        return { id: a.id, name: typeof name === 'string' ? name : undefined, balance: typeof balance === 'number' ? balance : undefined };
+    });
+}

package/dist/src/server/httpServer.js

@@ -0,0 +1,540 @@
+// src/server/httpServer.ts
+import { AsyncLocalStorage } from 'async_hooks';
+import express from 'express';
+import { randomUUID } from 'crypto';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { ListToolsRequestSchema, CallToolRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import logger from '../logger.js';
+import { getLocalIp } from '../utils.js';
+import actualToolsManager from '../actualToolsManager.js';
+import { getConnectionState, connectToActualForSession, shutdownActualForSession, shutdownActual, canAcceptNewSession } from '../actualConnection.js';
+import observability from '../observability.js';
+import config from '../config.js';
+import { createRemoteJWKSet, jwtVerify } from 'jose';
+import { createMcpAuth } from '../auth/setup.js';
+import { budgetAclMiddleware } from '../auth/budget-acl.js';
+import * as https from 'node:https';
+import * as fs from 'node:fs';
+// AsyncLocalStorage for request context (sessionId accessible to tools)
+export const requestContext = new AsyncLocalStorage();
+export async function startHttpServer(mcp, port, httpPath, capabilities, // was passed by index.ts
+implementedTools, // was passed by index.ts
+serverDescription, // was passed by index.ts
+serverInstructions, // was passed by index.ts
+toolSchemas, // was passed by index.ts
+version, // server version from package.json
+bindHost = 'localhost', advertisedUrl) {
+    const app = express();
+    app.use(express.json());
+    const scheme = config.MCP_ENABLE_HTTPS ? 'https' : 'http';
+    // --- OIDC / mcp-auth (CF-5) ---
+    // When AUTH_PROVIDER=oidc, validate JWTs and enforce budget ACL.
+    // When AUTH_PROVIDER=none (default), the existing static Bearer token check applies.
+    let mcpAuth = null;
+    if (config.AUTH_PROVIDER === 'oidc') {
+        mcpAuth = createMcpAuth(); // throws if OIDC_ISSUER / OIDC_RESOURCE missing
+        if (mcpAuth) {
+            // Serve RFC 8707 Protected Resource Metadata (/.well-known/oauth-protected-resource/...)
+            app.use(mcpAuth.protectedResourceMetadataRouter());
+            // Protect ALL httpPath routes with JWT validation + budget ACL
+            const requiredScopes = config.OIDC_SCOPES
+                ? config.OIDC_SCOPES.split(',').map((s) => s.trim()).filter(Boolean)
+                : [];
+            // Custom jose-based JWT verifier — bypasses mcp-auth's strict PKCE/discovery
+            // validation that fails when the IdP (e.g. Casdoor v2.13) doesn't advertise
+            // code_challenge_methods_supported in its discovery document.
+            // JWKS is fetched lazily on the first request and cached by jose internally.
+            const jwks = createRemoteJWKSet(new URL(`${config.OIDC_ISSUER}/.well-known/jwks`));
+            const customJwtVerify = async (token) => {
+                const { payload } = await jwtVerify(token, jwks, {
+                    issuer: config.OIDC_ISSUER,
+                });
+                const rawAud = payload.aud;
+                const audience = Array.isArray(rawAud) ? rawAud : (rawAud ? [rawAud] : []);
+                const rawScope = typeof payload.scope === 'string' ? payload.scope : '';
+                return {
+                    token,
+                    issuer: payload.iss ?? config.OIDC_ISSUER,
+                    clientId: audience[0] ?? '',
+                    audience,
+                    scopes: rawScope ? rawScope.split(' ') : [],
+                    expiresAt: payload.exp,
+                    claims: payload,
+                };
+            };
+            app.use(httpPath, mcpAuth.bearerAuth(customJwtVerify, {
+                resource: config.OIDC_RESOURCE,
+                // audience intentionally omitted: Casdoor sets aud=clientId (not the resource URL)
+                requiredScopes,
+                showErrorDetails: process.env.NODE_ENV !== 'production',
+            }), budgetAclMiddleware);
+            logger.info(`[OIDC] JWT authentication enabled — issuer: ${config.OIDC_ISSUER}`);
+        }
+    }
+    const transports = new Map();
+    const sessionLastActivity = new Map();
+    const sessionInitPromises = new Map(); // Track session init completion
+    // Use same timeout as ConnectionPool (SESSION_IDLE_TIMEOUT_MINUTES env var, default: 2 minutes)
+    const idleTimeoutMinutes = parseInt(process.env.SESSION_IDLE_TIMEOUT_MINUTES || '2', 10);
+    const SESSION_TIMEOUT_MS = idleTimeoutMinutes * 60 * 1000;
+    const SESSION_CLEANUP_INTERVAL_MS = 30 * 1000; // Check every 30 seconds
+    // safe fallback if index didn't provide implementedTools
+    const toolsList = Array.isArray(implementedTools) ? implementedTools : [];
+    // Session cleanup: check for idle sessions periodically
+    const cleanupInterval = setInterval(async () => {
+        const now = Date.now();
+        const sessionsToCleanup = [];
+        for (const [sessionId, lastActivity] of sessionLastActivity.entries()) {
+            if (now - lastActivity > SESSION_TIMEOUT_MS) {
+                sessionsToCleanup.push(sessionId);
+            }
+        }
+        for (const sessionId of sessionsToCleanup) {
+            logger.info(`[SESSION] Cleaning up idle session: ${sessionId}`);
+            transports.delete(sessionId);
+            sessionLastActivity.delete(sessionId);
+            sessionInitPromises.delete(sessionId);
+            await shutdownActualForSession(sessionId);
+        }
+    }, SESSION_CLEANUP_INTERVAL_MS);
+    // Authentication middleware
+    const authenticateRequest = (req, res) => {
+        // OIDC mode: mcp-auth middleware has already validated the JWT and populated req.auth.
+        if (config.AUTH_PROVIDER === 'oidc')
+            return true;
+        // Legacy static Bearer token mode (default).
+        // If MCP_SSE_AUTHORIZATION is not configured, allow all requests
+        if (!config.MCP_SSE_AUTHORIZATION) {
+            return true;
+        }
+        const authHeader = req.headers.authorization;
+        if (!authHeader) {
+            logger.warn(`[HTTP] Unauthorized request from ${req.ip || req.connection.remoteAddress}: Missing Authorization header`);
+            res.status(401).json({ error: 'Unauthorized: Missing Authorization header' });
+            return false;
+        }
+        // Check for Bearer token format
+        const match = authHeader.match(/^Bearer\s+(.+)$/i);
+        if (!match) {
+            logger.warn(`[HTTP] Unauthorized request from ${req.ip || req.connection.remoteAddress}: Invalid Authorization header format`);
+            res.status(401).json({ error: 'Unauthorized: Invalid Authorization header format. Expected "Bearer <token>"' });
+            return false;
+        }
+        const token = match[1];
+        // Debug logging for token comparison
+        logger.debug(`[HTTP] Auth header received: "${authHeader}"`);
+        logger.debug(`[HTTP] Extracted token: "${token}" (length: ${token.length})`);
+        logger.debug(`[HTTP] Expected token: "${config.MCP_SSE_AUTHORIZATION}" (length: ${config.MCP_SSE_AUTHORIZATION?.length || 0})`);
+        logger.debug(`[HTTP] Tokens equal: ${token === config.MCP_SSE_AUTHORIZATION}`);
+        logger.debug(`[HTTP] Token hex dump (received): ${Buffer.from(token).toString('hex')}`);
+        logger.debug(`[HTTP] Token hex dump (expected): ${Buffer.from(config.MCP_SSE_AUTHORIZATION || '').toString('hex')}`);
+        if (token !== config.MCP_SSE_AUTHORIZATION) {
+            logger.warn(`[HTTP] Unauthorized request from ${req.ip || req.connection.remoteAddress}: Invalid token`);
+            res.status(401).json({ error: 'Unauthorized: Invalid token' });
+            return false;
+        }
+        return true;
+    };
+    // Create a fresh Server instance similar to httpServer_testing
+    function createServerInstance() {
+        // ensure capabilities.tools is an object mapping tool name -> {}
+        const capabilitiesObj = capabilities && Object.keys(capabilities).length
+            ? capabilities
+            : { tools: toolsList.reduce((acc, n) => { acc[n] = {}; return acc; }, {}) };
+        const serverOptions = {
+            // Provide instructions and capabilities so the SDK initialize response is correct
+            instructions: serverInstructions || "Welcome to the Actual MCP server.",
+            serverInstructions: { instructions: serverInstructions || "Welcome to the Actual MCP server." },
+            capabilities: capabilitiesObj,
+            implementedTools: toolsList,
+            // Include tools array explicitly so initialize result contains tools: string[]
+            tools: toolsList,
+        };
+        const server = new Server({
+            name: serverDescription || "actual-mcp-server",
+            version: version || "0.1.0",
+        }, serverOptions);
+        // List tools handler
+        server.setRequestHandler(ListToolsRequestSchema, async () => {
+            logger.debug('[TOOLS LIST] Listing available tools');
+            logger.debug(`[TOOLS LIST] toolsList length: ${toolsList.length}`);
+            const tools = toolsList.map((name) => {
+                const schemaFromParam = toolSchemas && toolSchemas[name];
+                const schemaFromManager = actualToolsManager?.getToolSchema?.(name);
+                const schema = schemaFromParam || schemaFromManager;
+                // Ensure inputSchema is a valid JSON Schema object with required properties
+                const inputSchema = schema && typeof schema === 'object' && Object.keys(schema).length > 0
+                    ? schema
+                    : { type: 'object', properties: {}, additionalProperties: false };
+                // Get the actual tool description from the tool definition
+                const tool = actualToolsManager.getTool(name);
+                const description = tool?.description || `Tool ${name}`;
+                return {
+                    name,
+                    description,
+                    inputSchema,
+                };
+            });
+            logger.debug(`[TOOLS LIST] Returning ${tools.length} tools`);
+            return { tools };
+        });
+        // Call tool handler -> proxy to mcp.executeTool or to actualToolsManager
+        // Note: sessionId is available via requestContext.getStore() for tools that need it
+        server.setRequestHandler(CallToolRequestSchema, async (request) => {
+            const req = request;
+            const params = req?.params ?? {};
+            const rawName = params.name;
+            const args = params.arguments;
+            if (typeof rawName !== 'string') {
+                throw new Error('Tool name must be a string');
+            }
+            const name = rawName;
+            logger.debug(`[TOOL CALL] ${name} args=${JSON.stringify(args)}`);
+            // Prefer ActualMCPConnection executor if provided
+            if (typeof mcp.executeTool === 'function') {
+                const result = await mcp.executeTool(name, args ?? {});
+                return {
+                    content: [{ type: 'text', text: typeof result === 'string' ? result : JSON.stringify(result) }],
+                };
+            }
+            // fallback: attempt actualToolsManager
+            if (actualToolsManager && typeof actualToolsManager.invoke === 'function') {
+                const r = await actualToolsManager.invoke(name, args ?? {});
+                return { content: [{ type: 'text', text: JSON.stringify(r) }] };
+            }
+            throw new Error(`Tool executor not available for ${name}`);
+        });
+        return { server };
+    }
+    // Middleware to inject Accept header for LobeChat compatibility
+    // Must be before the route handler
+    app.use(httpPath, (req, _res, next) => {
+        const accept = req.get('Accept');
+        logger.debug(`[ACCEPT HEADER MIDDLEWARE] Original: ${accept || 'undefined'}`);
+        // Fix Accept header if it's missing, */* , or doesn't include BOTH required types
+        const needsFix = !accept ||
+            accept === '*/*' ||
+            !accept.includes('application/json') ||
+            !accept.includes('text/event-stream');
+        if (needsFix) {
+            logger.debug('[ACCEPT HEADER MIDDLEWARE] Modifying Accept header for MCP SDK compatibility');
+            // Use setHeader to properly modify the request headers
+            req.headers.accept = 'application/json, text/event-stream';
+            // Also try modifying the raw headers object
+            if (req.rawHeaders) {
+                const acceptIndex = req.rawHeaders.findIndex((h) => h.toLowerCase() === 'accept');
+                if (acceptIndex >= 0 && acceptIndex + 1 < req.rawHeaders.length) {
+                    req.rawHeaders[acceptIndex + 1] = 'application/json, text/event-stream';
+                }
+            }
+        }
+        next();
+    });
+    // Unified POST handler. Create new server/transport only on initialize (no session id).
+    app.post(httpPath, async (req, res) => {
+        // Authenticate the request
+        if (!authenticateRequest(req, res)) {
+            return;
+        }
+        const sessionId = req.headers['mcp-session-id'];
+        const payload = (req.body && Object.keys(req.body).length) ? req.body : {};
+        const method = payload?.method;
+        // Special handling for tools/list without session (LobeChat compatibility)
+        // LobeChat sends Accept: */* or Accept: application/json which the MCP SDK rejects
+        // Handle this case directly without going through the transport
+        if (!sessionId && method === 'tools/list') {
+            logger.debug('[LOBECHAT COMPAT] Handling tools/list without session directly');
+            const tools = toolsList.map((name) => {
+                const schemaFromParam = toolSchemas && toolSchemas[name];
+                const schemaFromManager = actualToolsManager?.getToolSchema?.(name);
+                const schema = schemaFromParam || schemaFromManager;
+                // Ensure inputSchema is a valid JSON Schema object with required properties
+                const inputSchema = schema && typeof schema === 'object' && Object.keys(schema).length > 0
+                    ? schema
+                    : { type: 'object', properties: {}, additionalProperties: false };
+                // Get the actual tool description from the tool definition
+                const tool = actualToolsManager.getTool(name);
+                const description = tool?.description || `Tool ${name}`;
+                return {
+                    name,
+                    description,
+                    inputSchema,
+                };
+            });
+            res.json({
+                jsonrpc: '2.0',
+                id: payload?.id ?? null,
+                result: { tools }
+            });
+            return;
+        }
+        try {
+            if (!sessionId) {
+                // Allow initialize or tools/list without session id (LobeChat compatibility)
+                // For tools/list, we'll auto-create a session
+                if (method !== 'initialize' && method !== 'tools/list') {
+                    res.status(400).json({
+                        jsonrpc: '2.0',
+                        id: payload?.id ?? null,
+                        error: { code: -32000, message: 'Missing session id; only initialize or tools/list allowed without session' },
+                    });
+                    return;
+                }
+                // Check if we can accept a new session (concurrent limit)
+                if (!canAcceptNewSession()) {
+                    const state = getConnectionState();
+                    const stats = state.connectionPool;
+                    const timeoutMinutes = state.idleTimeoutMinutes || 2;
+                    const errorMsg = `Max concurrent sessions (${stats?.maxConcurrent}) reached. Active: ${stats?.activeSessions}. Please close existing sessions or wait for idle sessions to timeout (${timeoutMinutes} minutes).`;
+                    logger.warn(`[SESSION] Rejecting new session: ${errorMsg}`);
+                    res.status(503).json({
+                        jsonrpc: '2.0',
+                        id: payload?.id ?? null,
+                        error: {
+                            code: -32000,
+                            message: errorMsg,
+                            data: {
+                                maxConcurrent: stats?.maxConcurrent,
+                                activeSessions: stats?.activeSessions,
+                                availableSlots: (stats?.maxConcurrent ?? 0) - (stats?.activeSessions ?? 0),
+                                idleTimeoutMinutes: timeoutMinutes
+                            }
+                        },
+                    });
+                    return;
+                }
+                logger.debug('[SESSION] Creating new MCP server + transport for initialize');
+                const { server } = createServerInstance();
+                // Create a promise to track session initialization completion
+                let resolveInit;
+                let rejectInit;
+                const initPromise = new Promise((resolve, reject) => {
+                    resolveInit = resolve;
+                    rejectInit = reject;
+                });
+                const transport = new StreamableHTTPServerTransport({
+                    sessionIdGenerator: () => randomUUID(),
+                    enableJsonResponse: true,
+                    onsessioninitialized: async (sid) => {
+                        logger.debug(`Session initialized: ${sid}`);
+                        // Store the promise before starting initialization
+                        sessionInitPromises.set(sid, initPromise);
+                        // Initialize connection pool for this session
+                        try {
+                            await connectToActualForSession(sid);
+                            // Only add to transports/activity map if connection successful
+                            transports.set(sid, transport);
+                            sessionLastActivity.set(sid, Date.now());
+                            logger.info(`[SESSION] Actual connection initialized for session: ${sid}`);
+                            resolveInit?.();
+                        }
+                        catch (err) {
+                            logger.error(`[SESSION] Failed to initialize Actual for session ${sid}:`, err);
+                            // Don't add failed sessions to transports map - they won't be usable anyway
+                            // This prevents accumulation of dead sessions
+                            rejectInit?.(err);
+                        }
+                        finally {
+                            // Clean up the promise after a short delay to allow pending requests to complete
+                            setTimeout(() => sessionInitPromises.delete(sid), 1000);
+                        }
+                    },
+                });
+                // connect transport then handle request (matching working example)
+                await server.connect(transport);
+                try {
+                    // Run in AsyncLocalStorage context so tools can access sessionId
+                    await requestContext.run({ sessionId: undefined }, async () => {
+                        await transport.handleRequest(req, res, req.body);
+                    });
+                }
+                catch (err) {
+                    logger.error('Transport.handleRequest failed during initialize: %o', err);
+                    const e = err;
+                    if (e && typeof e.stack === 'string')
+                        logger.error(e.stack);
+                    throw err;
+                }
+                return;
+            }
+            // sessionId present -> reuse
+            let transport = transports.get(sessionId);
+            if (!transport) {
+                // Check if session is currently being initialized
+                const initPromise = sessionInitPromises.get(sessionId);
+                if (initPromise) {
+                    logger.debug(`[SESSION] Waiting for session ${sessionId} initialization to complete...`);
+                    try {
+                        // Wait for initialization to complete
+                        await initPromise;
+                        transport = transports.get(sessionId);
+                        if (transport) {
+                            logger.debug(`[SESSION] Session ${sessionId} initialization complete, proceeding with request`);
+                        }
+                    }
+                    catch (err) {
+                        logger.error(`[SESSION] Session ${sessionId} initialization failed:`, err);
+                        // Fall through to session not found handling
+                    }
+                }
+                if (!transport) {
+                    // Session doesn't exist (expired, server restarted, or invalid)
+                    // For tools/list, return tools for LobeChat discovery (they cache session IDs)
+                    // This allows LobeChat's backend to discover available tools even with expired sessions
+                    if (method === 'tools/list') {
+                        logger.debug('[LOBECHAT COMPAT] Handling tools/list with expired/invalid session - returning tools for discovery');
+                        const tools = toolsList.map((name) => {
+                            const schemaFromParam = toolSchemas && toolSchemas[name];
+                            const schemaFromManager = actualToolsManager?.getToolSchema?.(name);
+                            const schema = schemaFromParam || schemaFromManager;
+                            const inputSchema = schema && typeof schema === 'object' && Object.keys(schema).length > 0
+                                ? schema
+                                : { type: 'object', properties: {}, additionalProperties: false };
+                            const tool = actualToolsManager.getTool(name);
+                            const description = tool?.description || `Tool ${name}`;
+                            return {
+                                name,
+                                description,
+                                inputSchema,
+                            };
+                        });
+                        res.json({
+                            jsonrpc: '2.0',
+                            id: payload?.id ?? null,
+                            result: { tools }
+                        });
+                        return;
+                    }
+                    // For other methods, reject the request and tell client to re-initialize
+                    logger.warn(`[SESSION] Session ${sessionId} not found (method: ${method}). Client must re-initialize.`);
+                    res.status(400).json({
+                        jsonrpc: '2.0',
+                        id: payload?.id ?? null,
+                        error: {
+                            code: -32000,
+                            message: 'Session expired or invalid. Please re-initialize by calling initialize without mcp-session-id header.'
+                        },
+                    });
+                    return;
+                }
+            }
+            // Update activity timestamp for valid session
+            sessionLastActivity.set(sessionId, Date.now());
+            // Run in AsyncLocalStorage context so tools can access sessionId
+            await requestContext.run({ sessionId }, async () => {
+                await transport.handleRequest(req, res, req.body);
+            });
+        }
+        catch (err) {
+            logger.error('POST handler error: %o', err);
+            const e2 = err;
+            if (e2 && typeof e2.stack === 'string')
+                logger.error(e2.stack);
+            if (!res.headersSent) {
+                res.status(500).json({ jsonrpc: '2.0', id: payload?.id ?? null, error: { code: -32603, message: String(err) } });
+            }
+        }
+    });
+    // GET for SSE connect (reuse transport)
+    app.get(httpPath, async (req, res) => {
+        const sessionId = req.headers['mcp-session-id'];
+        if (!sessionId) {
+            res.status(400).json({ jsonrpc: '2.0', error: { code: -32000, message: 'No session id' }, id: null });
+            return;
+        }
+        sessionLastActivity.set(sessionId, Date.now()); // Track activity
+        const transport = transports.get(sessionId);
+        if (!transport) {
+            res.status(400).json({ jsonrpc: '2.0', error: { code: -32000, message: 'Transport not ready' }, id: null });
+            return;
+        }
+        await transport.handleRequest(req, res);
+    });
+    // quick GET info endpoints (some clients probe)
+    const serverIp = process.env.MCP_BRIDGE_PUBLIC_HOST || getLocalIp();
+    app.get('/.well-known/oauth-protected-resource', (_req, res) => {
+        res.json({
+            jsonrpc: '2.0',
+            result: {
+                description: serverDescription || "Actual MCP server",
+                instructions: serverInstructions || "Welcome to the Actual MCP server.",
+                serverInstructions: { instructions: serverInstructions || "Welcome to the Actual MCP server." },
+                capabilities: capabilities && Object.keys(capabilities).length ? capabilities : { tools: toolsList.reduce((a, n) => ({ ...a, [n]: {} }), {}) },
+                tools: toolsList,
+                advertisedUrl: advertisedUrl || `${scheme}://${serverIp}:${port}${httpPath}`,
+            },
+        });
+    });
+    app.get('/.well-known/oauth-protected-resource/http', (_req, res) => {
+        res.json({
+            jsonrpc: '2.0',
+            result: {
+                description: serverDescription || "Actual MCP server",
+                instructions: serverInstructions || "Welcome to the Actual MCP server.",
+                serverInstructions: { instructions: serverInstructions || "Welcome to the Actual MCP server." },
+                capabilities: capabilities && Object.keys(capabilities).length ? capabilities : { tools: toolsList.reduce((a, n) => ({ ...a, [n]: {} }), {}) },
+                tools: toolsList,
+                advertisedUrl: advertisedUrl || `${scheme}://${serverIp}:${port}${httpPath}`,
+            },
+        });
+    });
+    app.get('/health', (_req, res) => {
+        const state = getConnectionState();
+        const poolStats = state.connectionPool || null;
+        res.json({
+            status: state.initialized ? 'ok' : 'not-initialized',
+            ...state,
+            transport: 'streamable-http',
+            activeSessions: transports.size,
+            connectionPool: poolStats
+        });
+    });
+    app.get('/metrics', async (_req, res) => {
+        const txt = await observability.getMetricsText();
+        if (!txt) {
+            res.status(204).end();
+            return;
+        }
+        res.setHeader('Content-Type', 'text/plain; version=0.0.4');
+        res.send(txt);
+    });
+    const tlsOptions = config.MCP_ENABLE_HTTPS
+        ? { cert: fs.readFileSync(config.MCP_HTTPS_CERT), key: fs.readFileSync(config.MCP_HTTPS_KEY) }
+        : undefined;
+    const listener = (tlsOptions ? https.createServer(tlsOptions, app) : app).listen(port, () => {
+        const advertised = advertisedUrl || `${scheme}://${serverIp}:${port}${httpPath}`;
+        console.info(`MCP Streamable HTTP Server listening on ${port}`);
+        console.info(`📨 MCP endpoint: ${advertised}`);
+        console.info(`❤️ Health check: ${scheme}://localhost:${port}/health`);
+        if (config.AUTH_PROVIDER === 'oidc') {
+            logger.info(`🔒 OIDC authentication enabled (JWT Bearer token required — issuer: ${config.OIDC_ISSUER})`);
+        }
+        else if (config.MCP_SSE_AUTHORIZATION) {
+            logger.info(`🔒 HTTP authentication enabled (static Bearer token required)`);
+        }
+        else {
+            logger.warn(`⚠️  HTTP authentication disabled (no MCP_SSE_AUTHORIZATION or OIDC configured)`);
+        }
+    });
+    // Configure keep-alive to maintain persistent connections
+    listener.keepAliveTimeout = 65000; // 65 seconds (slightly higher than typical client timeout)
+    listener.headersTimeout = 66000; // 66 seconds (must be higher than keepAliveTimeout)
+    logger.info(`⏱️  HTTP keep-alive enabled (timeout: ${listener.keepAliveTimeout}ms)`);
+    // Cleanup on server shutdown
+    const cleanup = async () => {
+        logger.info('[SERVER] Shutting down, cleaning up sessions...');
+        clearInterval(cleanupInterval);
+        for (const sessionId of transports.keys()) {
+            await shutdownActualForSession(sessionId);
+        }
+        transports.clear();
+        sessionLastActivity.clear();
+        sessionInitPromises.clear();
+        // Also shut down the shared/pooled connections
+        await shutdownActual();
+    };
+    process.on('SIGTERM', cleanup);
+    process.on('SIGINT', cleanup);
+    return { app, listener, cleanup };
+}