@mcp-web/bridge 0.1.0

package/src/adapters/deno.ts

@@ -0,0 +1,282 @@
+/**
+ * MCPWebBridgeDeno - Deno adapter for the MCP Web Bridge.
+ *
+ * Uses Deno.serve() with WebSocket upgrade for a single-port server.
+ * Handles both HTTP requests and WebSocket connections on the same port.
+ *
+ * @example
+ * ```typescript
+ * // main.ts
+ * import { MCPWebBridgeDeno } from '@mcp-web/bridge';
+ *
+ * const bridge = new MCPWebBridgeDeno({
+ *   name: 'My App',
+ *   description: 'My awesome app',
+ *   port: 3001,
+ * });
+ *
+ * // Bridge is now listening on ws://localhost:3001 and http://localhost:3001
+ * ```
+ *
+ * @example Deploy to Deno Deploy
+ * ```typescript
+ * // main.ts - Entry point for Deno Deploy
+ * import { MCPWebBridgeDeno } from '@mcp-web/bridge';
+ *
+ * new MCPWebBridgeDeno({
+ *   name: 'My Production App',
+ *   description: 'Production bridge server',
+ *   // Port is typically provided by Deno Deploy via environment
+ *   port: Number(Deno.env.get('PORT')) || 8000,
+ * });
+ * ```
+ *
+ * @remarks
+ * This adapter requires Deno runtime. It uses:
+ * - `Deno.serve()` for the HTTP server
+ * - `Deno.upgradeWebSocket()` for WebSocket connections
+ *
+ * For Deno Deploy, ensure your entry point is at the root of your repository
+ * or configure the entry point in your deployment settings.
+ *
+ * @see https://docs.deno.com/deploy/
+ * @see https://deno.land/api?s=Deno.serve
+ */
+
+import type { MCPWebConfig } from '@mcp-web/types';
+import { MCPWebBridge } from '../core.js';
+import { TimerScheduler } from '../runtime/scheduler.js';
+import type { HttpRequest, WebSocketConnection } from '../runtime/types.js';
+import { isSSEResponse } from '../runtime/types.js';
+
+/**
+ * Configuration for the Deno bridge adapter.
+ */
+export interface MCPWebBridgeDenoConfig extends Omit<MCPWebConfig, 'bridgeUrl'> {
+  /** Port to listen on (default: 3001, or PORT env var on Deno Deploy) */
+  port?: number;
+
+  /** Hostname to bind to (default: '0.0.0.0') */
+  hostname?: string;
+}
+
+/**
+ * Wraps a Deno WebSocket in our runtime-agnostic interface.
+ */
+function wrapDenoWebSocket(socket: WebSocket): WebSocketConnection {
+  const messageHandlers = new Set<(data: string) => void>();
+
+  socket.onmessage = (event) => {
+    const data = typeof event.data === 'string' ? event.data : event.data.toString();
+    for (const handler of messageHandlers) {
+      handler(data);
+    }
+  };
+
+  return {
+    send(data: string): void {
+      if (socket.readyState === WebSocket.OPEN) {
+        socket.send(data);
+      }
+    },
+
+    close(code?: number, reason?: string): void {
+      socket.close(code, reason);
+    },
+
+    get readyState(): 'CONNECTING' | 'OPEN' | 'CLOSING' | 'CLOSED' {
+      switch (socket.readyState) {
+        case WebSocket.CONNECTING:
+          return 'CONNECTING';
+        case WebSocket.OPEN:
+          return 'OPEN';
+        case WebSocket.CLOSING:
+          return 'CLOSING';
+        case WebSocket.CLOSED:
+        default:
+          return 'CLOSED';
+      }
+    },
+
+    onMessage(handler: (data: string) => void): void {
+      messageHandlers.add(handler);
+    },
+
+    offMessage(handler: (data: string) => void): void {
+      messageHandlers.delete(handler);
+    },
+  };
+}
+
+/**
+ * Wraps a Deno Request in our runtime-agnostic HttpRequest interface.
+ */
+function wrapDenoRequest(req: Request): HttpRequest {
+  return {
+    method: req.method,
+    url: req.url,
+    headers: {
+      get(name: string): string | null {
+        return req.headers.get(name);
+      },
+    },
+    text(): Promise<string> {
+      return req.text();
+    },
+  };
+}
+
+/**
+ * Deno adapter for MCPWebBridge.
+ * Provides a single-port server using Deno.serve() with WebSocket upgrade.
+ *
+ * @example
+ * ```typescript
+ * const bridge = new MCPWebBridgeDeno({
+ *   name: 'My App',
+ *   description: 'My app',
+ *   port: 3001,
+ * });
+ * ```
+ */
+export class MCPWebBridgeDeno {
+  #core: MCPWebBridge;
+  #controller: AbortController;
+  #port: number;
+  #hostname: string;
+
+  constructor(config: MCPWebBridgeDenoConfig) {
+    // biome-ignore lint/suspicious/noExplicitAny: Deno global is runtime-specific
+    const Deno = (globalThis as any).Deno;
+    const envPort = Deno?.env?.get?.('PORT');
+    this.#port = config.port ?? (envPort ? Number(envPort) : 3001);
+    this.#hostname = config.hostname ?? '0.0.0.0';
+    this.#controller = new AbortController();
+
+    // Create the core with a timer-based scheduler
+    const scheduler = new TimerScheduler();
+    this.#core = new MCPWebBridge(config, scheduler);
+    const handlers = this.#core.getHandlers();
+
+    // Start Deno server
+    Deno.serve(
+      {
+        port: this.#port,
+        hostname: this.#hostname,
+        signal: this.#controller.signal,
+        onListen: ({ port, hostname }: { port: number; hostname: string }) => {
+          console.log(`🌉 MCP Web Bridge (Deno) listening on ${hostname}:${port}`);
+          console.log(`   WebSocket: ws://${hostname === '0.0.0.0' ? 'localhost' : hostname}:${port}`);
+          console.log(`   HTTP/MCP:  http://${hostname === '0.0.0.0' ? 'localhost' : hostname}:${port}`);
+        },
+      },
+      async (req: Request): Promise<Response> => {
+        const url = new URL(req.url);
+
+        // Handle WebSocket upgrade
+        if (req.headers.get('upgrade')?.toLowerCase() === 'websocket') {
+          const sessionId = url.searchParams.get('session');
+
+          if (!sessionId) {
+            return new Response('Missing session parameter', { status: 400 });
+          }
+
+          const { socket, response } = Deno.upgradeWebSocket(req);
+          const wrapped = wrapDenoWebSocket(socket);
+
+          socket.onopen = () => {
+            handlers.onWebSocketConnect(sessionId, wrapped, url);
+          };
+
+          socket.onmessage = (event: MessageEvent) => {
+            const data = typeof event.data === 'string' ? event.data : event.data.toString();
+            handlers.onWebSocketMessage(sessionId, wrapped, data);
+          };
+
+          socket.onclose = () => {
+            handlers.onWebSocketClose(sessionId);
+          };
+
+          socket.onerror = (error: Event) => {
+            console.error(`WebSocket error for session ${sessionId}:`, error);
+          };
+
+          return response;
+        }
+
+        // Handle regular HTTP requests
+        const wrappedReq = wrapDenoRequest(req);
+        const httpResponse = await handlers.onHttpRequest(wrappedReq);
+
+        // Check if this is an SSE response
+        if (isSSEResponse(httpResponse)) {
+          // Create a ReadableStream for SSE
+          const stream = new ReadableStream({
+            start(controller) {
+              // Create writer function that sends SSE-formatted data
+              const writer = (data: string): void => {
+                controller.enqueue(new TextEncoder().encode(`data: ${data}\n\n`));
+              };
+
+              // Set up the SSE stream
+              httpResponse.setup(writer, () => {
+                controller.close();
+              });
+
+              // Keep connection alive with periodic comments
+              const keepAlive = setInterval(() => {
+                try {
+                  controller.enqueue(new TextEncoder().encode(': keepalive\n\n'));
+                } catch {
+                  clearInterval(keepAlive);
+                }
+              }, 30000);
+            },
+          });
+
+          return new Response(stream, {
+            status: httpResponse.status,
+            headers: httpResponse.headers,
+          });
+        }
+
+        return new Response(httpResponse.body, {
+          status: httpResponse.status,
+          headers: httpResponse.headers,
+        });
+      }
+    );
+  }
+
+  /**
+   * Get the underlying MCPWebBridge core instance.
+   */
+  get core(): MCPWebBridge {
+    return this.#core;
+  }
+
+  /**
+   * Get the bridge handlers for custom integrations.
+   */
+  getHandlers() {
+    return this.#core.getHandlers();
+  }
+
+  /**
+   * Get the port the server is listening on.
+   */
+  get port(): number {
+    return this.#port;
+  }
+
+  /**
+   * Gracefully shut down the bridge.
+   */
+  async close(): Promise<void> {
+    // Abort the server
+    this.#controller.abort();
+
+    // Close the core (cleans up sessions, timers)
+    await this.#core.close();
+  }
+}

