claude-flow 2.7.33 → 2.7.34

package/src/mcp/protocol/version-negotiation.ts

@@ -0,0 +1,329 @@
+/**
+ * MCP 2025-11 Version Negotiation Protocol
+ *
+ * Implements version negotiation and capability exchange
+ * per MCP 2025-11 specification
+ */
+
+import type { ILogger } from '../../interfaces/logger.js';
+
+/**
+ * MCP version in YYYY-MM format
+ */
+export type MCPVersion = '2025-11' | '2024-11' | '2024-10';
+
+/**
+ * MCP capability flags
+ */
+export type MCPCapability =
+  | 'async'       // Job handles, poll/resume
+  | 'registry'    // Self-registration
+  | 'code_exec'   // External code execution
+  | 'stream'      // Streaming output
+  | 'sandbox'     // Isolated execution
+  | 'schema_ref'; // Shared schema references
+
+/**
+ * MCP handshake request/response
+ */
+export interface MCPHandshake {
+  mcp_version: MCPVersion;
+  client_id?: string;
+  server_id?: string;
+  transport: 'stdio' | 'http' | 'ws';
+  capabilities: MCPCapability[];
+  metadata?: {
+    name?: string;
+    version?: string;
+    description?: string;
+  };
+}
+
+/**
+ * Version negotiation result
+ */
+export interface NegotiationResult {
+  success: boolean;
+  agreed_version: MCPVersion;
+  agreed_capabilities: MCPCapability[];
+  error?: string;
+}
+
+/**
+ * Version negotiation errors
+ */
+export class VersionNegotiationError extends Error {
+  constructor(
+    message: string,
+    public code: 'VERSION_MISMATCH' | 'UNSUPPORTED_CAPABILITY' | 'INVALID_HANDSHAKE'
+  ) {
+    super(message);
+    this.name = 'VersionNegotiationError';
+  }
+}
+
+/**
+ * MCP Version Negotiator
+ *
+ * Handles version compatibility checking and capability negotiation
+ */
+export class VersionNegotiator {
+  // Supported versions in order of preference
+  private supportedVersions: MCPVersion[] = ['2025-11', '2024-11'];
+
+  // Current server version
+  private serverVersion: MCPVersion = '2025-11';
+
+  // Server capabilities
+  private serverCapabilities: MCPCapability[] = [
+    'async',
+    'registry',
+    'code_exec',
+    'stream',
+  ];
+
+  constructor(private logger: ILogger) {}
+
+  /**
+   * Negotiate version with client
+   */
+  async negotiate(clientHandshake: MCPHandshake): Promise<NegotiationResult> {
+    this.logger.info('Starting version negotiation', {
+      clientVersion: clientHandshake.mcp_version,
+      serverVersion: this.serverVersion,
+      clientCapabilities: clientHandshake.capabilities,
+    });
+
+    // Validate handshake structure
+    if (!this.isValidHandshake(clientHandshake)) {
+      return {
+        success: false,
+        agreed_version: this.serverVersion,
+        agreed_capabilities: [],
+        error: 'Invalid handshake structure',
+      };
+    }
+
+    // Check version compatibility
+    const versionResult = this.checkVersionCompatibility(clientHandshake.mcp_version);
+    if (!versionResult.compatible) {
+      return {
+        success: false,
+        agreed_version: this.serverVersion,
+        agreed_capabilities: [],
+        error: versionResult.error,
+      };
+    }
+
+    // Negotiate capabilities
+    const agreedCapabilities = this.negotiateCapabilities(
+      clientHandshake.capabilities
+    );
+
+    this.logger.info('Version negotiation successful', {
+      agreedVersion: versionResult.version,
+      agreedCapabilities,
+    });
+
+    return {
+      success: true,
+      agreed_version: versionResult.version,
+      agreed_capabilities: agreedCapabilities,
+    };
+  }
+
+  /**
+   * Check if handshake is valid
+   */
+  private isValidHandshake(handshake: MCPHandshake): boolean {
+    return !!(
+      handshake.mcp_version &&
+      handshake.transport &&
+      Array.isArray(handshake.capabilities)
+    );
+  }
+
+  /**
+   * Check version compatibility
+   */
+  private checkVersionCompatibility(clientVersion: MCPVersion): {
+    compatible: boolean;
+    version: MCPVersion;
+    error?: string;
+  } {
+    // Exact match - best case
+    if (clientVersion === this.serverVersion) {
+      return { compatible: true, version: clientVersion };
+    }
+
+    // Check if client version is supported
+    if (this.supportedVersions.includes(clientVersion)) {
+      this.logger.warn('Client using older version, but compatible', {
+        clientVersion,
+        serverVersion: this.serverVersion,
+      });
+      return { compatible: true, version: clientVersion };
+    }
+
+    // Check version gap
+    const clientDate = this.parseVersion(clientVersion);
+    const serverDate = this.parseVersion(this.serverVersion);
+    const monthsDiff = this.getMonthsDifference(clientDate, serverDate);
+
+    // Reject if more than 1 cycle (1 month) difference
+    if (Math.abs(monthsDiff) > 1) {
+      return {
+        compatible: false,
+        version: this.serverVersion,
+        error: `Version mismatch: client ${clientVersion}, server ${this.serverVersion}. Difference exceeds 1 cycle.`,
+      };
+    }
+
+    // Accept with warning for small differences
+    this.logger.warn('Version close enough, accepting', {
+      clientVersion,
+      serverVersion: this.serverVersion,
+      monthsDiff,
+    });
+    return { compatible: true, version: this.serverVersion };
+  }
+
+  /**
+   * Negotiate capabilities between client and server
+   */
+  private negotiateCapabilities(
+    clientCapabilities: MCPCapability[]
+  ): MCPCapability[] {
+    // Return intersection of client and server capabilities
+    return clientCapabilities.filter(cap =>
+      this.serverCapabilities.includes(cap)
+    );
+  }
+
+  /**
+   * Parse version string to date
+   */
+  private parseVersion(version: MCPVersion): Date {
+    const [year, month] = version.split('-').map(Number);
+    return new Date(year, month - 1, 1);
+  }
+
+  /**
+   * Calculate months difference between dates
+   */
+  private getMonthsDifference(date1: Date, date2: Date): number {
+    const months = (date2.getFullYear() - date1.getFullYear()) * 12;
+    return months + date2.getMonth() - date1.getMonth();
+  }
+
+  /**
+   * Create server handshake response
+   */
+  createServerHandshake(
+    serverId: string,
+    transport: 'stdio' | 'http' | 'ws',
+    metadata?: MCPHandshake['metadata']
+  ): MCPHandshake {
+    return {
+      mcp_version: this.serverVersion,
+      server_id: serverId,
+      transport,
+      capabilities: this.serverCapabilities,
+      metadata,
+    };
+  }
+
+  /**
+   * Get current server version
+   */
+  getServerVersion(): MCPVersion {
+    return this.serverVersion;
+  }
+
+  /**
+   * Get server capabilities
+   */
+  getServerCapabilities(): MCPCapability[] {
+    return [...this.serverCapabilities];
+  }
+
+  /**
+   * Check if capability is supported
+   */
+  hasCapability(capability: MCPCapability): boolean {
+    return this.serverCapabilities.includes(capability);
+  }
+
+  /**
+   * Add capability (dynamic capability registration)
+   */
+  addCapability(capability: MCPCapability): void {
+    if (!this.serverCapabilities.includes(capability)) {
+      this.serverCapabilities.push(capability);
+      this.logger.info('Capability added', { capability });
+    }
+  }
+
+  /**
+   * Remove capability
+   */
+  removeCapability(capability: MCPCapability): void {
+    const index = this.serverCapabilities.indexOf(capability);
+    if (index > -1) {
+      this.serverCapabilities.splice(index, 1);
+      this.logger.info('Capability removed', { capability });
+    }
+  }
+}
+
+/**
+ * Backward compatibility helper
+ * Converts legacy requests to MCP 2025-11 format
+ */
+export class BackwardCompatibilityAdapter {
+  constructor(private logger: ILogger) {}
+
+  /**
+   * Detect if request is legacy format
+   */
+  isLegacyRequest(request: any): boolean {
+    // Legacy requests don't have mcp_version field
+    return !request.mcp_version || request.version;
+  }
+
+  /**
+   * Convert legacy request to MCP 2025-11 format
+   */
+  convertToModern(legacyRequest: any): MCPHandshake {
+    this.logger.info('Converting legacy request to MCP 2025-11 format');
+
+    return {
+      mcp_version: '2025-11',
+      client_id: legacyRequest.clientId || 'legacy-client',
+      transport: legacyRequest.transport || 'stdio',
+      capabilities: legacyRequest.capabilities || [],
+      metadata: {
+        name: legacyRequest.name || 'Legacy Client',
+        version: legacyRequest.version || '1.0.0',
+      },
+    };
+  }
+
+  /**
+   * Convert modern response to legacy format if needed
+   */
+  convertToLegacy(modernResponse: any, requestedLegacy: boolean): any {
+    if (!requestedLegacy) {
+      return modernResponse;
+    }
+
+    this.logger.info('Converting response to legacy format');
+
+    return {
+      version: modernResponse.mcp_version,
+      serverId: modernResponse.server_id,
+      capabilities: modernResponse.capabilities,
+      ...modernResponse,
+    };
+  }
+}

