paygate-mcp 1.0.0 → 1.2.0

package/dist/session.d.ts

@@ -0,0 +1,91 @@
+/**
+ * SessionManager — MCP session tracking for Streamable HTTP transport.
+ *
+ * Manages:
+ *   - Session creation and lifecycle (Mcp-Session-Id)
+ *   - SSE connection tracking per session
+ *   - Server-to-client notification routing
+ *   - Session cleanup on DELETE or timeout
+ *
+ * Per MCP spec (2025-03-26):
+ *   - POST /mcp may return SSE or JSON
+ *   - GET /mcp opens SSE stream for server notifications
+ *   - DELETE /mcp terminates a session
+ *   - Mcp-Session-Id correlates all requests in a session
+ */
+import { ServerResponse } from 'http';
+import { JsonRpcResponse } from './types';
+export interface McpSession {
+    id: string;
+    createdAt: number;
+    lastActivityAt: number;
+    /** SSE connections for server-to-client notifications */
+    sseConnections: Set<ServerResponse>;
+    /** API key associated with this session (null if unauthenticated) */
+    apiKey: string | null;
+}
+export interface SessionManagerConfig {
+    /** Session timeout in ms. Default: 30 minutes. */
+    sessionTimeoutMs: number;
+    /** Max concurrent sessions. Default: 1000. */
+    maxSessions: number;
+    /** Max SSE connections per session. Default: 3. */
+    maxSsePerSession: number;
+}
+/**
+ * Write SSE headers to a response.
+ * Extra headers (e.g., Mcp-Session-Id) can be merged in.
+ */
+export declare function writeSseHeaders(res: ServerResponse, extraHeaders?: Record<string, string>): void;
+/**
+ * Write a JSON-RPC response as an SSE event.
+ */
+export declare function writeSseEvent(res: ServerResponse, data: JsonRpcResponse | object, eventType?: string): void;
+/**
+ * Write a keepalive comment to an SSE stream (prevents connection timeout).
+ */
+export declare function writeSseKeepAlive(res: ServerResponse): void;
+export declare class SessionManager {
+    private sessions;
+    private readonly config;
+    private cleanupInterval;
+    constructor(config?: Partial<SessionManagerConfig>);
+    /**
+     * Create a new session. Returns the session ID.
+     */
+    createSession(apiKey: string | null): string;
+    /**
+     * Get a session by ID. Returns null if not found or expired.
+     */
+    getSession(sessionId: string): McpSession | null;
+    /**
+     * Register an SSE connection for a session.
+     * Returns false if the session is at its SSE limit.
+     */
+    addSseConnection(sessionId: string, res: ServerResponse): boolean;
+    /**
+     * Send a server-initiated notification to all SSE connections in a session.
+     */
+    sendNotification(sessionId: string, notification: JsonRpcResponse | object): void;
+    /**
+     * Destroy a session, closing all SSE connections.
+     */
+    destroySession(sessionId: string): boolean;
+    /**
+     * Get active session count.
+     */
+    get sessionCount(): number;
+    /**
+     * Cleanup expired sessions.
+     */
+    private cleanup;
+    /**
+     * Evict the oldest session to make room for a new one.
+     */
+    private evictOldest;
+    /**
+     * Stop the session manager, clean up all sessions.
+     */
+    destroy(): void;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,MAAM,CAAC;AACtC,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAI1C,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,yDAAyD;IACzD,cAAc,EAAE,GAAG,CAAC,cAAc,CAAC,CAAC;IACpC,qEAAqE;IACrE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB;IACnC,kDAAkD;IAClD,gBAAgB,EAAE,MAAM,CAAC;IACzB,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAUD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,cAAc,EAAE,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAUhG;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,eAAe,GAAG,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAK3G;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI,CAE3D;AAID,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAiC;IACjD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuB;IAC9C,OAAO,CAAC,eAAe,CAAiC;gBAE5C,MAAM,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC;IAMlD;;OAEG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM;IAmB5C;;OAEG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAchD;;;OAGG;IACH,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO;IAkBjE;;OAEG;IACH,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,eAAe,GAAG,MAAM,GAAG,IAAI;IAcjF;;OAEG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAkB1C;;OAEG;IACH,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED;;OAEG;IACH,OAAO,CAAC,OAAO;IASf;;OAEG;IACH,OAAO,CAAC,WAAW;IAgBnB;;OAEG;IACH,OAAO,IAAI,IAAI;CAMhB"}

package/dist/session.js

@@ -0,0 +1,202 @@
+"use strict";
+/**
+ * SessionManager — MCP session tracking for Streamable HTTP transport.
+ *
+ * Manages:
+ *   - Session creation and lifecycle (Mcp-Session-Id)
+ *   - SSE connection tracking per session
+ *   - Server-to-client notification routing
+ *   - Session cleanup on DELETE or timeout
+ *
+ * Per MCP spec (2025-03-26):
+ *   - POST /mcp may return SSE or JSON
+ *   - GET /mcp opens SSE stream for server notifications
+ *   - DELETE /mcp terminates a session
+ *   - Mcp-Session-Id correlates all requests in a session
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionManager = void 0;
+exports.writeSseHeaders = writeSseHeaders;
+exports.writeSseEvent = writeSseEvent;
+exports.writeSseKeepAlive = writeSseKeepAlive;
+const crypto_1 = require("crypto");
+const DEFAULT_SESSION_CONFIG = {
+    sessionTimeoutMs: 30 * 60 * 1000, // 30 minutes
+    maxSessions: 1000,
+    maxSsePerSession: 3,
+};
+// ─── SSE Helpers ─────────────────────────────────────────────────────────────
+/**
+ * Write SSE headers to a response.
+ * Extra headers (e.g., Mcp-Session-Id) can be merged in.
+ */
+function writeSseHeaders(res, extraHeaders) {
+    res.writeHead(200, {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache, no-transform',
+        'Connection': 'keep-alive',
+        'X-Accel-Buffering': 'no', // Disable Nginx buffering
+        'Access-Control-Allow-Origin': '*',
+        'Access-Control-Expose-Headers': 'Mcp-Session-Id',
+        ...extraHeaders,
+    });
+}
+/**
+ * Write a JSON-RPC response as an SSE event.
+ */
+function writeSseEvent(res, data, eventType) {
+    if (eventType) {
+        res.write(`event: ${eventType}\n`);
+    }
+    res.write(`data: ${JSON.stringify(data)}\n\n`);
+}
+/**
+ * Write a keepalive comment to an SSE stream (prevents connection timeout).
+ */
+function writeSseKeepAlive(res) {
+    res.write(': keepalive\n\n');
+}
+// ─── SessionManager ──────────────────────────────────────────────────────────
+class SessionManager {
+    sessions = new Map();
+    config;
+    cleanupInterval;
+    constructor(config) {
+        this.config = { ...DEFAULT_SESSION_CONFIG, ...config };
+        // Cleanup expired sessions every 60 seconds
+        this.cleanupInterval = setInterval(() => this.cleanup(), 60_000);
+    }
+    /**
+     * Create a new session. Returns the session ID.
+     */
+    createSession(apiKey) {
+        // Enforce max sessions
+        if (this.sessions.size >= this.config.maxSessions) {
+            this.evictOldest();
+        }
+        const id = `mcp_sess_${(0, crypto_1.randomBytes)(16).toString('hex')}`;
+        const session = {
+            id,
+            createdAt: Date.now(),
+            lastActivityAt: Date.now(),
+            sseConnections: new Set(),
+            apiKey,
+        };
+        this.sessions.set(id, session);
+        return id;
+    }
+    /**
+     * Get a session by ID. Returns null if not found or expired.
+     */
+    getSession(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            return null;
+        // Check timeout
+        if (Date.now() - session.lastActivityAt > this.config.sessionTimeoutMs) {
+            this.destroySession(sessionId);
+            return null;
+        }
+        session.lastActivityAt = Date.now();
+        return session;
+    }
+    /**
+     * Register an SSE connection for a session.
+     * Returns false if the session is at its SSE limit.
+     */
+    addSseConnection(sessionId, res) {
+        const session = this.getSession(sessionId);
+        if (!session)
+            return false;
+        if (session.sseConnections.size >= this.config.maxSsePerSession) {
+            return false;
+        }
+        session.sseConnections.add(res);
+        // Clean up when the connection closes
+        res.on('close', () => {
+            session.sseConnections.delete(res);
+        });
+        return true;
+    }
+    /**
+     * Send a server-initiated notification to all SSE connections in a session.
+     */
+    sendNotification(sessionId, notification) {
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            return;
+        for (const res of session.sseConnections) {
+            try {
+                writeSseEvent(res, notification, 'message');
+            }
+            catch {
+                // Connection already closed
+                session.sseConnections.delete(res);
+            }
+        }
+    }
+    /**
+     * Destroy a session, closing all SSE connections.
+     */
+    destroySession(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            return false;
+        // Close all SSE connections
+        for (const res of session.sseConnections) {
+            try {
+                res.end();
+            }
+            catch {
+                // Already closed
+            }
+        }
+        session.sseConnections.clear();
+        this.sessions.delete(sessionId);
+        return true;
+    }
+    /**
+     * Get active session count.
+     */
+    get sessionCount() {
+        return this.sessions.size;
+    }
+    /**
+     * Cleanup expired sessions.
+     */
+    cleanup() {
+        const now = Date.now();
+        for (const [id, session] of this.sessions) {
+            if (now - session.lastActivityAt > this.config.sessionTimeoutMs) {
+                this.destroySession(id);
+            }
+        }
+    }
+    /**
+     * Evict the oldest session to make room for a new one.
+     */
+    evictOldest() {
+        let oldestId = null;
+        let oldestTime = Infinity;
+        for (const [id, session] of this.sessions) {
+            if (session.lastActivityAt < oldestTime) {
+                oldestTime = session.lastActivityAt;
+                oldestId = id;
+            }
+        }
+        if (oldestId) {
+            this.destroySession(oldestId);
+        }
+    }
+    /**
+     * Stop the session manager, clean up all sessions.
+     */
+    destroy() {
+        clearInterval(this.cleanupInterval);
+        for (const id of this.sessions.keys()) {
+            this.destroySession(id);
+        }
+    }
+}
+exports.SessionManager = SessionManager;
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paygate-mcp",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Pay-per-tool-call gating proxy for MCP servers. Wrap any MCP server with API key auth, per-tool pricing, rate limiting, and usage metering.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",