Prompt Auto-Optimizer MCP

Instructions

Implementation Reference

• src/mcp/server.ts:1092-1172 (handler)

  Main handler implementation for 'gepa_select_optimal' tool. Selects optimal prompt candidate from Pareto frontier using weighted performance and diversity scores, employing UCB sampling strategy. Returns detailed selection report with metrics.
  private async selectOptimal(params: SelectOptimalParams): Promise<{ content: { type: string; text: string; }[]; }> { const { taskContext, performanceWeight = 0.7, diversityWeight = 0.3 } = params; // Validate weights sum to 1 if (Math.abs(performanceWeight + diversityWeight - 1.0) > 0.001) { throw new Error('performanceWeight and diversityWeight must sum to 1.0'); } try { // Get current Pareto frontier const frontierCandidates = this.paretoFrontier.getFrontier(); if (frontierCandidates.length === 0) { throw new Error('No candidates available in Pareto frontier'); } // Sample candidate using the specified strategy const selectedCandidate = await this.paretoFrontier.sampleCandidate({ name: 'ucb', parameters: { confidence: 1.96 } }); if (!selectedCandidate) { throw new Error('Failed to select optimal candidate'); } // TypeScript assertion: selectedCandidate is not null after the check above const candidate = selectedCandidate as GEPAPromptCandidate; // Calculate selection metrics const performanceScore = candidate.averageScore; const diversityScore = candidate.generation / 10; // Simple diversity metric const combinedScore = ( performanceScore * performanceWeight + diversityScore * diversityWeight ); // Get frontier statistics for context const stats = this.paretoFrontier.getStatistics(); return { content: [ { type: 'text', text: `# Optimal Candidate Selected ## Selection Context - **Task Context**: ${taskContext || 'General optimization'} - **Performance Weight**: ${(performanceWeight * 100).toFixed(1)}% - **Diversity Weight**: ${(diversityWeight * 100).toFixed(1)}% - **Selection Strategy**: Upper Confidence Bound (UCB) ## Selected Candidate - **Candidate ID**: ${candidate.id} - **Fitness Score**: ${candidate.averageScore.toFixed(3)} - **Combined Score**: ${combinedScore.toFixed(3)} ## Performance Breakdown - **Performance Score**: ${performanceScore.toFixed(3)} (${(performanceScore * 100).toFixed(1)}%) - **Diversity Score**: ${diversityScore.toFixed(3)} (${(diversityScore * 100).toFixed(1)}%) ## Candidate Metadata - **Generation**: ${candidate.generation} - **Parent ID**: ${candidate.parentId || 'None'} - **Mutation Type**: ${candidate.mutationType || 'Unknown'} ## Frontier Context - **Total Candidates**: ${frontierCandidates.length} - **Frontend Size**: ${stats.frontierSize} - **Average Rank**: ${stats.averageRank.toFixed(3)} - **Position in Frontier**: Top ${Math.ceil((1 - candidate.averageScore) * frontierCandidates.length)} ## Recommendation This candidate represents the optimal balance between performance (${(performanceWeight * 100).toFixed(1)}%) and diversity (${(diversityWeight * 100).toFixed(1)}%) for the given context. Use this prompt for your target task.`, }, ], }; } catch (error) { throw new Error(`Failed to select optimal candidate: ${error instanceof Error ? error.message : 'Unknown error'}`); } }
• src/mcp/server.ts:228-250 (schema)

  Tool schema definition in TOOLS array, including inputSchema for validation, used by listTools endpoint.
  { name: 'gepa_select_optimal', description: 'Select best prompt candidate for given context', inputSchema: { type: 'object', properties: { taskContext: { type: 'string', description: 'Context description for prompt selection (optional)' }, performanceWeight: { type: 'number', default: 0.7, description: 'Weight for performance in selection criteria' }, diversityWeight: { type: 'number', default: 0.3, description: 'Weight for diversity in selection criteria' } } } },
• src/mcp/server.ts:541-543 (registration)

  Registration of the tool handler in the CallToolRequestSchema switch statement within setupToolHandlers method.
  case 'gepa_select_optimal': return await this.selectOptimal(args as unknown as SelectOptimalParams);
• src/types/gepa.ts:271-275 (schema)

  TypeScript interface defining input parameters for the selectOptimal handler.
  export interface SelectOptimalParams { taskContext?: string; performanceWeight?: number; diversityWeight?: number; }
• src/mcp/types.ts:263-270 (schema)

  TOOL_NAMES constant defining the tool name for type safety.
  export const TOOL_NAMES = { // Core GEPA tools START_EVOLUTION: 'gepa_start_evolution', RECORD_TRAJECTORY: 'gepa_record_trajectory', EVALUATE_PROMPT: 'gepa_evaluate_prompt', REFLECT: 'gepa_reflect', GET_PARETO_FRONTIER: 'gepa_get_pareto_frontier', SELECT_OPTIMAL: 'gepa_select_optimal',