Add SSE transport message endpoint and HTTP-Streamable transport support (#15)

This adds two missing transport capabilities to mcp-front.

First, SSE servers can now expose message endpoints for request/response
patterns alongside their streaming connections. This was needed because
some MCP servers use dual endpoints - one for SSE streaming and another
for JSON-RPC requests.

Second, we now support HTTP-Streamable transport as specified in the MCP
spec. This transport uses a single endpoint that can return either JSON
responses or SSE streams depending on the Accept header. POST requests
handle tool calls and can stream responses, while GET requests establish
SSE connections for server-initiated messages.

Both transports maintain the same authentication and proxy behavior as
existing SSE support.

Author: dgellow

integration/config/config.sse-test.json

@@ -0,0 +1,22 @@
+{
+  "version": "v0.0.1-DEV_EDITION_EXPECT_CHANGES",
+  "proxy": {
+    "baseURL": "http://localhost:8080",
+    "addr": ":8080",
+    "name": "mcp-front-sse-test",
+    "auth": {
+      "kind": "bearerToken",
+      "tokens": {
+        "test-sse": [
+          "sse-test-token"
+        ]
+      }
+    }
+  },
+  "mcpServers": {
+    "test-sse": {
+      "transportType": "sse",
+      "url": "http://localhost:3001/sse"
+    }
+  }
+}

integration/config/config.streamable-test.json

@@ -0,0 +1,22 @@
+{
+  "version": "v0.0.1-DEV_EDITION_EXPECT_CHANGES",
+  "proxy": {
+    "baseURL": "http://localhost:8080",
+    "addr": ":8080",
+    "name": "mcp-front-streamable-test",
+    "auth": {
+      "kind": "bearerToken",
+      "tokens": {
+        "test-streamable": [
+          "streamable-test-token"
+        ]
+      }
+    }
+  },
+  "mcpServers": {
+    "test-streamable": {
+      "transportType": "streamable-http",
+      "url": "http://localhost:3002"
+    }
+  }
+}

integration/docker-compose.yml

@@ -14,3 +14,33 @@ services:
       interval: 5s
       timeout: 5s
       retries: 5
+  
+  test-sse-server:
+    image: node:20-alpine
+    command: node /app/mock-sse-server.js
+    ports:
+      - "3001:3001"
+    environment:
+      - PORT=3001
+    volumes:
+      - ./fixtures/mock-sse-server.js:/app/mock-sse-server.js
+    healthcheck:
+      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:3001"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+  
+  test-streamable-server:
+    image: node:20-alpine
+    command: node /app/mock-streamable-server.js
+    ports:
+      - "3002:3002"
+    environment:
+      - PORT=3002
+    volumes:
+      - ./fixtures/mock-streamable-server.js:/app/mock-streamable-server.js
+    healthcheck:
+      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:3002"]
+      interval: 5s
+      timeout: 5s
+      retries: 5

integration/fixtures/mock-sse-server.js

@@ -0,0 +1,130 @@
+const http = require('http');
+
+const PORT = process.env.PORT || 3001;
+
+// Simple mock SSE MCP server for testing
+const server = http.createServer((req, res) => {
+  console.log(`${req.method} ${req.url}`);
+  
+  if (req.url === '/' && req.method === 'GET') {
+    res.writeHead(200, { 'Content-Type': 'text/plain' });
+    res.end('Mock SSE MCP Server');
+  } else if (req.url === '/sse' && req.method === 'GET') {
+    // SSE endpoint
+    res.writeHead(200, {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      'Connection': 'keep-alive',
+      'Access-Control-Allow-Origin': '*'
+    });
+    
+    // Send initial endpoint message
+    res.write('data: {"jsonrpc":"2.0","method":"endpoint","params":{"type":"endpoint","url":"/message"}}\n\n');
+    
+    // Keep connection alive
+    const keepAlive = setInterval(() => {
+      res.write(':keepalive\n\n');
+    }, 30000);
+    
+    req.on('close', () => {
+      clearInterval(keepAlive);
+    });
+  } else if (req.url === '/message' && req.method === 'POST') {
+    // Message endpoint
+    let body = '';
+    req.on('data', chunk => {
+      body += chunk.toString();
+    });
+    req.on('end', () => {
+      try {
+        const request = JSON.parse(body);
+        console.log('Received request:', request);
+        
+        let response;
+        if (request.method === 'tools/list') {
+          response = {
+            jsonrpc: '2.0',
+            id: request.id,
+            result: {
+              tools: [
+                {
+                  name: 'echo_text',
+                  description: 'Echo the provided text',
+                  inputSchema: {
+                    type: 'object',
+                    properties: {
+                      text: { type: 'string' }
+                    },
+                    required: ['text']
+                  }
+                },
+                {
+                  name: 'sample_stream',
+                  description: 'Sample streaming tool',
+                  inputSchema: {
+                    type: 'object',
+                    properties: {}
+                  }
+                }
+              ]
+            }
+          };
+        } else if (request.method === 'tools/call') {
+          if (request.params.name === 'echo_text') {
+            response = {
+              jsonrpc: '2.0',
+              id: request.id,
+              result: {
+                toolResult: request.params.arguments.text
+              }
+            };
+          } else if (request.params.name === 'non_existent_tool_xyz') {
+            response = {
+              jsonrpc: '2.0',
+              id: request.id,
+              error: {
+                code: -32601,
+                message: 'Tool not found: ' + request.params.name
+              }
+            };
+          } else {
+            response = {
+              jsonrpc: '2.0',
+              id: request.id,
+              result: {
+                toolResult: 'Tool executed successfully'
+              }
+            };
+          }
+        } else {
+          response = {
+            jsonrpc: '2.0',
+            id: request.id,
+            result: {}
+          };
+        }
+        
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(response));
+      } catch (e) {
+        console.error('Error processing request:', e);
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+          jsonrpc: '2.0',
+          id: null,
+          error: {
+            code: -32700,
+            message: 'Parse error'
+          }
+        }));
+      }
+    });
+  } else {
+    res.writeHead(404, { 'Content-Type': 'text/plain' });
+    res.end('Not found');
+  }
+});
+
+server.listen(PORT, () => {
+  console.log(`Mock SSE MCP server listening on port ${PORT}`);
+});

