@oobe-protocol-labs/sap-mcp-server 0.8.0 → 0.9.1

package/dist/remote/server.js

@@ -25,6 +25,7 @@ const OOBE_LOGO_ASSET_PATH = join(dirname(fileURLToPath(import.meta.url)), '..',
 const LOGO_ASSET_ROOT_PATH = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'assets', 'logos');
 const DOCS_ROOT_PATH = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'docs');
 const USER_DOCS_ROOT_PATH = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'USER_DOCS');
+const SMITHERY_CONFIG_SCHEMA_PATH = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'smithery.config.schema.json');
 const PAYMENT_STATS_CACHE_MS = 15_000;
 const SERVER_CARD_CACHE_MS = 300_000;
 const RELEASE_DOWNLOAD_BASE_URL = `https://github.com/OOBE-PROTOCOL/sap-mcp/releases/download/${MCP_SERVER_VERSION}`;
@@ -40,14 +41,51 @@ let oobeLogoAssetCache;
 let paymentStatsCache;
 let serverCardCapabilitiesCache;
 const PUBLIC_LOGO_ASSETS = {
+    '/logos/claude.png': { filename: 'claude.png', contentType: 'image/png' },
+    '/logos/codex.webp': { filename: 'codex.webp', contentType: 'image/webp' },
     '/logos/drift.svg': { filename: 'drift.svg', contentType: 'image/svg+xml' },
+    '/logos/hermes.png': { filename: 'hermes.png', contentType: 'image/png' },
     '/logos/jupiter.ico': { filename: 'jupiter.ico', contentType: 'image/x-icon' },
     '/logos/mcp.svg': { filename: 'mcp.svg', contentType: 'image/svg+xml' },
     '/logos/meteora.png': { filename: 'meteora.png', contentType: 'image/png' },
     '/logos/orca.ico': { filename: 'orca.ico', contentType: 'image/x-icon' },
+    '/logos/openclaw.svg': { filename: 'openclaw.svg', contentType: 'image/svg+xml' },
     '/logos/raydium.ico': { filename: 'raydium.ico', contentType: 'image/x-icon' },
     '/logos/smithery.svg': { filename: 'smithery.svg', contentType: 'image/svg+xml' },
 };