package/src/adapters/index.ts

@@ -0,0 +1,28 @@
+/**
+ * Bridge adapters for different JavaScript runtimes.
+ *
+ * Each adapter wraps the core MCPWebBridge class and provides
+ * runtime-specific I/O implementations.
+ *
+ * Available adapters:
+ * - `MCPWebBridgeNode` - Node.js (production ready)
+ * - `MCPWebBridgeDeno` - Deno / Deno Deploy
+ * - `MCPWebBridgeBun` - Bun runtime
+ * - `MCPWebBridgeParty` / `createPartyKitBridge` - PartyKit / Cloudflare
+ */
+
+// Node.js adapter (production ready)
+export { Bridge, MCPWebBridgeNode } from './node.js';
+export type { MCPWebBridgeNodeConfig, MCPWebBridgeNodeSSLConfig } from './node.js';
+
+// Deno adapter
+export { MCPWebBridgeDeno } from './deno.js';
+export type { MCPWebBridgeDenoConfig } from './deno.js';
+
+// Bun adapter
+export { MCPWebBridgeBun } from './bun.js';
+export type { MCPWebBridgeBunConfig } from './bun.js';
+
+// PartyKit adapter
+export { AlarmScheduler, createPartyKitBridge, MCPWebBridgeParty } from './partykit.js';
+export type { MCPWebBridgePartyConfig } from './partykit.js';