package/src/mcp/registry/mcp-registry-client-2025.ts

@@ -0,0 +1,334 @@
+/**
+ * MCP 2025-11 Registry Client
+ *
+ * Implements server registration and health reporting
+ * per MCP 2025-11 specification
+ */
+
+import type { ILogger } from '../../interfaces/logger.js';
+import type { MCPVersion, MCPCapability } from '../protocol/version-negotiation.js';
+
+/**
+ * MCP Registry entry (2025-11 format)
+ */
+export interface MCPRegistryEntry {
+  server_id: string;
+  version: MCPVersion;
+  endpoint: string;
+  tools: string[];
+  auth: 'bearer' | 'mutual_tls' | 'none';
+  capabilities: MCPCapability[];
+  metadata: {
+    name: string;
+    description: string;
+    author: string;
+    homepage?: string;
+    documentation?: string;
+    repository?: string;
+  };
+  health: {
+    status: 'healthy' | 'degraded' | 'unhealthy';
+    last_check: string; // ISO 8601
+    latency_ms: number;
+  };
+}
+
+/**
+ * Registry search query
+ */
+export interface RegistrySearchQuery {
+  category?: string;
+  tags?: string[];
+  capabilities?: MCPCapability[];
+  limit?: number;
+}
+
+/**
+ * Registry configuration
+ */
+export interface RegistryConfig {
+  enabled: boolean;
+  registryUrl?: string;
+  apiKey?: string;
+  serverId: string;
+  serverEndpoint: string;
+  authMethod: 'bearer' | 'mutual_tls' | 'none';
+  metadata: MCPRegistryEntry['metadata'];
+  healthCheckInterval?: number; // milliseconds
+}
+
+/**
+ * MCP 2025-11 Registry Client
+ */
+export class MCPRegistryClient {
+  private registryUrl: string;
+  private healthCheckInterval?: NodeJS.Timeout;
+
+  constructor(
+    private config: RegistryConfig,
+    private logger: ILogger,
+    private getTools: () => Promise<string[]>,
+    private getCapabilities: () => MCPCapability[],
+    private getHealth: () => Promise<{ status: 'healthy' | 'degraded' | 'unhealthy'; latency_ms: number }>
+  ) {
+    this.registryUrl = config.registryUrl || 'https://registry.mcp.anthropic.com/api/v1';
+  }
+
+  /**
+   * Register server with MCP Registry
+   */
+  async register(): Promise<void> {
+    if (!this.config.enabled) {
+      this.logger.info('Registry registration disabled');
+      return;
+    }
+
+    try {
+      const entry = await this.buildRegistryEntry();
+
+      this.logger.info('Registering server with MCP Registry', {
+        server_id: entry.server_id,
+        endpoint: entry.endpoint,
+        capabilities: entry.capabilities,
+      });
+
+      const response = await fetch(`${this.registryUrl}/servers`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          ...(this.config.apiKey && {
+            'Authorization': `Bearer ${this.config.apiKey}`,
+          }),
+        },
+        body: JSON.stringify(entry),
+      });
+
+      if (!response.ok) {
+        const error = await response.text();
+        throw new Error(`Registration failed: ${response.status} - ${error}`);
+      }
+
+      const result = await response.json();
+      this.logger.info('Server registered successfully', {
+        server_id: result.server_id,
+      });
+
+      // Start periodic health reporting
+      this.startHealthReporting();
+    } catch (error) {
+      this.logger.error('Failed to register with MCP Registry', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+      throw error;
+    }
+  }
+
+  /**
+   * Update server metadata in registry
+   */
+  async updateMetadata(updates: Partial<MCPRegistryEntry>): Promise<void> {
+    if (!this.config.enabled) {
+      return;
+    }
+
+    try {
+      this.logger.info('Updating server metadata in registry', {
+        server_id: this.config.serverId,
+      });
+
+      const response = await fetch(
+        `${this.registryUrl}/servers/${this.config.serverId}`,
+        {
+          method: 'PATCH',
+          headers: {
+            'Content-Type': 'application/json',
+            ...(this.config.apiKey && {
+              'Authorization': `Bearer ${this.config.apiKey}`,
+            }),
+          },
+          body: JSON.stringify(updates),
+        }
+      );
+
+      if (!response.ok) {
+        const error = await response.text();
+        throw new Error(`Update failed: ${response.status} - ${error}`);
+      }
+
+      this.logger.info('Server metadata updated successfully');
+    } catch (error) {
+      this.logger.error('Failed to update metadata', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  /**
+   * Report health status to registry
+   */
+  async reportHealth(): Promise<void> {
+    if (!this.config.enabled) {
+      return;
+    }
+
+    try {
+      const health = await this.getHealth();
+
+      const response = await fetch(
+        `${this.registryUrl}/servers/${this.config.serverId}/health`,
+        {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            ...(this.config.apiKey && {
+              'Authorization': `Bearer ${this.config.apiKey}`,
+            }),
+          },
+          body: JSON.stringify({
+            status: health.status,
+            last_check: new Date().toISOString(),
+            latency_ms: health.latency_ms,
+          }),
+        }
+      );
+
+      if (!response.ok) {
+        this.logger.warn('Health report failed', {
+          status: response.status,
+        });
+      }
+    } catch (error) {
+      this.logger.error('Failed to report health', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  /**
+   * Search for servers in registry
+   */
+  async searchServers(query: RegistrySearchQuery): Promise<MCPRegistryEntry[]> {
+    try {
+      const params = new URLSearchParams();
+
+      if (query.category) {
+        params.set('category', query.category);
+      }
+      if (query.tags) {
+        params.set('tags', query.tags.join(','));
+      }
+      if (query.capabilities) {
+        params.set('capabilities', query.capabilities.join(','));
+      }
+      if (query.limit) {
+        params.set('limit', query.limit.toString());
+      }
+
+      const response = await fetch(`${this.registryUrl}/servers?${params}`);
+
+      if (!response.ok) {
+        throw new Error(`Search failed: ${response.status}`);
+      }
+
+      const results = await response.json();
+      return results.servers || [];
+    } catch (error) {
+      this.logger.error('Failed to search servers', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return [];
+    }
+  }
+
+  /**
+   * Unregister from registry
+   */
+  async unregister(): Promise<void> {
+    if (!this.config.enabled) {
+      return;
+    }
+
+    // Stop health reporting
+    this.stopHealthReporting();
+
+    try {
+      this.logger.info('Unregistering from MCP Registry', {
+        server_id: this.config.serverId,
+      });
+
+      const response = await fetch(
+        `${this.registryUrl}/servers/${this.config.serverId}`,
+        {
+          method: 'DELETE',
+          headers: {
+            ...(this.config.apiKey && {
+              'Authorization': `Bearer ${this.config.apiKey}`,
+            }),
+          },
+        }
+      );
+
+      if (!response.ok) {
+        this.logger.warn('Unregistration failed', {
+          status: response.status,
+        });
+      } else {
+        this.logger.info('Server unregistered successfully');
+      }
+    } catch (error) {
+      this.logger.error('Failed to unregister', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  /**
+   * Build registry entry from current server state
+   */
+  private async buildRegistryEntry(): Promise<MCPRegistryEntry> {
+    const tools = await this.getTools();
+    const capabilities = this.getCapabilities();
+    const health = await this.getHealth();
+
+    return {
+      server_id: this.config.serverId,
+      version: '2025-11',
+      endpoint: this.config.serverEndpoint,
+      tools,
+      auth: this.config.authMethod,
+      capabilities,
+      metadata: this.config.metadata,
+      health: {
+        status: health.status,
+        last_check: new Date().toISOString(),
+        latency_ms: health.latency_ms,
+      },
+    };
+  }
+
+  /**
+   * Start periodic health reporting
+   */
+  private startHealthReporting(): void {
+    const interval = this.config.healthCheckInterval || 60000; // Default: 60 seconds
+
+    this.healthCheckInterval = setInterval(async () => {
+      await this.reportHealth();
+    }, interval);
+
+    this.logger.info('Health reporting started', {
+      interval_ms: interval,
+    });
+  }
+
+  /**
+   * Stop health reporting
+   */
+  private stopHealthReporting(): void {
+    if (this.healthCheckInterval) {
+      clearInterval(this.healthCheckInterval);
+      this.healthCheckInterval = undefined;
+      this.logger.info('Health reporting stopped');
+    }
+  }
+}