@j0hanz/superfetch 1.2.5 → 2.0.1

package/dist/http/mcp-routes.js

@@ -1,31 +1,48 @@
+import { z } from 'zod';
 import { logError, logInfo } from '../services/logger.js';
-import { resolveTransportForPost, } from './mcp-session.js';
-import { isMcpRequestBody } from './mcp-validation.js';
-import { getSessionId } from './sessions.js';
-function sendJsonRpcError(res, code, message, status = 400) {
-    res.status(status).json({
-        jsonrpc: '2.0',
-        error: {
-            code,
-            message,
-        },
-        id: null,
-    });
+import { getSessionId, resolveTransportForPost, sendJsonRpcError, } from './mcp-sessions.js';
+const paramsSchema = z.looseObject({});
+const mcpRequestSchema = z.looseObject({
+    jsonrpc: z.literal('2.0'),
+    method: z.string().min(1),
+    id: z.union([z.string(), z.number()]).optional(),
+    params: paramsSchema.optional(),
+});
+function wrapAsync(fn) {
+    return (req, res, next) => {
+        Promise.resolve(fn(req, res)).catch(next);
+    };
+}
+export function isJsonRpcBatchRequest(body) {
+    return Array.isArray(body);
+}
+export function isMcpRequestBody(body) {
+    return mcpRequestSchema.safeParse(body).success;
 }
 function respondInvalidRequestBody(res) {
     sendJsonRpcError(res, -32600, 'Invalid Request: Malformed request body', 400);
 }
 function respondMissingSession(res) {
-    res.status(400).json({ error: 'Missing mcp-session-id header' });
+    sendJsonRpcError(res, -32600, 'Missing mcp-session-id header', 400);
 }
 function respondSessionNotFound(res) {
-    res.status(404).json({ error: 'Session not found' });
+    sendJsonRpcError(res, -32600, 'Session not found', 404);
+}
+function validatePostPayload(payload, res) {
+    if (isJsonRpcBatchRequest(payload)) {
+        sendJsonRpcError(res, -32600, 'Batch requests are not supported', 400);
+        return null;
+    }
+    if (!isMcpRequestBody(payload)) {
+        respondInvalidRequestBody(res);
+        return null;
+    }
+    return payload;
 }
 function logPostRequest(body, sessionId, options) {
     logInfo('[MCP POST]', {
         method: body.method,
         id: body.id,
-        sessionId: sessionId ?? 'none',
         isInitialize: body.method === 'initialize',
         sessionCount: options.sessionStore.size(),
     });
@@ -50,49 +67,138 @@ function dispatchTransportRequest(transport, req, res, body) {
         : transport.handleRequest(req, res);
 }
 function resolveSessionTransport(sessionId, options, res) {
+    const { sessionStore } = options;
     if (!sessionId) {
         respondMissingSession(res);
         return null;
     }
-    const session = options.sessionStore.get(sessionId);
+    const session = sessionStore.get(sessionId);
     if (!session) {
         respondSessionNotFound(res);
         return null;
     }
-    options.sessionStore.touch(sessionId);
+    sessionStore.touch(sessionId);
     return session.transport;
 }
+const MCP_PROTOCOL_VERSION_HEADER = 'mcp-protocol-version';
+const MCP_PROTOCOL_VERSIONS = {
+    defaultVersion: '2025-03-26',
+    supported: new Set(['2025-03-26', '2025-11-25']),
+};
+function getHeaderValue(req, headerNameLower) {
+    const value = req.headers[headerNameLower];
+    if (typeof value === 'string')
+        return value;
+    if (Array.isArray(value))
+        return value[0] ?? null;
+    return null;
+}
+function setHeaderValue(req, headerNameLower, value) {
+    // Express exposes req.headers as a plain object, but the type is readonly-ish.
+    req.headers[headerNameLower] = value;
+}
+export function ensureMcpProtocolVersionHeader(req, res) {
+    const raw = getHeaderValue(req, MCP_PROTOCOL_VERSION_HEADER);
+    const version = raw?.trim();
+    if (!version) {
+        setHeaderValue(req, MCP_PROTOCOL_VERSION_HEADER, MCP_PROTOCOL_VERSIONS.defaultVersion);
+        return true;
+    }
+    if (!MCP_PROTOCOL_VERSIONS.supported.has(version)) {
+        sendJsonRpcError(res, -32600, `Unsupported MCP-Protocol-Version: ${version}`, 400);
+        return false;
+    }
+    return true;
+}
+function getAcceptHeader(req) {
+    const value = req.headers.accept;
+    if (typeof value === 'string')
+        return value;
+    return '';
+}
+function setAcceptHeader(req, value) {
+    req.headers.accept = value;
+    const { rawHeaders } = req;
+    if (!Array.isArray(rawHeaders))
+        return;
+    for (let i = 0; i + 1 < rawHeaders.length; i += 2) {
+        const key = rawHeaders[i];
+        if (typeof key === 'string' && key.toLowerCase() === 'accept') {
+            rawHeaders[i + 1] = value;
+            return;
+        }
+    }
+    rawHeaders.push('Accept', value);
+}
+function hasToken(header, token) {
+    return header
+        .split(',')
+        .map((part) => part.trim().toLowerCase())
+        .some((part) => part === token || part.startsWith(`${token};`));
+}
+export function ensurePostAcceptHeader(req) {
+    const accept = getAcceptHeader(req);
+    // Some clients send */* or omit Accept; the SDK transport is picky.
+    if (!accept || hasToken(accept, '*/*')) {
+        setAcceptHeader(req, 'application/json, text/event-stream');
+        return;
+    }
+    const hasJson = hasToken(accept, 'application/json');
+    const hasSse = hasToken(accept, 'text/event-stream');
+    if (!hasJson || !hasSse) {
+        setAcceptHeader(req, 'application/json, text/event-stream');
+    }
+}
+export function acceptsEventStream(req) {
+    const accept = getAcceptHeader(req);
+    if (!accept)
+        return false;
+    return hasToken(accept, 'text/event-stream');
+}
 async function handlePost(req, res, options) {
+    ensurePostAcceptHeader(req);
+    if (!ensureMcpProtocolVersionHeader(req, res))
+        return;
     const sessionId = getSessionId(req);
-    const { body } = req;
-    if (!isMcpRequestBody(body)) {
-        respondInvalidRequestBody(res);
+    const payload = validatePostPayload(req.body, res);
+    if (!payload)
         return;
-    }
-    logPostRequest(body, sessionId, options);
-    const transport = await resolveTransportForPost(req, res, body, sessionId, options);
+    logPostRequest(payload, sessionId, options);
+    const transport = await resolveTransportForPost({
+        res,
+        body: payload,
+        sessionId,
+        options,
+    });
     if (!transport)
         return;
-    await handleTransportRequest(transport, req, res, body);
+    await handleTransportRequest(transport, req, res, payload);
 }
 async function handleGet(req, res, options) {
+    if (!ensureMcpProtocolVersionHeader(req, res))
+        return;
+    if (!acceptsEventStream(req)) {
+        res.status(406).json({
+            error: 'Not Acceptable',
+            code: 'ACCEPT_NOT_SUPPORTED',
+        });
+        return;
+    }
     const transport = resolveSessionTransport(getSessionId(req), options, res);
     if (!transport)
         return;
     await handleTransportRequest(transport, req, res);
 }
 async function handleDelete(req, res, options) {
+    if (!ensureMcpProtocolVersionHeader(req, res))
+        return;
     const transport = resolveSessionTransport(getSessionId(req), options, res);
     if (!transport)
         return;
     await handleTransportRequest(transport, req, res);
 }
 export function registerMcpRoutes(app, options) {
-    const asyncHandler = (fn) => (req, res, next) => {
-        Promise.resolve(fn(req, res)).catch(next);
-    };
-    app.post('/mcp', asyncHandler((req, res) => handlePost(req, res, options)));
-    app.get('/mcp', asyncHandler((req, res) => handleGet(req, res, options)));
-    app.delete('/mcp', asyncHandler((req, res) => handleDelete(req, res, options)));
+    app.post('/mcp', wrapAsync((req, res) => handlePost(req, res, options)));
+    app.get('/mcp', wrapAsync((req, res) => handleGet(req, res, options)));
+    app.delete('/mcp', wrapAsync((req, res) => handleDelete(req, res, options)));
 }
-export { evictExpiredSessions } from './mcp-session.js';

package/dist/http/mcp-session-eviction.d.ts

@@ -0,0 +1,3 @@
+import type { SessionStore } from './sessions.js';
+export declare function evictExpiredSessions(store: SessionStore): number;
+export declare function evictOldestSession(store: SessionStore): boolean;

package/dist/http/mcp-session-eviction.js

@@ -0,0 +1,24 @@
+import { logWarn } from '../services/logger.js';
+import { getErrorMessage } from '../utils/error-details.js';
+export function evictExpiredSessions(store) {
+    const evicted = store.evictExpired();
+    for (const session of evicted) {
+        void session.transport.close().catch((error) => {
+            logWarn('Failed to close expired session', {
+                error: getErrorMessage(error),
+            });
+        });
+    }
+    return evicted.length;
+}
+export function evictOldestSession(store) {
+    const session = store.evictOldest();
+    if (!session)
+        return false;
+    void session.transport.close().catch((error) => {
+        logWarn('Failed to close evicted session', {
+            error: getErrorMessage(error),
+        });
+    });
+    return true;
+}

package/dist/http/mcp-session-helpers.d.ts

@@ -6,7 +6,6 @@ export interface SlotTracker {
     readonly isInitialized: () => boolean;
 }
 export declare function reserveSessionSlot(store: SessionStore, maxSessions: number): boolean;
-export declare function releaseSessionSlot(): void;
 export declare function createSlotTracker(): SlotTracker;
 export declare function ensureSessionCapacity(store: SessionStore, maxSessions: number, res: Response, evictOldest: (store: SessionStore) => boolean): boolean;
 export declare function respondServerBusy(res: Response): void;

package/dist/http/mcp-session-helpers.js

@@ -6,7 +6,7 @@ export function reserveSessionSlot(store, maxSessions) {
     inFlightSessions += 1;
     return true;
 }
-export function releaseSessionSlot() {
+function releaseSessionSlot() {
     if (inFlightSessions > 0) {
         inFlightSessions -= 1;
     }

package/dist/http/mcp-session-init.d.ts

@@ -0,0 +1,7 @@
+import type { Response } from 'express';
+import type { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import type { McpSessionOptions } from './mcp-session-types.js';
+export declare function createAndConnectTransport({ options, res, }: {
+    options: McpSessionOptions;
+    res: Response;
+}): Promise<StreamableHTTPServerTransport | null>;

package/dist/http/mcp-session-init.js

@@ -0,0 +1,94 @@
+import { logError, logInfo, logWarn } from '../services/logger.js';
+import { getErrorMessage } from '../utils/error-details.js';
+import { createMcpServer } from '../server.js';
+import { evictOldestSession } from './mcp-session-eviction.js';
+import { createSlotTracker, ensureSessionCapacity, reserveSessionSlot, respondBadRequest, respondServerBusy, } from './mcp-session-slots.js';
+import { createSessionTransport } from './mcp-session-transport-init.js';
+import { createTimeoutController, createTransportAdapter, } from './mcp-session-transport.js';
+async function connectTransportOrThrow({ transport, clearInitTimeout, releaseSlot, }) {
+    const mcpServer = createMcpServer();
+    const transportAdapter = createTransportAdapter(transport);
+    try {
+        await mcpServer.connect(transportAdapter);
+    }
+    catch (error) {
+        clearInitTimeout();
+        releaseSlot();
+        void transport.close().catch((closeError) => {
+            logWarn('Failed to close transport after connect error', {
+                error: getErrorMessage(closeError),
+            });
+        });
+        logError('Failed to initialize MCP session', error instanceof Error ? error : undefined);
+        throw error;
+    }
+}
+export async function createAndConnectTransport({ options, res, }) {
+    if (!reserveSessionIfPossible({ options, res }))
+        return null;
+    const tracker = createSlotTracker();
+    const timeoutController = createTimeoutController();
+    const transport = createSessionTransport({ tracker, timeoutController });
+    await connectTransportOrThrow({
+        transport,
+        clearInitTimeout: timeoutController.clear,
+        releaseSlot: tracker.releaseSlot,
+    });
+    const sessionId = resolveSessionId({
+        transport,
+        res,
+        tracker,
+        clearInitTimeout: timeoutController.clear,
+    });
+    if (!sessionId)
+        return null;
+    finalizeSession({
+        store: options.sessionStore,
+        transport,
+        sessionId,
+        tracker,
+        clearInitTimeout: timeoutController.clear,
+    });
+    return transport;
+}
+function reserveSessionIfPossible({ options, res, }) {
+    if (!ensureSessionCapacity({
+        store: options.sessionStore,
+        maxSessions: options.maxSessions,
+        res,
+        evictOldest: evictOldestSession,
+    })) {
+        return false;
+    }
+    if (!reserveSessionSlot(options.sessionStore, options.maxSessions)) {
+        respondServerBusy(res);
+        return false;
+    }
+    return true;
+}
+function resolveSessionId({ transport, res, tracker, clearInitTimeout, }) {
+    const { sessionId } = transport;
+    if (typeof sessionId !== 'string') {
+        clearInitTimeout();
+        tracker.releaseSlot();
+        respondBadRequest(res);
+        return null;
+    }
+    return sessionId;
+}
+function finalizeSession({ store, transport, sessionId, tracker, clearInitTimeout, }) {
+    clearInitTimeout();
+    tracker.markInitialized();
+    tracker.releaseSlot();
+    const now = Date.now();
+    store.set(sessionId, {
+        transport,
+        createdAt: now,
+        lastSeen: now,
+    });
+    transport.onclose = () => {
+        store.remove(sessionId);
+        logInfo('Session closed');
+    };
+    logInfo('Session initialized');
+}

package/dist/http/mcp-session-slots.d.ts

@@ -0,0 +1,17 @@
+import type { Response } from 'express';
+import type { SessionStore } from './sessions.js';
+export interface SlotTracker {
+    readonly releaseSlot: () => void;
+    readonly markInitialized: () => void;
+    readonly isInitialized: () => boolean;
+}
+export declare function reserveSessionSlot(store: SessionStore, maxSessions: number): boolean;
+export declare function createSlotTracker(): SlotTracker;
+export declare function ensureSessionCapacity({ store, maxSessions, res, evictOldest, }: {
+    store: SessionStore;
+    maxSessions: number;
+    res: Response;
+    evictOldest: (store: SessionStore) => boolean;
+}): boolean;
+export declare function respondServerBusy(res: Response): void;
+export declare function respondBadRequest(res: Response): void;

package/dist/http/mcp-session-slots.js

@@ -0,0 +1,55 @@
+import { sendJsonRpcError } from './jsonrpc-http.js';
+let inFlightSessions = 0;
+export function reserveSessionSlot(store, maxSessions) {
+    if (store.size() + inFlightSessions >= maxSessions) {
+        return false;
+    }
+    inFlightSessions += 1;
+    return true;
+}
+function releaseSessionSlot() {
+    if (inFlightSessions > 0) {
+        inFlightSessions -= 1;
+    }
+}
+export function createSlotTracker() {
+    let slotReleased = false;
+    let initialized = false;
+    return {
+        releaseSlot: () => {
+            if (slotReleased)
+                return;
+            slotReleased = true;
+            releaseSessionSlot();
+        },
+        markInitialized: () => {
+            initialized = true;
+        },
+        isInitialized: () => initialized,
+    };
+}
+export function ensureSessionCapacity({ store, maxSessions, res, evictOldest, }) {
+    if (!isServerAtCapacity(store, maxSessions)) {
+        return true;
+    }
+    if (tryEvictSlot(store, maxSessions, evictOldest)) {
+        return !isServerAtCapacity(store, maxSessions);
+    }
+    respondServerBusy(res);
+    return false;
+}
+function isServerAtCapacity(store, maxSessions) {
+    return store.size() + inFlightSessions >= maxSessions;
+}
+function tryEvictSlot(store, maxSessions, evictOldest) {
+    const currentSize = store.size();
+    const canFreeSlot = currentSize >= maxSessions &&
+        currentSize - 1 + inFlightSessions < maxSessions;
+    return canFreeSlot && evictOldest(store);
+}
+export function respondServerBusy(res) {
+    sendJsonRpcError(res, -32000, 'Server busy: maximum sessions reached', 503);
+}
+export function respondBadRequest(res) {
+    sendJsonRpcError(res, -32000, 'Bad Request: Missing session ID or not an initialize request', 400);
+}

package/dist/http/mcp-session-transport-init.d.ts

@@ -0,0 +1,7 @@
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import type { SlotTracker } from './mcp-session-slots.js';
+import type { createTimeoutController } from './mcp-session-transport.js';
+export declare function createSessionTransport({ tracker, timeoutController, }: {
+    tracker: SlotTracker;
+    timeoutController: ReturnType<typeof createTimeoutController>;
+}): StreamableHTTPServerTransport;

package/dist/http/mcp-session-transport-init.js

@@ -0,0 +1,41 @@
+import { randomUUID } from 'node:crypto';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { config } from '../config/index.js';
+import { logWarn } from '../services/logger.js';
+import { getErrorMessage } from '../utils/error-details.js';
+function startSessionInitTimeout({ transport, tracker, clearInitTimeout, timeoutMs, }) {
+    if (timeoutMs <= 0)
+        return null;
+    const timeout = setTimeout(() => {
+        clearInitTimeout();
+        if (tracker.isInitialized())
+            return;
+        tracker.releaseSlot();
+        void transport.close().catch((error) => {
+            logWarn('Failed to close stalled session', {
+                error: getErrorMessage(error),
+            });
+        });
+        logWarn('Session initialization timed out', { timeoutMs });
+    }, timeoutMs);
+    timeout.unref();
+    return timeout;
+}
+export function createSessionTransport({ tracker, timeoutController, }) {
+    const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: () => randomUUID(),
+    });
+    transport.onclose = () => {
+        timeoutController.clear();
+        if (!tracker.isInitialized()) {
+            tracker.releaseSlot();
+        }
+    };
+    timeoutController.set(startSessionInitTimeout({
+        transport,
+        tracker,
+        clearInitTimeout: timeoutController.clear,
+        timeoutMs: config.server.sessionInitTimeoutMs,
+    }));
+    return transport;
+}

package/dist/http/mcp-session-transport.d.ts

@@ -0,0 +1,7 @@
+import type { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+export declare function createTimeoutController(): {
+    clear: () => void;
+    set: (timeout: NodeJS.Timeout | null) => void;
+};
+export declare function createTransportAdapter(transport: StreamableHTTPServerTransport): Transport;

package/dist/http/mcp-session-transport.js

@@ -0,0 +1,57 @@
+export function createTimeoutController() {
+    let initTimeout = null;
+    return {
+        clear: () => {
+            if (!initTimeout)
+                return;
+            clearTimeout(initTimeout);
+            initTimeout = null;
+        },
+        set: (timeout) => {
+            initTimeout = timeout;
+        },
+    };
+}
+export function createTransportAdapter(transport) {
+    const adapter = buildTransportAdapter(transport);
+    attachTransportAccessors(adapter, transport);
+    return adapter;
+}
+function buildTransportAdapter(transport) {
+    return {
+        start: () => transport.start(),
+        send: (message, options) => transport.send(message, options),
+        close: () => transport.close(),
+    };
+}
+function createAccessorDescriptor(getter, setter) {
+    return {
+        get: getter,
+        ...(setter ? { set: setter } : {}),
+        enumerable: true,
+        configurable: true,
+    };
+}
+function createOnCloseDescriptor(transport) {
+    return createAccessorDescriptor(() => transport.onclose, (handler) => {
+        transport.onclose = handler;
+    });
+}
+function createOnErrorDescriptor(transport) {
+    return createAccessorDescriptor(() => transport.onerror, (handler) => {
+        transport.onerror = handler;
+    });
+}
+function createOnMessageDescriptor(transport) {
+    return createAccessorDescriptor(() => transport.onmessage, (handler) => {
+        transport.onmessage = handler;
+    });
+}
+function attachTransportAccessors(adapter, transport) {
+    Object.defineProperties(adapter, {
+        onclose: createOnCloseDescriptor(transport),
+        onerror: createOnErrorDescriptor(transport),
+        onmessage: createOnMessageDescriptor(transport),
+        sessionId: createAccessorDescriptor(() => transport.sessionId),
+    });
+}

package/dist/http/mcp-session-types.d.ts

@@ -0,0 +1,5 @@
+import type { SessionStore } from './sessions.js';
+export interface McpSessionOptions {
+    readonly sessionStore: SessionStore;
+    readonly maxSessions: number;
+}

package/dist/http/mcp-session-types.js

@@ -0,0 +1 @@
+export {};

package/dist/http/mcp-session.d.ts

@@ -1,10 +1,10 @@
-import type { Request, Response } from 'express';
-import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import type { Response } from 'express';
+import type { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import type { McpRequestBody } from '../config/types/runtime.js';
-import { type SessionStore } from './sessions.js';
-export interface McpSessionOptions {
-    readonly sessionStore: SessionStore;
-    readonly maxSessions: number;
-}
-export declare function resolveTransportForPost(_req: Request, res: Response, body: McpRequestBody, sessionId: string | undefined, options: McpSessionOptions): Promise<StreamableHTTPServerTransport | null>;
-export declare function evictExpiredSessions(store: SessionStore): number;
+import type { McpSessionOptions } from './mcp-session-types.js';
+export declare function resolveTransportForPost({ res, body, sessionId, options, }: {
+    res: Response;
+    body: McpRequestBody;
+    sessionId: string | undefined;
+    options: McpSessionOptions;
+}): Promise<StreamableHTTPServerTransport | null>;