Prompt Auto-Optimizer MCP

Instructions

Implementation Reference

• src/mcp/server.ts:659-744 (handler)

  The primary handler function for 'gepa_start_evolution' tool. It validates input, generates evolution ID, creates initial prompt population, and returns detailed initialization status.

    private async startEvolution(params: StartEvolutionParams): Promise<{
      content: { type: string; text: string; }[];
    }> {
      const { taskDescription, seedPrompt, targetModules, config } = params;
  
      // Validate required parameters
      if (!taskDescription) {
        throw new Error('taskDescription is required');
      }
  
      // Merge with default evolution config
      const evolutionConfig = {
        taskDescription,
        populationSize: 20,
        maxGenerations: 10,
        mutationRate: 0.15,
        ...config,
      };
  
      // Generate evolution ID
      const evolutionId = `evolution_${Date.now()}_${Math.random().toString(36).substring(7)}`;
  
      // Initialize evolution with seed prompt if provided
      const initialPrompts: GEPAPromptCandidate[] = [];
      if (seedPrompt) {
        initialPrompts.push({
          id: `seed_${evolutionId}`,
          content: seedPrompt,
          generation: 0,
          taskPerformance: new Map(),
          averageScore: 0,
          rolloutCount: 0,
          createdAt: new Date(),
          lastEvaluated: new Date(),
          mutationType: 'initial',
        });
      }
  
      // Generate initial population (simplified for now)
      const additionalPrompts: GEPAPromptCandidate[] = [];
      const remainingCount = (evolutionConfig.populationSize || 20) - initialPrompts.length;
      
      for (let i = 0; i < remainingCount; i++) {
        additionalPrompts.push({
          id: `generated_${evolutionId}_${i}`,
          content: `Generated prompt ${i + 1} for: ${taskDescription}`,
          generation: 0,
          ...(seedPrompt && { parentId: `seed_${evolutionId}` }),
          taskPerformance: new Map(),
          averageScore: 0,
          rolloutCount: 0,
          createdAt: new Date(),
          lastEvaluated: new Date(),
          mutationType: 'random',
        });
      }
  
      const totalCandidates = initialPrompts.length + additionalPrompts.length;
  
      return {
        content: [
          {
            type: 'text',
            text: `# Evolution Process Started
  
  ## Evolution Details
  - **Evolution ID**: ${evolutionId}
  - **Task**: ${taskDescription}
  - **Target Modules**: ${targetModules?.join(', ') || 'All'}
  - **Seed Prompt**: ${seedPrompt ? 'Provided' : 'Auto-generated'}
  
  ## Configuration
  - **Population Size**: ${evolutionConfig.populationSize || 20}
  - **Max Generations**: ${evolutionConfig.maxGenerations || 10}
  - **Mutation Rate**: ${evolutionConfig.mutationRate || 0.15}
  
  ## Initial Population
  - **Total Candidates**: ${totalCandidates}
  - **Seed Candidates**: ${initialPrompts.length}
  - **Generated Candidates**: ${additionalPrompts.length}
  
  Evolution process initialized successfully. Use \`gepa_evaluate_prompt\` to begin evaluating candidates.`,
          },
        ],
      };
    }

• src/mcp/server.ts:60-92 (schema)

  JSON schema definition and registration of the 'gepa_start_evolution' tool in the TOOLS array, used for MCP list tools and validation.

  {
    name: 'gepa_start_evolution',
    description: 'Initialize evolution process with configuration and seed prompt',
    inputSchema: {
      type: 'object',
      properties: {
        taskDescription: {
          type: 'string',
          description: 'Description of the task to optimize prompts for'
        },
        seedPrompt: {
          type: 'string',
          description: 'Initial prompt to start evolution from (optional)'
        },
        targetModules: {
          type: 'array',
          items: { type: 'string' },
          description: 'Specific modules or components to target (optional)'
        },
        config: {
          type: 'object',
          properties: {
            populationSize: { type: 'number', default: 20 },
            generations: { type: 'number', default: 10 },
            mutationRate: { type: 'number', default: 0.15 },
            crossoverRate: { type: 'number', default: 0.7 },
            elitismPercentage: { type: 'number', default: 0.1 }
          },
          description: 'Evolution configuration parameters (optional)'
        }
      },
      required: ['taskDescription']
    }

• src/types/gepa.ts:228-233 (schema)

  TypeScript interface defining the input parameters for the gepa_start_evolution tool handler, matching the JSON schema.

  export interface StartEvolutionParams {
    taskDescription: string;
    seedPrompt?: string;
    targetModules?: string[];
    config?: Partial<EvolutionConfig>;
  }

• src/mcp/server.ts:526-528 (registration)

  Registration of the tool handler in the MCP CallToolRequestSchema switch statement, dispatching calls to the startEvolution method.

  case 'gepa_start_evolution':
    return await this.startEvolution(args as unknown as StartEvolutionParams);

• src/mcp/types.ts:265-265 (schema)

  Constant definition of the tool name for type safety in GEPA MCP server.

  START_EVOLUTION: 'gepa_start_evolution',