@mcp-weave/nestjs 0.1.1 → 0.2.0

package/README.md

@@ -27,6 +27,7 @@ pnpm add @mcp-weave/nestjs reflect-metadata
 - **Method Decorators** - `@McpTool`, `@McpResource`, `@McpPrompt`
 - **Parameter Decorators** - `@McpInput`, `@McpParam`, `@McpPromptArg`
 - **Runtime Server** - Start MCP servers from decorated classes
+- **Multiple Transports** - Stdio (default) and SSE (Server-Sent Events)
 
 ## Quick Start
 
@@ -215,6 +216,46 @@ const server = new McpRuntimeServer(MyServer, {
 await server.start();
 ```
 
+### SSE Transport (Server-Sent Events)
+
+For web-based integrations, use the SSE transport:
+
+```typescript
+import { McpRuntimeServer } from '@mcp-weave/nestjs';
+
+const server = new McpRuntimeServer(MyServer, {
+  transport: 'sse',
+  port: 3000,
+  endpoint: '/sse',
+});
+
+// Starts HTTP server with SSE endpoint
+const httpServer = await server.start();
+
+// Server available at:
+// - SSE endpoint: http://localhost:3000/sse
+// - Health check: http://localhost:3000/health
+```
+
+Or use the `startSSE` method directly:
+
+```typescript
+const server = new McpRuntimeServer(MyServer);
+
+// Start with SSE transport
+const httpServer = await server.startSSE({
+  port: 8080,
+  endpoint: '/mcp',
+});
+```
+
+**SSE Features:**
+
+- CORS enabled by default
+- Health check endpoint at `/health`
+- Session management for multiple clients
+- Automatic cleanup on connection close
+
 ## Metadata Extraction
 
 Extract metadata from decorated classes for code generation:

package/dist/index.d.mts

@@ -1,6 +1,7 @@
 import { ToolInputSchema, PromptArgument, McpParamMetadata, McpPromptMetadata, McpResourceMetadata, McpServerMetadata, McpToolMetadata } from '@mcp-weave/core';
 export { METADATA_KEYS, McpParamMetadata, McpPromptMetadata, McpResourceMetadata, McpServerMetadata, McpToolMetadata, ScannedMetadata, extractMetadata } from '@mcp-weave/core';
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { Server as Server$1 } from '@modelcontextprotocol/sdk/server/index.js';
+import { Server } from 'http';
 
 /**
  * Options for @McpServer decorator
@@ -209,9 +210,17 @@ declare function getParamsMetadata(target: Function): McpParamMetadata[];
  */
 interface McpRuntimeOptions {
     /**
-     * Transport type
+     * Transport type: 'stdio' (default), 'sse', or 'websocket'
      */
-    transport?: 'stdio' | 'sse';
+    transport?: 'stdio' | 'sse' | 'websocket';
+    /**
+     * Port for SSE/WebSocket transport (default: 3000)
+     */
+    port?: number;
+    /**
+     * Endpoint path for SSE/WebSocket (default: '/sse' or '/ws')
+     */
+    endpoint?: string;
 }
 /**
  * Runtime MCP server that wraps a decorated class
@@ -230,16 +239,46 @@ declare class McpRuntimeServer {
     private resolvePromptArgs;
     private extractUriParams;
     /**
-     * Start the MCP server
+     * Start the MCP server with stdio transport
      */
     start(): Promise<void>;
+    /**
+     * Start the MCP server with SSE transport
+     */
+    startSSE(options?: {
+        port?: number;
+        endpoint?: string;
+    }): Promise<Server>;
     /**
      * Get the underlying MCP server instance
      */
-    getServer(): Server;
+    getServer(): Server$1;
+    /**
+     * Start the MCP server with WebSocket transport
+     */
+    startWebSocket(options?: {
+        port?: number;
+        endpoint?: string;
+    }): Promise<Server>;
+    /**
+     * Handle WebSocket JSON-RPC messages
+     */
+    private handleWebSocketMessage;
 }
 /**
  * Create and start an MCP server from a decorated class
+ *
+ * @example
+ * // Stdio transport (default)
+ * await createMcpServer(MyServer);
+ *
+ * @example
+ * // SSE transport
+ * await createMcpServer(MyServer, { transport: 'sse', port: 3000 });
+ *
+ * @example
+ * // WebSocket transport
+ * await createMcpServer(MyServer, { transport: 'websocket', port: 8080 });
  */
 declare function createMcpServer(target: Function, options?: McpRuntimeOptions): Promise<McpRuntimeServer>;
 

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { ToolInputSchema, PromptArgument, McpParamMetadata, McpPromptMetadata, McpResourceMetadata, McpServerMetadata, McpToolMetadata } from '@mcp-weave/core';
 export { METADATA_KEYS, McpParamMetadata, McpPromptMetadata, McpResourceMetadata, McpServerMetadata, McpToolMetadata, ScannedMetadata, extractMetadata } from '@mcp-weave/core';
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { Server as Server$1 } from '@modelcontextprotocol/sdk/server/index.js';
+import { Server } from 'http';
 
 /**
  * Options for @McpServer decorator
@@ -209,9 +210,17 @@ declare function getParamsMetadata(target: Function): McpParamMetadata[];
  */
 interface McpRuntimeOptions {
     /**
-     * Transport type
+     * Transport type: 'stdio' (default), 'sse', or 'websocket'
      */
-    transport?: 'stdio' | 'sse';
+    transport?: 'stdio' | 'sse' | 'websocket';
+    /**
+     * Port for SSE/WebSocket transport (default: 3000)
+     */
+    port?: number;
+    /**
+     * Endpoint path for SSE/WebSocket (default: '/sse' or '/ws')
+     */
+    endpoint?: string;
 }
 /**
  * Runtime MCP server that wraps a decorated class
@@ -230,16 +239,46 @@ declare class McpRuntimeServer {
     private resolvePromptArgs;
     private extractUriParams;
     /**
-     * Start the MCP server
+     * Start the MCP server with stdio transport
      */
     start(): Promise<void>;
+    /**
+     * Start the MCP server with SSE transport
+     */
+    startSSE(options?: {
+        port?: number;
+        endpoint?: string;
+    }): Promise<Server>;
     /**
      * Get the underlying MCP server instance
      */
-    getServer(): Server;
+    getServer(): Server$1;
+    /**
+     * Start the MCP server with WebSocket transport
+     */
+    startWebSocket(options?: {
+        port?: number;
+        endpoint?: string;
+    }): Promise<Server>;
+    /**
+     * Handle WebSocket JSON-RPC messages
+     */
+    private handleWebSocketMessage;
 }
 /**
  * Create and start an MCP server from a decorated class
+ *
+ * @example
+ * // Stdio transport (default)
+ * await createMcpServer(MyServer);
+ *
+ * @example
+ * // SSE transport
+ * await createMcpServer(MyServer, { transport: 'sse', port: 3000 });
+ *
+ * @example
+ * // WebSocket transport
+ * await createMcpServer(MyServer, { transport: 'websocket', port: 8080 });
  */
 declare function createMcpServer(target: Function, options?: McpRuntimeOptions): Promise<McpRuntimeServer>;
 

package/dist/index.js

@@ -4,8 +4,15 @@ require('reflect-metadata');
 var core = require('@mcp-weave/core');
 var index_js = require('@modelcontextprotocol/sdk/server/index.js');
 var stdio_js = require('@modelcontextprotocol/sdk/server/stdio.js');
+var sse_js = require('@modelcontextprotocol/sdk/server/sse.js');
+var http = require('http');
 
-// src/index.ts
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
 function McpServer(options) {
   return (target) => {
     const metadata = {
@@ -125,8 +132,6 @@ function getPromptsMetadata(target) {
 function getParamsMetadata(target) {
   return Reflect.getMetadata(core.METADATA_KEYS.PARAMS, target) ?? [];
 }
-
-// src/runtime/server.ts
 var McpRuntimeServer = class {
   server;
   instance;
@@ -326,23 +331,386 @@ var McpRuntimeServer = class {
     return params;
   }
   /**
-   * Start the MCP server
+   * Start the MCP server with stdio transport
    */
   async start() {
     const transport = new stdio_js.StdioServerTransport();
     await this.server.connect(transport);
     console.error(`MCP server '${this.metadata.server?.name}' started on stdio`);
   }
+  /**
+   * Start the MCP server with SSE transport
+   */
+  async startSSE(options = {}) {
+    const port = options.port ?? 3e3;
+    const endpoint = options.endpoint ?? "/sse";
+    const httpServer = http.createServer(async (req, res) => {
+      res.setHeader("Access-Control-Allow-Origin", "*");
+      res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+      res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+      if (req.method === "OPTIONS") {
+        res.writeHead(200);
+        res.end();
+        return;
+      }
+      const url = new URL(req.url ?? "/", `http://localhost:${port}`);
+      if (url.pathname === endpoint && req.method === "GET") {
+        const transport = new sse_js.SSEServerTransport(endpoint, res);
+        await this.server.connect(transport);
+        return;
+      }
+      if (url.pathname === `${endpoint}/message` && req.method === "POST") {
+        let body = "";
+        req.on("data", (chunk) => {
+          body += chunk.toString();
+        });
+        req.on("end", () => {
+          res.writeHead(200, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ received: true }));
+        });
+        return;
+      }
+      if (url.pathname === "/health") {
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(
+          JSON.stringify({
+            status: "ok",
+            server: this.metadata.server?.name,
+            version: this.metadata.server?.version
+          })
+        );
+        return;
+      }
+      res.writeHead(404, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Not found" }));
+    });
+    return new Promise((resolve, reject) => {
+      httpServer.on("error", reject);
+      httpServer.listen(port, () => {
+        console.error(
+          `MCP server '${this.metadata.server?.name}' started on http://localhost:${port}${endpoint}`
+        );
+        resolve(httpServer);
+      });
+    });
+  }
   /**
    * Get the underlying MCP server instance
    */
   getServer() {
     return this.server;
   }
