claude-flow 2.7.32 → 2.7.34

package/src/mcp/tools/system/status.ts

@@ -0,0 +1,206 @@
+/**
+ * System Status Tool
+ *
+ * Returns comprehensive system status including:
+ * - Uptime and version information
+ * - Active agents and tasks
+ * - Memory usage
+ * - Performance metrics
+ */
+
+import type { MCPTool, ClaudeFlowToolContext } from '../../types.js';
+import type { ILogger } from '../../../interfaces/logger.js';
+
+interface SystemStatusInput {
+  includeMetrics?: boolean;
+  includeAgents?: boolean;
+  includeTasks?: boolean;
+}
+
+interface SystemStatusResult {
+  success: boolean;
+  status: 'healthy' | 'degraded' | 'unhealthy';
+  uptime: number;
+  version: string;
+  timestamp: string;
+  agents?: {
+    total: number;
+    active: number;
+    idle: number;
+  };
+  tasks?: {
+    total: number;
+    running: number;
+    completed: number;
+    failed: number;
+  };
+  metrics?: {
+    memoryUsage: number;
+    cpuUsage: number;
+    avgResponseTime: number;
+  };
+}
+
+export function createSystemStatusTool(logger: ILogger): MCPTool {
+  return {
+    name: 'system/status',
+    description: 'Get comprehensive system status including uptime, active agents, tasks, and performance metrics. Use this to check system health.',
+
+    inputSchema: {
+      type: 'object',
+      properties: {
+        includeMetrics: {
+          type: 'boolean',
+          description: 'Include performance metrics',
+          default: false,
+        },
+        includeAgents: {
+          type: 'boolean',
+          description: 'Include agent statistics',
+          default: true,
+        },
+        includeTasks: {
+          type: 'boolean',
+          description: 'Include task statistics',
+          default: true,
+        },
+      },
+      required: [],
+    },
+
+    metadata: {
+      category: 'system',
+      tags: ['status', 'health', 'monitoring', 'metrics'],
+      examples: [
+        {
+          description: 'Get basic system status',
+          input: {},
+          expectedOutput: {
+            success: true,
+            status: 'healthy',
+            uptime: 3600000,
+            version: '2.7.32',
+          },
+        },
+        {
+          description: 'Get full system status with metrics',
+          input: {
+            includeMetrics: true,
+            includeAgents: true,
+            includeTasks: true,
+          },
+          expectedOutput: {
+            success: true,
+            status: 'healthy',
+            agents: { total: 5, active: 3, idle: 2 },
+            tasks: { total: 20, running: 5, completed: 12, failed: 3 },
+            metrics: { memoryUsage: 250, cpuUsage: 45, avgResponseTime: 150 },
+          },
+        },
+      ],
+      detailLevel: 'standard',
+    },
+
+    handler: async (
+      input: any,
+      context?: ClaudeFlowToolContext
+    ): Promise<SystemStatusResult> => {
+      if (!context?.orchestrator) {
+        throw new Error('Orchestrator not available in tool context');
+      }
+
+      const validatedInput = input as SystemStatusInput;
+
+      logger.info('system/status invoked', {
+        input: validatedInput,
+        sessionId: context.sessionId,
+      });
+
+      try {
+        // Get base status
+        const result: SystemStatusResult = {
+          success: true,
+          status: 'healthy',
+          uptime: process.uptime() * 1000, // Convert to milliseconds
+          version: process.env.npm_package_version || '2.7.32',
+          timestamp: new Date().toISOString(),
+        };
+
+        // Get agent statistics if requested
+        if (validatedInput.includeAgents !== false) {
+          try {
+            const agentStats = await context.orchestrator.getAgentStats?.();
+            if (agentStats) {
+              result.agents = {
+                total: agentStats.total || 0,
+                active: agentStats.active || 0,
+                idle: agentStats.idle || 0,
+              };
+            }
+          } catch (error) {
+            logger.warn('Failed to get agent statistics', { error });
+          }
+        }
+
+        // Get task statistics if requested
+        if (validatedInput.includeTasks !== false) {
+          try {
+            const taskStats = await context.orchestrator.getTaskStats?.();
+            if (taskStats) {
+              result.tasks = {
+                total: taskStats.total || 0,
+                running: taskStats.running || 0,
+                completed: taskStats.completed || 0,
+                failed: taskStats.failed || 0,
+              };
+            }
+          } catch (error) {
+            logger.warn('Failed to get task statistics', { error });
+          }
+        }
+
+        // Get performance metrics if requested
+        if (validatedInput.includeMetrics) {
+          try {
+            const memUsage = process.memoryUsage();
+            result.metrics = {
+              memoryUsage: Math.round(memUsage.heapUsed / 1024 / 1024), // MB
+              cpuUsage: Math.round(process.cpuUsage().user / 1000), // Approximate %
+              avgResponseTime: 0, // TODO: Get from metrics store
+            };
+          } catch (error) {
+            logger.warn('Failed to get performance metrics', { error });
+          }
+        }
+
+        // Determine overall health status
+        if (result.agents && result.agents.active === 0 && result.agents.total > 0) {
+          result.status = 'degraded';
+        }
+        if (result.tasks && result.tasks.failed > result.tasks.completed / 2) {
+          result.status = 'unhealthy';
+        }
+
+        logger.info('system/status completed successfully', {
+          status: result.status,
+          uptime: result.uptime,
+        });
+
+        return result;
+      } catch (error) {
+        logger.error('system/status failed', {
+          error,
+          input: validatedInput,
+        });
+        throw error;
+      }
+    },
+  };
+}
+
+export const toolMetadata = {
+  name: 'system/status',
+  description: 'Get system health status and metrics',
+  category: 'system',
+  detailLevel: 'standard' as const,
+};

