claude-flow 3.28.0 → 3.30.0

package/v3/@claude-flow/shared/dist/mcp/types.d.ts

@@ -0,0 +1,436 @@
+/**
+ * V3 MCP Types and Interfaces
+ *
+ * Optimized type definitions for the V3 MCP server with:
+ * - Strict typing for performance
+ * - Connection pooling types
+ * - Transport layer abstractions
+ * - Tool registry interfaces
+ *
+ * Performance Targets:
+ * - Server startup: <400ms
+ * - Tool registration: <10ms
+ * - Tool execution: <50ms overhead
+ */
+/**
+ * JSON-RPC 2.0 Protocol Version
+ */
+export type JsonRpcVersion = '2.0';
+/**
+ * MCP Protocol Version. Per the [MCP spec](https://spec.modelcontextprotocol.io/specification/basic/lifecycle/#initialization)
+ * this must be a `YYYY-MM-DD` date string (e.g. `'2024-11-05'`, `'2025-06-18'`).
+ * Claude Code's Zod validator rejects any other shape (#1874).
+ */
+export type MCPProtocolVersion = string;
+/**
+ * MCP Request ID (can be string, number, or null)
+ */
+export type RequestId = string | number | null;
+/**
+ * Base MCP Message
+ */
+export interface MCPMessage {
+    jsonrpc: JsonRpcVersion;
+}
+/**
+ * MCP Request
+ */
+export interface MCPRequest extends MCPMessage {
+    id: RequestId;
+    method: string;
+    params?: Record<string, unknown>;
+}
+/**
+ * MCP Notification (request without id)
+ */
+export interface MCPNotification extends MCPMessage {
+    method: string;
+    params?: Record<string, unknown>;
+}
+/**
+ * MCP Error
+ */
+export interface MCPError {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+/**
+ * MCP Response
+ */
+export interface MCPResponse extends MCPMessage {
+    id: RequestId;
+    result?: unknown;
+    error?: MCPError;
+}
+/**
+ * Transport type options
+ */
+export type TransportType = 'stdio' | 'http' | 'websocket' | 'in-process';
+/**
+ * Authentication method
+ */
+export type AuthMethod = 'token' | 'oauth' | 'api-key' | 'none';
+/**
+ * Authentication configuration
+ */
+export interface AuthConfig {
+    enabled: boolean;
+    method: AuthMethod;
+    tokens?: string[];
+    apiKeys?: string[];
+    jwtSecret?: string;
+    oauth?: {
+        clientId: string;
+        clientSecret: string;
+        authorizationUrl: string;
+        tokenUrl: string;
+    };
+}
+/**
+ * Load balancer configuration
+ */
+export interface LoadBalancerConfig {
+    enabled: boolean;
+    maxConcurrentRequests: number;
+    rateLimit?: {
+        requestsPerSecond: number;
+        burstSize: number;
+    };
+    circuitBreaker?: {
+        failureThreshold: number;
+        resetTimeout: number;
+    };
+}
+/**
+ * Connection pool configuration
+ */
+export interface ConnectionPoolConfig {
+    maxConnections: number;
+    minConnections: number;
+    idleTimeout: number;
+    acquireTimeout: number;
+    maxWaitingClients: number;
+    evictionRunInterval: number;
+}
+/**
+ * MCP Server configuration
+ */
+export interface MCPServerConfig {
+    name: string;
+    version: string;
+    transport: TransportType;
+    host?: string;
+    port?: number;
+    tlsEnabled?: boolean;
+    tlsCert?: string;
+    tlsKey?: string;
+    auth?: AuthConfig;
+    loadBalancer?: LoadBalancerConfig;
+    connectionPool?: ConnectionPoolConfig;
+    corsEnabled?: boolean;
+    corsOrigins?: string[];
+    maxRequestSize?: number;
+    requestTimeout?: number;
+    enableMetrics?: boolean;
+    enableCaching?: boolean;
+    cacheTTL?: number;
+    logLevel?: 'debug' | 'info' | 'warn' | 'error';
+}
+/**
+ * MCP Session state
+ */
+export type SessionState = 'created' | 'initializing' | 'ready' | 'closing' | 'closed' | 'error';
+/**
+ * MCP Session
+ */
+export interface MCPSession {
+    id: string;
+    state: SessionState;
+    transport: TransportType;
+    createdAt: Date;
+    lastActivityAt: Date;
+    isInitialized: boolean;
+    isAuthenticated: boolean;
+    clientInfo?: MCPClientInfo;
+    protocolVersion?: MCPProtocolVersion;
+    capabilities?: MCPCapabilities;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Client information from initialization
+ */
+export interface MCPClientInfo {
+    name: string;
+    version: string;
+}
+/**
+ * MCP Capabilities
+ */
+export interface MCPCapabilities {
+    logging?: {
+        level: 'debug' | 'info' | 'warn' | 'error';
+    };
+    tools?: {
+        listChanged: boolean;
+    };
+    resources?: {
+        listChanged: boolean;
+        subscribe: boolean;
+    };
+    prompts?: {
+        listChanged: boolean;
+    };
+    experimental?: Record<string, unknown>;
+}
+/**
+ * Initialize request parameters
+ */
+export interface MCPInitializeParams {
+    protocolVersion: MCPProtocolVersion;
+    capabilities: MCPCapabilities;
+    clientInfo: MCPClientInfo;
+}
+/**
+ * Initialize response result
+ */
+export interface MCPInitializeResult {
+    protocolVersion: MCPProtocolVersion;
+    capabilities: MCPCapabilities;
+    serverInfo: {
+        name: string;
+        version: string;
+    };
+    instructions?: string;
+}
+/**
+ * JSON Schema type for tool input
+ */
+export interface JSONSchema {
+    type: string;
+    properties?: Record<string, JSONSchema>;
+    required?: string[];
+    items?: JSONSchema;
+    enum?: string[];
+    description?: string;
+    default?: unknown;
+    minimum?: number;
+    maximum?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    additionalProperties?: boolean | JSONSchema;
+}
+/**
+ * Tool execution context
+ */
+export interface ToolContext {
+    sessionId: string;
+    requestId?: RequestId;
+    orchestrator?: unknown;
+    swarmCoordinator?: unknown;
+    agentManager?: unknown;
+    resourceManager?: unknown;
+    messageBus?: unknown;
+    monitor?: unknown;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Tool handler function type
+ */
+export type ToolHandler<TInput = unknown, TOutput = unknown> = (input: TInput, context?: ToolContext) => Promise<TOutput>;
+/**
+ * MCP Tool definition
+ */
+export interface MCPTool<TInput = unknown, TOutput = unknown> {
+    name: string;
+    description: string;
+    inputSchema: JSONSchema;
+    handler: ToolHandler<TInput, TOutput>;
+    category?: string;
+    tags?: string[];
+    version?: string;
+    deprecated?: boolean;
+    cacheable?: boolean;
+    cacheTTL?: number;
+    timeout?: number;
+}
+/**
+ * Tool call result
+ */
+export interface ToolCallResult {
+    content: Array<{
+        type: 'text' | 'image' | 'resource';
+        text?: string;
+        data?: string;
+        mimeType?: string;
+    }>;
+    isError: boolean;
+}
+/**
+ * Tool registration options
+ */
+export interface ToolRegistrationOptions {
+    override?: boolean;
+    validate?: boolean;
+    preload?: boolean;
+}
+/**
+ * Request handler function type
+ */
+export type RequestHandler = (request: MCPRequest) => Promise<MCPResponse>;
+/**
+ * Notification handler function type
+ */
+export type NotificationHandler = (notification: MCPNotification) => Promise<void>;
+/**
+ * Transport health status
+ */
+export interface TransportHealthStatus {
+    healthy: boolean;
+    error?: string;
+    metrics?: Record<string, number>;
+}
+/**
+ * Transport interface
+ */
+export interface ITransport {
+    readonly type: TransportType;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    onRequest(handler: RequestHandler): void;
+    onNotification(handler: NotificationHandler): void;
+    sendNotification?(notification: MCPNotification): Promise<void>;
+    getHealthStatus(): Promise<TransportHealthStatus>;
+}
+/**
+ * Connection state
+ */
+export type ConnectionState = 'idle' | 'busy' | 'closing' | 'closed' | 'error';
+/**
+ * Pooled connection
+ */
+export interface PooledConnection {
+    id: string;
+    state: ConnectionState;
+    createdAt: Date;
+    lastUsedAt: Date;
+    useCount: number;
+    transport: TransportType;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Connection pool statistics
+ */
+export interface ConnectionPoolStats {
+    totalConnections: number;
+    idleConnections: number;
+    busyConnections: number;
+    pendingRequests: number;
+    totalAcquired: number;
+    totalReleased: number;
+    totalCreated: number;
+    totalDestroyed: number;
+    avgAcquireTime: number;
+}
+/**
+ * Connection pool interface
+ */
+export interface IConnectionPool {
+    acquire(): Promise<PooledConnection>;
+    release(connection: PooledConnection): void;
+    destroy(connection: PooledConnection): void;
+    getStats(): ConnectionPoolStats;
+    drain(): Promise<void>;
+    clear(): Promise<void>;
+}
+/**
+ * Tool call metrics
+ */
+export interface ToolCallMetrics {
+    toolName: string;
+    duration: number;
+    success: boolean;
+    timestamp: number;
+    transport: TransportType;
+    cached?: boolean;
+}
+/**
+ * MCP Server metrics
+ */
+export interface MCPServerMetrics {
+    totalRequests: number;
+    successfulRequests: number;
+    failedRequests: number;
+    averageResponseTime: number;
+    activeSessions: number;
+    toolInvocations: Record<string, number>;
+    errors: Record<string, number>;
+    lastReset: Date;
+    startupTime?: number;
+    uptime?: number;
+}
+/**
+ * Session metrics
+ */
+export interface SessionMetrics {
+    total: number;
+    active: number;
+    authenticated: number;
+    expired: number;
+}
+/**
+ * MCP Event types
+ */
+export type MCPEventType = 'server:started' | 'server:stopped' | 'server:error' | 'session:created' | 'session:initialized' | 'session:closed' | 'session:error' | 'tool:registered' | 'tool:unregistered' | 'tool:called' | 'tool:completed' | 'tool:error' | 'transport:connected' | 'transport:disconnected' | 'transport:error' | 'pool:connection:acquired' | 'pool:connection:released' | 'pool:connection:created' | 'pool:connection:destroyed';
+/**
+ * MCP Event
+ */
+export interface MCPEvent {
+    type: MCPEventType;
+    timestamp: Date;
+    data?: unknown;
+}
+/**
+ * Event handler function type
+ */
+export type EventHandler = (event: MCPEvent) => void;
+/**
+ * Log level
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Logger interface
+ */
+export interface ILogger {
+    debug(message: string, data?: unknown): void;
+    info(message: string, data?: unknown): void;
+    warn(message: string, data?: unknown): void;
+    error(message: string, data?: unknown): void;
+}
+/**
+ * Standard JSON-RPC error codes
+ */
+export declare const ErrorCodes: {
+    readonly PARSE_ERROR: -32700;
+    readonly INVALID_REQUEST: -32600;
+    readonly METHOD_NOT_FOUND: -32601;
+    readonly INVALID_PARAMS: -32602;
+    readonly INTERNAL_ERROR: -32603;
+    readonly SERVER_NOT_INITIALIZED: -32002;
+    readonly UNKNOWN_ERROR: -32001;
+    readonly REQUEST_CANCELLED: -32800;
+    readonly RATE_LIMITED: -32000;
+    readonly AUTHENTICATION_REQUIRED: -32001;
+    readonly AUTHORIZATION_FAILED: -32002;
+};
+/**
+ * MCP Error class
+ */
+export declare class MCPServerError extends Error {
+    code: number;
+    data?: unknown | undefined;
+    constructor(message: string, code?: number, data?: unknown | undefined);
+    toMCPError(): MCPError;
+}
+//# sourceMappingURL=types.d.ts.map

package/v3/@claude-flow/shared/dist/mcp/types.js

@@ -0,0 +1,54 @@
+/**
+ * V3 MCP Types and Interfaces
+ *
+ * Optimized type definitions for the V3 MCP server with:
+ * - Strict typing for performance
+ * - Connection pooling types
+ * - Transport layer abstractions
+ * - Tool registry interfaces
+ *
+ * Performance Targets:
+ * - Server startup: <400ms
+ * - Tool registration: <10ms
+ * - Tool execution: <50ms overhead
+ */
+// ============================================================================
+// Error Codes
+// ============================================================================
+/**
+ * Standard JSON-RPC error codes
+ */
+export const ErrorCodes = {
+    PARSE_ERROR: -32700,
+    INVALID_REQUEST: -32600,
+    METHOD_NOT_FOUND: -32601,
+    INVALID_PARAMS: -32602,
+    INTERNAL_ERROR: -32603,
+    SERVER_NOT_INITIALIZED: -32002,
+    UNKNOWN_ERROR: -32001,
+    REQUEST_CANCELLED: -32800,
+    RATE_LIMITED: -32000,
+    AUTHENTICATION_REQUIRED: -32001,
+    AUTHORIZATION_FAILED: -32002,
+};
+/**
+ * MCP Error class
+ */
+export class MCPServerError extends Error {
+    code;
+    data;
+    constructor(message, code = ErrorCodes.INTERNAL_ERROR, data) {
+        super(message);
+        this.code = code;
+        this.data = data;
+        this.name = 'MCPServerError';
+    }
+    toMCPError() {
+        return {
+            code: this.code,
+            message: this.message,
+            data: this.data,
+        };
+    }
+}
+//# sourceMappingURL=types.js.map