iflow-mcp_bio-mcp-bio-mcp-blast 0.1.7
MCP server for NCBI BLAST sequence alignment
License: MIT
Requires Python: >=3.9

# Bio-MCP BLAST

🔍 **MCP server for NCBI BLAST sequence similarity search**

Enable AI assistants to perform BLAST searches through natural language. Search nucleotide and protein databases, create custom databases, and get formatted results instantly.

## 🧬 Features

- **blastn** - Nucleotide-nucleotide BLAST search
- **blastp** - Protein-protein BLAST search  
- **makeblastdb** - Create custom BLAST databases
- **Multiple output formats** - JSON, XML, tabular, pairwise
- **Flexible input** - File paths or raw sequences
- **Queue support** - Async processing for large searches

## 🚀 Quick Start

### Installation

```bash
# Install BLAST+
conda install -c bioconda blast

# Or via package manager
# macOS: brew install blast
# Ubuntu: sudo apt-get install ncbi-blast+

# Install MCP server
git clone https://github.com/bio-mcp/bio-mcp-blast.git
cd bio-mcp-blast
pip install -e .
```

### Basic Usage

```bash
# Start the server
python -m src.server

# Or with queue support
python -m src.main --mode queue
```

### Configuration

Add to your MCP client config:

```json
{
  "mcpServers": {
    "bio-blast": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/bio-mcp-blast"
    }
  }
}
```

## 💡 Usage Examples

### Simple Sequence Search
```
User: "BLAST this sequence against nr: ATGCGATCGATCG"
AI: [calls blastn] → Returns top hits with E-values and alignments
```

### File-Based Search
```
User: "Search proteins.fasta against SwissProt database"
AI: [calls blastp] → Processes file and returns similarity results
```

### Database Creation
```
User: "Create a BLAST database from reference_genomes.fasta"
AI: [calls makeblastdb] → Creates searchable database files
```

### Long-Running Search
```
User: "BLAST large_dataset.fasta against nt database"
AI: [calls blastn_async] → "Job submitted! ID: abc123, checking progress..."
```

## 🛠️ Available Tools

### `blastn`
Nucleotide-nucleotide BLAST search

**Parameters:**
- `query` (required) - Path to FASTA file or sequence string
- `database` (required) - Database name (e.g., "nt", "nr") or path
- `evalue` - E-value threshold (default: 10)
- `max_hits` - Maximum hits to return (default: 50)
- `output_format` - Output format: "tabular", "xml", "json", "pairwise"

### `blastp`
Protein-protein BLAST search

**Parameters:**
- Same as blastn, but for protein sequences

### `makeblastdb`
Create BLAST database from FASTA file

**Parameters:**
- `input_file` (required) - Path to FASTA file
- `database_name` (required) - Name for output database
- `dbtype` (required) - "nucl" or "prot"
- `title` - Database title (optional)

### Async Variants (Queue Mode)
- `blastn_async` - Submit nucleotide search to queue
- `blastp_async` - Submit protein search to queue
- `get_job_status` - Check job progress
- `get_job_result` - Retrieve completed results

## ⚙️ Configuration

### Environment Variables

```bash
# Basic settings
export BIO_MCP_MAX_FILE_SIZE=100000000    # 100MB max file size
export BIO_MCP_TIMEOUT=300                # 5 minute timeout
export BIO_MCP_BLAST_PATH="blastn"        # BLAST executable path

# Queue mode settings
export BIO_MCP_QUEUE_URL="http://localhost:8000"
```

### Database Setup

```bash
# Download common databases
mkdir -p ~/blast-databases
cd ~/blast-databases

# NCBI databases (large downloads!)
update_blastdb.pl --decompress nt
update_blastdb.pl --decompress nr
update_blastdb.pl --decompress swissprot

# Set environment variable
export BLASTDB=~/blast-databases
```

## 🐳 Docker Deployment

### Local Docker

```bash
# Build image
docker build -t bio-mcp-blast .

# Run container
docker run -p 5000:5000 \
  -v ~/blast-databases:/data/blast-db:ro \
  -e BLASTDB=/data/blast-db \
  bio-mcp-blast
```