+class RemoteCapacityError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RemoteCapacityError';
+    }
+}
+class InFlightRequestLimiter {
+    maxInFlightRequests;
+    active = 0;
+    constructor(maxInFlightRequests) {
+        this.maxInFlightRequests = maxInFlightRequests;
+    }
+    tryAcquire() {
+        if (this.maxInFlightRequests <= 0) {
+            return () => undefined;
+        }
+        if (this.active >= this.maxInFlightRequests) {
+            return undefined;
+        }
+        this.active += 1;
+        let released = false;
+        return () => {
+            if (released) {
+                return;
+            }
+            released = true;
+            this.active = Math.max(0, this.active - 1);
+        };
+    }
+    getActiveCount() {
+        return this.active;
+    }
+}
 /**
  * @name parseApiKeys
  * @description Parses comma-separated `apiKey=userId` entries from environment configuration.
@@ -81,6 +119,9 @@ export function defaultRemoteConfig(appConfig) {
         corsOrigins: appConfig.httpCorsOrigins,
         stateless: parseRemoteBoolean(process.env.SAP_MCP_HTTP_STATELESS, false),
         rateLimit: buildRemoteRateLimitConfigFromEnv(appConfig.rateLimitPerMinute),
+        sessions: buildRemoteSessionConfigFromEnv(),
+        concurrency: buildRemoteConcurrencyConfigFromEnv(),
+        http: buildRemoteHttpTuningConfigFromEnv(),
         paymentDiscovery: buildPublicPaymentDiscovery(appConfig),
         paymentPriceRange: {
             minUsd: appConfig.monetization.prices.minUsd,
@@ -173,6 +214,34 @@ function parseRemoteBoolean(raw, fallback) {
     }
     return ['true', '1', 'yes', 'on'].includes(raw.trim().toLowerCase());
 }
+function buildRemoteSessionConfigFromEnv() {
+    return {
+        maxStatefulSessions: parseRemotePositiveInteger(process.env.SAP_MCP_REMOTE_MAX_STATEFUL_SESSIONS, 2_000),
+        idleTtlMs: parseRemotePositiveInteger(process.env.SAP_MCP_REMOTE_SESSION_IDLE_TTL_MS, 10 * 60 * 1000),
+        absoluteTtlMs: parseRemotePositiveInteger(process.env.SAP_MCP_REMOTE_SESSION_ABSOLUTE_TTL_MS, 60 * 60 * 1000),
+        cleanupIntervalMs: parseRemotePositiveInteger(process.env.SAP_MCP_REMOTE_SESSION_CLEANUP_INTERVAL_MS, 30_000),
+    };
+}
+function buildRemoteConcurrencyConfigFromEnv() {
+    return {
+        maxInFlightRequests: parseRemotePositiveInteger(process.env.SAP_MCP_REMOTE_MAX_IN_FLIGHT_REQUESTS, 1_024),
+    };
+}
+function buildRemoteHttpTuningConfigFromEnv() {
+    return {
+        requestTimeoutMs: parseRemotePositiveInteger(process.env.SAP_MCP_REMOTE_REQUEST_TIMEOUT_MS, 5 * 60 * 1000),
+        headersTimeoutMs: parseRemotePositiveInteger(process.env.SAP_MCP_REMOTE_HEADERS_TIMEOUT_MS, 65_000),
+        keepAliveTimeoutMs: parseRemotePositiveInteger(process.env.SAP_MCP_REMOTE_KEEP_ALIVE_TIMEOUT_MS, 75_000),
+        maxRequestsPerSocket: parseRemotePositiveInteger(process.env.SAP_MCP_REMOTE_MAX_REQUESTS_PER_SOCKET, 0),
+    };
+}
+function parseRemotePositiveInteger(raw, fallback) {
+    if (!raw) {
+        return fallback;
+    }
+    const value = Number.parseInt(raw, 10);
+    return Number.isFinite(value) && value > 0 ? value : fallback;
+}
 /**
  * @name writeJson
  * @description Writes a JSON response with optional additional headers.
@@ -475,6 +544,8 @@ function readPaymentStatsFromLedger() {
         totalPaymentRequests: 0,
         totalVerifiedPayments: 0,
         totalFailedSettlements: 0,
+        uniqueRemoteCallers: 0,
+        uniqueUserAgents: 0,
         ledgerAvailable: false,
     };
     const ledgerPath = join(getDataDir(), 'payments', 'usage-ledger.jsonl');
@@ -482,12 +553,20 @@ function readPaymentStatsFromLedger() {
         return stats;
     }
     stats.ledgerAvailable = true;
+    const remoteCallers = new Set();
+    const userAgents = new Set();
     const lines = readFileSync(ledgerPath, 'utf-8').split('\n');
     for (const line of lines) {
         const event = parsePaymentLedgerEvent(line);
         if (!event) {
             continue;
         }
+        if (event.remoteAddress) {
+            remoteCallers.add(event.remoteAddress);
+        }
+        if (event.userAgent) {
+            userAgents.add(event.userAgent);
+        }
         if (event.event === 'payment_required') {
             stats.totalPaymentRequests += 1;
         }
@@ -503,6 +582,8 @@ function readPaymentStatsFromLedger() {
             stats.totalFailedSettlements += 1;
         }
     }
+    stats.uniqueRemoteCallers = remoteCallers.size;
+    stats.uniqueUserAgents = userAgents.size;
     return stats;
 }
 function parsePaymentLedgerEvent(line) {
@@ -607,6 +688,7 @@ export function buildPublicServerInfo(req, config) {
             serverInfo: `${baseUrl}/server.json`,
             openApi: `${baseUrl}/openapi.json`,
             x402Discovery: `${baseUrl}/.well-known/x402`,
+            smitheryConfigSchema: `${baseUrl}/smithery.config.schema.json`,
             smitheryServerCard: `${baseUrl}/.well-known/mcp/server-card.json`,
             payShProvider: `${baseUrl}/pay/provider.yml`,
             agentCard: `${baseUrl}/.well-known/agent-card.json`,
@@ -650,6 +732,34 @@ export function buildPublicServerInfo(req, config) {
         },
     };
 }
+/**
+ * @name buildMarketplaceConfigurationMetadata
+ * @description Builds public Smithery/marketplace configuration hints for non-custodial x402 usage.
+ */
+export function buildMarketplaceConfigurationMetadata(req, config) {
+    const baseUrl = buildPublicBaseUrl(req, config);
+    return {
+        required: false,
+        schemaUrl: `${baseUrl}/smithery.config.schema.json`,
+        configSchema: readSmitheryConfigSchema(),
+        recommendedMode: 'free-discovery',
+        paidToolModes: ['x402-native-client', 'local-sap-payments-bridge'],
+        instructions: 'Start with free discovery tools in Smithery. Paid/write tools return x402 challenges; complete them with a native x402-capable client or with the local sap_payments bridge installed by the SAP MCP wizard.',
+        setupCommand: WIZARD_NPM_COMMAND,
+        localBridge: {
+            serverName: 'sap_payments',
+            readinessTool: 'sap_payments_readiness',
+            paidCallTool: 'sap_payments_call_paid_tool',
+        },
+    };
+}
+/**
+ * @name readSmitheryConfigSchema
+ * @description Reads the published Smithery JSON schema from the packaged root.
+ */
+export function readSmitheryConfigSchema() {
+    return JSON.parse(readFileSync(SMITHERY_CONFIG_SCHEMA_PATH, 'utf-8'));
+}
 /**
  * @name getStaticServerCardCapabilities
  * @description Reads capabilities from the real MCP registration store so static metadata never drifts from tools/list.
@@ -727,6 +837,7 @@ export async function buildStaticServerCard(req, config, appConfig) {
             required: authRequired,
             schemes: authRequired ? ['Bearer'] : ['none', 'x402'],
         },
+        configuration: buildMarketplaceConfigurationMetadata(req, config),
         transport: {
             type: 'streamable-http',
             url: `${baseUrl}/mcp`,
@@ -1046,52 +1157,219 @@ export function buildDocsHtml(req, config) {
     :root {
       --theme-color: #28d8e8;
       --sidebar-width: 310px;
+      --sap-bg: #111413;
+      --sap-panel: rgba(255, 255, 255, .055);
+      --sap-line: rgba(255, 255, 255, .14);
+      --sap-aqua: #28d8e8;
+      --sap-ink: #f5fbfc;
+      --sap-muted: #a8b9bc;
+    }
+    * {
+      box-sizing: border-box;
+    }
+    html {
+      background: var(--sap-bg);
     }
     body {
       font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
-      color: #17242b;
+      color: var(--sap-ink);
+      background:
+        linear-gradient(rgba(40, 216, 232, .025) 1px, transparent 1px),
+        linear-gradient(90deg, rgba(40, 216, 232, .025) 1px, transparent 1px),
+        var(--sap-bg);
+      background-size: 80px 80px;
+      overflow-x: hidden;
+    }
+    body::before {
+      content: "";
+      position: fixed;
+      inset: 0;
+      z-index: -1;
+      pointer-events: none;
+      background:
+        radial-gradient(circle at 16% 10%, rgba(40, 216, 232, .12), transparent 30%),
+        radial-gradient(circle at 84% 18%, rgba(134, 166, 255, .08), transparent 28%),
+        linear-gradient(180deg, rgba(255,255,255,.025), transparent 40%);
+    }
+    .docs-home {
+      position: fixed;
+      top: 14px;
+      left: 14px;
+      z-index: 80;
+      display: inline-flex;
+      align-items: center;
+      gap: 10px;
+      min-height: 54px;
+      border: 1px solid rgba(255,255,255,.12);
+      border-radius: 999px;
+      padding: 7px 15px 7px 8px;
+      color: var(--sap-ink);
+      text-decoration: none;
+      font-weight: 850;
+      background: rgba(11, 17, 17, .82);
+      box-shadow: 0 18px 44px rgba(0, 0, 0, .28);
+      backdrop-filter: blur(18px);
+      -webkit-backdrop-filter: blur(18px);
+    }
+    .docs-home:hover,
+    .docs-home:focus-visible {
+      border-color: rgba(40,216,232,.44);
+      background: rgba(40,216,232,.09);
+    }
+    .docs-home img {
+      width: 38px;
+      height: 38px;
+      border-radius: 12px;
+      box-shadow: 0 0 0 1px rgba(40,216,232,.2);
+    }
+    .docs-home span {
+      display: grid;
+      gap: 1px;
+      line-height: 1.05;
+    }
+    .docs-home small {
+      color: var(--sap-muted);
+      font-size: 11px;
+      font-weight: 750;
+    }
+    .app-nav {
+      background: rgba(11, 17, 17, .9);
+      border-bottom: 1px solid var(--sap-line);
+      color: var(--sap-ink);
+      backdrop-filter: blur(16px);
+      -webkit-backdrop-filter: blur(16px);
+    }
+    .github-corner svg {
+      color: var(--sap-bg);
+      fill: var(--sap-aqua);
+    }
+    .search input {
+      border: 1px solid rgba(255,255,255,.12);
+      border-radius: 999px;
+      color: var(--sap-ink);
+      background: rgba(255,255,255,.055);
     }
     .app-name-link {
-      color: #062730;
+      color: var(--sap-ink);
       font-weight: 800;
     }
+    .app-name {
+      margin-top: 82px;
+    }
     .sidebar {
-      border-right: 1px solid rgba(6,39,48,.10);
+      border-right: 1px solid var(--sap-line);
+      background:
+        linear-gradient(180deg, rgba(255,255,255,.055), rgba(255,255,255,.028)),
+        rgba(9, 17, 18, .92);
+      color: var(--sap-muted);
+    }
+    .sidebar-toggle {
+      background: rgba(11, 17, 17, .88);
+      border-radius: 0 14px 14px 0;
+      border: 1px solid var(--sap-line);
+      border-left: 0;
     }
     .sidebar-nav strong,
     .markdown-section h1,
     .markdown-section h2,
     .markdown-section h3 {
-      color: #062730;
+      color: var(--sap-ink);
       letter-spacing: 0;
     }
+    .sidebar ul li a,
+    .sidebar ul li.active > a,
+    .anchor span {
+      color: var(--sap-muted);
+    }
+    .sidebar ul li.active > a,
+    .sidebar ul li a:hover {
+      color: var(--sap-aqua);
+    }
+    .markdown-section {
+      max-width: 920px;
+      color: var(--sap-muted);
+    }
+    .markdown-section strong,
+    .markdown-section table,
+    .markdown-section li {
+      color: var(--sap-muted);
+    }
     .markdown-section a {
-      color: #087f91;
+      color: var(--sap-aqua);
       text-underline-offset: 3px;
     }
     .markdown-section code {
-      color: #062730;
+      color: #d8faff;
       border-radius: 6px;
+      background: rgba(255,255,255,.08);
     }
     .markdown-section pre {
       border-radius: 8px;
-      border: 1px solid rgba(6,39,48,.10);
+      border: 1px solid var(--sap-line);
+      background: rgba(0,0,0,.34);
     }
     .markdown-section table {
       display: table;
       width: 100%;
+      overflow-wrap: anywhere;
+    }
+    .markdown-section th,
+    .markdown-section td {
+      border-color: rgba(255,255,255,.12);
     }
     .markdown-section blockquote {
-      border-left-color: #28d8e8;
-      color: #49656f;
+      border-left-color: var(--sap-aqua);
+      color: var(--sap-muted);
+      background: rgba(40,216,232,.045);
     }
     .cover-main,
     section.cover {
-      background: linear-gradient(115deg, rgba(40,216,232,.13), transparent 34%), #f8fdff;
+      background:
+        linear-gradient(115deg, rgba(40,216,232,.13), transparent 34%),
+        var(--sap-bg);
+    }
+    @media (max-width: 768px) {
+      .docs-home {
+        position: sticky;
+        top: 8px;
+        left: auto;
+        width: calc(100% - 24px);
+        margin: 8px 12px;
+        justify-content: flex-start;
+      }
+      .app-name {
+        margin-top: 18px;
+      }
+      .markdown-section {
+        padding: 32px 18px 40px;
+      }
+      .markdown-section h1 {
+        font-size: 34px;
+        line-height: 1;
+      }
+      .markdown-section table {
+        display: block;
+        overflow-x: auto;
+      }
+    }
+    @media (max-width: 420px) {
+      .docs-home {
+        border-radius: 20px;
+      }
+      .docs-home span strong {
+        font-size: 14px;
+      }
     }
   </style>
 </head>
 <body>
+  <a class="docs-home" href="${escapeHtml(info.endpoints.landing)}" aria-label="Back to SAP MCP home">
+    <img src="/favicon.png" width="38" height="38" alt="">
+    <span>
+      <strong>SAP MCP Docs</strong>
+      <small>Back to hosted gateway</small>
+    </span>
+  </a>
   <div id="app">Loading SAP MCP documentation...</div>
   <script>
     window.$docsify = ${docsifyConfig};
@@ -1305,7 +1583,11 @@ export class RemoteMCPServer {
     appConfig;
     authManager;
     rateLimiter;
+    requestLimiter;
     statefulSessions = new Map();
+    sessionConfig;
+    httpTuning;
+    sessionCleanupInterval;
     httpServer;
     constructor(config) {
         this.appConfig = loadConfig();
@@ -1317,6 +1599,9 @@ export class RemoteMCPServer {
         this.config = config ?? defaultRemoteConfig(this.appConfig);
         this.authManager = new AuthManager(this.config.auth);
         this.rateLimiter = new RemoteRateLimiter(this.config.rateLimit);
+        this.sessionConfig = this.config.sessions ?? buildRemoteSessionConfigFromEnv();
+        this.httpTuning = this.config.http ?? buildRemoteHttpTuningConfigFromEnv();
+        this.requestLimiter = new InFlightRequestLimiter(this.config.concurrency?.maxInFlightRequests ?? buildRemoteConcurrencyConfigFromEnv().maxInFlightRequests);
     }
     /**
      * @name start
@@ -1325,6 +1610,7 @@ export class RemoteMCPServer {
     async start() {
         this.validateAuthConfig();
         await this.rateLimiter.initialize();
+        this.startSessionCleanup();
         const monetizationGate = await McpMonetizationGate.create(this.appConfig);
         this.httpServer = http.createServer(async (req, res) => {
             if (this.applyCors(req, res)) {
@@ -1345,6 +1631,12 @@ export class RemoteMCPServer {
                 }, isHeadMethod(req.method));
                 return;
             }
+            if (isPublicReadMethod(req.method) && url.pathname === '/smithery.config.schema.json') {
+                writeJson(res, 200, readSmitheryConfigSchema(), {
+                    'Cache-Control': 'public, max-age=300',
+                }, isHeadMethod(req.method));
+                return;
+            }
             const publicLogoAsset = resolvePublicLogoAsset(req.method, url.pathname);
             if (publicLogoAsset) {
                 writeLogoAsset(res, publicLogoAsset);
@@ -1444,6 +1736,21 @@ export class RemoteMCPServer {
                 });
                 return;
             }
+            const releaseRequest = this.requestLimiter.tryAcquire();
+            if (!releaseRequest) {
+                writeJson(res, 503, {
+                    error: 'remote_mcp_over_capacity',
+                    retryAfterSeconds: 2,
+                    hint: 'The hosted MCP gateway is protecting itself from overload. Retry shortly or reduce parallel calls.',
+                }, {
+                    'Retry-After': '2',
+                    'X-MCP-In-Flight': String(this.requestLimiter.getActiveCount()),
+                });
+                return;
+            }
+            res.once('finish', releaseRequest);
+            res.once('close', releaseRequest);
+            res.setHeader('X-MCP-In-Flight', String(this.requestLimiter.getActiveCount()));
             // ── Request logging ─────────────────────────────────────────────
             const reqStart = Date.now();
             const callerIp = getRateLimitKey(req);
@@ -1505,6 +1812,23 @@ export class RemoteMCPServer {
                 }
             }
             catch (error) {
+                if (error instanceof RemoteCapacityError) {
+                    logger.warn('Remote MCP capacity limit reached', {
+                        error: error.message,
+                        activeSessions: this.statefulSessions.size,
+                    });
+                    if (!res.headersSent) {
+                        writeJson(res, 503, {
+                            error: 'remote_mcp_session_capacity',
+                            retryAfterSeconds: 5,
+                            activeSessions: this.statefulSessions.size,
+                            maxStatefulSessions: this.sessionConfig.maxStatefulSessions,
+                        }, {
+                            'Retry-After': '5',
+                        });
+                    }
+                    return;
+                }
                 logger.error('Remote MCP request failed', { error });
                 if (!res.headersSent) {
                     writeJson(res, 500, {
@@ -1518,6 +1842,10 @@ export class RemoteMCPServer {
                 }
             }
         });
+        this.httpServer.requestTimeout = this.httpTuning.requestTimeoutMs;
+        this.httpServer.headersTimeout = this.httpTuning.headersTimeoutMs;
+        this.httpServer.keepAliveTimeout = this.httpTuning.keepAliveTimeoutMs;
+        this.httpServer.maxRequestsPerSocket = this.httpTuning.maxRequestsPerSocket;
         await new Promise((resolve, reject) => {
             this.httpServer?.once('error', reject);
             this.httpServer?.listen(this.config.port, this.config.host, resolve);
@@ -1532,6 +1860,10 @@ export class RemoteMCPServer {
             stateless: this.config.stateless,
             rateLimitPerMinute: this.config.rateLimit.enabled ? this.config.rateLimit.requestsPerMinute : 0,
             redisRateLimit: Boolean(this.config.rateLimit.redisUrl),
+            maxStatefulSessions: this.sessionConfig.maxStatefulSessions,
+            sessionIdleTtlMs: this.sessionConfig.idleTtlMs,
+            maxInFlightRequests: this.config.concurrency?.maxInFlightRequests,
+            requestTimeoutMs: this.httpTuning.requestTimeoutMs,
         });
     }
     /**
@@ -1539,6 +1871,10 @@ export class RemoteMCPServer {
      * @description Gracefully closes the MCP transport and HTTP listener.
      */
     async stop() {
+        if (this.sessionCleanupInterval) {
+            clearInterval(this.sessionCleanupInterval);
+            this.sessionCleanupInterval = undefined;
+        }
         const sessions = Array.from(this.statefulSessions.values());
         this.statefulSessions.clear();
         await Promise.allSettled(sessions.map(session => session.transport.close()));
@@ -1644,6 +1980,10 @@ export class RemoteMCPServer {
      * @description Creates one MCP server and Streamable HTTP transport for a single initialized session.
      */
     async createStatefulSessionTransport() {
+        await this.pruneStatefulSessions('before-create');
+        if (this.statefulSessions.size >= this.sessionConfig.maxStatefulSessions) {
+            throw new RemoteCapacityError(`Stateful MCP session capacity reached (${this.sessionConfig.maxStatefulSessions})`);
+        }
         const server = await createSapMcpServer(this.appConfig);
         const transport = new StreamableHTTPServerTransport({
             sessionIdGenerator: () => randomUUID(),
@@ -1663,16 +2003,85 @@ export class RemoteMCPServer {
         transport.onclose = () => {
             const sessionId = transport.sessionId;
             if (sessionId) {
-                this.statefulSessions.delete(sessionId);
-                logger.info('Stateful MCP session closed', {
-                    sessionId,
-                    activeSessions: this.statefulSessions.size,
-                });
+                const deleted = this.statefulSessions.delete(sessionId);
+                if (deleted) {
+                    logger.info('Stateful MCP session closed', {
+                        sessionId,
+                        activeSessions: this.statefulSessions.size,
+                    });
+                }
             }
         };
         await server.connect(transport);
         return transport;
     }
+    startSessionCleanup() {
+        if (this.config.stateless || this.sessionCleanupInterval) {
+            return;
+        }
+        this.sessionCleanupInterval = setInterval(() => {
+            void this.pruneStatefulSessions('interval').catch(error => {
+                logger.warn('Stateful MCP session cleanup failed', { error });
+            });
+        }, this.sessionConfig.cleanupIntervalMs);
+        this.sessionCleanupInterval.unref?.();
+    }
+    async pruneStatefulSessions(reason) {
+        if (this.statefulSessions.size === 0) {
+            return;
+        }
+        const now = Date.now();
+        const expiredSessionIds = [];
+        for (const [sessionId, session] of this.statefulSessions.entries()) {
+            const idleMs = now - session.lastSeenAt;
+            const ageMs = now - session.createdAt;
+            if (idleMs > this.sessionConfig.idleTtlMs || ageMs > this.sessionConfig.absoluteTtlMs) {
+                expiredSessionIds.push(sessionId);
+            }
+        }
+        for (const sessionId of expiredSessionIds) {
+            await this.closeStatefulSession(sessionId, 'expired');
+        }
+        if (this.statefulSessions.size < this.sessionConfig.maxStatefulSessions) {
+            if (expiredSessionIds.length > 0) {
+                logger.info('Stateful MCP session cleanup completed', {
+                    reason,
+                    closed: expiredSessionIds.length,
+                    activeSessions: this.statefulSessions.size,
+                });
+            }
+            return;
+        }
+        const targetSize = Math.max(0, this.sessionConfig.maxStatefulSessions - 1);
+        const sessionsByIdleAge = Array.from(this.statefulSessions.entries())
+            .sort(([, left], [, right]) => left.lastSeenAt - right.lastSeenAt);
+        const overflowCount = Math.max(0, this.statefulSessions.size - targetSize);
+        for (const [sessionId] of sessionsByIdleAge.slice(0, overflowCount)) {
+            await this.closeStatefulSession(sessionId, 'capacity-prune');
+        }
+        if (expiredSessionIds.length > 0 || overflowCount > 0) {
+            logger.info('Stateful MCP session cleanup completed', {
+                reason,
+                expired: expiredSessionIds.length,
+                prunedForCapacity: overflowCount,
+                activeSessions: this.statefulSessions.size,
+            });
+        }
+    }
+    async closeStatefulSession(sessionId, reason) {
+        const session = this.statefulSessions.get(sessionId);
+        if (!session) {
+            return;
+        }
+        this.statefulSessions.delete(sessionId);
+        await session.transport.close().catch(error => {
+            logger.warn('Failed to close stateful MCP session', {
+                sessionId,
+                reason,
+                error,
+            });
+        });
+    }
     /**
      * @name applyCors
      * @description Applies configured CORS headers and handles preflight requests.