actual-mcp-server 0.5.0

package/dist/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"
+}

package/dist/src/actualConnection.js

@@ -0,0 +1,157 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import api from '@actual-app/api';
+import logger from './logger.js';
+import config from './config.js';
+import { connectionPool } from './lib/ActualConnectionPool.js';
+import { createModuleLogger } from './lib/loggerFactory.js';
+const log = createModuleLogger('CONNECTION');
+const DEFAULT_DATA_DIR = path.resolve(os.homedir() || '.', '.actual');
+let initialized = false;
+let initializing = false;
+let initializationError = null;
+// Feature flag to enable connection pooling - can be disabled via environment variable
+let useConnectionPool = process.env.USE_CONNECTION_POOL !== 'false';
+export async function connectToActual() {
+    if (initialized)
+        return;
+    if (initializing) {
+        while (initializing)
+            await new Promise(r => setTimeout(r, 100));
+        if (initializationError)
+            throw initializationError;
+        return;
+    }
+    initializing = true;
+    try {
+        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; // optional for E2E encrypted budgets
+        const TEST_ACTUAL_CONNECTION = process.argv.includes('--test-actual-connection');
+        // Use configured MCP_BRIDGE_DATA_DIR (fallback to DEFAULT_DATA_DIR) for all runs
+        const DATA_DIR = config.MCP_BRIDGE_DATA_DIR || DEFAULT_DATA_DIR;
+        new URL(SERVER_URL);
+        if (!fs.existsSync(DATA_DIR))
+            fs.mkdirSync(DATA_DIR, { recursive: true });
+        log.info(`Initializing Actual API with dataDir=${DATA_DIR}`);
+        await api.init({
+            dataDir: DATA_DIR,
+            serverURL: SERVER_URL,
+            password: PASSWORD,
+        });
+        log.info(`Downloading budget with sync ID: ${BUDGET_SYNC_ID}`);
+        // According to official docs, downloadBudget accepts optional second parameter for E2E encryption
+        if (BUDGET_PASSWORD) {
+            const apiWithOptions = api;
+            await apiWithOptions.downloadBudget(BUDGET_SYNC_ID, { password: BUDGET_PASSWORD });
+        }
+        else {
+            await api.downloadBudget(BUDGET_SYNC_ID);
+        }
+        if (TEST_ACTUAL_CONNECTION) {
+            logger.info('Test flag detected (--test-actual-connection) — closing Actual session.');
+            // Prefer the documented shutdown method only
+            try {
+                const maybeApi = api;
+                if (typeof maybeApi.shutdown === 'function') {
+                    await maybeApi.shutdown();
+                }
+                else {
+                    logger.warn('No shutdown method found on Actual API; leaving session as-is.');
+                }
+            }
+            catch (closeErr) {
+                logger.error('Error while shutting down Actual session during test run:', closeErr);
+            }
+            // allow small grace period for any IO to finish before cleanup/exit
+            await new Promise((res) => setTimeout(res, 500));
+            // no temp data dir cleanup — use persistent MCP_BRIDGE_DATA_DIR as configured
+            logger.info('Exiting process after test connection.');
+            // exit explicitly for test mode
+            process.exit(0);
+        }
+        initialized = true;
+        logger.info('✅ Connected to Actual Finance and downloaded budget');
+    }
+    catch (err) {
+        initializationError = err instanceof Error ? err : new Error(String(err));
+        logger.error('❌ Failed to connect to Actual Finance:', initializationError);
+        throw initializationError;
+    }
+    finally {
+        initializing = false;
+    }
+}
+export async function shutdownActual() {
+    if (useConnectionPool) {
+        await connectionPool.shutdownAll();
+        initialized = false;
+        return;
+    }
+    try {
+        const maybeApi = api;
+        if (typeof maybeApi.shutdown === 'function') {
+            await maybeApi.shutdown();
+        }
+        initialized = false;
+        logger.info('Actual API shutdown complete.');
+    }
+    catch (err) {
+        logger.error('Error during Actual API shutdown:', err);
+    }
+}
+/**
+ * Initialize connection for a specific MCP session
+ * Uses connection pooling to give each session its own Actual Budget connection
+ */
+export async function connectToActualForSession(sessionId) {
+    if (!useConnectionPool) {
+        // Fallback to shared connection
+        return connectToActual();
+    }
+    try {
+        // Ensure connection pool initialization is complete before accepting connections
+        await connectionPool.waitForInitialization();
+        await connectionPool.getConnection(sessionId);
+        logger.info(`Actual API connection ready for session: ${sessionId}`);
+    }
+    catch (err) {
+        logger.error(`Failed to connect to Actual for session ${sessionId}:`, err);
+        throw err;
+    }
+}
+/**
+ * Shutdown connection for a specific MCP session
+ */
+export async function shutdownActualForSession(sessionId) {
+    if (!useConnectionPool) {
+        return;
+    }
+    try {
+        await connectionPool.shutdownConnection(sessionId);
+        logger.info(`Actual API connection shutdown for session: ${sessionId}`);
+    }
+    catch (err) {
+        logger.error(`Error shutting down Actual for session ${sessionId}:`, err);
+    }
+}
+export function getConnectionState() {
+    // When using connection pooling, consider server initialized if pool is ready
+    // (even with 0 active connections, pool being initialized means server is ready to accept sessions)
+    const isPoolInitialized = useConnectionPool && connectionPool.isInitialized();
+    const effectivelyInitialized = useConnectionPool ? isPoolInitialized : initialized;
+    return {
+        initialized: effectivelyInitialized,
+        initializationError,
+        connectionPool: useConnectionPool ? connectionPool.getStats() : null,
+        idleTimeoutMinutes: useConnectionPool ? connectionPool.getIdleTimeoutMinutes() : null,
+    };
+}
+export function canAcceptNewSession() {
+    if (!useConnectionPool) {
+        return true; // Shared connection mode - always accept
+    }
+    return connectionPool.canAcceptNewSession();
+}

