mcpevolve 0.0.9
A framework for systematically refining MCP server prompts, enhancing tool descriptions, and optimizing function code to improve clarity, consistency, and overall system performance.
License: Apache License 2.0
Requires Python: <4,>=3.10
Keywords: AI, Agents, MCP, LLM, machine-learning

# MCPEvolve

A framework for systematically refining MCP (Model Context Protocol) server prompts, enhancing tool descriptions, and optimizing function code to improve clarity, consistency, and overall system performance.

## Overview

MCPEvolve provides a comprehensive evaluation and refinement system for MCP servers, featuring:

- **Modular Evaluators**: Pluggable evaluation system with LLM-based code quality analysis
- **Agent Framework**: Built on mcpuniverse for seamless MCP protocol integration
- **Flexible Configuration**: JSON-based configuration system for evaluators and agents
- **Parallel Processing**: Support for concurrent evaluations to improve performance
- **Extensible Architecture**: Easy to add custom evaluators and agents

## Architecture

The framework is organized into four main modules:

- **`mcpevolve.agent`**: Agent implementations for MCP operations (NaiveAgent)
- **`mcpevolve.evaluator`**: Evaluation system with multiple evaluator types (NaiveEvaluator, BasicEvaluator)
- **`mcpevolve.mcp`**: MCP server configuration and management utilities
- **`mcpevolve.common`**: Shared utilities, configuration management, and logging

## Getting Started

### Prerequisites

- **Python**: Version 3.10 or higher
- **Docker**: For running Dockerized MCP servers
- **API Keys**: For LLM providers (OpenAI, etc.)

### Installation

1. **Clone the repository**
   ```bash
   git clone https://github.com/airesearch-emu/MCPEvolve
   cd MCPEvolve
   ```

2. **Create and activate virtual environment**
   ```bash
   python3 -m venv venv
   source venv/bin/activate
   ```

3. **Install dependencies**
   ```bash
   pip install -r requirements.txt
   pip install -r dev-requirements.txt
   ```

4. **Configure pre-commit hooks**
   ```bash
   pre-commit install
   ```

5. **Environment configuration**
   ```bash
   cp .env.example .env
   # Edit .env with your API keys and configuration
   ```

## Usage

### Basic Evaluation

```python
from mcpevolve.evaluator.evaluation import Evaluation
from mcpevolve.evaluator.base import EvaluatorInput

# Configure evaluation
config = {
    "evaluators": [
        {
            "name": "code_quality",
            "type": "BasicEvaluator",
            "llm": {"type": "openai"}
        }
    ]
}

# Create evaluation instance
evaluation = Evaluation(config)

# Prepare input
eval_input = EvaluatorInput(
    code_files=["path/to/code.py"],
    project_folder="/path/to/project"
)

# Run evaluation
results = await evaluation.evaluate(eval_input)
```

### Available Evaluators

- **NaiveEvaluator**: Simple evaluator for testing (always returns success)
- **BasicEvaluator**: LLM-based code quality analysis with anti-pattern detection

## Development

### Running Tests

```bash
make test
# or
PYTHONPATH=. pytest tests/
```

### Code Quality

```bash
# Run linting
python3 -m pylint mcpevolve/

# Pre-commit hooks will run automatically on commit
```

## License

This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.