# bio-mcp-evo2

MCP server for evo2 DNA language model - enabling AI assistants to generate and analyze DNA sequences using state-of-the-art genomic foundation models.

## Overview

evo2 is a genomic foundation model capable of:
- Generating DNA sequences with specified properties
- Scoring sequence likelihoods and calculating perplexity
- Extracting learned representations for downstream tasks
- Predicting variant effects on biological function

This MCP server provides multiple execution modes to support various computational environments:
- **Local**: Direct GPU execution (requires H100 or compatible GPU)
- **SBATCH**: Submit jobs to SLURM clusters
- **Singularity/Docker**: Container-based execution
- **API**: Nvidia NIM cloud API (no local GPU required)

## Installation

### Local Installation
```bash
git clone https://github.com/bio-mcp/bio-mcp-evo2.git
cd bio-mcp-evo2
pip install -e .[dev]
```

### Container Installation

#### Docker
```bash
docker build -t bio-mcp-evo2 .
docker run --gpus all bio-mcp-evo2
```

#### Singularity (HPC)
```bash
singularity build --fakeroot evo2.sif Singularity.def
singularity run --nv evo2.sif
```

## Configuration

### Environment Variables

```bash
# Execution mode selection
export BIO_MCP_EVO2_EXECUTION_MODE=api  # Options: local, sbatch, singularity, docker, api

# Model configuration
export BIO_MCP_EVO2_MODEL_SIZE=7b  # Options: 7b, 40b
export BIO_MCP_EVO2_CUDA_DEVICE=0

# API configuration (for API mode)
export BIO_MCP_EVO2_NIM_API_KEY=your-api-key

# SBATCH configuration (for HPC clusters)
export BIO_MCP_EVO2_SBATCH_PARTITION=gpu
export BIO_MCP_EVO2_SBATCH_TIME=01:00:00
export BIO_MCP_EVO2_SBATCH_MEMORY=64G
export BIO_MCP_EVO2_SBATCH_GPU_TYPE=h100
```

### Claude Desktop Integration

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "bio-evo2": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/bio-mcp-evo2",
      "env": {
        "BIO_MCP_EVO2_EXECUTION_MODE": "api",
        "BIO_MCP_EVO2_NIM_API_KEY": "your-api-key"
      }
    }
  }
}
```

For HPC with Singularity:
```json
{
  "mcpServers": {
    "bio-evo2": {
      "command": "singularity",
      "args": ["run", "--nv", "/path/to/evo2.sif"],
      "env": {
        "BIO_MCP_EVO2_EXECUTION_MODE": "local"
      }
    }
  }
}
```

## Available Tools

### evo2_generate
Generate DNA sequences from a prompt.

```python
# Example usage
result = await evo2_generate({
    "prompt": "ATCGATCGATCG",
    "n_tokens": 100,
    "temperature": 1.0,
    "top_k": 4
})
```

### evo2_score
Calculate sequence perplexity or get raw logits.

```python
# Example usage
result = await evo2_score({
    "sequence": "ATCGATCGATCGATCGATCG",
    "return_logits": False
})
```

### evo2_embed
Extract learned representations from sequences.

```python
# Example usage
result = await evo2_embed({
    "sequence": "ATCGATCGATCGATCGATCG",
    "layer": "blocks.28.mlp.l3"
})
```

### evo2_variant_effect
Predict the effect of mutations.

```python
# Example usage
result = await evo2_variant_effect({
    "reference_sequence": "ATCGATCGATCGATCGATCG",
    "variant_sequence": "ATCGATCGATCGATCAATCG",
    "context_window": 1000
})
```

## Execution Modes

### API Mode (Recommended for Getting Started)
No GPU required. Uses Nvidia's hosted API.
```bash
export BIO_MCP_EVO2_EXECUTION_MODE=api
export BIO_MCP_EVO2_NIM_API_KEY=your-key
python -m src.server
```

### Local Mode
Requires H100 GPU with sufficient memory.
```bash
export BIO_MCP_EVO2_EXECUTION_MODE=local
python -m src.server
```

### SBATCH Mode
For HPC clusters with SLURM.
```bash
export BIO_MCP_EVO2_EXECUTION_MODE=sbatch
export BIO_MCP_EVO2_SBATCH_PARTITION=gpu
python -m src.server
```

### Container Modes
For isolated execution environments.
```bash
# Docker
export BIO_MCP_EVO2_EXECUTION_MODE=docker
docker run --gpus all -v $PWD:/workspace bio-mcp-evo2

# Singularity
export BIO_MCP_EVO2_EXECUTION_MODE=singularity
singularity run --nv evo2.sif
```

## Examples

### Generate a promoter sequence
```
User: Generate a 200bp DNA sequence that could function as a promoter