+  /**
+   * Start the MCP server with WebSocket transport
+   */
+  async startWebSocket(options = {}) {
+    const port = options.port ?? 8080;
+    const endpoint = options.endpoint ?? "/ws";
+    const httpServer = http.createServer((req, res) => {
+      res.setHeader("Access-Control-Allow-Origin", "*");
+      res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+      res.setHeader("Access-Control-Allow-Headers", "Content-Type, Upgrade, Connection");
+      if (req.method === "OPTIONS") {
+        res.writeHead(200);
+        res.end();
+        return;
+      }
+      if (req.url === "/health") {
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(
+          JSON.stringify({
+            status: "ok",
+            server: this.metadata.server?.name,
+            version: this.metadata.server?.version,
+            transport: "websocket"
+          })
+        );
+        return;
+      }
+      if (req.url === "/") {
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(
+          JSON.stringify({
+            name: this.metadata.server?.name,
+            version: this.metadata.server?.version,
+            websocket: `ws://localhost:${port}${endpoint}`,
+            tools: this.metadata.tools.length,
+            resources: this.metadata.resources.length,
+            prompts: this.metadata.prompts.length
+          })
+        );
+        return;
+      }
+      res.writeHead(426, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Upgrade Required", message: `Connect via WebSocket at ${endpoint}` }));
+    });
+    httpServer.on("upgrade", (req, socket, _head) => {
+      const url = new URL(req.url ?? "/", `http://localhost:${port}`);
+      if (url.pathname !== endpoint) {
+        socket.write("HTTP/1.1 404 Not Found\r\n\r\n");
+        socket.destroy();
+        return;
+      }
+      const key = req.headers["sec-websocket-key"];
+      if (!key) {
+        socket.write("HTTP/1.1 400 Bad Request\r\n\r\n");
+        socket.destroy();
+        return;
+      }
+      const crypto = __require("crypto");
+      const acceptKey = crypto.createHash("sha1").update(key + "258EAFA5-E914-47DA-95CA-C5AB0DC85B11").digest("base64");
+      socket.write(
+        `HTTP/1.1 101 Switching Protocols\r
+Upgrade: websocket\r
+Connection: Upgrade\r
+Sec-WebSocket-Accept: ${acceptKey}\r
+\r
+`
+      );
+      const sessions = /* @__PURE__ */ new Map();
+      const sessionId = crypto.randomUUID();
+      const encodeFrame = (data) => {
+        const payload = Buffer.from(data, "utf8");
+        const length = payload.length;
+        let frame;
+        if (length < 126) {
+          frame = Buffer.alloc(2 + length);
+          frame[0] = 129;
+          frame[1] = length;
+          payload.copy(frame, 2);
+        } else if (length < 65536) {
+          frame = Buffer.alloc(4 + length);
+          frame[0] = 129;
+          frame[1] = 126;
+          frame.writeUInt16BE(length, 2);
+          payload.copy(frame, 4);
+        } else {
+          frame = Buffer.alloc(10 + length);
+          frame[0] = 129;
+          frame[1] = 127;
+          frame.writeBigUInt64BE(BigInt(length), 2);
+          payload.copy(frame, 10);
+        }
+        return frame;
+      };
+      const decodeFrame = (buffer) => {
+        if (buffer.length < 2) return null;
+        const byte0 = buffer[0];
+        const byte1 = buffer[1];
+        const opcode = byte0 & 15;
+        const masked = (byte1 & 128) !== 0;
+        let payloadLength = byte1 & 127;
+        let offset = 2;
+        if (payloadLength === 126) {
+          if (buffer.length < 4) return null;
+          payloadLength = buffer.readUInt16BE(2);
+          offset = 4;
+        } else if (payloadLength === 127) {
+          if (buffer.length < 10) return null;
+          payloadLength = Number(buffer.readBigUInt64BE(2));
+          offset = 10;
+        }
+        if (masked) {
+          if (buffer.length < offset + 4 + payloadLength) return null;
+          const mask = buffer.slice(offset, offset + 4);
+          offset += 4;
+          const payload = buffer.slice(offset, offset + payloadLength);
+          for (let i = 0; i < payload.length; i++) {
+            const maskByte = mask[i % 4] ?? 0;
+            payload[i] = (payload[i] ?? 0) ^ maskByte;
+          }
+          return { opcode, payload: payload.toString("utf8") };
+        } else {
+          if (buffer.length < offset + payloadLength) return null;
+          return { opcode, payload: buffer.slice(offset, offset + payloadLength).toString("utf8") };
+        }
+      };
+      const send = (data) => {
+        try {
+          socket.write(encodeFrame(data));
+        } catch {
+        }
+      };
+      sessions.set(sessionId, { send });
+      send(JSON.stringify({
+        jsonrpc: "2.0",
+        method: "connection/established",
+        params: { sessionId, server: this.metadata.server?.name }
+      }));
+      let messageBuffer = Buffer.alloc(0);
+      socket.on("data", async (chunk) => {
+        messageBuffer = Buffer.concat([messageBuffer, chunk]);
+        while (messageBuffer.length > 0) {
+          const frame = decodeFrame(messageBuffer);
+          if (!frame) break;
+          let frameSize = 2;
+          const byte1 = messageBuffer[1] ?? 0;
+          const payloadLength = byte1 & 127;
+          if (payloadLength === 126) frameSize = 4;
+          else if (payloadLength === 127) frameSize = 10;
+          if ((byte1 & 128) !== 0) frameSize += 4;
+          frameSize += frame.payload.length;
+          messageBuffer = messageBuffer.slice(frameSize);
+          if (frame.opcode === 8) {
+            socket.end();
+            return;
+          }
+          if (frame.opcode === 9) {
+            socket.write(Buffer.from([138, 0]));
+            continue;
+          }
+          if (frame.opcode === 1) {
+            try {
+              const message = JSON.parse(frame.payload);
+              const response = await this.handleWebSocketMessage(message);
+              if (response) {
+                send(JSON.stringify(response));
+              }
+            } catch (error) {
+              send(JSON.stringify({
+                jsonrpc: "2.0",
+                error: { code: -32700, message: "Parse error" },
+                id: null
+              }));
+            }
+          }
+        }
+      });
+      socket.on("close", () => {
+        sessions.delete(sessionId);
+      });
+      socket.on("error", () => {
+        sessions.delete(sessionId);
+      });
+    });
+    return new Promise((resolve, reject) => {
+      httpServer.on("error", reject);
+      httpServer.listen(port, () => {
+        console.error(
+          `MCP server '${this.metadata.server?.name}' started on ws://localhost:${port}${endpoint}`
+        );
+        resolve(httpServer);
+      });
+    });
+  }
+  /**
+   * Handle WebSocket JSON-RPC messages
+   */
+  async handleWebSocketMessage(message) {
+    if (!message || typeof message !== "object") {
+      return { jsonrpc: "2.0", error: { code: -32600, message: "Invalid Request" }, id: null };
+    }
+    const req = message;
+    if (req.jsonrpc !== "2.0" || !req.method) {
+      return { jsonrpc: "2.0", error: { code: -32600, message: "Invalid Request" }, id: req.id ?? null };
+    }
+    try {
+      let result;
+      switch (req.method) {
+        case "initialize":
+          result = {
+            protocolVersion: "2024-11-05",
+            serverInfo: {
+              name: this.metadata.server?.name,
+              version: this.metadata.server?.version ?? "1.0.0"
+            },
+            capabilities: {
+              tools: this.metadata.tools.length > 0 ? {} : void 0,
+              resources: this.metadata.resources.length > 0 ? {} : void 0,
+              prompts: this.metadata.prompts.length > 0 ? {} : void 0
+            }
+          };
+          break;
+        case "tools/list":
+          result = {
+            tools: this.metadata.tools.map((t) => ({
+              name: t.name,
+              description: t.description,
+              inputSchema: t.inputSchema ?? { type: "object", properties: {} }
+            }))
+          };
+          break;
+        case "tools/call":
+          const toolParams = req.params;
+          const tool = this.metadata.tools.find((t) => t.name === toolParams.name);
+          if (!tool) {
+            return { jsonrpc: "2.0", error: { code: -32602, message: `Unknown tool: ${toolParams.name}` }, id: req.id };
+          }
+          const method = Reflect.get(this.instance, tool.propertyKey);
+          const toolResult = await method.apply(this.instance, [toolParams.arguments ?? {}]);
+          result = {
+            content: [{
+              type: "text",
+              text: typeof toolResult === "string" ? toolResult : JSON.stringify(toolResult)
+            }]
+          };
+          break;
+        case "resources/list":
+          result = {
+            resources: this.metadata.resources.map((r) => ({
+              uri: r.uri,
+              name: r.name,
+              description: r.description,
+              mimeType: r.mimeType
+            }))
+          };
+          break;
+        case "resources/read":
+          const resParams = req.params;
+          for (const resource of this.metadata.resources) {
+            const uriParams = this.extractUriParams(resource.uri, resParams.uri);
+            if (uriParams) {
+              const resMethod = Reflect.get(this.instance, resource.propertyKey);
+              const args = this.resolveResourceArgs(resource.propertyKey, uriParams);
+              result = await resMethod.apply(this.instance, args);
+              break;
+            }
+          }
+          if (!result) {
+            return { jsonrpc: "2.0", error: { code: -32602, message: `Resource not found: ${resParams.uri}` }, id: req.id };
+          }
+          break;
+        case "prompts/list":
+          result = {
+            prompts: this.metadata.prompts.map((p) => ({
+              name: p.name,
+              description: p.description,
+              arguments: p.arguments ?? []
+            }))
+          };
+          break;
+        case "prompts/get":
+          const promptParams = req.params;
+          const prompt = this.metadata.prompts.find((p) => p.name === promptParams.name);
+          if (!prompt) {
+            return { jsonrpc: "2.0", error: { code: -32602, message: `Unknown prompt: ${promptParams.name}` }, id: req.id };
+          }
+          const promptMethod = Reflect.get(this.instance, prompt.propertyKey);
+          const promptArgs = this.resolvePromptArgs(prompt.propertyKey, promptParams.arguments ?? {});
+          result = await promptMethod.apply(this.instance, promptArgs);
+          break;
+        default:
+          return { jsonrpc: "2.0", error: { code: -32601, message: `Method not found: ${req.method}` }, id: req.id };
+      }
+      return { jsonrpc: "2.0", result, id: req.id };
+    } catch (error) {
+      return {
+        jsonrpc: "2.0",
+        error: { code: -32e3, message: error instanceof Error ? error.message : "Internal error" },
+        id: req.id
+      };
+    }
+  }
 };
-async function createMcpServer(target, options) {
+async function createMcpServer(target, options = {}) {
   const server = new McpRuntimeServer(target, options);
-  await server.start();
+  if (options.transport === "sse") {
+    await server.startSSE({ port: options.port, endpoint: options.endpoint });
+  } else if (options.transport === "websocket") {
+    await server.startWebSocket({ port: options.port, endpoint: options.endpoint });
+  } else {
+    await server.start();
+  }
   return server;
 }