Prompt Auto-Optimizer MCP

Instructions

Implementation Reference

• src/mcp/server.ts:924-1007 (handler)

  The main handler function that executes the gepa_reflect tool logic. Loads execution trajectories, performs batch analysis using ReflectionEngine, processes failure patterns into prioritized improvements, and returns a comprehensive Markdown analysis report.
  private async reflect(params: ReflectParams): Promise<{ content: { type: string; text: string; }[]; }> { const { trajectoryIds, targetPromptId, analysisDepth = 'deep', focusAreas } = params; // Validate required parameters if (!trajectoryIds || trajectoryIds.length === 0 || !targetPromptId) { throw new Error('trajectoryIds and targetPromptId are required'); } const reflectionId = `reflection_${Date.now()}_${Math.random().toString(36).substring(7)}`; try { // Load trajectories for analysis const trajectories = []; for (const trajectoryId of trajectoryIds) { try { const trajectory = await this.trajectoryStore.load(trajectoryId); if (trajectory) { trajectories.push(trajectory); } } catch (error) { // eslint-disable-next-line no-console console.warn(`Failed to load trajectory ${trajectoryId}:`, error); } } if (trajectories.length === 0) { throw new Error('No valid trajectories found for analysis'); } // Perform failure analysis using reflection engine const analysisResult = await this.reflectionEngine.analyzeBatch(trajectories); // Generate improvement suggestions const improvements = analysisResult.commonPatterns.map(pattern => ({ issue: pattern.description, frequency: pattern.frequency, severity: pattern.frequency, suggestion: `Address ${pattern.type} by improving prompt clarity and specificity`, priority: pattern.frequency > 0.7 ? 'High' : pattern.frequency > 0.4 ? 'Medium' : 'Low', })); return { content: [ { type: 'text', text: `# Reflection Analysis Complete ## Analysis Details - **Reflection ID**: ${reflectionId} - **Target Prompt**: ${targetPromptId} - **Trajectories Analyzed**: ${trajectories.length}/${trajectoryIds.length} - **Analysis Depth**: ${analysisDepth} - **Focus Areas**: ${focusAreas?.join(', ') || 'Default'} ## Failure Pattern Analysis - **Patterns Detected**: ${analysisResult.commonPatterns.length} - **Recommendations**: ${analysisResult.recommendations.length} - **Confidence**: ${(analysisResult.overallConfidence * 100).toFixed(1)}% ## Key Findings ${analysisResult.commonPatterns.slice(0, 5).map((pattern, idx) => `${idx + 1}. **${pattern.type}** (${(pattern.frequency * 100).toFixed(1)}% frequency) - Severity: ${(pattern.frequency * 100).toFixed(1)}% - Description: ${pattern.description}` ).join('\n')} ## Improvement Recommendations ${improvements.slice(0, 5).map((imp, idx) => `${idx + 1}. **${imp.priority} Priority**: ${imp.suggestion} - Issue: ${imp.issue} - Frequency: ${(imp.frequency * 100).toFixed(1)}%` ).join('\n')} ## Summary The analysis identified ${analysisResult.commonPatterns.length} distinct failure patterns across ${trajectories.length} trajectories. Focus on addressing high-priority issues first to maximize improvement impact.`, }, ], }; } catch (error) { throw new Error(`Failed to perform reflection analysis: ${error instanceof Error ? error.message : 'Unknown error'}`); } }
• src/mcp/server.ts:175-204 (schema)

  MCP tool schema definition including name, description, and input validation schema for gepa_reflect, used for tool listing and validation.
  { name: 'gepa_reflect', description: 'Analyze failures and generate prompt improvements', inputSchema: { type: 'object', properties: { trajectoryIds: { type: 'array', items: { type: 'string' }, description: 'List of trajectory IDs to analyze for failure patterns' }, targetPromptId: { type: 'string', description: 'Prompt ID to generate improvements for' }, analysisDepth: { type: 'string', enum: ['shallow', 'deep'], default: 'deep', description: 'Depth of failure analysis to perform' }, focusAreas: { type: 'array', items: { type: 'string' }, description: 'Specific areas to focus analysis on (optional)' } }, required: ['trajectoryIds', 'targetPromptId'] } },
• src/mcp/server.ts:535-536 (registration)

  Tool handler registration in the MCP CallToolRequestSchema switch statement, dispatching calls to the reflect method.
  case 'gepa_reflect': return await this.reflect(args as unknown as ReflectParams);
• src/types/gepa.ts:258-263 (schema)

  TypeScript type definition for ReflectParams, providing compile-time validation for the tool's input parameters.
  export interface ReflectParams { trajectoryIds: string[]; targetPromptId: string; analysisDepth?: 'shallow' | 'deep'; focusAreas?: string[]; }
• src/mcp/types.ts:268-268 (helper)

  TOOL_NAMES constant providing the exact string identifier 'gepa_reflect' for type-safe tool name references.
  REFLECT: 'gepa_reflect',