chore: bump version to 1.5.0 and document stateless HTTP mode

Author: Robbie1977

LLM_GUIDANCE.md

@@ -355,6 +355,6 @@ For application development, use the `mcp` and `google-genai` libraries to conne
 
 Setup: `pip install google-genai mcp`
 
-Implementation: Use an `SSEClientTransport` to connect to the VFB URL, list its tools, and pass their schemas to the Gemini model as Function Declarations.
+Implementation: Use a streamable HTTP transport in JSON response mode (e.g. `enableJsonResponse: true`) to connect to the VFB URL, list its tools, and pass their schemas to the Gemini model as Function Declarations.
 
 This MCP enables powerful neuroscience research by providing programmatic access to one of the most comprehensive neuroanatomical databases available.

README.md

@@ -1,6 +1,6 @@
 # VFB3-MCP Server
 
-A Model Context Protocol (MCP) server for interacting with VirtualFlyBrain (VFB) APIs. This server provides tools to query VFB data, run queries, and search for terms.
+A Model Context Protocol (MCP) server for interacting with VirtualFlyBrain (VFB) APIs. This server provides tools to query VFB data, run queries, and search for terms. In HTTP mode it runs statelessly (no session tracking), so any replica can handle any request and standard load balancing works.
 
 ## 🚀 Quick Start
 
@@ -111,7 +111,7 @@ For application development, use the `mcp` and `google-genai` libraries to conne
 
 Setup: `pip install google-genai mcp`
 
-Implementation: Use an `SSEClientTransport` to connect to the VFB URL, list its tools, and pass their schemas to the Gemini model as Function Declarations.
+Implementation: Use a streamable HTTP transport in JSON response mode (e.g. `enableJsonResponse: true`) to connect to the VFB URL, list its tools, and pass their schemas to the Gemini model as Function Declarations.
 
 #### Testing the Connection
 

TECHNICAL.md

@@ -14,17 +14,18 @@ The VFB3-MCP server supports two operational modes:
 - Compatible with Claude Desktop local MCP configuration
 
 #### HTTP Mode (Production)
-- Express.js server with Server-Sent Events (SSE) for bidirectional communication
-- RESTful endpoints for MCP protocol
+- Express.js server with stateless JSON-over-HTTP request/response (no SSE)
+- RESTful endpoints for MCP protocol (POST / for MCP requests, GET/DELETE return 405 unless requesting HTML)
 - OAuth 2.0 metadata endpoints (returns 404 - no authentication required)
 - CORS enabled for web client access
 
 ### MCP Protocol Implementation
 
 - Built using the official `@modelcontextprotocol/sdk`
-- Express transport for HTTP mode with SSE
+- Express transport for HTTP mode using stateless JSON-over-HTTP (no SSE)
 - Stdio transport for local development
-- Session management with UUID-based session IDs
+- Stateless HTTP mode (no session tracking / no session IDs)
+- GA4 analytics use a stable server-side client ID in HTTP mode (no per-session IDs)
 
 ## Infrastructure
 
@@ -35,9 +36,9 @@ The VFB3-MCP server supports two operational modes:
 The production deployment runs on VFB's Rancher/Cattle Kubernetes infrastructure with:
 
 - **Protocol**: HTTPS with automatic SSL certificate management
-- **Transport**: Server-Sent Events (SSE) for real-time bidirectional communication
+- **Transport**: Stateless JSON-over-HTTP request/response (no SSE)
 - **Authentication**: Open server (no authentication required)
-- **Load Balancing**: Kubernetes service with automatic scaling
+- **Load Balancing**: Kubernetes service with automatic scaling (stateless; no sticky sessions required)
 - **Resource Limits**: 512Mi memory, 500m CPU
 - **Security**: Non-root user (UID 1000), read-only filesystem
 - **MCP Endpoint**: `/` (root path)
@@ -227,7 +228,7 @@ For application development, use the `mcp` and `google-genai` libraries to conne
 
 Setup: `pip install google-genai mcp`
 
-Implementation: Use an `SSEClientTransport` to connect to the VFB URL, list its tools, and pass their schemas to the Gemini model as Function Declarations.
+Implementation: Use a streamable HTTP transport in JSON response mode (e.g. `enableJsonResponse: true`) to connect to the VFB URL, list its tools, and pass their schemas to the Gemini model as Function Declarations.
 
 ## Security
 
@@ -255,7 +256,7 @@ While the server includes OAuth metadata endpoints for MCP SDK compatibility, au
 - **Console Output**: Structured logging to stdout/stderr
 - **Debug Mode**: Verbose logging with `MCP_DEBUG=true`
 - **Error Handling**: Comprehensive error logging with context