### Docker Compose

```yaml
services:
  blast-server:
    build: .
    ports:
      - "5000:5000"
    volumes:
      - ./databases:/data/blast-db:ro
    environment:
      - BLASTDB=/data/blast-db
      - BIO_MCP_TIMEOUT=600
```

## 🔄 Queue System

For long-running BLAST searches, use the queue system:

### Setup

```bash
# Start queue infrastructure
cd ../bio-mcp-queue
./setup-local.sh

# Start BLAST server with queue support
python -m src.main --mode queue --queue-url http://localhost:8000
```

### Usage

```python
# Submit async job
job_info = await blast_server.submit_job(
    job_type="blastn",
    parameters={
        "query": "large_sequences.fasta",
        "database": "nt",
        "evalue": 0.001
    }
)

# Check status
status = await blast_server.get_job_status(job_info["job_id"])

# Get results when complete
results = await blast_server.get_job_result(job_info["job_id"])
```

## 📊 Output Formats

### Tabular (Default)
```
# Fields: query_id, subject_id, percent_identity, alignment_length, ...
Query_1    gi|123456    98.5    500    7    0    1    500    1000    1499    1e-180    633
```

### JSON
```json
{
  "BlastOutput2": [{
    "report": {
      "results": {
        "search": {
          "query_title": "Query_1",
          "hits": [...]
        }
      }
    }
  }]
}
```

### XML
Standard BLAST XML format for programmatic parsing.

## 🧪 Testing

```bash
# Run tests
pytest tests/ -v

# Test with real data
python tests/test_integration.py

# Performance testing
python tests/benchmark.py
```

## 📈 Performance Tips

### Local Optimization
- Use SSD storage for databases
- Increase available RAM
- Use multiple CPU cores: `export BLAST_NUM_THREADS=8`

### Database Selection
- Use smaller, specific databases when possible
- Consider pre-filtering sequences
- Use appropriate E-value thresholds

### Queue Optimization
- Scale workers based on CPU cores
- Use separate queues for different database sizes
- Monitor memory usage with large databases

## 🔐 Security

### Input Validation
- File size limits prevent resource exhaustion
- Path validation prevents directory traversal
- Command injection protection

### Sandboxing
- Containers run as non-root user
- Temporary files isolated per job
- Network access restricted in production

## 🐛 Troubleshooting

### Common Issues

**BLAST not found**
```bash
# Check installation
which blastn
blastn -version

# Install via conda
conda install -c bioconda blast
```

**Database not found**
```bash
# Check BLASTDB environment variable
echo $BLASTDB

# List available databases
blastdbcmd -list /path/to/databases
```

**Out of memory**
```bash
# Reduce max_target_seqs
blastn -max_target_seqs 100

# Use streaming for large outputs
# Increase system swap space
```

**Timeout errors**
```bash
# Increase timeout
export BIO_MCP_TIMEOUT=3600  # 1 hour

# Or use queue mode for long searches
python -m src.main --mode queue
```

## 📚 Resources

- **[BLAST Documentation](https://blast.ncbi.nlm.nih.gov/Blast.cgi?CMD=Web&PAGE_TYPE=BlastDocs)**
- **[BLAST Databases](https://ftp.ncbi.nlm.nih.gov/blast/db/)**
- **[Bio-MCP Examples](https://github.com/bio-mcp/bio-mcp-examples)**
- **[Queue System Setup](https://github.com/bio-mcp/bio-mcp-queue)**

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.

## 📄 License

MIT License - see [LICENSE](LICENSE) file.

## 🆘 Support

- 🐛 **Bug Reports**: [GitHub Issues](https://github.com/bio-mcp/bio-mcp-blast/issues)
- 💡 **Feature Requests**: [GitHub Issues](https://github.com/bio-mcp/bio-mcp-blast/issues/new?template=feature_request.md)
- 📖 **Documentation**: [Bio-MCP Docs](https://github.com/bio-mcp/bio-mcp-docs)
- 💬 **Discussions**: [GitHub Discussions](https://github.com/bio-mcp/bio-mcp-blast/discussions)

---

*Happy BLASTing! 🧬🔍*