feat: support mcp sse/streamable http transport (#21)

* feat: enhance MCP server with new transport options and update documentation

- Added support for Express.js to handle SSE and Streamable transport protocols.
- Introduced command line options for transport type, port, and endpoint configuration.
- Updated README to include new usage instructions for desktop applications and transport options.
- Added health check and message endpoints for improved server functionality.
- Included automatic server instance creation for each request to ensure stateless operation.

* feat: add error handling for uncaught exceptions and unhandled rejections

- Implemented global error handling for uncaught exceptions and unhandled promise rejections.
- Added logging for errors to improve debugging and application stability.

* fix: remove error logging on server start failure

* chore: add contributor

---------

Co-authored-by: hustcc <i@hust.cc>

Author: 2niuhe

README.md

@@ -21,6 +21,8 @@ Generate <img src="https://echarts.apache.org/zh/images/favicon.png" height="14"
 
 ## 🤖 Usage
 
+### Desktop Applications (stdio transport)
+
 To use with `Desktop APP`, such as Claude, VSCode, Cline, Cherry Studio, and so on, add the  MCP server config below. On Mac system:
 
 ```json
@@ -58,6 +60,46 @@ On Window system:
 Also, you can use it on [modelscope](https://www.modelscope.cn/mcp/servers/hustcc/MCP-ECharts), [glama.ai](https://glama.ai/mcp/servers/@hustcc/mcp-echarts), [smithery.ai](https://smithery.ai/server/@hustcc/mcp-echarts) or others with HTTP, SSE Protocol.
 
 
+## 🚰 Run with SSE or Streamable transport
+
+Install the package globally.
+
+```bash
+npm install -g mcp-echarts
+```
+
+Run the server with your preferred transport option:
+
+```bash
+# For SSE transport (default endpoint: /sse)
+mcp-echarts -t sse
+
+# For Streamable transport with custom endpoint
+mcp-echarts -t streamable
+```
+
+Then you can access the server at:
+- SSE transport: `http://localhost:3033/sse`
+- Streamable transport: `http://localhost:3033/mcp`
+
+
+## 🎮 CLI Options
+
+You can also use the following CLI options when running the MCP server. Command options by run cli with `-h`.
+
+```plain
+MCP ECharts CLI
+
+Options:
+  --transport, -t  Specify the transport protocol: "stdio", "sse", or "streamable" (default: "stdio")
+  --port, -p       Specify the port for SSE or streamable transport (default: 3033)
+  --endpoint, -e   Specify the endpoint for the transport:
+                    - For SSE: default is "/sse"
+                    - For streamable: default is "/mcp"
+  --help, -h       Show this help message
+```
+
+
 ## 🗂️ MinIO Configuration (Optional)
 
 For better performance and sharing capabilities, you can configure MinIO object storage to store chart images as URLs instead of Base64 data.
@@ -126,6 +168,7 @@ npm run start
 ## 🧑🏻‍💻 Contributors
 
 - [lyw405](https://github.com/lyw405): Supports `15+` charting MCP tool. [#2](https://github.com/hustcc/mcp-echarts/issues/2)
+- [2niuhe](https://github.com/2niuhe): Support MCP with SSE and Streaming HTTP. [#17](https://github.com/hustcc/mcp-echarts/issues/17)
 - [susuperli](https://github.com/susuperli): Use `MinIO` to save the chart image base64 and return the url. [#10](https://github.com/hustcc/mcp-echarts/issues/10)
 - [BQXBQX](https://github.com/BQXBQX): Use `@napi-rs/canvas` instead node-canvas. [#3](https://github.com/hustcc/mcp-echarts/issues/3)
 - [hustcc](https://github.com/hustcc): Initial the repo.

package.json

@@ -21,12 +21,14 @@
     "@napi-rs/canvas": "^0.1.73",
     "dotenv": "^17.2.1",
     "echarts": "^6.0.0",
+    "express": "^5.1.0",
     "minio": "^8.0.5",
     "zod": "^3.25.16"
   },
   "devDependencies": {
     "@biomejs/biome": "1.9.4",
     "@modelcontextprotocol/inspector": "^0.15.0",
+    "@types/express": "^5.0.3",
     "@types/node": "^22.15.21",
     "@types/pixelmatch": "^5.2.6",
     "@types/pngjs": "^6.0.5",

src/index.ts

@@ -1,8 +1,14 @@
 #!/usr/bin/env node
+import { randomUUID } from "node:crypto";
 import process from "node:process";
+import { parseArgs } from "node:util";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 import { config } from "dotenv";
+import express from "express";
 import { tools } from "./tools";
 
 // Load environment variables from .env file (completely silent to avoid stdout contamination)
@@ -13,63 +19,218 @@ config({ override: false, debug: false });
  * MCP Server for ECharts.
  * This server provides tools for generating ECharts visualizations and validate ECharts configurations.
  */
-class MCPServerECharts {
-  /**
-   * The MCP server instance.
-   * This server handles requests and provides tools for ECharts-related tasks.
-   */
-  private readonly server: McpServer;
-
-  constructor() {
-    this.server = new McpServer({
-      name: "mcp-echarts",
-      version: "0.1.0",
-    });
+function createEChartsServer(): McpServer {
+  const server = new McpServer({
+    name: "mcp-echarts",
+    version: "0.1.0",
+  });
 
-    for (const tool of tools) {
-      const { name, description, inputSchema, run } = tool;
-      // biome-ignore lint/suspicious/noExplicitAny: <explanation>
-      this.server.tool(name, description, inputSchema.shape, run as any);
-    }
+  for (const tool of tools) {
+    const { name, description, inputSchema, run } = tool;
+    // biome-ignore lint/suspicious/noExplicitAny: <explanation>
+    server.tool(name, description, inputSchema.shape, run as any);
   }
 
-  async runWithStdio(): Promise<void> {
-    const transport = new StdioServerTransport();
-    await this.server.connect(transport);
-  }
+  return server;
+}
+
+// Parse command line arguments
+const { values } = parseArgs({
+  options: {
+    transport: {
+      type: "string",
+      short: "t",
+      default: "stdio",
+    },
+    port: {
+      type: "string",
+      short: "p",
+      default: "3033",
+    },
+    endpoint: {
+      type: "string",
+      short: "e",
+      default: "", // We'll handle defaults per transport type
+    },
+    help: {
+      type: "boolean",
+      short: "h",
+    },
+  },
+});
 
-  async shutdown(): Promise<void> {}
+// Display help information if requested
+if (values.help) {
+  console.log(`
+MCP ECharts CLI
+
+Options:
+  --transport, -t  Specify the transport protocol: "stdio", "sse", or "streamable" (default: "stdio")
+  --port, -p       Specify the port for SSE or streamable transport (default: 3033)
+  --endpoint, -e   Specify the endpoint for the transport:
+                   - For SSE: default is "/sse"
+                   - For streamable: default is "/mcp"
+  --help, -h       Show this help message
+  `);
+  process.exit(0);
 }
 
-/**
- * Main entry point for the MCP ECharts server application.
- * This function initializes the server, sets up error handling, and starts the server.
- * It handles uncaught exceptions and unhandled promise rejections to ensure graceful shutdown.
- */
+// Main function to start the server
 async function main(): Promise<void> {
-  const server = new MCPServerECharts();
+  const transport = values.transport?.toLowerCase() || "stdio";
+  const port = Number.parseInt(values.port as string, 10);
+
+  if (transport === "sse") {
+    const endpoint = values.endpoint || "/sse";
+    await runSSEServer(port, endpoint);
+  } else if (transport === "streamable") {
+    const endpoint = values.endpoint || "/mcp";
+    await runStreamableHTTPServer(port, endpoint);
+  } else {
+    await runStdioServer();
+  }
+}
 
-  process.on("uncaughtException", (error) => {
-    server.shutdown().finally(() => {
-      process.exit(1);
+async function runStdioServer(): Promise<void> {
+  const server = createEChartsServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+async function runSSEServer(port: number, endpoint: string): Promise<void> {
+  const app = express();
+  app.use(express.json());
+
+  // Store transports by session ID
+  const transports: Record<string, SSEServerTransport> = {};
+
+  // SSE endpoint
+  app.get(endpoint, async (req, res) => {
+    const server = createEChartsServer();
+    const transport = new SSEServerTransport("/messages", res);
+    transports[transport.sessionId] = transport;
+
+    res.on("close", () => {
+      delete transports[transport.sessionId];
     });
+
+    await server.connect(transport);
   });
 
-  process.on("unhandledRejection", (reason, promise) => {
-    server.shutdown().finally(() => {
-      process.exit(1);
-    });
+  // Message endpoint for SSE
+  app.post("/messages", async (req, res) => {
+    const sessionId = req.query.sessionId as string;
+    const transport = transports[sessionId];
+    if (transport) {
+      await transport.handlePostMessage(req, res, req.body);
+    } else {
+      res.status(400).send("No transport found for sessionId");
+    }
   });
 
-  try {
-    await server.runWithStdio();
-  } catch (error) {
-    process.exit(1);
-  }
+  app.listen(port, () => {
+    console.log(
+      `MCP ECharts SSE server running on http://localhost:${port}${endpoint}`,
+    );
+  });
 }
 
+async function runStreamableHTTPServer(
+  port: number,
+  endpoint: string,
+): Promise<void> {
+  const app = express();
+  app.use(express.json());
+
+  // Store transports by session ID
+  const transports: Record<string, StreamableHTTPServerTransport> = {};
+
+  // Handle POST requests for client-to-server communication
+  app.post(endpoint, async (req, res) => {
+    const sessionId = req.headers["mcp-session-id"] as string | undefined;
+    let transport: StreamableHTTPServerTransport;
+
+    if (sessionId && transports[sessionId]) {
+      // Reuse existing transport
+      transport = transports[sessionId];
+    } else if (!sessionId && isInitializeRequest(req.body)) {
+      // New initialization request
+      transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: () => randomUUID(),
+        onsessioninitialized: (sessionId) => {
+          transports[sessionId] = transport;
+        },
+      });
+
+      // Clean up transport when closed
+      transport.onclose = () => {
+        if (transport.sessionId) {
+          delete transports[transport.sessionId];
+        }
+      };
+
+      const server = createEChartsServer();
+      await server.connect(transport);
+    } else {
+      // Invalid request
+      res.status(400).json({
+        jsonrpc: "2.0",
+        error: {
+          code: -32000,
+          message: "Bad Request: No valid session ID provided",
+        },
+        id: null,
+      });
+      return;
+    }
+
+    // Handle the request
+    await transport.handleRequest(req, res, req.body);
+  });
+
+  // Handle GET requests for server-to-client notifications via SSE
+  app.get(endpoint, async (req, res) => {
+    const sessionId = req.headers["mcp-session-id"] as string | undefined;
+    if (!sessionId || !transports[sessionId]) {
+      res.status(400).send("Invalid or missing session ID");
+      return;
+    }
+
+    const transport = transports[sessionId];
+    await transport.handleRequest(req, res);
+  });
+
+  // Handle DELETE requests for session termination
+  app.delete(endpoint, async (req, res) => {
+    const sessionId = req.headers["mcp-session-id"] as string | undefined;
+    if (!sessionId || !transports[sessionId]) {
+      res.status(400).send("Invalid or missing session ID");
+      return;
+    }
+
+    const transport = transports[sessionId];
+    await transport.handleRequest(req, res);
+  });
+
+  app.listen(port, () => {
+    console.log(
+      `MCP ECharts Streamable HTTP server running on http://localhost:${port}${endpoint}`,
+    );
+  });
+}
+
+// Error handling for uncaught exceptions and unhandled rejections
+process.on("uncaughtException", (error) => {
+  console.error("Uncaught exception:", error);
+  process.exit(1);
+});
+
+process.on("unhandledRejection", (reason, promise) => {
+  console.error("Unhandled rejection at:", promise, "reason:", reason);
+  process.exit(1);
+});
+
 // Start application
 main().catch((error) => {
-  // Don't use console.error in MCP servers as it interferes with JSON protocol
   process.exit(1);
 });