Prompt Auto-Optimizer MCP

openapi: 3.0.0 info: title: GEPA MCP Server API version: 1.0.0 description: | Genetic Evolutionary Prompt Adaptation MCP Server The GEPA MCP Server provides powerful tools for genetic prompt evolution, trajectory recording, reflection-based improvements, and multi-objective optimization using Pareto frontiers. ## Features - Genetic algorithm-based prompt evolution - Comprehensive trajectory recording and analysis - Reflection-driven failure analysis and improvement - Multi-objective optimization with Pareto frontiers - Disaster recovery and system resilience - Performance monitoring and optimization ## API Design All tools follow the MCP (Model Context Protocol) specification and return structured responses with detailed information about operations and results. contact: name: GEPA Team url: https://github.com/gepa-team/gepa-mcp-server email: support@gepa-server.com license: name: MIT url: https://opensource.org/licenses/MIT servers: - url: stdio:// description: MCP Stdio Transport (Local) - url: tcp://localhost:3000 description: MCP TCP Transport (Development) tags: - name: Evolution description: Genetic prompt evolution and population management - name: Evaluation description: Prompt performance evaluation and scoring - name: Optimization description: Multi-objective optimization and Pareto frontier management - name: Analysis description: Reflection analysis and improvement suggestions - name: Recovery description: Disaster recovery, backup, and system resilience - name: Legacy description: Legacy tools for backward compatibility paths: /tools/gepa_start_evolution: post: tags: - Evolution summary: Initialize evolution process description: | Starts a new genetic evolution process with configuration parameters and optional seed prompt. Creates initial population and sets up evolutionary framework for iterative improvement. operationId: startEvolution requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/StartEvolutionRequest' examples: basic: summary: Basic evolution initialization value: taskDescription: "Generate TypeScript interfaces from natural language descriptions" seedPrompt: "Create a TypeScript interface that represents the following concept:" advanced: summary: Advanced configuration value: taskDescription: "API documentation generation with high quality requirements" seedPrompt: "Analyze the following code and generate comprehensive API documentation:" targetModules: ["documentation", "code_analysis"] config: populationSize: 25 generations: 15 mutationRate: 0.12 responses: '200': description: Evolution process started successfully content: application/json: schema: $ref: '#/components/schemas/ToolResponse' example: content: - type: text text: | # Evolution Process Started ## Evolution Details - **Evolution ID**: evolution_1733140800_abc123 - **Task**: Generate TypeScript interfaces from natural language descriptions - **Seed Prompt**: Provided ## Configuration - **Population Size**: 20 - **Max Generations**: 10 - **Mutation Rate**: 0.15 Evolution process initialized successfully. '400': $ref: '#/components/responses/ValidationError' '500': $ref: '#/components/responses/ProcessingError' /tools/gepa_record_trajectory: post: tags: - Evaluation summary: Record execution trajectory description: | Records detailed execution trajectory for prompt evaluation, capturing performance metrics, execution steps, and system-level metadata for reflection analysis and optimization. operationId: recordTrajectory requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RecordTrajectoryRequest' examples: successful_execution: summary: Successful code generation trajectory value: promptId: "evolution_1733140800_candidate_5" taskId: "typescript_interface_task" executionSteps: - action: "parse_input" reasoning: "Parse natural language description for interface requirements" timestamp: "2024-12-02T14:30:00.000Z" success: true - action: "generate_interface" toolName: "typescript_generator" input: {"description": "User profile data structure"} output: {"interface": "interface UserProfile { id: string; name: string; }"} timestamp: "2024-12-02T14:30:02.000Z" success: true result: success: true score: 0.87 output: generatedInterface: "interface UserProfile { id: string; name: string; email: string; }" metadata: llmModel: "claude-3-sonnet" executionTime: 2500 tokenUsage: 450 responses: '200': description: Trajectory recorded successfully content: application/json: schema: $ref: '#/components/schemas/ToolResponse' '400': $ref: '#/components/responses/ValidationError' '500': $ref: '#/components/responses/ProcessingError' /tools/gepa_evaluate_prompt: post: tags: - Evaluation summary: Evaluate prompt performance description: | Evaluates a prompt candidate's performance across multiple tasks using configurable rollout counts and execution strategies. Updates Pareto frontier with results. operationId: evaluatePrompt requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/EvaluatePromptRequest' examples: multi_task_evaluation: summary: Evaluate across multiple tasks value: promptId: "evolution_1733140800_candidate_12" taskIds: ["code_doc_basic", "code_doc_complex", "api_ref_gen"] rolloutCount: 5 parallel: true responses: '200': description: Prompt evaluation completed content: application/json: schema: $ref: '#/components/schemas/ToolResponse' '400': $ref: '#/components/responses/ValidationError' '500': $ref: '#/components/responses/ProcessingError' /tools/gepa_reflect: post: tags: - Analysis summary: Analyze trajectories for improvements description: | Performs intelligent failure analysis on execution trajectories to identify patterns and generate actionable prompt improvement suggestions using reflection engine. operationId: reflect requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ReflectRequest' examples: failure_analysis: summary: Analyze failed trajectories value: trajectoryIds: ["trajectory_1", "trajectory_2", "trajectory_3"] targetPromptId: "evolution_1733140800_candidate_15" analysisDepth: "deep" focusAreas: ["instruction_clarity", "example_quality"] responses: '200': description: Reflection analysis completed content: application/json: schema: $ref: '#/components/schemas/ToolResponse' '400': $ref: '#/components/responses/ValidationError' '500': $ref: '#/components/responses/ProcessingError' /tools/gepa_get_pareto_frontier: post: tags: - Optimization summary: Get Pareto frontier candidates description: | Retrieves optimal prompt candidates from the Pareto frontier based on multi-objective optimization criteria (performance vs. diversity). operationId: getParetoFrontier requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/GetParetoFrontierRequest' examples: high_performance_filter: summary: Get high-performance candidates value: minPerformance: 0.8 limit: 10 task_specific_filter: summary: Filter by task types value: taskFilter: ["code_generation", "documentation"] limit: 15 responses: '200': description: Pareto frontier results retrieved content: application/json: schema: $ref: '#/components/schemas/ToolResponse' '400': $ref: '#/components/responses/ValidationError' '500': $ref: '#/components/responses/ProcessingError' /tools/gepa_select_optimal: post: tags: - Optimization summary: Select optimal candidate description: | Selects the best prompt candidate for a given context using configurable objective weights and Upper Confidence Bound selection strategy. operationId: selectOptimal requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/SelectOptimalRequest' examples: production_deployment: summary: Production-focused selection value: taskContext: "Production API documentation with strict quality requirements" performanceWeight: 0.9 diversityWeight: 0.1 exploration_mode: summary: Research-focused selection value: taskContext: "Experimental feature development" performanceWeight: 0.4 diversityWeight: 0.6 responses: '200': description: Optimal candidate selected content: application/json: schema: $ref: '#/components/schemas/ToolResponse' '400': $ref: '#/components/responses/ValidationError' '500': $ref: '#/components/responses/ProcessingError' /tools/gepa_create_backup: post: tags: - Recovery summary: Create system backup description: | Creates comprehensive system backup including evolution state, trajectories, Pareto frontier data, and component configurations. operationId: createBackup requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/CreateBackupRequest' examples: scheduled_backup: summary: Daily automated backup value: label: "daily-backup-2024-12-02" includeTrajectories: true pre_update_backup: summary: Pre-update safety backup value: label: "pre-major-update" includeTrajectories: true responses: '200': description: Backup created successfully content: application/json: schema: $ref: '#/components/schemas/ToolResponse' '500': $ref: '#/components/responses/ProcessingError' /tools/gepa_restore_backup: post: tags: - Recovery summary: Restore from backup description: | Restores system state from a previously created backup with optional integrity validation and pre-restore backup creation. operationId: restoreBackup requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RestoreBackupRequest' examples: safe_restore: summary: Safe restoration with validation value: backupId: "backup_1733140800_abc123def" validateIntegrity: true createPreRestoreBackup: true responses: '200': description: Backup restored successfully content: application/json: schema: $ref: '#/components/schemas/ToolResponse' '400': $ref: '#/components/responses/ValidationError' '500': $ref: '#/components/responses/ProcessingError' /tools/gepa_recovery_status: post: tags: - Recovery summary: Get recovery status description: | Provides comprehensive disaster recovery status and health information for all system components with detailed metrics. operationId: getRecoveryStatus requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/RecoveryStatusRequest' responses: '200': description: Recovery status retrieved content: application/json: schema: $ref: '#/components/schemas/ToolResponse' '500': $ref: '#/components/responses/ProcessingError' components: schemas: # Request Schemas StartEvolutionRequest: type: object required: - taskDescription properties: taskDescription: type: string description: Clear description of the task to optimize prompts for example: "Generate comprehensive API documentation from code comments" seedPrompt: type: string description: Initial prompt to start evolution from (optional) example: "Analyze the following code and generate detailed API documentation:" targetModules: type: array items: type: string description: Specific modules or components to target (optional) example: ["documentation", "code_analysis"] config: $ref: '#/components/schemas/EvolutionConfig' EvolutionConfig: type: object properties: populationSize: type: integer minimum: 5 maximum: 50 default: 20 description: Number of candidates in each generation generations: type: integer minimum: 1 maximum: 100 default: 10 description: Maximum number of evolution generations mutationRate: type: number minimum: 0.0 maximum: 1.0 default: 0.15 description: Probability of mutation per candidate crossoverRate: type: number minimum: 0.0 maximum: 1.0 default: 0.7 description: Probability of crossover between candidates elitismPercentage: type: number minimum: 0.0 maximum: 0.5 default: 0.1 description: Percentage of top candidates preserved each generation RecordTrajectoryRequest: type: object required: - promptId - taskId - executionSteps - result properties: promptId: type: string description: Unique identifier for the prompt candidate example: "evolution_1733140800_candidate_5" taskId: type: string description: Identifier for the specific task instance example: "typescript_interface_task" executionSteps: type: array items: $ref: '#/components/schemas/ExecutionStep' description: Sequence of execution steps with details result: $ref: '#/components/schemas/ExecutionResult' metadata: $ref: '#/components/schemas/TrajectoryMetadata' ExecutionStep: type: object required: - action - timestamp - success properties: action: type: string description: Action performed in this step example: "parse_input" input: type: object description: Input data for this step output: type: object description: Output produced by this step timestamp: type: string format: date-time description: ISO timestamp of step execution success: type: boolean description: Whether step completed successfully reasoning: type: string description: AI reasoning for this step example: "Parse natural language description for interface requirements" toolName: type: string description: Tool used in this step example: "typescript_generator" error: type: string description: Error message if step failed ExecutionResult: type: object required: - success - score properties: success: type: boolean description: Overall execution success score: type: number minimum: 0.0 maximum: 1.0 description: Performance score (0.0-1.0) output: type: object description: Final output of execution error: type: string description: Error message if execution failed TrajectoryMetadata: type: object properties: llmModel: type: string description: LLM model used example: "claude-3-sonnet" executionTime: type: integer description: Total execution time in milliseconds example: 2500 tokenUsage: type: integer description: Total tokens consumed example: 450 retryCount: type: integer description: Number of retries attempted environment: type: string description: Execution environment info example: "production" EvaluatePromptRequest: type: object required: - promptId - taskIds properties: promptId: type: string description: Unique identifier for prompt to evaluate example: "evolution_1733140800_candidate_12" taskIds: type: array items: type: string description: List of task IDs to evaluate against example: ["code_doc_basic", "code_doc_complex", "api_ref_gen"] rolloutCount: type: integer minimum: 1 maximum: 20 default: 5 description: Number of evaluation rollouts per task parallel: type: boolean default: true description: Whether to run evaluations in parallel ReflectRequest: type: object required: - trajectoryIds - targetPromptId properties: trajectoryIds: type: array items: type: string description: List of trajectory IDs to analyze for patterns example: ["trajectory_1", "trajectory_2", "trajectory_3"] targetPromptId: type: string description: Prompt ID to generate improvements for example: "evolution_1733140800_candidate_15" analysisDepth: type: string enum: [shallow, deep] default: deep description: Depth of analysis to perform focusAreas: type: array items: type: string description: Specific areas to focus analysis on example: ["instruction_clarity", "example_quality"] GetParetoFrontierRequest: type: object properties: minPerformance: type: number minimum: 0.0 maximum: 1.0 description: Minimum performance threshold for candidates example: 0.8 taskFilter: type: array items: type: string description: Filter candidates by specific task types example: ["code_generation", "documentation"] limit: type: integer minimum: 1 maximum: 100 default: 10 description: Maximum number of candidates to return SelectOptimalRequest: type: object properties: taskContext: type: string description: Context description for selection example: "Production API documentation with strict quality requirements" performanceWeight: type: number minimum: 0.0 maximum: 1.0 default: 0.7 description: Weight for performance in selection criteria diversityWeight: type: number minimum: 0.0 maximum: 1.0 default: 0.3 description: Weight for diversity in selection criteria CreateBackupRequest: type: object properties: label: type: string description: Optional descriptive label for the backup example: "daily-backup-2024-12-02" includeTrajectories: type: boolean default: true description: Include trajectory data in backup RestoreBackupRequest: type: object required: - backupId properties: backupId: type: string description: ID of the backup to restore from example: "backup_1733140800_abc123def" validateIntegrity: type: boolean default: true description: Perform integrity validation before restore createPreRestoreBackup: type: boolean default: true description: Create backup before restoration RecoveryStatusRequest: type: object properties: includeMetrics: type: boolean default: true description: Include detailed metrics in response # Response Schemas ToolResponse: type: object required: - content properties: content: type: array items: $ref: '#/components/schemas/ContentItem' description: Response content array isError: type: boolean description: Whether this response represents an error default: false ContentItem: type: object required: - type properties: type: type: string enum: [text, image] description: Type of content item text: type: string description: Text content (required for text type) data: type: string description: Base64 encoded data (for image type) mimeType: type: string description: MIME type for data content # Error Schemas ErrorResponse: type: object required: - content - isError properties: content: type: array items: type: object properties: type: type: string enum: [text] text: type: string isError: type: boolean enum: [true] responses: ValidationError: description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: content: - type: text text: "Error executing gepa_start_evolution: taskDescription is required" isError: true ProcessingError: description: Internal processing error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: content: - type: text text: "Error executing operation: Component initialization failed" isError: true examples: SuccessfulEvolution: summary: Successful evolution start value: content: - type: text text: | # Evolution Process Started ## Evolution Details - **Evolution ID**: evolution_1733140800_abc123 - **Task**: Generate TypeScript interfaces - **Seed Prompt**: Provided ## Configuration - **Population Size**: 20 - **Max Generations**: 10 - **Mutation Rate**: 0.15 TrajectoryRecorded: summary: Successful trajectory recording value: content: - type: text text: | # Trajectory Recorded Successfully ## Trajectory Details - **Trajectory ID**: trajectory_1733140850_def456 - **Success**: ✅ - **Performance Score**: 0.870 ✨ Candidate added to Pareto frontier for optimization. ParetoFrontierResults: summary: Pareto frontier query results value: content: - type: text text: | # Pareto Frontier Results ## Frontier Statistics - **Total Candidates**: 47 - **Filtered Candidates**: 23 - **Returned**: 15 ## Top Candidates ### 1. Candidate evolution_1733140800_candidate_23 - **Fitness Score**: 0.924 - **Generation**: 8