claude-flow 2.7.32 → 2.7.34

package/src/cli/commands/mcp.ts

@@ -6,10 +6,17 @@ import { Command } from '@cliffy/command';
 import chalk from 'chalk';
 import { logger } from '../../core/logger.js';
 import { configManager } from '../../core/config.js';
-import { MCPServer } from '../../mcp/server.js';
+import { MCPServer, type IMCPServer } from '../../mcp/server.js';
 import { eventBus } from '../../core/event-bus.js';
+import {
+  createMCPServer,
+  isMCP2025Available,
+  getServerCapabilities,
+  type ExtendedMCPConfig,
+} from '../../mcp/server-factory.js';
+import type { MCP2025Server } from '../../mcp/server-mcp-2025.js';
 
-let mcpServer: MCPServer | null = null;
+let mcpServer: IMCPServer | MCP2025Server | null = null;
 
 export const mcpCommand = new Command()
   .description('Manage MCP server and tools')
@@ -32,29 +39,95 @@ export const mcpCommand = new Command()
       .option('--transport <transport:string>', 'Transport type (stdio, http)', {
         default: 'stdio',
       })
+      .option('--mcp2025', 'Enable MCP 2025-11 features (version negotiation, async jobs, etc.)', {
+        default: false,
+      })
+      .option('--no-legacy', 'Disable legacy client support', { default: false })
       .action(async (options: any) => {
         try {
           const config = await configManager.load();
 
-          // Override with CLI options
-          const mcpConfig = {
+          // Check if MCP 2025-11 dependencies are available
+          const mcp2025Available = isMCP2025Available();
+          const enableMCP2025 = options.mcp2025 && mcp2025Available;
+
+          if (options.mcp2025 && !mcp2025Available) {
+            console.log(
+              chalk.yellow(
+                '⚠️  MCP 2025-11 dependencies not found. Install with: npm install uuid ajv ajv-formats ajv-errors'
+              )
+            );
+            console.log(chalk.yellow('   Falling back to legacy MCP server...'));
+          }
+
+          // Build extended configuration
+          const mcpConfig: ExtendedMCPConfig = {
             ...config.mcp,
             port: options.port,
             host: options.host,
             transport: options.transport,
+            features: {
+              enableMCP2025,
+              supportLegacyClients: options.legacy !== false,
+              enableVersionNegotiation: enableMCP2025,
+              enableAsyncJobs: enableMCP2025,
+              enableRegistryIntegration: false, // Opt-in via env var
+              enableSchemaValidation: enableMCP2025,
+              enableProgressiveDisclosure: true, // Phase 1 feature (always enabled)
+            },
+            mcp2025: enableMCP2025
+              ? {
+                  async: {
+                    enabled: true,
+                    maxJobs: 100,
+                    jobTTL: 3600000,
+                  },
+                  registry: {
+                    enabled: process.env.MCP_REGISTRY_ENABLED === 'true',
+                    url: process.env.MCP_REGISTRY_URL,
+                    apiKey: process.env.MCP_REGISTRY_API_KEY,
+                  },
+                  validation: {
+                    enabled: true,
+                    strictMode: false,
+                  },
+                }
+              : undefined,
           };
 
-          mcpServer = new MCPServer(mcpConfig, eventBus, logger);
+          // Create server using factory
+          mcpServer = await createMCPServer(mcpConfig, eventBus, logger, {
+            autoDetectFeatures: false, // Use explicit config
+          });
+
           await mcpServer.start();
 
+          // Get capabilities
+          const capabilities = getServerCapabilities(mcpConfig);
+
           console.log(chalk.green(`✅ MCP server started on ${options.host}:${options.port}`));
-          console.log(chalk.cyan(`📡 Server URL: http://${options.host}:${options.port}`));
-          console.log(chalk.cyan(`🔧 Available tools: Research, Code, Terminal, Memory`));
           console.log(
-            chalk.cyan(`📚 API documentation: http://${options.host}:${options.port}/docs`),
+            chalk.cyan(`🎯 Mode: ${enableMCP2025 ? 'MCP 2025-11 Enhanced' : 'Legacy Compatible'}`)
           );
+          console.log(chalk.cyan(`📡 Transport: ${options.transport}`));
+
+          if (capabilities.length > 0) {
+            console.log(chalk.cyan(`✨ Capabilities: ${capabilities.join(', ')}`));
+          }
+
+          if (enableMCP2025) {
+            console.log(chalk.green('   • Version negotiation (YYYY-MM format)'));
+            console.log(chalk.green('   • Async job support (poll/resume)'));
+            console.log(chalk.green('   • JSON Schema 1.1 validation'));
+            console.log(chalk.green('   • Progressive disclosure (98.7% token reduction)'));
+          }
+
+          if (options.transport === 'http') {
+            console.log(chalk.cyan(`📚 Server URL: http://${options.host}:${options.port}`));
+          }
         } catch (error) {
           console.error(chalk.red(`❌ Failed to start MCP server: ${(error as Error).message}`));
+          logger.error('MCP server startup failed', { error });
           process.exit(1);
         }
       }),
@@ -151,7 +224,11 @@ export const mcpCommand = new Command()
 
         console.log(chalk.yellow('🔄 Starting MCP server...'));
         const config = await configManager.load();
-        mcpServer = new MCPServer(config.mcp, eventBus, logger);
+
+        // Use factory to create server with same capabilities as before
+        mcpServer = await createMCPServer(config.mcp, eventBus, logger, {
+          autoDetectFeatures: true, // Auto-detect on restart
+        });
         await mcpServer.start();
 
         console.log(

package/src/mcp/async/job-manager-mcp25.ts

@@ -0,0 +1,456 @@
+/**
+ * MCP 2025-11 Async Job Manager
+ *
+ * Implements async job lifecycle per MCP 2025-11 specification:
+ * - Job handles with request_id
+ * - Poll/resume semantics
+ * - Progress tracking
+ * - Job persistence
+ */
+
+import { EventEmitter } from 'events';
+import { v4 as uuidv4 } from 'uuid';
+import type { ILogger } from '../../interfaces/logger.js';
+
+/**
+ * MCP tool request (2025-11 format)
+ */
+export interface MCPToolRequest {
+  request_id: string;
+  tool_id: string;
+  arguments: Record<string, any>;
+  session?: string;
+  mode: 'async' | 'sync';
+  context?: {
+    trace_id?: string;
+    client_name?: string;
+    [key: string]: any;
+  };
+}
+
+/**
+ * MCP job handle (2025-11 format)
+ */
+export interface MCPJobHandle {
+  request_id: string;
+  job_id: string;
+  status: 'in_progress' | 'success' | 'error';
+  poll_after: number; // seconds
+  progress?: {
+    percent: number;
+    message?: string;
+  };
+}
+
+/**
+ * MCP job result (2025-11 format)
+ */
+export interface MCPJobResult {
+  request_id: string;
+  status: 'success' | 'error' | 'in_progress';
+  result?: any;
+  error?: {
+    code: string;
+    message: string;
+    details?: any;
+  };
+  progress?: {
+    percent: number;
+    message?: string;
+  };
+  metadata: {
+    duration_ms?: number;
+    tokens_used?: number;
+    [key: string]: any;
+  };
+}
+
+/**
+ * Internal job state
+ */
+interface AsyncJob {
+  request_id: string;
+  job_id: string;
+  tool_id: string;
+  arguments: Record<string, any>;
+  mode: 'async' | 'sync';
+  status: 'queued' | 'running' | 'success' | 'error' | 'cancelled';
+  progress: number;
+  progress_message?: string;
+  result?: any;
+  error?: any;
+  context?: any;
+  created_at: Date;
+  started_at?: Date;
+  completed_at?: Date;
+  tokens_used?: number;
+  abortController?: AbortController;
+}
+
+/**
+ * Job persistence interface
+ */
+export interface JobPersistence {
+  save(job: AsyncJob): Promise<void>;
+  load(job_id: string): Promise<AsyncJob | null>;
+  list(filter?: { status?: string; limit?: number }): Promise<AsyncJob[]>;
+  delete(job_id: string): Promise<void>;
+}
+
+/**
+ * Simple in-memory job persistence (fallback)
+ */
+export class MemoryJobPersistence implements JobPersistence {
+  private jobs: Map<string, AsyncJob> = new Map();
+
+  async save(job: AsyncJob): Promise<void> {
+    this.jobs.set(job.job_id, { ...job });
+  }
+
+  async load(job_id: string): Promise<AsyncJob | null> {
+    const job = this.jobs.get(job_id);
+    return job ? { ...job } : null;
+  }
+
+  async list(filter?: { status?: string; limit?: number }): Promise<AsyncJob[]> {
+    let jobs = Array.from(this.jobs.values());
+
+    if (filter?.status) {
+      jobs = jobs.filter(j => j.status === filter.status);
+    }
+
+    if (filter?.limit) {
+      jobs = jobs.slice(0, filter.limit);
+    }
+
+    return jobs;
+  }
+
+  async delete(job_id: string): Promise<void> {
+    this.jobs.delete(job_id);
+  }
+}
+
+/**
+ * MCP 2025-11 Async Job Manager
+ */
+export class MCPAsyncJobManager extends EventEmitter {
+  private jobs: Map<string, AsyncJob> = new Map();
+  private executors: Map<string, Promise<any>> = new Map();
+  private persistence: JobPersistence;
+
+  constructor(
+    persistence: JobPersistence | null,
+    private logger: ILogger,
+    private config: {
+      maxJobs?: number;
+      jobTTL?: number;
+      defaultPollInterval?: number;
+    } = {}
+  ) {
+    super();
+    this.persistence = persistence || new MemoryJobPersistence();
+
+    // Default config
+    this.config.maxJobs = this.config.maxJobs || 1000;
+    this.config.jobTTL = this.config.jobTTL || 86400000; // 24 hours
+    this.config.defaultPollInterval = this.config.defaultPollInterval || 5;
+
+    // Cleanup expired jobs periodically
+    setInterval(() => this.cleanupExpiredJobs(), 3600000); // Every hour
+  }
+
+  /**
+   * Submit async job (MCP 2025-11 format)
+   */
+  async submitJob(
+    request: MCPToolRequest,
+    executor: (args: any, onProgress: (percent: number, message?: string) => void) => Promise<any>
+  ): Promise<MCPJobHandle> {
+    // Check capacity
+    if (this.jobs.size >= this.config.maxJobs!) {
+      throw new Error('Job queue full. Please try again later.');
+    }
+
+    // Check for duplicate request_id (prevent race conditions)
+    const existingJob = Array.from(this.jobs.values()).find(
+      j => j.request_id === request.request_id &&
+           (j.status === 'queued' || j.status === 'running')
+    );
+    if (existingJob) {
+      throw new Error(`Duplicate request_id: ${request.request_id}. Job already submitted.`);
+    }
+
+    // Create job
+    const job: AsyncJob = {
+      request_id: request.request_id,
+      job_id: uuidv4(),
+      tool_id: request.tool_id,
+      arguments: request.arguments,
+      mode: request.mode,
+      status: 'queued',
+      progress: 0,
+      context: request.context,
+      created_at: new Date(),
+    };
+
+    // Save to persistence
+    await this.persistence.save(job);
+    this.jobs.set(job.job_id, job);
+
+    this.logger.info('Job submitted', {
+      job_id: job.job_id,
+      request_id: job.request_id,
+      tool_id: job.tool_id,
+    });
+
+    // Start execution in background
+    this.executeJob(job, executor);
+
+    // Return job handle immediately
+    return {
+      request_id: job.request_id,
+      job_id: job.job_id,
+      status: 'in_progress',
+      poll_after: this.config.defaultPollInterval!,
+    };
+  }
+
+  /**
+   * Poll job status
+   */
+  async pollJob(job_id: string): Promise<MCPJobHandle> {
+    const job = await this.persistence.load(job_id);
+
+    if (!job) {
+      throw new Error(`Job not found: ${job_id}`);
+    }
+
+    const status = job.status === 'success' ? 'success' :
+                   job.status === 'error' ? 'error' : 'in_progress';
+
+    const handle: MCPJobHandle = {
+      request_id: job.request_id,
+      job_id: job.job_id,
+      status,
+      poll_after: status === 'in_progress' ? this.config.defaultPollInterval! : 0,
+    };
+
+    if (status === 'in_progress') {
+      handle.progress = {
+        percent: job.progress,
+        message: job.progress_message,
+      };
+    }
+
+    return handle;
+  }
+
+  /**
+   * Resume job (get results)
+   */
+  async resumeJob(job_id: string): Promise<MCPJobResult> {
+    const job = await this.persistence.load(job_id);
+
+    if (!job) {
+      throw new Error(`Job not found: ${job_id}`);
+    }
+
+    const result: MCPJobResult = {
+      request_id: job.request_id,
+      status: job.status === 'success' ? 'success' :
+              job.status === 'error' ? 'error' : 'in_progress',
+      metadata: {},
+    };
+
+    if (job.status === 'success') {
+      result.result = job.result;
+      result.metadata.duration_ms = job.completed_at && job.started_at
+        ? job.completed_at.getTime() - job.started_at.getTime()
+        : undefined;
+      result.metadata.tokens_used = job.tokens_used;
+    } else if (job.status === 'error') {
+      result.error = {
+        code: 'EXECUTION_ERROR',
+        message: job.error?.message || 'Job execution failed',
+        details: job.error,
+      };
+    } else {
+      // Still in progress
+      result.progress = {
+        percent: job.progress,
+        message: job.progress_message,
+      };
+    }
+
+    return result;
+  }
+
+  /**
+   * Cancel a running job
+   */
+  async cancelJob(job_id: string): Promise<boolean> {
+    const job = this.jobs.get(job_id);
+
+    if (!job) {
+      return false;
+    }
+
+    if (job.status === 'success' || job.status === 'error') {
+      return false; // Already finished
+    }
+
+    // Abort execution if AbortController is available
+    if (job.abortController) {
+      job.abortController.abort();
+    }
+
+    job.status = 'cancelled';
+    job.completed_at = new Date();
+    await this.persistence.save(job);
+
+    this.emit('job:cancelled', job_id);
+    this.logger.info('Job cancelled', { job_id });
+
+    return true;
+  }
+
+  /**
+   * List jobs
+   */
+  async listJobs(filter?: {
+    status?: string;
+    limit?: number;
+  }): Promise<AsyncJob[]> {
+    return await this.persistence.list(filter);
+  }
+
+  /**
+   * Execute job in background
+   */
+  private async executeJob(
+    job: AsyncJob,
+    executor: (args: any, onProgress: (percent: number, message?: string) => void) => Promise<any>
+  ): Promise<void> {
+    // Update status to running
+    job.status = 'running';
+    job.started_at = new Date();
+
+    // Create AbortController for cancellation support
+    job.abortController = new AbortController();
+
+    await this.persistence.save(job);
+
+    this.emit('job:started', job.job_id);
+    this.logger.info('Job started', { job_id: job.job_id, tool_id: job.tool_id });
+
+    try {
+      // Progress callback
+      const onProgress = (percent: number, message?: string) => {
+        job.progress = Math.min(100, Math.max(0, percent));
+        job.progress_message = message;
+        this.persistence.save(job).catch(err =>
+          this.logger.error('Failed to save progress', { job_id: job.job_id, error: err })
+        );
+        this.emit('job:progress', job.job_id, job.progress, message);
+      };
+
+      // Check if already cancelled
+      if (job.abortController.signal.aborted) {
+        throw new Error('Job cancelled before execution');
+      }
+
+      // Execute with abort support
+      const result = await executor(job.arguments, onProgress);
+
+      // Mark successful
+      job.status = 'success';
+      job.result = result;
+      job.progress = 100;
+      job.completed_at = new Date();
+      await this.persistence.save(job);
+
+      this.emit('job:completed', job.job_id, result);
+      this.logger.info('Job completed', {
+        job_id: job.job_id,
+        duration_ms: job.completed_at.getTime() - job.started_at!.getTime(),
+      });
+    } catch (error: any) {
+      // Mark failed
+      job.status = 'error';
+      job.error = {
+        message: error.message,
+        stack: error.stack,
+        code: error.code,
+      };
+      job.completed_at = new Date();
+      await this.persistence.save(job);
+
+      this.emit('job:failed', job.job_id, error);
+      this.logger.error('Job failed', {
+        job_id: job.job_id,
+        error: error.message,
+      });
+    }
+  }
+
+  /**
+   * Cleanup expired jobs
+   */
+  private async cleanupExpiredJobs(): Promise<number> {
+    const now = Date.now();
+    const jobs = await this.persistence.list();
+    let cleaned = 0;
+
+    for (const job of jobs) {
+      const age = now - job.created_at.getTime();
+
+      // Remove if expired and not running
+      if (age > this.config.jobTTL! && job.status !== 'running') {
+        await this.persistence.delete(job.job_id);
+        this.jobs.delete(job.job_id);
+        cleaned++;
+      }
+    }
+
+    if (cleaned > 0) {
+      this.logger.info('Cleaned up expired jobs', { count: cleaned });
+    }
+
+    return cleaned;
+  }
+
+  /**
+   * Get metrics
+   */
+  getMetrics() {
+    const jobs = Array.from(this.jobs.values());
+
+    return {
+      total: jobs.length,
+      byStatus: {
+        queued: jobs.filter(j => j.status === 'queued').length,
+        running: jobs.filter(j => j.status === 'running').length,
+        success: jobs.filter(j => j.status === 'success').length,
+        error: jobs.filter(j => j.status === 'error').length,
+        cancelled: jobs.filter(j => j.status === 'cancelled').length,
+      },
+      averageDuration: this.calculateAverageDuration(jobs),
+    };
+  }
+
+  private calculateAverageDuration(jobs: AsyncJob[]): number {
+    const completed = jobs.filter(j =>
+      (j.status === 'success' || j.status === 'error') &&
+      j.started_at && j.completed_at
+    );
+
+    if (completed.length === 0) return 0;
+
+    const total = completed.reduce((sum, j) =>
+      sum + (j.completed_at!.getTime() - j.started_at!.getTime()), 0
+    );
+
+    return total / completed.length;
+  }
+}

package/src/mcp/index.ts

@@ -27,6 +27,66 @@ export type { SDKIntegrationConfig } from './sdk-integration.js';
 // Core MCP Server
 export { MCPServer, type IMCPServer } from './server.js';
 
+// MCP 2025-11 Server and Components
+export { MCP2025Server, type MCP2025ServerConfig } from './server-mcp-2025.js';
+export {
+  MCPServerFactory,
+  createMCPServer,
+  isMCP2025Available,
+  getServerCapabilities,
+  type MCPFeatureFlags,
+  type ExtendedMCPConfig,
+} from './server-factory.js';
+
+// MCP 2025-11 Protocol Components
+export {
+  VersionNegotiator,
+  BackwardCompatibilityAdapter,
+  type MCPHandshake,
+  type MCPVersion,
+  type MCPCapability,
+  type NegotiationResult as MCP2025NegotiationResult,
+} from './protocol/version-negotiation.js';
+
+// MCP 2025-11 Async Job Management
+export {
+  MCPAsyncJobManager,
+  type MCPToolRequest,
+  type MCPJobHandle,
+  type MCPJobResult,
+  type AsyncJob,
+  type JobStatus,
+} from './async/job-manager-mcp25.js';
+
+// MCP 2025-11 Registry Integration
+export {
+  MCPRegistryClient,
+  type RegistryConfig,
+  type ServerRegistryEntry,
+} from './registry/mcp-registry-client-2025.js';
+
+// MCP 2025-11 Schema Validation
+export {
+  SchemaValidator,
+  upgradeToolSchema,
+  type ValidationResult,
+} from './validation/schema-validator-2025.js';
+
+// Progressive Tool Registry (Phase 1 & 2)
+export {
+  ProgressiveToolRegistry,
+  createProgressiveToolRegistry,
+  createProgressiveClaudeFlowSdkServer,
+  type ProgressiveToolRegistryConfig,
+} from './tool-registry-progressive.js';
+
+// Dynamic Tool Loader (Phase 1)
+export {
+  DynamicToolLoader,
+  type ToolMetadata,
+  type ToolSearchQuery,
+} from './tools/loader.js';
+
 // Lifecycle Management
 export {
   MCPLifecycleManager,