@sparkleideas/shared 3.0.0-alpha.7

package/src/mcp/transport/index.ts

@@ -0,0 +1,294 @@
+/**
+ * V3 MCP Transport Factory
+ *
+ * Central factory for creating transport instances:
+ * - Unified transport creation API
+ * - Transport type validation
+ * - Configuration defaults
+ * - Multi-transport support
+ *
+ * Supported transports:
+ * - stdio: Standard I/O (default for CLI)
+ * - http: HTTP/REST with WebSocket upgrade
+ * - websocket: Standalone WebSocket
+ * - in-process: Direct function calls (fastest)
+ */
+
+import {
+  ITransport,
+  TransportType,
+  TransportHealthStatus,
+  ILogger,
+} from '../types.js';
+import { StdioTransport, StdioTransportConfig, createStdioTransport } from './stdio.js';
+import { HttpTransport, HttpTransportConfig, createHttpTransport } from './http.js';
+import { WebSocketTransport, WebSocketTransportConfig, createWebSocketTransport } from './websocket.js';
+
+// Re-export transport classes (values)
+export { StdioTransport } from './stdio.js';
+export { HttpTransport } from './http.js';
+export { WebSocketTransport } from './websocket.js';
+
+// Re-export transport config types
+export type { StdioTransportConfig } from './stdio.js';
+export type { HttpTransportConfig } from './http.js';
+export type { WebSocketTransportConfig } from './websocket.js';
+
+/**
+ * Transport configuration union
+ */
+export type TransportConfig =
+  | { type: 'stdio' } & StdioTransportConfig
+  | { type: 'http' } & HttpTransportConfig
+  | { type: 'websocket' } & WebSocketTransportConfig
+  | { type: 'in-process' };
+
+/**
+ * Create a transport instance based on type
+ */
+export function createTransport(
+  type: TransportType,
+  logger: ILogger,
+  config?: Partial<TransportConfig>
+): ITransport {
+  switch (type) {
+    case 'stdio':
+      return createStdioTransport(logger, config as StdioTransportConfig);
+
+    case 'http':
+      if (!config || !('host' in config) || !('port' in config)) {
+        throw new Error('HTTP transport requires host and port configuration');
+      }
+      return createHttpTransport(logger, {
+        host: config.host as string,
+        port: config.port as number,
+        ...config,
+      } as HttpTransportConfig);
+
+    case 'websocket':
+      if (!config || !('host' in config) || !('port' in config)) {
+        throw new Error('WebSocket transport requires host and port configuration');
+      }
+      return createWebSocketTransport(logger, {
+        host: config.host as string,
+        port: config.port as number,
+        ...config,
+      } as WebSocketTransportConfig);
+
+    case 'in-process':
+      // In-process transport is handled directly by the server
+      // Return a no-op transport wrapper
+      return createInProcessTransport(logger);
+
+    default:
+      throw new Error(`Unknown transport type: ${type}`);
+  }
+}
+
+/**
+ * In-process transport (no-op wrapper)
+ *
+ * Used when tools are executed directly without network transport
+ */
+class InProcessTransport implements ITransport {
+  public readonly type: TransportType = 'in-process';
+
+  constructor(private readonly logger: ILogger) {}
+
+  async start(): Promise<void> {
+    this.logger.debug('In-process transport started');
+  }
+
+  async stop(): Promise<void> {
+    this.logger.debug('In-process transport stopped');
+  }
+
+  onRequest(): void {
+    // No-op - requests are handled directly
+  }
+
+  onNotification(): void {
+    // No-op - notifications are handled directly
+  }
+
+  async getHealthStatus(): Promise<TransportHealthStatus> {
+    return {
+      healthy: true,
+      metrics: {
+        latency: 0,
+        connections: 1,
+      },
+    };
+  }
+}
+
+/**
+ * Create in-process transport
+ */
+export function createInProcessTransport(logger: ILogger): ITransport {
+  return new InProcessTransport(logger);
+}
+
+/**
+ * Transport manager for multi-transport scenarios
+ */
+export class TransportManager {
+  private transports: Map<string, ITransport> = new Map();
+  private running = false;
+
+  constructor(private readonly logger: ILogger) {}
+
+  /**
+   * Add a transport
+   */
+  addTransport(name: string, transport: ITransport): void {
+    if (this.transports.has(name)) {
+      throw new Error(`Transport "${name}" already exists`);
+    }
+    this.transports.set(name, transport);
+    this.logger.debug('Transport added', { name, type: transport.type });
+  }
+
+  /**
+   * Remove a transport
+   */
+  async removeTransport(name: string): Promise<boolean> {
+    const transport = this.transports.get(name);
+    if (!transport) {
+      return false;
+    }
+
+    await transport.stop();
+    this.transports.delete(name);
+    this.logger.debug('Transport removed', { name });
+    return true;
+  }
+
+  /**
+   * Get a transport by name
+   */
+  getTransport(name: string): ITransport | undefined {
+    return this.transports.get(name);
+  }
+
+  /**
+   * Get all transport names
+   */
+  getTransportNames(): string[] {
+    return Array.from(this.transports.keys());
+  }
+
+  /**
+   * Start all transports
+   */
+  async startAll(): Promise<void> {
+    if (this.running) {
+      throw new Error('TransportManager already running');
+    }
+
+    this.logger.info('Starting all transports', { count: this.transports.size });
+
+    const startPromises = Array.from(this.transports.entries()).map(
+      async ([name, transport]) => {
+        try {
+          await transport.start();
+          this.logger.info('Transport started', { name, type: transport.type });
+        } catch (error) {
+          this.logger.error('Failed to start transport', { name, error });
+          throw error;
+        }
+      }
+    );
+
+    await Promise.all(startPromises);
+    this.running = true;
+    this.logger.info('All transports started');
+  }
+
+  /**
+   * Stop all transports
+   */
+  async stopAll(): Promise<void> {
+    if (!this.running) {
+      return;
+    }
+
+    this.logger.info('Stopping all transports');
+
+    const stopPromises = Array.from(this.transports.entries()).map(
+      async ([name, transport]) => {
+        try {
+          await transport.stop();
+          this.logger.info('Transport stopped', { name });
+        } catch (error) {
+          this.logger.error('Error stopping transport', { name, error });
+        }
+      }
+    );
+
+    await Promise.all(stopPromises);
+    this.running = false;
+    this.logger.info('All transports stopped');
+  }
+
+  /**
+   * Get health status of all transports
+   */
+  async getHealthStatus(): Promise<Record<string, { healthy: boolean; error?: string }>> {
+    const results: Record<string, { healthy: boolean; error?: string }> = {};
+
+    for (const [name, transport] of this.transports) {
+      try {
+        const status = await transport.getHealthStatus();
+        results[name] = { healthy: status.healthy, error: status.error };
+      } catch (error) {
+        results[name] = {
+          healthy: false,
+          error: error instanceof Error ? error.message : 'Unknown error',
+        };
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Check if any transport is running
+   */
+  isRunning(): boolean {
+    return this.running;
+  }
+}
+
+/**
+ * Create a transport manager
+ */
+export function createTransportManager(logger: ILogger): TransportManager {
+  return new TransportManager(logger);
+}
+
+/**
+ * Default transport configurations
+ */
+export const DEFAULT_TRANSPORT_CONFIGS = {
+  stdio: {} as StdioTransportConfig,
+
+  http: {
+    host: 'localhost',
+    port: 3000,
+    corsEnabled: true,
+    corsOrigins: ['*'],
+    maxRequestSize: '10mb',
+    requestTimeout: 30000,
+  } as HttpTransportConfig,
+
+  websocket: {
+    host: 'localhost',
+    port: 3001,
+    path: '/ws',
+    maxConnections: 100,
+    heartbeatInterval: 30000,
+    heartbeatTimeout: 10000,
+    maxMessageSize: 10 * 1024 * 1024,
+  } as WebSocketTransportConfig,
+} as const;

package/src/mcp/transport/stdio.ts

@@ -0,0 +1,324 @@
+/**
+ * V3 MCP Stdio Transport
+ *
+ * Standard I/O transport for MCP communication:
+ * - Optimized JSON parsing with streaming
+ * - Buffer management for large messages
+ * - Graceful shutdown handling
+ *
+ * Performance Targets:
+ * - Message parsing: <5ms
+ * - Response sending: <2ms
+ */
+
+import { EventEmitter } from 'events';
+import * as readline from 'readline';
+import {
+  ITransport,
+  TransportType,
+  MCPRequest,
+  MCPResponse,
+  MCPNotification,
+  RequestHandler,
+  NotificationHandler,
+  TransportHealthStatus,
+  ILogger,
+} from '../types.js';
+
+/**
+ * Stdio Transport Configuration
+ */
+export interface StdioTransportConfig {
+  inputStream?: NodeJS.ReadableStream;
+  outputStream?: NodeJS.WritableStream;
+  maxMessageSize?: number;
+}
+
+/**
+ * Stdio Transport Implementation
+ *
+ * Uses readline for efficient line-by-line processing of JSON-RPC messages
+ */
+export class StdioTransport extends EventEmitter implements ITransport {
+  public readonly type: TransportType = 'stdio';
+
+  private requestHandler?: RequestHandler;
+  private notificationHandler?: NotificationHandler;
+  private rl?: readline.Interface;
+  private running = false;
+  private messageBuffer = '';
+
+  // Statistics
+  private messagesReceived = 0;
+  private messagesSent = 0;
+  private errors = 0;
+
+  private readonly inputStream: NodeJS.ReadableStream;
+  private readonly outputStream: NodeJS.WritableStream;
+  private readonly maxMessageSize: number;
+
+  constructor(
+    private readonly logger: ILogger,
+    config: StdioTransportConfig = {}
+  ) {
+    super();
+    this.inputStream = config.inputStream || process.stdin;
+    this.outputStream = config.outputStream || process.stdout;
+    this.maxMessageSize = config.maxMessageSize || 10 * 1024 * 1024; // 10MB default
+  }
+
+  /**
+   * Start the transport
+   */
+  async start(): Promise<void> {
+    if (this.running) {
+      throw new Error('Stdio transport already running');
+    }
+
+    this.logger.info('Starting stdio transport');
+
+    // Create readline interface for efficient line processing
+    this.rl = readline.createInterface({
+      input: this.inputStream,
+      crlfDelay: Infinity,
+    });
+
+    // Handle incoming lines
+    this.rl.on('line', (line) => {
+      this.handleLine(line);
+    });
+
+    // Handle close
+    this.rl.on('close', () => {
+      this.handleClose();
+    });
+
+    // Handle errors on input stream
+    this.inputStream.on('error', (error) => {
+      this.handleError(error);
+    });
+
+    this.running = true;
+    this.logger.info('Stdio transport started');
+  }
+
+  /**
+   * Stop the transport
+   */
+  async stop(): Promise<void> {
+    if (!this.running) {
+      return;
+    }
+
+    this.logger.info('Stopping stdio transport');
+    this.running = false;
+
+    if (this.rl) {
+      this.rl.close();
+      this.rl = undefined;
+    }
+
+    this.logger.info('Stdio transport stopped');
+  }
+
+  /**
+   * Register request handler
+   */
+  onRequest(handler: RequestHandler): void {
+    this.requestHandler = handler;
+  }
+
+  /**
+   * Register notification handler
+   */
+  onNotification(handler: NotificationHandler): void {
+    this.notificationHandler = handler;
+  }
+
+  /**
+   * Get health status
+   */
+  async getHealthStatus(): Promise<TransportHealthStatus> {
+    return {
+      healthy: this.running,
+      metrics: {
+        messagesReceived: this.messagesReceived,
+        messagesSent: this.messagesSent,
+        errors: this.errors,
+      },
+    };
+  }
+
+  /**
+   * Handle incoming line
+   */
+  private async handleLine(line: string): Promise<void> {
+    if (!line.trim()) {
+      return;
+    }
+
+    // Check message size
+    if (line.length > this.maxMessageSize) {
+      this.logger.error('Message exceeds maximum size', {
+        size: line.length,
+        max: this.maxMessageSize,
+      });
+      this.errors++;
+      return;
+    }
+
+    try {
+      const message = JSON.parse(line);
+      this.messagesReceived++;
+
+      // Validate JSON-RPC format
+      if (message.jsonrpc !== '2.0') {
+        this.logger.warn('Invalid JSON-RPC version', { received: message.jsonrpc });
+        await this.sendError(message.id, -32600, 'Invalid JSON-RPC version');
+        return;
+      }
+
+      if (!message.method) {
+        this.logger.warn('Missing method in request');
+        await this.sendError(message.id, -32600, 'Missing method');
+        return;
+      }
+
+      // Determine if this is a request or notification
+      if (message.id !== undefined) {
+        // Request - needs response
+        await this.handleRequest(message as MCPRequest);
+      } else {
+        // Notification - no response needed
+        await this.handleNotification(message as MCPNotification);
+      }
+    } catch (error) {
+      this.errors++;
+      this.logger.error('Failed to parse message', { error, line: line.substring(0, 100) });
+      await this.sendError(null, -32700, 'Parse error');
+    }
+  }
+
+  /**
+   * Handle MCP request
+   */
+  private async handleRequest(request: MCPRequest): Promise<void> {
+    if (!this.requestHandler) {
+      this.logger.warn('No request handler registered');
+      await this.sendError(request.id, -32603, 'No request handler');
+      return;
+    }
+
+    try {
+      const startTime = performance.now();
+      const response = await this.requestHandler(request);
+      const duration = performance.now() - startTime;
+
+      this.logger.debug('Request processed', {
+        method: request.method,
+        duration: `${duration.toFixed(2)}ms`,
+      });
+
+      await this.sendResponse(response);
+    } catch (error) {
+      this.logger.error('Request handler error', { method: request.method, error });
+      await this.sendError(
+        request.id,
+        -32603,
+        error instanceof Error ? error.message : 'Internal error'
+      );
+    }
+  }
+
+  /**
+   * Handle MCP notification
+   */
+  private async handleNotification(notification: MCPNotification): Promise<void> {
+    if (!this.notificationHandler) {
+      this.logger.debug('Notification received but no handler', { method: notification.method });
+      return;
+    }
+
+    try {
+      await this.notificationHandler(notification);
+    } catch (error) {
+      this.logger.error('Notification handler error', { method: notification.method, error });
+      // Notifications don't send error responses
+    }
+  }
+
+  /**
+   * Send response to stdout
+   */
+  private async sendResponse(response: MCPResponse): Promise<void> {
+    const json = JSON.stringify(response);
+    await this.write(json);
+    this.messagesSent++;
+  }
+
+  /**
+   * Send error response
+   */
+  private async sendError(id: string | number | null, code: number, message: string): Promise<void> {
+    const response: MCPResponse = {
+      jsonrpc: '2.0',
+      id,
+      error: { code, message },
+    };
+    await this.sendResponse(response);
+    this.errors++;
+  }
+
+  /**
+   * Send notification to stdout
+   */
+  async sendNotification(notification: MCPNotification): Promise<void> {
+    const json = JSON.stringify(notification);
+    await this.write(json);
+    this.messagesSent++;
+  }
+
+  /**
+   * Write to output stream
+   */
+  private write(data: string): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.outputStream.write(data + '\n', (error) => {
+        if (error) {
+          this.errors++;
+          reject(error);
+        } else {
+          resolve();
+        }
+      });
+    });
+  }
+
+  /**
+   * Handle stream close
+   */
+  private handleClose(): void {
+    this.logger.info('Stdio stream closed');
+    this.running = false;
+    this.emit('close');
+  }
+
+  /**
+   * Handle stream error
+   */
+  private handleError(error: Error): void {
+    this.logger.error('Stdio stream error', error);
+    this.errors++;
+    this.emit('error', error);
+  }
+}
+
+/**
+ * Create stdio transport
+ */
+export function createStdioTransport(
+  logger: ILogger,
+  config: StdioTransportConfig = {}
+): StdioTransport {
+  return new StdioTransport(logger, config);
+}