package/dist/src/actualToolsManager.js

@@ -0,0 +1,211 @@
+import logger from './logger.js';
+import { z } from 'zod';
+// ✅ List of tools already implemented in this class.
+// Adding the tool name here is considered fully implemented.
+const IMPLEMENTED_TOOLS = [
+    'actual_accounts_close',
+    'actual_accounts_create',
+    'actual_accounts_delete',
+    'actual_accounts_get_balance',
+    'actual_accounts_list',
+    'actual_accounts_reopen',
+    'actual_accounts_update',
+    'actual_bank_sync',
+    'actual_budgets_get_all',
+    'actual_budgets_list_available',
+    'actual_budgets_switch',
+    'actual_budgets_getMonth',
+    'actual_budgets_getMonths',
+    'actual_budgets_holdForNextMonth',
+    'actual_budgets_resetHold',
+    'actual_budgets_setAmount',
+    'actual_budgets_setCarryover',
+    'actual_budgets_transfer',
+    'actual_budget_updates_batch',
+    'actual_categories_create',
+    'actual_categories_delete',
+    'actual_categories_get',
+    'actual_categories_update',
+    'actual_category_groups_create',
+    'actual_category_groups_delete',
+    'actual_category_groups_get',
+    'actual_category_groups_update',
+    'actual_payees_create',
+    'actual_payees_delete',
+    'actual_payees_get',
+    'actual_payees_merge',
+    'actual_payees_update',
+    'actual_payee_rules_get',
+    'actual_query_run',
+    'actual_rules_create',
+    'actual_rules_create_or_update',
+    'actual_rules_delete',
+    'actual_rules_get',
+    'actual_rules_update',
+    'actual_schedules_create',
+    'actual_schedules_delete',
+    'actual_schedules_get',
+    'actual_schedules_update',
+    'actual_transactions_create',
+    'actual_transactions_delete',
+    'actual_transactions_filter',
+    'actual_transactions_get',
+    'actual_transactions_import',
+    'actual_transactions_search_by_amount',
+    'actual_transactions_search_by_category',
+    'actual_transactions_search_by_month',
+    'actual_transactions_search_by_payee',
+    'actual_transactions_summary_by_category',
+    'actual_transactions_summary_by_payee',
+    'actual_transactions_uncategorized',
+    'actual_transactions_update',
+    'actual_transactions_update_batch',
+    'actual_server_info',
+    'actual_session_close',
+    'actual_session_list',
+    'actual_get_id_by_name',
+    'actual_server_get_version',
+];
+// 🔑 Mapping of Actual API function names → your MCP tool names
+// This allows us to compare what exists in the API vs. what it has been wrapped.
+const API_TOOL_MAP = {
+    getAccounts: 'actual_accounts_list',
+    createAccount: 'actual_accounts_create',
+    updateAccount: 'actual_accounts_update',
+    deleteAccount: 'actual_accounts_delete',
+    getAccountBalance: 'actual_accounts_get_balance',
+    getTransactions: 'actual_transactions_get',
+    addTransactions: 'actual_transactions_create',
+    importTransactions: 'actual_transactions_import',
+    updateTransaction: 'actual_transactions_update',
+    deleteTransaction: 'actual_transactions_delete',
+    getBudgetMonths: 'actual_budgets_getMonths',
+    getBudgetMonth: 'actual_budgets_getMonth',
+    setBudgetAmount: 'actual_budgets_setAmount',
+    setBudgetCarryover: 'actual_budgets_setCarryover',
+    getCategories: 'actual_categories_get',
+    createCategory: 'actual_categories_create',
+    updateCategory: 'actual_categories_update',
+    deleteCategory: 'actual_categories_delete',
+    getPayees: 'actual_payees_get',
+    createPayee: 'actual_payees_create',
+    updatePayee: 'actual_payees_update',
+    deletePayee: 'actual_payees_delete',
+    mergePayees: 'actual_payees_merge',
+    getPayeeRules: 'actual_payee_rules_get',
+    batchBudgetUpdates: 'actual_budget_updates_batch',
+    holdBudgetForNextMonth: 'actual_budgets_holdForNextMonth',
+    resetBudgetHold: 'actual_budgets_resetHold',
+    getRules: 'actual_rules_get',
+    createRule: 'actual_rules_create',
+    updateRule: 'actual_rules_update',
+    deleteRule: 'actual_rules_delete',
+    closeAccount: 'actual_accounts_close',
+    reopenAccount: 'actual_accounts_reopen',
+    getCategoryGroups: 'actual_category_groups_get',
+    createCategoryGroup: 'actual_category_groups_create',
+    updateCategoryGroup: 'actual_category_groups_update',
+    deleteCategoryGroup: 'actual_category_groups_delete',
+    getIDByName: 'actual_get_id_by_name',
+    getServerVersion: 'actual_server_get_version',
+};
+// Define Account schema for validation (simplified example)
+const AccountSchema = z.object({
+    id: z.string().optional(),
+    name: z.string(),
+    type: z.string(), // Consider enum if you have fixed valid types
+    offbudget: z.boolean().optional().default(false),
+    closed: z.boolean().optional().default(false),
+});
+// Input schema for get_accounts - no args
+const GetAccountsInputSchema = z.object({});
+// Input schema for get_account_balance
+const GetAccountBalanceInputSchema = z.object({
+    id: z.string().optional().describe('Account ID to get balance for (optional; defaults to first account)'),
+    cutoff: z.string().optional().describe('Optional ISO date string cutoff'),
+});
+class ActualToolsManager {
+    tools = new Map();
+    constructor() { }
+    async initialize() {
+        // Dynamically import all tool modules from src/tools/index.ts
+        const toolModules = (await import('./tools/index.js'));
+        let count = 0;
+        for (const [key, tool] of Object.entries(toolModules)) {
+            const t = tool;
+            if (t && t.name) {
+                this.tools.set(t.name, tool);
+                count++;
+            }
+        }
+        logger.info(`🔗 Loaded ${count} tool modules from src/tools`);
+    }
+    getToolNames() {
+        return Array.from(this.tools.keys());
+    }
+    getTool(name) {
+        return this.tools.get(name);
+    }
+    async callTool(name, args) {
+        const tool = this.getTool(name);
+        if (!tool)
+            throw new Error(`Tool not found: ${name}`);
+        try {
+            const result = await tool.call(args);
+            // Force-serialize/deserialize to ensure result is JSON-safe (no circular refs,
+            // Buffers, class instances, etc). Convert undefined -> null so callers always
+            // receive a valid JSON value.
+            const safe = result === undefined ? null : JSON.parse(JSON.stringify(result));
+            logger.info(`[TOOL RESULT] ${name}: ${JSON.stringify(safe)}`);
+            return safe;
+        }
+        catch (err) {
+            // Format Zod validation errors more clearly
+            if (err && typeof err === 'object' && 'issues' in err) {
+                const zodError = err;
+                const issues = zodError.issues.map(issue => {
+                    const path = issue.path.join('.');
+                    return `${path}: ${issue.message}`;
+                }).join(', ');
+                const formattedMsg = `Validation error: ${issues}`;
+                logger.error(`[TOOL ERROR] ${name}: ${formattedMsg}`);
+                throw new Error(formattedMsg);
+            }
+            const e = err;
+            const msg = e && typeof e.message === 'string' ? e.message : String(err);
+            logger.error(`[TOOL ERROR] ${name}: ${msg}`);
+            throw err;
+        }
+    }
+    /**
+     * Get coverage statistics comparing implemented tools with available API methods
+     */
+    getCoverageStats() {
+        const apiMethods = Object.keys(API_TOOL_MAP);
+        const mappedTools = Object.values(API_TOOL_MAP);
+        const implemented = IMPLEMENTED_TOOLS;
+        const missing = mappedTools.filter(tool => !implemented.includes(tool));
+        const coverage = (implemented.length / mappedTools.length) * 100;
+        return {
+            totalApiMethods: apiMethods.length,
+            totalMappedTools: mappedTools.length,
+            implementedTools: implemented.length,
+            missingTools: missing.length,
+            coveragePercent: Math.round(coverage * 100) / 100,
+            missingToolsList: missing,
+        };
+    }
+    /**
+     * Get the API method name for a given tool name
+     */
+    getApiMethodForTool(toolName) {
+        return Object.entries(API_TOOL_MAP).find(([_, tool]) => tool === toolName)?.[0];
+    }
+    /**
+     * Get the tool name for a given API method
+     */
+    getToolForApiMethod(apiMethod) {
+        return API_TOOL_MAP[apiMethod];
+    }
+}
+export default new ActualToolsManager();

