Prompt Auto-Optimizer MCP

Instructions

Implementation Reference

• src/mcp/server.ts:749-827 (handler)

  The primary handler function for the 'gepa_record_trajectory' tool. It validates input parameters, constructs an ExecutionTrajectory object, saves it to the TrajectoryStore, conditionally adds a candidate to the ParetoFrontier if successful, and returns a formatted text response with details.
  private async recordTrajectory(params: RecordTrajectoryParams): Promise<{ content: { type: string; text: string; }[]; }> { const { promptId, taskId, executionSteps, result, metadata } = params; // Validate required parameters if (!promptId || !taskId || !executionSteps || !result) { throw new Error('promptId, taskId, executionSteps, and result are required'); } // Create trajectory object const trajectory: ExecutionTrajectory = { id: `trajectory_${Date.now()}_${Math.random().toString(36).substring(7)}`, promptId, taskId, timestamp: new Date(), steps: executionSteps, finalResult: result, llmCalls: [], toolCalls: [], totalTokens: metadata?.tokenUsage || 0, executionTime: metadata?.executionTime || 0, }; try { // Save trajectory to store const saveResult = await this.trajectoryStore.save(trajectory); // Update Pareto frontier if this is a successful execution if (result.success && result.score > 0) { const candidate: GEPAPromptCandidate = { id: promptId, content: '', // Will be retrieved if needed generation: 0, taskPerformance: new Map([[taskId, result.score]]), averageScore: result.score, rolloutCount: 1, createdAt: new Date(), lastEvaluated: new Date(), mutationType: 'initial', }; this.paretoFrontier.addCandidate(candidate); } return { content: [ { type: 'text', text: `# Trajectory Recorded Successfully ## Trajectory Details - **Trajectory ID**: ${trajectory.id} - **Prompt ID**: ${promptId} - **Task ID**: ${taskId} - **Execution Steps**: ${executionSteps.length} - **Success**: ${result.success ? '✅' : '❌'} - **Performance Score**: ${result.score.toFixed(3)} ## Execution Summary - **Total Steps**: ${executionSteps.length} - **Successful Steps**: ${executionSteps.filter(step => !step.error).length} - **Failed Steps**: ${executionSteps.filter(step => step.error).length} - **Execution Time**: ${metadata?.executionTime || 'N/A'}ms - **Token Usage**: ${metadata?.tokenUsage || 'N/A'} ## Storage - **File**: ${saveResult.filePath || 'N/A'} - **Success**: ${saveResult.success ? 'Yes' : 'No'} - **ID**: ${saveResult.id || 'N/A'} ${result.success && result.score > 0 ? '✨ Candidate added to Pareto frontier for optimization.' : ''}`, }, ], }; } catch (error) { throw new Error(`Failed to record trajectory: ${error instanceof Error ? error.message : 'Unknown error'}`); } }
• src/mcp/server.ts:94-145 (schema)

  The JSON input schema definition for the gepa_record_trajectory tool, including all properties, descriptions, and required fields, used for tool listing and validation.
  { name: 'gepa_record_trajectory', description: 'Record execution trajectory for prompt evaluation', inputSchema: { type: 'object', properties: { promptId: { type: 'string', description: 'Unique identifier for the prompt candidate' }, taskId: { type: 'string', description: 'Identifier for the specific task instance' }, executionSteps: { type: 'array', items: { type: 'object', properties: { action: { type: 'string' }, input: { type: 'object' }, output: { type: 'object' }, timestamp: { type: 'string' }, success: { type: 'boolean' } }, required: ['action', 'timestamp', 'success'] }, description: 'Sequence of execution steps' }, result: { type: 'object', properties: { success: { type: 'boolean' }, score: { type: 'number' }, output: { type: 'object' } }, required: ['success', 'score'], description: 'Final execution result and performance score' }, metadata: { type: 'object', properties: { llmModel: { type: 'string' }, executionTime: { type: 'number' }, tokenUsage: { type: 'number' } }, description: 'Additional execution metadata (optional)' } }, required: ['promptId', 'taskId', 'executionSteps', 'result'] } },
• src/mcp/server.ts:529-531 (registration)

  The switch case registration that maps incoming tool calls named 'gepa_record_trajectory' to the recordTrajectory handler method.
  case 'gepa_record_trajectory': return await this.recordTrajectory(args as unknown as RecordTrajectoryParams);
• src/mcp/types.ts:266-266 (schema)

  Type-safe constant defining the tool name 'gepa_record_trajectory' as RECORD_TRAJECTORY in the TOOL_NAMES object.
  RECORD_TRAJECTORY: 'gepa_record_trajectory',