package/src/adapters/node.ts

@@ -0,0 +1,385 @@
+/**
+ * MCPWebBridgeNode - Node.js adapter for the MCP Web Bridge.
+ *
+ * Uses a single port for both HTTP and WebSocket connections.
+ * WebSocket connections are upgraded from HTTP via the `upgrade` event.
+ *
+ * @example
+ * ```typescript
+ * import { MCPWebBridgeNode } from '@mcp-web/bridge';
+ *
+ * const bridge = new MCPWebBridgeNode({
+ *   name: 'My App',
+ *   description: 'My awesome app',
+ *   port: 3001,
+ * });
+ *
+ * // Bridge is now listening on ws://localhost:3001 and http://localhost:3001
+ * ```
+ */
+
+import {
+  createServer as createHttpServer,
+  type IncomingMessage,
+  type Server,
+  type ServerResponse,
+} from 'node:http';
+import { createServer as createHttpsServer } from 'node:https';
+import { WebSocket, WebSocketServer } from 'ws';
+import type { MCPWebConfig } from '@mcp-web/types';
+import { MCPWebBridge } from '../core.js';
+import { TimerScheduler } from '../runtime/scheduler.js';
+import type { HttpRequest, WebSocketConnection } from '../runtime/types.js';
+import { readyStateToString, isSSEResponse } from '../runtime/types.js';
+
+/**
+ * Configuration for the Node.js bridge adapter.
+ */
+/**
+ * SSL/TLS configuration for secure connections.
+ */
+export interface MCPWebBridgeNodeSSLConfig {
+  /** Private key in PEM format (string content, not file path) */
+  key: string | Buffer;
+
+  /** Certificate in PEM format (string content, not file path) */
+  cert: string | Buffer;
+}
+
+/**
+ * Configuration for the Node.js bridge adapter.
+ */
+export interface MCPWebBridgeNodeConfig extends Omit<MCPWebConfig, 'bridgeUrl'> {
+  /** Port to listen on (default: 3001) */
+  port?: number;
+
+  /** Host to bind to (default: '0.0.0.0') */
+  host?: string;
+
+  /**
+   * SSL/TLS configuration for HTTPS/WSS support.
+   * When provided, the bridge will use secure connections.
+   *
+   * @example
+   * ```typescript
+   * import { readFileSync } from 'node:fs';
+   *
+   * const bridge = new MCPWebBridgeNode({
+   *   name: 'My App',
+   *   port: 3001,
+   *   ssl: {
+   *     key: readFileSync('./localhost-key.pem'),
+   *     cert: readFileSync('./localhost.pem'),
+   *   },
+   * });
+   * ```
+   */
+  ssl?: MCPWebBridgeNodeSSLConfig;
+}
+
+/**
+ * Wraps a Node.js ws WebSocket in our runtime-agnostic interface.
+ */
+function wrapWebSocket(ws: WebSocket): WebSocketConnection {
+  const messageHandlers = new Set<(data: string) => void>();
+
+  ws.on('message', (data) => {
+    const str = data.toString();
+    for (const handler of messageHandlers) {
+      handler(str);
+    }
+  });
+
+  return {
+    send(data: string): void {
+      if (ws.readyState === WebSocket.OPEN) {
+        ws.send(data);
+      }
+    },
+
+    close(code?: number, reason?: string): void {
+      ws.close(code, reason);
+    },
+
+    get readyState(): 'CONNECTING' | 'OPEN' | 'CLOSING' | 'CLOSED' {
+      return readyStateToString(ws.readyState);
+    },
+
+    onMessage(handler: (data: string) => void): void {
+      messageHandlers.add(handler);
+    },
+
+    offMessage(handler: (data: string) => void): void {
+      messageHandlers.delete(handler);
+    },
+  };
+}
+
+/**
+ * Wraps a Node.js IncomingMessage in our runtime-agnostic HttpRequest interface.
+ */
+function wrapRequest(req: IncomingMessage, body: string): HttpRequest {
+  return {
+    method: req.method || 'GET',
+    url: `http://${req.headers.host || 'localhost'}${req.url || '/'}`,
+    headers: {
+      get(name: string): string | null {
+        const value = req.headers[name.toLowerCase()];
+        if (Array.isArray(value)) {
+          return value[0] || null;
+        }
+        return value || null;
+      },
+    },
+    text(): Promise<string> {
+      return Promise.resolve(body);
+    },
+  };
+}
+
+/**
+ * Node.js adapter for MCPWebBridge.
+ * Provides a single-port server for both WebSocket and HTTP traffic.
+ */
+export class MCPWebBridgeNode {
+  #core: MCPWebBridge;
+  #server: Server;
+  #wss: WebSocketServer;
+  #port: number;
+  #host: string;
+  #isSecure: boolean;
+  #readyPromise: Promise<void>;
+  #isReady = false;
+
+  constructor(config: MCPWebBridgeNodeConfig) {
+    this.#port = config.port ?? 3001;
+    this.#host = config.host ?? '0.0.0.0';
+    this.#isSecure = !!config.ssl;
+
+    // Create the core with a timer-based scheduler
+    const scheduler = new TimerScheduler();
+    this.#core = new MCPWebBridge(config, scheduler);
+    const handlers = this.#core.getHandlers();
+
+    // Request handler (shared between HTTP and HTTPS)
+    const requestHandler = (req: IncomingMessage, res: ServerResponse) => {
+      // Collect body
+      let body = '';
+      req.on('data', (chunk) => {
+        body += chunk;
+      });
+      req.on('end', () => {
+        const wrappedReq = wrapRequest(req, body);
+        handlers.onHttpRequest(wrappedReq).then((response) => {
+          // Check if this is an SSE response
+          if (isSSEResponse(response)) {
+            // Set headers for SSE
+            res.writeHead(response.status, response.headers);
+
+            // Create writer function that sends SSE-formatted data
+            const writer = (data: string): void => {
+              res.write(`data: ${data}\n\n`);
+            };
+
+            // Track if connection is still open
+            let isOpen = true;
+
+            // Handle client disconnect
+            req.on('close', () => {
+              isOpen = false;
+            });
+
+            // Set up the SSE stream
+            response.setup(writer, () => {
+              if (isOpen) {
+                res.end();
+              }
+            });
+
+            // Keep connection alive with periodic comments
+            const keepAlive = setInterval(() => {
+              if (isOpen) {
+                res.write(': keepalive\n\n');
+              } else {
+                clearInterval(keepAlive);
+              }
+            }, 30000);
+
+            // Clean up on close
+            res.on('close', () => {
+              clearInterval(keepAlive);
+            });
+          } else {
+            // Regular HTTP response
+            res.writeHead(response.status, response.headers);
+            res.end(response.body);
+          }
+        });
+      });
+    };
+
+    // Create HTTP or HTTPS server based on SSL config
+    if (config.ssl) {
+      this.#server = createHttpsServer(
+        { key: config.ssl.key, cert: config.ssl.cert },
+        requestHandler,
+      );
+    } else {
+      this.#server = createHttpServer(requestHandler);
+    }
+
+    // Create WebSocket server without its own port (noServer mode)
+    this.#wss = new WebSocketServer({ noServer: true });
+
+    // Handle WebSocket upgrade requests
+    this.#server.on('upgrade', (req: IncomingMessage, socket, head) => {
+      const urlStr = `http://${req.headers.host || 'localhost'}${req.url || '/'}`;
+      const url = new URL(urlStr);
+      const sessionId = url.searchParams.get('session');
+
+      if (!sessionId) {
+        socket.write('HTTP/1.1 400 Bad Request\r\n\r\n');
+        socket.destroy();
+        return;
+      }
+
+      this.#wss.handleUpgrade(req, socket, head, (ws) => {
+        const wrapped = wrapWebSocket(ws);
+
+        if (handlers.onWebSocketConnect(sessionId, wrapped, url)) {
+          ws.on('message', (data) => {
+            handlers.onWebSocketMessage(sessionId, wrapped, data.toString());
+          });
+
+          ws.on('close', () => {
+            handlers.onWebSocketClose(sessionId);
+          });
+
+          ws.on('error', (error) => {
+            console.error(`WebSocket error for session ${sessionId}:`, error);
+          });
+        } else {
+          ws.close(1008, 'Connection rejected');
+        }
+      });
+    });
+
+    // Create a promise that resolves when the server is ready or rejects on error
+    this.#readyPromise = new Promise<void>((resolve, reject) => {
+      // Handle server errors (including EADDRINUSE)
+      this.#server.on('error', (error: NodeJS.ErrnoException) => {
+        if (error.code === 'EADDRINUSE') {
+          const displayHost = this.#host === '0.0.0.0' ? 'localhost' : this.#host;
+          console.error(`\n❌ Port ${this.#port} is already in use.`);
+          console.error(`   Another process is listening on ${displayHost}:${this.#port}`);
+          console.error(`\n   To fix this, either:`);
+          console.error(`   1. Stop the other process using port ${this.#port}:`);
+          console.error(`      lsof -i :${this.#port}  # Find the process`);
+          console.error(`      kill <PID>             # Kill it`);
+          console.error(`   2. Or use a different port in your bridge config\n`);
+        } else {
+          console.error(`\n❌ Failed to start bridge server:`, error.message);
+        }
+        reject(error);
+      });
+
+      // Start listening
+      this.#server.listen(this.#port, this.#host, () => {
+        this.#isReady = true;
+        const displayHost = this.#host === '0.0.0.0' ? 'localhost' : this.#host;
+        const wsProtocol = this.#isSecure ? 'wss' : 'ws';
+        const httpProtocol = this.#isSecure ? 'https' : 'http';
+        console.log(`🌉 MCP Web Bridge listening on ${displayHost}:${this.#port}`);
+        console.log(`   WebSocket: ${wsProtocol}://${displayHost}:${this.#port}`);
+        console.log(`   HTTP/MCP:  ${httpProtocol}://${displayHost}:${this.#port}`);
+        resolve();
+      });
+    });
+  }
+
+  /**
+   * Returns a promise that resolves when the server is ready to accept connections.
+   * Rejects if the server fails to start (e.g., port already in use).
+   *
+   * @example
+   * ```typescript
+   * const bridge = new MCPWebBridgeNode({ name: 'My App', port: 3001 });
+   * await bridge.ready();
+   * console.log('Bridge is ready!');
+   * ```
+   */
+  ready(): Promise<void> {
+    return this.#readyPromise;
+  }
+
+  /**
+   * Whether the server is ready to accept connections.
+   */
+  get isReady(): boolean {
+    return this.#isReady;
+  }
+
+  /**
+   * Get the underlying MCPWebBridge core instance.
+   * Useful for advanced usage or custom integrations.
+   */
+  get core(): MCPWebBridge {
+    return this.#core;
+  }
+
+  /**
+   * Get the bridge handlers for custom integrations.
+   */
+  getHandlers() {
+    return this.#core.getHandlers();
+  }
+
+  /**
+   * Get the port the server is listening on.
+   */
+  get port(): number {
+    return this.#port;
+  }
+
+  /**
+   * Whether the server is using SSL/TLS (HTTPS/WSS).
+   */
+  get isSecure(): boolean {
+    return this.#isSecure;
+  }
+
+  /**
+   * Gracefully shut down the bridge.
+   */
+  async close(): Promise<void> {
+    // Close the core (cleans up sessions, timers)
+    await this.#core.close();
+
+    // Force close all WebSocket connections
+    for (const client of this.#wss.clients) {
+      client.terminate();
+    }
+
+    // Close WebSocket server with timeout
+    await Promise.race([
+      new Promise<void>((resolve) => {
+        this.#wss.close(() => resolve());
+      }),
+      new Promise<void>((resolve) => setTimeout(resolve, 1000)),
+    ]);
+
+    // Close HTTP server with timeout
+    await Promise.race([
+      new Promise<void>((resolve) => {
+        this.#server.close(() => resolve());
+      }),
+      new Promise<void>((resolve) => setTimeout(resolve, 1000)),
+    ]);
+  }
+}
+
+/**
+ * For backwards compatibility, also export as Bridge
+ * @deprecated Use MCPWebBridgeNode instead
+ */
+export const Bridge = MCPWebBridgeNode;