nitrostack 1.0.18 → 1.0.20

package/dist/core/transports/streamable-http.js

@@ -0,0 +1,691 @@
+/**
+ * Streamable HTTP Transport for MCP
+ *
+ * Implements the MCP Streamable HTTP transport specification (2025-06-18).
+ * https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http
+ *
+ * Features:
+ * - Single MCP endpoint supporting both POST and GET
+ * - POST for sending messages to server
+ * - GET for SSE streams from server
+ * - Session management with Mcp-Session-Id header
+ * - Resumability support with Last-Event-ID
+ * - Multiple concurrent client connections
+ * - Protocol version header support
+ */
+import express from 'express';
+import { v4 as uuidv4 } from 'uuid';
+/**
+ * Streamable HTTP Transport
+ * Implements MCP Streamable HTTP specification
+ */
+export class StreamableHttpTransport {
+    app;
+    server = null;
+    sessions = new Map();
+    activeStreams = new Map(); // For sessionless mode
+    messageHandler;
+    closeHandler;
+    errorHandler;
+    options;
+    sessionCleanupInterval;
+    constructor(options = {}) {
+        this.options = {
+            port: options.port || 3000,
+            host: options.host || 'localhost',
+            endpoint: options.endpoint || '/mcp',
+            enableSessions: options.enableSessions === true, // Default to false for simpler clients
+            sessionTimeout: options.sessionTimeout || 30 * 60 * 1000, // 30 minutes
+            enableCors: options.enableCors !== false, // Default to true
+        };
+        this.app = options.app || express();
+        // CRITICAL: Disable Express's automatic OPTIONS handling
+        this.app.set('x-powered-by', false);
+        this.setupMiddleware();
+        this.setupRoutes();
+        this.startSessionCleanup();
+    }
+    /**
+     * Setup Express middleware
+     */
+    setupMiddleware() {
+        // CORS (if enabled) - MUST be the very first middleware, handles ALL requests
+        if (this.options.enableCors) {
+            // Add CORS headers to ALL responses
+            this.app.use((req, res, next) => {
+                res.setHeader('Access-Control-Allow-Origin', '*');
+                res.setHeader('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS');
+                res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Accept, Authorization, Mcp-Session-Id, MCP-Protocol-Version, Last-Event-ID');
+                res.setHeader('Access-Control-Expose-Headers', 'Mcp-Session-Id');
+                // Handle OPTIONS immediately
+                if (req.method === 'OPTIONS') {
+                    res.status(200).end();
+                    return;
+                }
+                next();
+            });
+        }
+        // Security: Validate Origin header to prevent DNS rebinding attacks (skip if CORS enabled)
+        if (!this.options.enableCors) {
+            this.app.use((req, res, next) => {
+                const origin = req.get('Origin');
+                const host = req.get('Host');
+                if (origin && host) {
+                    const originHost = new URL(origin).host;
+                    if (originHost !== host && !this.isLocalhost(originHost)) {
+                        res.status(403).json({ error: 'Invalid Origin header' });
+                        return;
+                    }
+                }
+                next();
+            });
+        }
+        // JSON parsing
+        this.app.use(express.json());
+    }
+    /**
+     * Setup MCP endpoint routes
+     */
+    setupRoutes() {
+        const endpoint = this.options.endpoint;
+        // IMPORTANT: Add OPTIONS handlers FIRST to override Express's auto-OPTIONS
+        if (this.options.enableCors) {
+            // Main endpoint OPTIONS
+            this.app.options(endpoint, (req, res) => {
+                res.sendStatus(200);
+            });
+            // SSE endpoint OPTIONS
+            this.app.options(`${endpoint}/sse`, (req, res) => {
+                res.sendStatus(200);
+            });
+            // Message endpoint OPTIONS
+            this.app.options(`${endpoint}/message`, (req, res) => {
+                res.sendStatus(200);
+            });
+        }
+        // MCP Endpoint - POST for sending messages to server
+        this.app.post(endpoint, async (req, res) => {
+            await this.handlePost(req, res);
+        });
+        // MCP Endpoint - GET for SSE streams
+        this.app.get(endpoint, (req, res) => {
+            this.handleGet(req, res);
+        });
+        // MCP Endpoint - DELETE for session termination
+        this.app.delete(endpoint, (req, res) => {
+            this.handleDelete(req, res);
+        });
+        // Backward compatibility: /sse endpoint (alias for GET /mcp)
+        this.app.get(`${endpoint}/sse`, (req, res) => {
+            this.handleGet(req, res);
+        });
+        // Backward compatibility: /message endpoint (alias for POST /mcp)
+        this.app.post(`${endpoint}/message`, async (req, res) => {
+            // Simple message handler that doesn't require all the session/SSE logic
+            try {
+                const message = req.body;
+                if (!message || !message.jsonrpc) {
+                    res.status(400).json({ error: 'Invalid JSON-RPC message' });
+                    return;
+                }
+                // Pass to message handler
+                if (this.messageHandler) {
+                    await this.messageHandler(message);
+                }
+                res.json({ status: 'received' });
+            }
+            catch (error) {
+                console.error('Error handling message:', error);
+                res.status(500).json({ error: error.message });
+            }
+        });
+        // Info endpoint for GET on /message
+        this.app.get(`${endpoint}/message`, (req, res) => {
+            res.json({
+                endpoint: `${endpoint}/message`,
+                method: 'POST',
+                description: 'Send JSON-RPC messages to the MCP server',
+                usage: 'POST with Content-Type: application/json',
+                example: {
+                    jsonrpc: '2.0',
+                    method: 'initialize',
+                    params: {
+                        protocolVersion: '2024-11-05',
+                        capabilities: {},
+                        clientInfo: { name: 'test-client', version: '1.0.0' }
+                    },
+                    id: 1
+                }
+            });
+        });
+        // Health check
+        this.app.get(`${endpoint}/health`, (req, res) => {
+            res.json({
+                status: 'ok',
+                transport: 'streamable-http',
+                version: '2025-06-18',
+                sessions: this.sessions.size,
+                uptime: process.uptime(),
+            });
+        });
+    }
+    /**
+     * Handle POST requests (client sending messages to server)
+     */
+    async handlePost(req, res) {
+        try {
+            const message = req.body;
+            const sessionId = req.get('Mcp-Session-Id');
+            const accept = req.get('Accept') || '';
+            // Validate JSON-RPC message
+            if (!message || !message.jsonrpc || message.jsonrpc !== '2.0') {
+                res.status(400).json({
+                    jsonrpc: '2.0',
+                    error: { code: -32600, message: 'Invalid JSON-RPC message' }
+                });
+                return;
+            }
+            // Check session
+            if (this.options.enableSessions && sessionId) {
+                const session = this.sessions.get(sessionId);
+                if (!session) {
+                    res.status(404).json({
+                        jsonrpc: '2.0',
+                        error: { code: -32001, message: 'Session not found' }
+                    });
+                    return;
+                }
+                session.lastActivity = Date.now();
+            }
+            // Handle different message types
+            const messageType = this.getMessageType(message);
+            if (messageType === 'notification' || messageType === 'response') {
+                // Notification or Response: Return 202 Accepted
+                if (this.messageHandler) {
+                    await this.messageHandler(message);
+                }
+                res.status(202).send();
+                return;
+            }
+            if (messageType === 'request') {
+                // Request: Accept header check (be lenient - if not specified, assume they want SSE)
+                const supportsSSE = !accept || accept.includes('text/event-stream') || accept.includes('*/*');
+                const supportsJSON = accept.includes('application/json');
+                // Pass to message handler
+                if (this.messageHandler) {
+                    await this.messageHandler(message);
+                }
+                // For InitializeRequest, create session if enabled
+                if (this.isInitializeRequest(message)) {
+                    if (this.options.enableSessions && !sessionId) {
+                        const newSessionId = this.generateSessionId();
+                        const session = {
+                            id: newSessionId,
+                            streams: new Map(),
+                            lastActivity: Date.now(),
+                            messageQueue: [],
+                            eventIdCounter: 0,
+                        };
+                        this.sessions.set(newSessionId, session);
+                        res.setHeader('Mcp-Session-Id', newSessionId);
+                    }
+                }
+                // For SSE: Just acknowledge receipt, response will come via existing SSE stream
+                if (supportsSSE) {
+                    // Accept the request
+                    res.status(202).send();
+                    // Response will be sent via the send() method to existing SSE streams
+                }
+                else {
+                    // Single JSON response (less common)
+                    res.setHeader('Content-Type', 'application/json');
+                    // Response will be sent by the protocol layer
+                    res._mcpWaitingForResponse = true;
+                    res._mcpRequestId = message.id;
+                }
+            }
+        }
+        catch (error) {
+            console.error('POST error:', error);
+            res.status(500).json({
+                jsonrpc: '2.0',
+                error: { code: -32603, message: 'Internal error' }
+            });
+        }
+    }
+    /**
+     * Handle GET requests (client opening SSE stream)
+     */
+    handleGet(req, res) {
+        const sessionId = req.get('Mcp-Session-Id');
+        const lastEventId = req.get('Last-Event-ID');
+        const accept = req.get('Accept') || '';
+        // Check if client explicitly doesn't want SSE (e.g., asking for JSON only)
+        const rejectsSSE = accept && !accept.includes('*/*') && !accept.includes('text/event-stream') && accept.length > 0;
+        if (rejectsSSE) {
+            res.status(405).send('Method Not Allowed - This endpoint provides Server-Sent Events');
+            return;
+        }
+        // Check session
+        let session;
+        if (this.options.enableSessions) {
+            if (!sessionId) {
+                res.status(400).json({ error: 'Mcp-Session-Id required' });
+                return;
+            }
+            session = this.sessions.get(sessionId);
+            if (!session) {
+                res.status(404).json({ error: 'Session not found' });
+                return;
+            }
+            session.lastActivity = Date.now();
+        }
+        // Setup SSE
+        res.setHeader('Content-Type', 'text/event-stream');
+        res.setHeader('Cache-Control', 'no-cache');
+        res.setHeader('Connection', 'keep-alive');
+        res.flushHeaders();
+        // Create stream
+        const streamId = uuidv4();
+        const stream = {
+            id: streamId,
+            response: res,
+            eventIdCounter: 0,
+            closed: false,
+        };
+        // Send endpoint event immediately (required by MCP SDK)
+        // This tells the client where to POST messages
+        const endpointUrl = `${req.protocol}://${req.get('host')}${this.options.endpoint}`;
+        try {
+            res.write(`event: endpoint\n`);
+            res.write(`data: ${endpointUrl}\n\n`);
+        }
+        catch (error) {
+            console.error('Error sending endpoint event:', error);
+            stream.closed = true;
+            return;
+        }
+        // Add to session or activeStreams
+        if (session) {
+            session.streams.set(streamId, stream);
+            // Resume support: replay messages after lastEventId
+            if (lastEventId) {
+                this.replayMessages(session, stream, lastEventId);
+            }
+        }
+        else {
+            // Sessionless mode: track in activeStreams
+            this.activeStreams.set(streamId, stream);
+        }
+        // Handle client disconnect
+        req.on('close', () => {
+            stream.closed = true;
+            if (session) {
+                session.streams.delete(streamId);
+            }
+            else {
+                this.activeStreams.delete(streamId);
+            }
+        });
+        // Send ping every 30 seconds to keep connection alive
+        const pingInterval = setInterval(() => {
+            if (stream.closed) {
+                clearInterval(pingInterval);
+                return;
+            }
+            try {
+                res.write(': ping\n\n');
+            }
+            catch (error) {
+                clearInterval(pingInterval);
+                stream.closed = true;
+            }
+        }, 30000);
+    }
+    /**
+     * Handle DELETE requests (session termination)
+     */
+    handleDelete(req, res) {
+        const sessionId = req.get('Mcp-Session-Id');
+        if (!sessionId) {
+            res.status(400).json({ error: 'Mcp-Session-Id required' });
+            return;
+        }
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            res.status(404).json({ error: 'Session not found' });
+            return;
+        }
+        // Close all streams
+        for (const stream of session.streams.values()) {
+            try {
+                stream.response.end();
+                stream.closed = true;
+            }
+            catch (error) {
+                // Ignore
+            }
+        }
+        // Remove session
+        this.sessions.delete(sessionId);
+        res.status(200).json({ status: 'session terminated' });
+    }
+    /**
+     * Start SSE stream for a request
+     */
+    async startSSEStream(req, res, request, sessionId) {
+        // Setup SSE
+        res.setHeader('Content-Type', 'text/event-stream');
+        res.setHeader('Cache-Control', 'no-cache');
+        res.setHeader('Connection', 'keep-alive');
+        res.flushHeaders();
+        // Create stream
+        const streamId = uuidv4();
+        const stream = {
+            id: streamId,
+            response: res,
+            eventIdCounter: 0,
+            closed: false,
+        };
+        // Store stream reference for this request
+        req._mcpStreamId = streamId;
+        req._mcpStream = stream;
+        // Add to session or activeStreams
+        if (sessionId) {
+            const session = this.sessions.get(sessionId);
+            if (session) {
+                session.streams.set(streamId, stream);
+            }
+        }
+        else {
+            // Sessionless mode: track in activeStreams
+            this.activeStreams.set(streamId, stream);
+        }
+        // Handle client disconnect
+        req.on('close', () => {
+            stream.closed = true;
+            if (sessionId) {
+                const session = this.sessions.get(sessionId);
+                if (session) {
+                    session.streams.delete(streamId);
+                }
+            }
+            else {
+                this.activeStreams.delete(streamId);
+            }
+        });
+    }
+    /**
+     * Send message to client(s)
+     */
+    async send(message) {
+        // Find target session/stream
+        // For responses, send to the stream that made the request
+        if (this.isResponse(message)) {
+            const response = message;
+            await this.sendToRequestStream(response);
+            return;
+        }
+        // For requests and notifications, send to all active streams
+        // First, send to session-based streams
+        for (const session of this.sessions.values()) {
+            for (const stream of session.streams.values()) {
+                if (!stream.closed) {
+                    await this.sendToStream(stream, message, session);
+                }
+            }
+        }
+        // Then, send to sessionless streams
+        for (const stream of this.activeStreams.values()) {
+            if (!stream.closed) {
+                await this.sendToStreamSessionless(stream, message);
+            }
+        }
+    }
+    /**
+     * Send message to a specific stream
+     */
+    async sendToStream(stream, message, session) {
+        try {
+            const eventId = `${session.id}-${++stream.eventIdCounter}`;
+            const data = JSON.stringify(message);
+            stream.response.write(`id: ${eventId}\n`);
+            stream.response.write(`data: ${data}\n\n`);
+            // Store in queue for resumability
+            session.messageQueue.push({
+                message,
+                streamId: stream.id,
+                eventId,
+            });
+        }
+        catch (error) {
+            console.error('Error sending to stream:', error);
+            stream.closed = true;
+        }
+    }
+    /**
+     * Send response to the stream that made the request
+     */
+    async sendToRequestStream(response) {
+        // Find the stream associated with this request
+        // For session-based streams
+        for (const session of this.sessions.values()) {
+            for (const stream of session.streams.values()) {
+                if (!stream.closed) {
+                    await this.sendToStream(stream, response, session);
+                    // Close stream after sending response (per spec)
+                    setTimeout(() => {
+                        try {
+                            stream.response.end();
+                            stream.closed = true;
+                            session.streams.delete(stream.id);
+                        }
+                        catch (error) {
+                            // Ignore
+                        }
+                    }, 100);
+                }
+            }
+        }
+        // For sessionless streams
+        for (const stream of this.activeStreams.values()) {
+            if (!stream.closed) {
+                await this.sendToStreamSessionless(stream, response);
+                // Close stream after sending response (per spec)
+                setTimeout(() => {
+                    try {
+                        stream.response.end();
+                        stream.closed = true;
+                        this.activeStreams.delete(stream.id);
+                    }
+                    catch (error) {
+                        // Ignore
+                    }
+                }, 100);
+            }
+        }
+    }
+    /**
+     * Send message to a sessionless stream
+     */
+    async sendToStreamSessionless(stream, message) {
+        try {
+            const eventId = `${stream.id}-${++stream.eventIdCounter}`;
+            const data = JSON.stringify(message);
+            stream.response.write(`id: ${eventId}\n`);
+            stream.response.write(`data: ${data}\n\n`);
+        }
+        catch (error) {
+            console.error('Error sending to sessionless stream:', error);
+            stream.closed = true;
+            this.activeStreams.delete(stream.id);
+        }
+    }
+    /**
+     * Replay messages for resumability
+     */
+    replayMessages(session, stream, lastEventId) {
+        const messages = session.messageQueue.filter((msg) => msg.streamId === stream.id && msg.eventId > lastEventId);
+        for (const { message, eventId } of messages) {
+            try {
+                const data = JSON.stringify(message);
+                stream.response.write(`id: ${eventId}\n`);
+                stream.response.write(`data: ${data}\n\n`);
+            }
+            catch (error) {
+                console.error('Error replaying message:', error);
+                break;
+            }
+        }
+    }
+    /**
+     * Start the HTTP server
+     */
+    async start() {
+        if (this.server) {
+            await this.close();
+        }
+        return new Promise((resolve, reject) => {
+            const errorHandler = (error) => {
+                console.error(`Failed to start Streamable HTTP transport: ${error.message}`);
+                this.server = null;
+                reject(error);
+            };
+            try {
+                const server = this.app.listen(this.options.port, this.options.host);
+                server.once('error', errorHandler);
+                server.once('listening', () => {
+                    server.removeListener('error', errorHandler);
+                    server.on('error', (error) => {
+                        if (this.errorHandler) {
+                            this.errorHandler(error);
+                        }
+                    });
+                    this.server = server;
+                    console.error(`🌐 MCP Streamable HTTP transport listening on http://${this.options.host}:${this.options.port}${this.options.endpoint}`);
+                    console.error(`   Protocol: MCP 2025-06-18`);
+                    console.error(`   Sessions: ${this.options.enableSessions ? 'enabled' : 'disabled'}`);
+                    resolve();
+                });
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+    }
+    /**
+     * Close the transport
+     */
+    async close() {
+        // Clear session cleanup
+        if (this.sessionCleanupInterval) {
+            clearInterval(this.sessionCleanupInterval);
+        }
+        // Close all sessions
+        for (const session of this.sessions.values()) {
+            for (const stream of session.streams.values()) {
+                try {
+                    stream.response.end();
+                    stream.closed = true;
+                }
+                catch (error) {
+                    // Ignore
+                }
+            }
+        }
+        this.sessions.clear();
+        // Close HTTP server
+        if (this.server) {
+            return new Promise((resolve) => {
+                const server = this.server;
+                this.server = null;
+                server.closeAllConnections?.();
+                server.close((err) => {
+                    if (err) {
+                        console.error('HTTP server close error:', err.message);
+                    }
+                    if (this.closeHandler) {
+                        this.closeHandler();
+                    }
+                    resolve();
+                });
+            });
+        }
+        if (this.closeHandler) {
+            this.closeHandler();
+        }
+    }
+    /**
+     * Set message handler
+     */
+    set onmessage(handler) {
+        this.messageHandler = handler;
+    }
+    /**
+     * Set close handler
+     */
+    set onclose(handler) {
+        this.closeHandler = handler;
+    }
+    /**
+     * Set error handler
+     */
+    set onerror(handler) {
+        this.errorHandler = handler;
+    }
+    /**
+     * Start session cleanup interval
+     */
+    startSessionCleanup() {
+        this.sessionCleanupInterval = setInterval(() => {
+            const now = Date.now();
+            for (const [sessionId, session] of this.sessions.entries()) {
+                if (now - session.lastActivity > this.options.sessionTimeout) {
+                    // Cleanup expired session
+                    for (const stream of session.streams.values()) {
+                        try {
+                            stream.response.end();
+                            stream.closed = true;
+                        }
+                        catch (error) {
+                            // Ignore
+                        }
+                    }
+                    this.sessions.delete(sessionId);
+                    console.error(`Session ${sessionId} expired and cleaned up`);
+                }
+            }
+        }, 60000); // Check every minute
+    }
+    /**
+     * Helper methods
+     */
+    generateSessionId() {
+        return uuidv4();
+    }
+    getMessageType(message) {
+        if ('method' in message && 'id' in message)
+            return 'request';
+        if ('result' in message || 'error' in message)
+            return 'response';
+        return 'notification';
+    }
+    isResponse(message) {
+        return 'result' in message || 'error' in message;
+    }
+    isInitializeRequest(message) {
+        return 'method' in message && message.method === 'initialize';
+    }
+    isLocalhost(host) {
+        // Extract hostname without port (host can be "localhost:3000")
+        const hostname = host.split(':')[0];
+        return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1';
+    }
+    /**
+     * Get the Express app (for adding custom routes)
+     */
+    getApp() {
+        return this.app;
+    }
+}
+//# sourceMappingURL=streamable-http.js.map