package/src/mcp/validation/schema-validator-2025.ts

@@ -0,0 +1,294 @@
+/**
+ * JSON Schema 1.1 Validator for MCP 2025-11
+ *
+ * Implements comprehensive schema validation per MCP 2025-11 specification
+ * using JSON Schema Draft 2020-12
+ */
+
+import Ajv, { type ErrorObject } from 'ajv';
+import addFormats from 'ajv-formats';
+import addErrors from 'ajv-errors';
+import type { ILogger } from '../../interfaces/logger.js';
+
+/**
+ * Validation result
+ */
+export interface ValidationResult {
+  valid: boolean;
+  errors?: Array<{
+    path: string;
+    message: string;
+    params?: any;
+  }>;
+}
+
+/**
+ * Schema cache entry
+ */
+interface CachedSchema {
+  schema: object;
+  validate: any;
+  timestamp: number;
+}
+
+/**
+ * MCP 2025-11 JSON Schema Validator
+ *
+ * Features:
+ * - JSON Schema Draft 2020-12 support
+ * - Format validation (uri, email, date-time, etc.)
+ * - Schema caching for performance
+ * - Custom error messages
+ * - $ref support
+ */
+export class SchemaValidator {
+  private ajv: Ajv;
+  private schemaCache: Map<string, CachedSchema> = new Map();
+  private cacheTTL = 3600000; // 1 hour
+  private readonly MAX_CACHE_SIZE = 1000; // Maximum cached schemas
+
+  constructor(private logger: ILogger) {
+    this.ajv = new Ajv({
+      allErrors: true,
+      strict: true,
+      validateFormats: true,
+      allowUnionTypes: true,
+      // Support JSON Schema Draft 2020-12
+      schemaId: 'auto',
+    });
+
+    // Add format validators (email, uri, date-time, etc.)
+    addFormats(this.ajv);
+
+    // Add custom error messages support
+    addErrors(this.ajv);
+
+    this.logger.info('Schema validator initialized', {
+      draft: '2020-12',
+      formats: 'enabled',
+    });
+  }
+
+  /**
+   * Validate input against JSON Schema 1.1
+   */
+  validateInput(schema: object, input: unknown): ValidationResult {
+    try {
+      const validate = this.getValidator(schema);
+      const valid = validate(input);
+
+      if (!valid && validate.errors) {
+        return {
+          valid: false,
+          errors: this.formatErrors(validate.errors),
+        };
+      }
+
+      return { valid: true };
+    } catch (error) {
+      this.logger.error('Schema validation error', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+
+      return {
+        valid: false,
+        errors: [{
+          path: '',
+          message: 'Schema validation failed',
+        }],
+      };
+    }
+  }
+
+  /**
+   * Validate output against schema
+   */
+  validateOutput(schema: object, output: unknown): ValidationResult {
+    return this.validateInput(schema, output);
+  }
+
+  /**
+   * Validate tool schema itself
+   */
+  validateToolSchema(toolSchema: object): ValidationResult {
+    // Ensure schema has required fields
+    const requiredFields = ['$schema', 'type', 'properties'];
+    const schemaObj = toolSchema as any;
+
+    const missing = requiredFields.filter(field => !(field in schemaObj));
+    if (missing.length > 0) {
+      return {
+        valid: false,
+        errors: missing.map(field => ({
+          path: '/',
+          message: `Missing required field: ${field}`,
+        })),
+      };
+    }
+
+    // Validate schema is valid JSON Schema
+    try {
+      this.ajv.compile(toolSchema);
+      return { valid: true };
+    } catch (error) {
+      return {
+        valid: false,
+        errors: [{
+          path: '/',
+          message: error instanceof Error ? error.message : 'Invalid schema',
+        }],
+      };
+    }
+  }
+
+  /**
+   * Get or create validator for schema
+   */
+  private getValidator(schema: object): any {
+    const schemaKey = JSON.stringify(schema);
+    const cached = this.schemaCache.get(schemaKey);
+
+    // Return cached validator if still valid
+    if (cached && Date.now() - cached.timestamp < this.cacheTTL) {
+      return cached.validate;
+    }
+
+    // Compile new validator
+    try {
+      const validate = this.ajv.compile(schema);
+
+      // Enforce cache size limit (LRU eviction - remove oldest entry)
+      if (this.schemaCache.size >= this.MAX_CACHE_SIZE) {
+        const oldest = Array.from(this.schemaCache.entries())
+          .sort((a, b) => a[1].timestamp - b[1].timestamp)[0];
+
+        if (oldest) {
+          this.schemaCache.delete(oldest[0]);
+          this.logger.debug('Evicted oldest schema from cache', {
+            cacheSize: this.schemaCache.size,
+            maxSize: this.MAX_CACHE_SIZE,
+          });
+        }
+      }
+
+      // Cache for future use
+      this.schemaCache.set(schemaKey, {
+        schema,
+        validate,
+        timestamp: Date.now(),
+      });
+
+      return validate;
+    } catch (error) {
+      this.logger.error('Failed to compile schema', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+      throw error;
+    }
+  }
+
+  /**
+   * Format ajv errors to user-friendly format
+   */
+  private formatErrors(errors: ErrorObject[]): ValidationResult['errors'] {
+    return errors.map(err => ({
+      path: err.instancePath || '/',
+      message: this.getErrorMessage(err),
+      params: err.params,
+    }));
+  }
+
+  /**
+   * Get user-friendly error message
+   */
+  private getErrorMessage(error: ErrorObject): string {
+    const { keyword, message, params } = error;
+
+    switch (keyword) {
+      case 'required':
+        return `Missing required property: ${params.missingProperty}`;
+      case 'type':
+        return `Expected ${params.type} but got ${typeof params.data}`;
+      case 'format':
+        return `Invalid format for ${params.format}`;
+      case 'minimum':
+        return `Value must be >= ${params.limit}`;
+      case 'maximum':
+        return `Value must be <= ${params.limit}`;
+      case 'minLength':
+        return `String must be at least ${params.limit} characters`;
+      case 'maxLength':
+        return `String must be at most ${params.limit} characters`;
+      case 'pattern':
+        return `String must match pattern: ${params.pattern}`;
+      case 'enum':
+        return `Value must be one of: ${params.allowedValues?.join(', ')}`;
+      default:
+        return message || `Validation failed: ${keyword}`;
+    }
+  }
+
+  /**
+   * Clear schema cache
+   */
+  clearCache(): void {
+    this.schemaCache.clear();
+    this.logger.info('Schema cache cleared');
+  }
+
+  /**
+   * Get cache statistics
+   */
+  getCacheStats() {
+    return {
+      size: this.schemaCache.size,
+      entries: Array.from(this.schemaCache.values()).map(entry => ({
+        age: Date.now() - entry.timestamp,
+        expired: Date.now() - entry.timestamp > this.cacheTTL,
+      })),
+    };
+  }
+
+  /**
+   * Cleanup expired cache entries
+   */
+  cleanupCache(): number {
+    const now = Date.now();
+    let cleaned = 0;
+
+    for (const [key, entry] of this.schemaCache.entries()) {
+      if (now - entry.timestamp > this.cacheTTL) {
+        this.schemaCache.delete(key);
+        cleaned++;
+      }
+    }
+
+    if (cleaned > 0) {
+      this.logger.info('Cleaned up expired schema cache entries', { count: cleaned });
+    }
+
+    return cleaned;
+  }
+}
+
+/**
+ * Convert legacy tool schema to MCP 2025-11 format
+ */
+export function upgradeToolSchema(legacySchema: any): object {
+  // If already in 2025-11 format, return as-is
+  if (legacySchema.$schema && legacySchema.$schema.includes('2020-12')) {
+    return legacySchema;
+  }
+
+  // Convert to 2025-11 format
+  return {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    type: legacySchema.type || 'object',
+    properties: legacySchema.properties || {},
+    required: legacySchema.required || [],
+    additionalProperties: legacySchema.additionalProperties !== undefined
+      ? legacySchema.additionalProperties
+      : false,
+    description: legacySchema.description,
+  };
+}