# Installation Guide
## Prerequisites
- **Python 3.12**
- **Conda** (recommended for managing CUDA dependencies)
- **NVIDIA GPU** with CUDA support (required for Evo2)
## Step-by-Step Installation
### 1. Install Evo2 Dependencies
Evo2 requires specific CUDA and deep learning dependencies that must be installed in a particular order. **This order is critical for proper functionality.**
#### Step 1.1: Install CUDA Dependencies
Using conda, install the NVIDIA CUDA toolkit components:
```bash
conda install -c nvidia cuda-nvcc cuda-cudart-dev
```
#### Step 1.2: Install Transformer Engine
Install the transformer engine for PyTorch:
```bash
conda install -c conda-forge transformer-engine-torch=2.3.0
```
#### Step 1.3: Install Flash Attention
Install flash-attn with the `--no-build-isolation` flag:
```bash
pip install flash-attn==2.8.0.post2 --no-build-isolation
```
**Note**: The `--no-build-isolation` flag is important for compatibility with the previously installed CUDA components.
#### Step 1.4: Install Evo2
Finally, install the Evo2 package:
```bash
pip install evo2
```
### 2. Install evo2-mcp
After completing all Evo2 dependencies, you can install the MCP server using pip:
```bash
pip install evo2_mcp
```
For development or latest changes:
```bash
pip install git+https://github.com/not-a-feature/evo2-mcp.git@main
```
To use this server with an MCP client, add the following to your `mcp.json` configuration:
```json
{
"mcpServers": {
"evo2-mcp": {
"command": "python",
"args": ["-m", "evo2_mcp.main"]
}
}
}
```
## Troubleshooting
### CUDA-related Errors
If you encounter CUDA-related errors:
1. Verify your NVIDIA GPU and driver are properly installed:
```bash
nvidia-smi
```
2. Ensure CUDA toolkit is accessible:
```bash
nvcc --version
```
3. Check that PyTorch detects CUDA:
```python
import torch
print(torch.cuda.is_available())
```
### Installation Order Issues
If Evo2 fails to import or run:
1. Uninstall all related packages:
```bash
pip uninstall evo2 flash-attn transformer-engine-torch -y
conda remove cuda-nvcc cuda-cudart-dev transformer-engine-torch -y
```
2. Follow the installation steps again in the exact order specified above.
### Memory Issues
Evo2 models are large and require significant GPU memory. If you encounter out-of-memory errors:
- Ensure you have a GPU with at least 16GB VRAM (24GB+ recommended)
- Close other GPU-intensive applications
- Consider using the dummy implementation for testing (see Development section)
## Development Installation (Without Evo2)
For testing and development without requiring the full Evo2 installation, you can use the dummy implementation:
```bash
# Set environment variable to use dummy implementation
export EVO2_MCP_USE_DUMMY=true # Linux/macOS
set EVO2_MCP_USE_DUMMY=true # Windows (cmd)
$env:EVO2_MCP_USE_DUMMY="true" # Windows (PowerShell)
# Install only the MCP server
pip install evo2_mcp
```
This is useful for:
- CI/CD pipelines
- Development without GPU access
- Testing MCP integration without model dependencies
## Verifying Installation
After installation, verify everything works:
```python
# Test Evo2 import
import evo2
# Test MCP server
from evo2_mcp import mcp
print("Installation successful!")
```
Or run the test suite:
```bash
# With real Evo2
pytest -m real_evo2
# With dummy implementation
EVO2_MCP_USE_DUMMY=true pytest
```
