# MCP AgentRun Server

An MCP (Model Context Protocol) server that provides Python code execution capabilities using [AgentRun](https://github.com/agentrun-ai/agentrun). This server can execute Python code in isolated Docker containers for safe and reproducible code execution.

## Features

- **Safe Code Execution**: Execute Python code in isolated Docker containers
- **Container Management**: Automatic container lifecycle management with docker-compose
- **Environment Isolation**: Each execution runs in a clean, isolated environment
- **Error Handling**: Comprehensive error handling and logging
- **Easy Integration**: Simple MCP interface for AI assistants and tools

## Installation

### Prerequisites

- Python 3.13 or higher
- Docker and Docker Compose
- UV package manager (recommended)

### Setup

1. Clone the repository:
```bash
git clone <repository-url>
cd mcp-agentrun
```

2. Run the setup script:
```bash
chmod +x setup.sh
./setup.sh
```

## Usage

### From Cursor

Go to Cursor Settings > Tools and Integrations > [New MCP Server]
In the mcp.json file add the following:

```json
{
  "mcpServers": {
    "python-code-executor": {
      "command": "/path/to/mcp-agentrun/.venv/bin/python",
      "args": [
        "/path/to/mcp-agentrun/src/server.py"
      ],
      "env": {
        "PYTHONPATH": "/path/to/mcp-agentrun",
        "AGENTRUN_API_DIR": "/path/to/mcp-agentrun/agentrun/agentrun-api",
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}
```

### Running the Server

```bash
python src/server.py
```

### Available Tools

#### Execute Python Code

Execute Python code in a container:

```python
result = execute_code(
    python_code="print('Hello, World!')\nprint(2 + 2)"
)
```

Returns the output of the code execution as a string.

### Example Usage

See `tests/test_build_container.py` for a complete example:

```python
import os
import subprocess
import dotenv
from agentrun import AgentRun

# Setup environment
rootdir = subprocess.run(["git", "rev-parse", "--show-toplevel"], 
                        capture_output=True, text=True).stdout.strip()
agentrun_api_dir = os.path.join(rootdir, "agentrun", "agentrun-api")

dotenv.load_dotenv(os.path.join(agentrun_api_dir, ".env.dev"))
container_name = os.getenv("CONTAINER_NAME")

# Execute code
with ComposeService(agentrun_api_dir):
    runner = AgentRun(container_name=container_name)
    code_from_llm = "print(1+2)"
    result = runner.execute_code_in_container(code_from_llm)
    print(result)  # Output: 3
```

## Project Structure

```
mcp-agentrun/
├── agentrun/                 # AgentRun submodule
├── src/
│   ├── __init__.py
│   └── server.py            # MCP server implementation
├── tests/
│   ├── test_build_container.py  # Container testing
│   ├── test.py              # Unit tests
│   ├── test_integration.py  # Integration tests
│   └── dev.ipynb            # Development notebook
├── pyproject.toml           # Project configuration
├── pytest.ini              # Pytest configuration
├── run_tests.py             # Test runner script
├── setup.sh                 # Setup script
└── README.md               # This file
```

## Configuration

The server requires a `.env.dev` file in the `agentrun/agentrun-api/` directory with the following variables:

```env
CONTAINER_NAME=your-container-name
```

## Testing


## Dependencies

- `agentrun>=0.2.5`: Python code execution in containers
- `docker>=7.1.0`: Docker API client
- `fastmcp>=2.10.5`: MCP server framework
- `pydantic>=2.11.7`: Data validation
- `dotenv>=0.9.9`: Environment variable management
- `tenacity>=9.1.2`: Retry logic

## Development

### Adding New Features

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

### Running in Development Mode

```bash
# Install in development mode
uv pip install -e .

# Run the server
python src/server.py
```

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Related Projects

- [AgentRun](https://github.com/agentrun-ai/agentrun): Python code execution in containers
- [FastMCP](https://github.com/jlowin/fastmcp): Fast MCP server framework