integration/fixtures/mock-streamable-server.js

@@ -0,0 +1,174 @@
+const http = require('http');
+
+const PORT = process.env.PORT || 3002;
+
+// Mock HTTP-Streamable MCP server for testing
+const server = http.createServer((req, res) => {
+  console.log(`${req.method} ${req.url}`);
+  
+  if (req.method === 'GET' && req.headers.accept?.includes('text/event-stream')) {
+    // Handle GET requests for SSE streaming
+    // Return SSE stream
+    res.writeHead(200, {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      'Connection': 'keep-alive'
+    });
+    
+    // Send initial endpoint message (expected by test client)
+    res.write('data: {"jsonrpc":"2.0","method":"endpoint","params":{"type":"endpoint","url":"/message"}}\n\n');
+    
+    // Keep connection alive with periodic messages
+    const keepAlive = setInterval(() => {
+      res.write(':keepalive\n\n');
+    }, 30000);
+    
+    // Send some server-initiated messages
+    setTimeout(() => {
+      res.write('data: {"jsonrpc":"2.0","method":"notification","params":{"type":"server_info","version":"1.0"}}\n\n');
+    }, 1000);
+    
+    req.on('close', () => {
+      clearInterval(keepAlive);
+    });
+  } else if (req.url === '/' && req.method === 'GET') {
+    // Health check endpoint
+    res.writeHead(200, { 'Content-Type': 'text/plain' });
+    res.end('Mock Streamable MCP Server');
+  } else if (req.method === 'POST') {
+    // Handle POST requests (single endpoint for streamable)
+    let body = '';
+    req.on('data', chunk => {
+      body += chunk.toString();
+    });
+    req.on('end', () => {
+      try {
+        const request = JSON.parse(body);
+        console.log('Received request:', request);
+        
+        // Check Accept header to decide response type
+        const acceptHeader = req.headers.accept || '';
+        const wantsSSE = acceptHeader.includes('text/event-stream');
+        
+        if (request.method === 'tools/list') {
+          const response = {
+            jsonrpc: '2.0',
+            id: request.id,
+            result: {
+              tools: [
+                {
+                  name: 'get_time',
+                  description: 'Get the current time',
+                  inputSchema: {
+                    type: 'object',
+                    properties: {}
+                  }
+                },
+                {
+                  name: 'echo_streamable',
+                  description: 'Echo text back',
+                  inputSchema: {
+                    type: 'object',
+                    properties: {
+                      text: { type: 'string' }
+                    },
+                    required: ['text']
+                  }
+                }
+              ]
+            }
+          };
+          
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify(response));
+        } else if (request.method === 'tools/call') {
+          if (request.params.name === 'get_time') {
+            const response = {
+              jsonrpc: '2.0',
+              id: request.id,
+              result: {
+                toolResult: new Date().toISOString()
+              }
+            };
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify(response));
+          } else if (request.params.name === 'echo_streamable') {
+            if (wantsSSE) {
+              // Return SSE stream for this tool
+              res.writeHead(200, {
+                'Content-Type': 'text/event-stream',
+                'Cache-Control': 'no-cache',
+                'Connection': 'keep-alive'
+              });
+              
+              // Send multiple responses in SSE format
+              const messages = [
+                { jsonrpc: '2.0', id: request.id, result: { toolResult: `Echo: ${request.params.arguments.text}` } },
+                { jsonrpc: '2.0', method: 'notification', params: { message: 'Processing complete' } }
+              ];
+              
+              messages.forEach((msg, index) => {
+                setTimeout(() => {
+                  res.write(`data: ${JSON.stringify(msg)}\n\n`);
+                }, index * 100);
+              });
+              
+              setTimeout(() => {
+                res.end();
+              }, 300);
+            } else {
+              // Regular JSON response
+              const response = {
+                jsonrpc: '2.0',
+                id: request.id,
+                result: {
+                  toolResult: `Echo: ${request.params.arguments.text}`
+                }
+              };
+              res.writeHead(200, { 'Content-Type': 'application/json' });
+              res.end(JSON.stringify(response));
+            }
+          } else {
+            const response = {
+              jsonrpc: '2.0',
+              id: request.id,
+              error: {
+                code: -32601,
+                message: 'Tool not found'
+              }
+            };
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify(response));
+          }
+        } else {
+          // Default response for other methods
+          const response = {
+            jsonrpc: '2.0',
+            id: request.id,
+            result: {}
+          };
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify(response));
+        }
+      } catch (e) {
+        console.error('Error processing request:', e);
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+          jsonrpc: '2.0',
+          id: null,
+          error: {
+            code: -32700,
+            message: 'Parse error'
+          }
+        }));
+      }
+    });
+  } else {
+    res.writeHead(405, { 'Content-Type': 'text/plain' });
+    res.end('Method not allowed');
+  }
+});
+
+server.listen(PORT, () => {
+  console.log(`Mock Streamable MCP server listening on port ${PORT}`);
+});