package/dist/src/auth/budget-acl.js

@@ -0,0 +1,143 @@
+// src/auth/budget-acl.ts
+//
+// Per-user budget ACL enforcement (CF-5: OIDC multi-user auth).
+//
+// When AUTH_PROVIDER=oidc and AUTH_BUDGET_ACL is set, this module restricts
+// which Actual Budget sync-IDs each authenticated user may access.
+//
+// ACL map format (AUTH_BUDGET_ACL env var, JSON):
+//   { "<principal>": ["<syncId1>", "<syncId2>"] }
+//
+//   Principal keys:
+//     "alice@example.com"  — matched against token email claim
+//     "some-sub-uuid"      — matched against token sub claim
+//     "group:admin"        — matched against token groups/roles array
+//
+//   Value ["*"] grants access to all budgets (admin shorthand).
+//
+// When AUTH_BUDGET_ACL is unset, all authenticated users are allowed ("*").
+//
+// Usage in httpServer.ts:
+//   app.use(httpPath, budgetAclMiddleware);   // after bearerAuth()
+//
+// Tools/adapters can read (req as any).allowedBudgets: string[] | undefined
+// to filter results by permitted sync IDs (forward-looking multi-budget support).
+import config from '../config.js';
+import logger from '../logger.js';
+// ---------------------------------------------------------------------------
+// ACL map (parsed once from env, cached)
+// ---------------------------------------------------------------------------
+let _aclMap = null;
+function getAclMap() {
+    if (_aclMap !== null)
+        return _aclMap;
+    if (!config.AUTH_BUDGET_ACL) {
+        _aclMap = {};
+        return _aclMap;
+    }
+    try {
+        const parsed = JSON.parse(config.AUTH_BUDGET_ACL);
+        if (typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new TypeError('AUTH_BUDGET_ACL must be a JSON object');
+        }
+        _aclMap = parsed;
+        logger.info(`[ACL] Budget ACL loaded: ${Object.keys(_aclMap).length} principal(s)`);
+    }
+    catch (err) {
+        logger.error('[ACL] Invalid AUTH_BUDGET_ACL JSON — treating as empty (no budget restrictions):', err);
+        _aclMap = {};
+    }
+    return _aclMap;
+}
+// ---------------------------------------------------------------------------
+// Public helpers
+// ---------------------------------------------------------------------------
+/**
+ * Returns the list of allowed budget sync-IDs for the currently authenticated
+ * request principal.
+ *
+ * - Returns `['*']` when ACL is empty / unset (no restrictions).
+ * - Returns `['*']` when any matched principal has wildcard access.
+ * - Returns `[]` when the user is authenticated but not in the ACL at all.
+ */
+export function getAllowedBudgets(req) {
+    const acl = getAclMap();
+    // No ACL configured → allow everything
+    if (Object.keys(acl).length === 0)
+        return ['*'];
+    const auth = req.auth;
+    if (!auth)
+        return [];
+    const claims = (auth.claims ?? {});
+    const sub = auth.subject;
+    const email = claims['email'];
+    const rawGroups = claims['groups'] ?? claims['roles'] ?? [];
+    const groups = Array.isArray(rawGroups) ? rawGroups : [];
+    // Build the list of principal identities for this request
+    const principals = [];
+    if (sub)
+        principals.push(sub);
+    if (email)
+        principals.push(email);
+    for (const g of groups)
+        principals.push(`group:${g}`);
+    // Check for wildcard admin access first
+    for (const p of principals) {
+        if (acl[p]?.includes('*'))
+            return ['*'];
+    }
+    // Collect all permitted sync-IDs
+    const permitted = new Set();
+    for (const p of principals) {
+        for (const id of acl[p] ?? [])
+            permitted.add(id);
+    }
+    return [...permitted];
+}
+/**
+ * Returns true if the authenticated user can access the given budget sync-ID.
+ */
+export function canAccessBudget(req, budgetSyncId) {
+    const allowed = getAllowedBudgets(req);
+    return allowed.includes('*') || allowed.includes(budgetSyncId);
+}
+// ---------------------------------------------------------------------------
+// Express middleware
+// ---------------------------------------------------------------------------
+/**
+ * Express middleware that enforces the budget ACL when OIDC auth is active.
+ *
+ * - Falls through immediately when AUTH_PROVIDER !== 'oidc' or AUTH_BUDGET_ACL
+ *   is unset (no-op — keeps backward compatibility).
+ * - Attaches `req.allowedBudgets` for downstream use (multi-budget tools).
+ * - Returns HTTP 403 if the authenticated user has no permitted budgets.
+ *
+ * Must be mounted AFTER mcp-auth's `bearerAuth()` middleware so `req.auth`
+ * is already populated.
+ */
+export function budgetAclMiddleware(req, res, next) {
+    // No-op unless OIDC + ACL configured
+    if (config.AUTH_PROVIDER !== 'oidc') {
+        next();
+        return;
+    }
+    const allowed = getAllowedBudgets(req);
+    if (allowed.includes('*') || allowed.length > 0) {
+        // Expose allowed budgets for use in tools
+        req.allowedBudgets = allowed;
+        next();
+        return;
+    }
+    const auth = req.auth;
+    const identity = auth?.subject ?? 'unknown';
+    logger.warn(`[ACL] Access denied for '${identity}': no permitted budgets in ACL`);
+    res.status(403).json({ error: 'Forbidden: no budget access configured for this user' });
+}
+/** Reset cached state (test helper). */
+export function _resetAclForTests() {
+    _aclMap = null;
+}
+/** Directly set the ACL map (test helper — bypasses config/env). */
+export function _setAclForTests(aclMap) {
+    _aclMap = aclMap;
+}

