Add SSE transport support for MCP protocol

- Create MCP server with executeQuery and listGraphs tools
- Add GET /api/sse endpoint for SSE connections
- Add POST /api/messages endpoint for client messages
- Update documentation with SSE configuration example

Co-authored-by: gkorland <753206+gkorland@users.noreply.github.com>

README.md

@@ -66,15 +66,41 @@ npm start
 
 ## API Endpoints
 
+### REST API Endpoints
+
 * `GET /api/mcp/metadata`: Get metadata about the FalkorDB instance and available capabilities
 * `POST /api/mcp/context`: Execute queries against FalkorDB
 * `GET /api/mcp/health`: Check server health
 * `GET /api/mcp/graphs`: Returns the list of Graphs
-* 
+
+### MCP Protocol Endpoints (SSE Transport)
+
+* `GET /api/sse`: Server-Sent Events endpoint for MCP protocol connections
+* `POST /api/messages`: Message endpoint for MCP protocol communication
 
 ## MCP Configuration
 
-To use this server with MCP clients, you can add it to your MCP configuration:
+### Using SSE Transport (Recommended for Remote Servers)
+
+For MCP clients that support HTTP/SSE transport (like Cline), configure as follows:
+
+```json
+{
+  "mcpServers": {
+    "falkordb": {
+      "disabled": false,
+      "autoApprove": [],
+      "timeout": 60,
+      "url": "http://localhost:3000/api/sse",
+      "transportType": "http"
+    }
+  }
+}
+```
+
+### Using Docker with stdio Transport
+
+To use this server with MCP clients via stdio:
 
 ```json
 {
@@ -95,7 +121,9 @@ To use this server with MCP clients, you can add it to your MCP configuration:
 }
 ```
 
-For client-side configuration:
+### REST API Configuration
+
+For client-side REST API configuration:
 
 ```json
 {

src/index.ts

@@ -1,6 +1,7 @@
 import express from 'express';
 import { config } from './config';
 import { mcpRoutes } from './routes/mcp.routes';
+import { sseRoutes } from './routes/sse.routes';
 import { authenticateMCP } from './middleware/auth.middleware';
 import { falkorDBService } from './services/falkordb.service';
 
@@ -14,6 +15,9 @@ app.use(express.urlencoded({ extended: true }));
 // Apply authentication to MCP routes
 app.use('/api/mcp', authenticateMCP, mcpRoutes);
 
+// SSE routes for MCP protocol (no authentication for SSE transport)
+app.use('/api', sseRoutes);
+
 // Basic routes
 app.get('/', (req, res) => {
   res.json({

src/routes/sse.routes.ts

@@ -0,0 +1,72 @@
+import { Router, Request, Response } from 'express';
+import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
+import { createMCPServer } from '../services/mcp.server';
+
+const router = Router();
+
+// Store active SSE transports by session ID
+const transports: { [sessionId: string]: SSEServerTransport } = {};
+
+/**
+ * SSE endpoint for MCP connections
+ * This establishes the Server-Sent Events connection for the MCP protocol
+ */
+router.get('/sse', async (req: Request, res: Response) => {
+  try {
+    // Create a new SSE transport
+    const transport = new SSEServerTransport('/api/messages', res);
+    const sessionId = transport.sessionId;
+
+    // Store the transport
+    transports[sessionId] = transport;
+
+    // Clean up when the connection closes
+    res.on('close', () => {
+      delete transports[sessionId];
+      console.log(`SSE connection closed for session: ${sessionId}`);
+    });
+
+    // Create a new MCP server instance for this connection
+    const server = createMCPServer();
+
+    // Connect the server to the transport
+    await server.connect(transport);
+
+    console.log(`SSE connection established for session: ${sessionId}`);
+  } catch (error) {
+    console.error('Error establishing SSE connection:', error);
+    if (!res.headersSent) {
+      res.status(500).json({ error: 'Failed to establish SSE connection' });
+    }
+  }
+});
+
+/**
+ * POST endpoint for MCP messages
+ * This receives messages from the MCP client
+ */
+router.post('/messages', async (req: Request, res: Response) => {
+  try {
+    const sessionId = req.query.sessionId as string;
+
+    if (!sessionId) {
+      return res.status(400).json({ error: 'sessionId query parameter is required' });
+    }
+
+    const transport = transports[sessionId];
+
+    if (!transport) {
+      return res.status(404).json({ error: 'No active session found for the provided sessionId' });
+    }
+
+    // Handle the POST message
+    await transport.handlePostMessage(req, res, req.body);
+  } catch (error) {
+    console.error('Error handling MCP message:', error);
+    if (!res.headersSent) {
+      res.status(500).json({ error: 'Failed to handle message' });
+    }
+  }
+});
+
+export const sseRoutes = router;

src/services/mcp.server.ts

@@ -0,0 +1,77 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { falkorDBService } from './falkordb.service';
+
+/**
+ * Create and configure the MCP server with FalkorDB tools
+ */
+export function createMCPServer(): McpServer {
+  const server = new McpServer({
+    name: 'FalkorDB MCP Server',
+    version: '1.0.0',
+  });
+
+  // Tool: Execute a Cypher query on a graph
+  server.tool(
+    'executeQuery',
+    {
+      graphName: z.string().describe('The name of the graph to query'),
+      query: z.string().describe('The Cypher query to execute'),
+      params: z.record(z.any()).optional().describe('Optional parameters for the query'),
+    },
+    async ({ graphName, query, params }) => {
+      try {
+        const result = await falkorDBService.executeQuery(graphName, query, params);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
+        };
+      } catch (error: any) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Error executing query: ${error.message}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  // Tool: List all available graphs
+  server.tool(
+    'listGraphs',
+    {},
+    async () => {
+      try {
+        const graphs = await falkorDBService.listGraphs();
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify({ graphs }, null, 2),
+            },
+          ],
+        };
+      } catch (error: any) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Error listing graphs: ${error.message}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  return server;
+}