-- **Request Tracking**: Session and request ID logging
+- **Request Tracking**: Request ID logging (no session IDs in HTTP mode)
 
 ### Infrastructure Monitoring
 
@@ -271,7 +272,7 @@ While the server includes OAuth metadata endpoints for MCP SDK compatibility, au
 - **API Caching**: VFB provides cached endpoints for performance
 - **Connection Pooling**: Axios configuration for efficient HTTP requests
 - **Memory Management**: Node.js memory limits and garbage collection
-- **Concurrent Requests**: Support for multiple simultaneous MCP sessions
+- **Concurrent Requests**: Support for multiple simultaneous MCP requests (stateless)
 
 ### Scalability
 

examples.md

@@ -149,7 +149,7 @@ For application development, use the `mcp` and `google-genai` libraries to conne
 
 Setup: `pip install google-genai mcp`
 
-Implementation: Use an `SSEClientTransport` to connect to the VFB URL, list its tools, and pass their schemas to the Gemini model as Function Declarations.
+Implementation: Use a streamable HTTP transport in JSON response mode (e.g. `enableJsonResponse: true`) to connect to the VFB URL, list its tools, and pass their schemas to the Gemini model as Function Declarations.
 
 ## Docker Usage
 ```bash

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "vfb3-mcp",
-  "version": "1.4.4",
+  "version": "1.5.0",
   "description": "MCP server for VirtualFlyBrain API integration",
   "main": "index.js",
   "scripts": {

package.json

@@ -3,7 +3,7 @@
   "name": "org.virtualflybrain/vfb3-mcp",
   "title": "VirtualFlyBrain",
   "description": "MCP server for Drosophila neuroscience data from VirtualFlyBrain",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "websiteUrl": "https://virtualflybrain.org",
   "repository": {
     "url": "https://github.com/Robbie1977/VFB3-MCP",

server.json

@@ -6,14 +6,13 @@ import {
   ErrorCode,
   ListToolsRequestSchema,
   McpError,
-  isInitializeRequest,
 } from '@modelcontextprotocol/sdk/types.js';
 import axios from 'axios';
 import cors from 'cors';
 import express from 'express';
 import { randomUUID } from 'node:crypto';
 
-const VERSION = '1.4.4';
+const VERSION = '1.5.0';
 
 // GA4 Analytics configuration
 const GA_MEASUREMENT_ID = process.env.GA_MEASUREMENT_ID || 'G-K7DDZVVXM7';
@@ -636,16 +635,14 @@ function getHtmlPage(): string {
 
 async function runHttpMode() {
   const port = process.env.PORT || '3000';
-  console.error(`MCP Debug: Starting VFB3-MCP server v${VERSION} in HTTP mode on port ${port}`);
+  console.error(`MCP Debug: Starting VFB3-MCP server v${VERSION} in STATELESS HTTP mode on port ${port}`);
   console.error(`MCP Debug: GA4 analytics ${GA_ENABLED ? 'enabled' : 'disabled (set GA_MEASUREMENT_ID and GA_API_SECRET to enable)'}`);
+  console.error('MCP Debug: Stateless mode — no session tracking, safe for multi-replica deployment');
 
   const app = express();
   app.use(cors());
   app.use(express.json());
 
-  // Store active transports by session ID
-  const transports: Record<string, StreamableHTTPServerTransport> = {};
-
   // MCP Registry HTTP authentication endpoint
   app.get('/.well-known/mcp-registry-auth', (_req: any, res: any) => {
     const authProof = process.env.MCP_REGISTRY_AUTH;
@@ -656,101 +653,46 @@ async function runHttpMode() {
     }
   });
 
-  // Handle GET requests: browser HTML page or SSE streams
+  // Handle GET requests: browser HTML page (SSE not supported in stateless mode)
   app.get('/', async (req: any, res: any) => {
     // Serve HTML page for browser requests
     if (req.headers.accept && req.headers.accept.includes('text/html')) {
       res.send(getHtmlPage());
       return;
     }
 
-    // SSE stream for existing MCP sessions
-    const sessionId = req.headers['mcp-session-id'] as string | undefined;
-    if (!sessionId) {
-      res.status(400).json({
-        jsonrpc: '2.0',
-        error: { code: -32000, message: 'Bad Request: Missing session ID' },
-        id: null,
-      });
-      return;
-    }
-    if (!transports[sessionId]) {
-      // Session not found — return 404 per MCP spec so client re-initializes
-      res.status(404).json({
-        jsonrpc: '2.0',
-        error: { code: -32001, message: 'Session not found' },
-        id: null,
-      });
-      return;
-    }
-
-    const transport = transports[sessionId];
-    await transport.handleRequest(req, res);
+    // SSE streams are not supported in stateless mode
+    res.writeHead(405).end(JSON.stringify({
+      jsonrpc: '2.0',
+      error: { code: -32000, message: 'Method not allowed. SSE streams are not supported in stateless mode.' },
+      id: null,
+    }));
   });
 
-  // Handle POST requests: MCP JSON-RPC messages
+  // Handle POST requests: stateless — fresh server + transport per request
   app.post('/', async (req: any, res: any) => {
-    const sessionId = req.headers['mcp-session-id'] as string | undefined;
-
     try {
-      if (sessionId && transports[sessionId]) {
-        // Existing session — reuse transport
-        const transport = transports[sessionId];
-        await transport.handleRequest(req, res, req.body);
-        return;
-      }
-
-      // Session ID provided but not found — return 404 per MCP spec so client re-initializes
-      if (sessionId && !transports[sessionId]) {
-        res.status(404).json({
-          jsonrpc: '2.0',
-          error: { code: -32001, message: 'Session not found' },
-          id: null,
-        });
-        return;
-      }
-
-      // Check for initialization request (handles both single and batch messages)
-      const body = req.body;
-      const hasInitRequest = Array.isArray(body)
-        ? body.some((msg: unknown) => isInitializeRequest(msg))
-        : isInitializeRequest(body);
-
-      if (hasInitRequest) {
-        // New initialization request — create transport and server
-        const sessionIdHolder: { id?: string } = {};
-        const transport = new StreamableHTTPServerTransport({
-          sessionIdGenerator: () => randomUUID(),
-          onsessioninitialized: (sid: string) => {
-            console.error(`MCP Debug: Session initialized: ${sid}`);
-            transports[sid] = transport;
-            sessionIdHolder.id = sid;
-          },
-        });
-
-        transport.onclose = () => {
-          const sid = transport.sessionId;
-          if (sid && transports[sid]) {
-            console.error(`MCP Debug: Session closed: ${sid}`);
-            delete transports[sid];
-          }
-        };
-
-        // Connect a new MCP server to this transport
-        const server = createServer(sessionIdHolder);
-        await server.connect(transport);
+      // Create a fresh server and transport for every request.
+      // sessionIdGenerator: undefined = stateless mode — no session ID is
+      // generated, returned, or validated. Any replica can handle any request.
+      const server = createServer();
+      const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: undefined,
+        enableJsonResponse: true,
+      });
 
-        // Handle the initialization request
-        await transport.handleRequest(req, res, req.body);
-        return;
-      }
+      transport.onerror = (error) => {
+        console.error('MCP transport error:', error);
+      };
 
-      // Invalid request — no valid session and not an initialize request
-      res.status(400).json({
-        jsonrpc: '2.0',
-        error: { code: -32000, message: 'Bad Request: No valid session ID provided' },
-        id: null,
+      // Clean up when the HTTP connection closes
+      res.on('close', () => {
+        transport.close();
+        server.close();
       });
+
+      await server.connect(transport);
+      await transport.handleRequest(req, res, req.body);
     } catch (error) {
       console.error('MCP Debug: Error handling POST request:', error);
       if (!res.headersSent) {
@@ -763,36 +705,13 @@ async function runHttpMode() {
     }
   });
 
-  // Handle DELETE requests: session termination
-  app.delete('/', async (req: any, res: any) => {
-    const sessionId = req.headers['mcp-session-id'] as string | undefined;
-    if (!sessionId) {
-      res.status(400).json({
-        jsonrpc: '2.0',
-        error: { code: -32000, message: 'Bad Request: Missing session ID' },
-        id: null,
-      });
-      return;
-    }
-    if (!transports[sessionId]) {
-      // Session not found — return 404 per MCP spec so client re-initializes
-      res.status(404).json({
-        jsonrpc: '2.0',
-        error: { code: -32001, message: 'Session not found' },
-        id: null,
-      });
-      return;
-    }
-
-    try {
-      const transport = transports[sessionId];
-      await transport.handleRequest(req, res);
-    } catch (error) {
-      console.error('MCP Debug: Error handling DELETE request:', error);
-      if (!res.headersSent) {
-        res.status(500).send('Error processing session termination');
-      }
-    }
+  // DELETE not supported in stateless mode (no sessions to terminate)
+  app.delete('/', async (_req: any, res: any) => {
+    res.writeHead(405).end(JSON.stringify({
+      jsonrpc: '2.0',
+      error: { code: -32000, message: 'Method not allowed. Session termination is not supported in stateless mode.' },
+      id: null,
+    }));
   });
 
   app.listen(parseInt(port), () => {
@@ -814,4 +733,4 @@ if (mode === 'http') {
   runHttpMode().catch(console.error);
 } else {
   runStdioMode().catch(console.error);
-}
+}