package/dist/src/auth/setup.js

@@ -0,0 +1,58 @@
+// src/auth/setup.ts
+//
+// Factory for the mcp-auth MCPAuth instance (CF-5: OIDC multi-user auth).
+// Returns null when AUTH_PROVIDER !== 'oidc' — existing static Bearer token
+// auth (MCP_SSE_AUTHORIZATION) is then used unchanged.
+//
+// Uses the mcp-auth "discovery config" approach: OIDC metadata is fetched
+// on-demand on the first incoming request, so no top-level async needed here.
+import { MCPAuth } from 'mcp-auth';
+import config from '../config.js';
+import logger from '../logger.js';
+let _instance = null;
+/**
+ * Returns an MCPAuth instance configured for this server's OIDC settings,
+ * or null if AUTH_PROVIDER is not 'oidc'.
+ *
+ * The instance is a singleton — safe to call multiple times.
+ *
+ * @throws If AUTH_PROVIDER=oidc but OIDC_ISSUER or OIDC_RESOURCE are unset.
+ */
+export function createMcpAuth() {
+    if (config.AUTH_PROVIDER !== 'oidc') {
+        return null;
+    }
+    if (!config.OIDC_ISSUER) {
+        throw new Error('[OIDC] AUTH_PROVIDER=oidc requires OIDC_ISSUER to be set. ' +
+            'Example: OIDC_ISSUER=https://auth.example.com/realms/myrealm');
+    }
+    if (!config.OIDC_RESOURCE) {
+        throw new Error('[OIDC] AUTH_PROVIDER=oidc requires OIDC_RESOURCE to be set. ' +
+            'Example: OIDC_RESOURCE=https://actual-mcp.example.com');
+    }
+    if (_instance)
+        return _instance;
+    const scopesSupported = config.OIDC_SCOPES
+        ? config.OIDC_SCOPES.split(',').map((s) => s.trim()).filter(Boolean)
+        : [];
+    logger.info(`[OIDC] Configuring mcp-auth — issuer: ${config.OIDC_ISSUER}`);
+    logger.info(`[OIDC] Resource identifier: ${config.OIDC_RESOURCE}`);
+    logger.info(`[OIDC] Scopes required: ${scopesSupported.length ? scopesSupported.join(', ') : '(none)'}`);
+    _instance = new MCPAuth({
+        protectedResources: [
+            {
+                metadata: {
+                    resource: config.OIDC_RESOURCE,
+                    // Discovery config: mcp-auth fetches OIDC metadata lazily on first request.
+                    authorizationServers: [{ issuer: config.OIDC_ISSUER, type: 'oidc' }],
+                    scopesSupported,
+                },
+            },
+        ],
+    });
+    return _instance;
+}
+/** Reset the singleton (test helper). */
+export function _resetMcpAuthForTests() {
+    _instance = null;
+}