Orchestrator MCP

Instructions

Implementation Reference

• src/server/handlers/orchestrator.ts:62-92 (handler)

  The primary handler function for the 'ai_process' MCP tool. It extracts the natural language request from input arguments, validates it, delegates processing to the AIOrchestrator, and returns the AI-generated response as MCP content.

  export async function handleAIProcess(args: any, aiOrchestrator: AIOrchestrator) {
    try {
      const request = args.request;
      if (!request) {
        throw new Error('Request parameter is required');
      }
  
      logger.info(`Processing AI request: ${request.substring(0, 100)}...`);
  
      const result = await aiOrchestrator.processRequest(request);
  
      return {
        content: [
          {
            type: 'text',
            text: result.response,
          },
        ],
      };
    } catch (error) {
      logger.error('Failed to process AI request:', error as Error);
      return {
        content: [
          {
            type: 'text',
            text: `Error processing request: ${error instanceof Error ? error.message : String(error)}`,
          },
        ],
      };
    }
  }

• src/server/handlers/dispatcher.ts:37-39 (registration)

  Registration of the 'ai_process' tool in the main tool call dispatcher switch statement, routing calls to the handleAIProcess function.

  case 'ai_process':
    return handleAIProcess(args, aiOrchestrator);

• src/server/handlers/tools.ts:25-36 (schema)

  JSON Schema definition for the 'ai_process' tool input, specifying a required 'request' string parameter with descriptive examples.

  inputSchema: {
    type: 'object',
    properties: {
      request: {
        type: 'string',
        description: 'Natural language description of what you want to accomplish. Examples: "Search for React 19 features and analyze code examples", "Find all TypeScript files with TODO comments", "Check git status and create a summary of recent changes", "Fetch the latest Next.js documentation and extract routing information"',
      },
    },
    required: ['request'],
    additionalProperties: false,
    $schema: 'http://json-schema.org/draft-07/schema#',
  },

• src/server/handlers/tools.ts:22-37 (registration)

  Tool definition object for 'ai_process' returned by the listTools handler, including name, description, and input schema.

  {
    name: 'ai_process',
    description: 'Primary AI orchestration interface - intelligently processes complex requests by automatically selecting and coordinating multiple tools. Handles file operations, git management, web search, web fetching, browser automation, security analysis, and more. Describe your goal naturally - the AI will determine the best approach and execute multi-step workflows.',
    inputSchema: {
      type: 'object',
      properties: {
        request: {
          type: 'string',
          description: 'Natural language description of what you want to accomplish. Examples: "Search for React 19 features and analyze code examples", "Find all TypeScript files with TODO comments", "Check git status and create a summary of recent changes", "Fetch the latest Next.js documentation and extract routing information"',
        },
      },
      required: ['request'],
      additionalProperties: false,
      $schema: 'http://json-schema.org/draft-07/schema#',
    },
  },

• src/ai/orchestrator.ts:72-122 (helper)

  Core processing method in AIOrchestrator class called by the tool handler. Orchestrates the AI workflow execution and formats the result with metadata.

  async processRequest(userRequest: string): Promise<AIOrchestrationResult> {
    if (!this.initialized) {
      throw new Error('AI Orchestrator not initialized. Call initialize() first.');
    }
  
    const startTime = Date.now();
    console.error(`🤖 AI Processing: "${userRequest}"`);
  
    try {
      // Execute AI-driven workflow
      const workflowResult = await this.workflowEngine.executeWorkflow(userRequest);
      
      const processingTime = Date.now() - startTime;
      const toolsUsed = workflowResult.context.results.map(r => r.tool);
      const successfulSteps = workflowResult.context.results.filter(r => r.success).length;
  
      console.error(`🎯 AI Processing completed in ${processingTime}ms`);
  
      return {
        success: workflowResult.success,
        response: workflowResult.finalResult,
        metadata: {
          processingTime,
          toolsUsed,
          confidence: this.calculateOverallConfidence(workflowResult.context.steps),
          workflowSteps: workflowResult.context.results.length,
          aiEnhanced: true,
        },
        rawResults: workflowResult.context.results.map(r => r.result),
      };
  
    } catch (error) {
      const processingTime = Date.now() - startTime;
      const errorMessage = error instanceof Error ? error.message : String(error);
      
      console.error(`💥 AI Processing failed: ${errorMessage}`);
  
      return {
        success: false,
        response: `I encountered an error while processing your request: ${errorMessage}`,
        metadata: {
          processingTime,
          toolsUsed: [],
          confidence: 0,
          workflowSteps: 0,
          aiEnhanced: true,
        },
        error: errorMessage,
      };
    }
  }