# mcp-bvbrc

A Model Context Protocol (MCP) server for interacting with the [BV-BRC (Bacterial and Viral Bioinformatics Resource Center)](https://www.bv-brc.org/) API. This server provides tools for querying and retrieving genomic data, features, antimicrobial resistance data, epitopes, and more.

## Overview

BV-BRC is a comprehensive bioinformatics resource for bacterial and viral pathogen data. This MCP server exposes the BV-BRC API through a set of tools that can be used with Claude and other MCP-compatible applications.

### Key Features

- **Query Genomes**: Search and retrieve genome data with filters for organism, strain, and more
- **Genomic Features**: Query genes, proteins, RNA molecules, and other genomic features
- **Antimicrobial Resistance**: Access AMR data and resistance mechanisms
- **Epitopes & Assays**: Retrieve vaccine target and epitope assay data
- **Advanced Queries**: Use RQL (Relational Query Language) for complex data queries
- **Multiple Data Types**: Access 13+ different data types in the BV-BRC database

## Installation

### Prerequisites

- Python 3.10 or higher
- pip (Python package manager)

### Quick Start

1. Clone or download this repository:
```bash
git clone https://github.com/soham-shukla/mcp-bvbrc.git
cd mcp-bvbrc
```

2. Install dependencies:
```bash
pip install -r requirements.txt
```

3. (Optional) Install in development mode with additional tools:
```bash
pip install -e ".[dev]"
```

## Configuration

### For Claude Desktop

The easiest way to use this server is with Claude Desktop:

1. Find your Claude Desktop configuration file:
   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

2. Add the server configuration:
```json
{
  "mcpServers": {
    "bvbrc": {
      "command": "python",
      "args": ["/absolute/path/to/bvbrc.py"]
    }
  }
}
```

3. Restart Claude Desktop

See [CONFIG.md](CONFIG.md) for more configuration options.

## Available Tools

### 1. query_data_type

Perform advanced queries on any BV-BRC data type using RQL syntax.

**Parameters:**
- `data_type` (required): The data type to query (e.g., `genome`, `genome_feature`, `epitope`)
- `query` (optional): RQL query string
- `limit` (optional, default: 10): Maximum results to return
- `offset` (optional, default: 0): Results to skip

**Example:**
```
Query genomes of Salmonella with organism name and genome size
data_type: "genome"
query: "eq(organism,Salmonella)&select(genome_id,organism,dna_size)"
limit: 5
```

### 2. get_record_by_id

Retrieve a specific record by its ID.

**Parameters:**
- `data_type` (required): The data type (e.g., `genome`, `genome_feature`)
- `record_id` (required): The ID of the record

**Example:**
```
Get genome with ID "1234567.890"
data_type: "genome"
record_id: "1234567.890"
```

### 3. search_genomes

Search for genomes with convenient filtering.

**Parameters:**
- `organism` (optional): Filter by organism name
- `genome_id` (optional): Filter by genome ID
- `strain` (optional): Filter by strain
- `limit` (optional, default: 10): Maximum results
- `offset` (optional, default: 0): Results to skip

**Example:**
```
Search for Escherichia coli genomes
organism: "Escherichia coli"
limit: 20
```

### 4. search_features

Search for genomic features (genes, proteins, etc.) with filtering.

**Parameters:**
- `genome_id` (optional): Filter by genome ID
- `feature_type` (optional): Filter by type (e.g., `CDS`, `RNA`)
- `keyword` (optional): Keyword search
- `limit` (optional, default: 10): Maximum results
- `offset` (optional, default: 0): Results to skip

**Example:**
```
Search for CDS features in a genome
genome_id: "1234567.890"
feature_type: "CDS"
limit: 50
```

### 5. get_available_data_types

Get information about all available data types in BV-BRC.

**Returns:** List of data types with descriptions and common fields.

## Supported Data Types

| Data Type | Description | Primary Key |
|-----------|-------------|------------|
| `genome` | Genome records with assembly and taxonomy | `genome_id` |
| `genome_feature` | Genomic features (genes, proteins, RNA) | `feature_id` |
| `strain` | Strain information and metadata | `strain_id` |
| `genome_amr` | Antimicrobial resistance data | `genome_id` |
| `epitope` | Epitope data including vaccine targets | `epitope_id` |
| `epitope_assay` | Epitope assay results | `assay_id` |
| `experiment` | Experiment metadata and results | `experiment_id` |
| `bioset` | Collection of genomes | `bioset_id` |
| `bioset_result` | Results associated with biosets | `result_id` |
| `feature_sequence` | Nucleotide and protein sequences | `feature_id` |
| `antibiotics` | Antibiotic information database | `antibiotic_id` |
| `enzyme_class_ref` | Enzyme classification reference | `enzyme_class_id` |
| `gene_ontology_ref` | Gene Ontology reference data | `go_id` |

## RQL Query Syntax

The BV-BRC API uses RQL (Relational Query Language) for advanced queries. Here are common operators:

### Comparison Operators
- `eq(field,value)` - Field equals value
- `ne(field,value)` - Field not equal to value
- `gt(field,value)` - Field greater than value
- `lt(field,value)` - Field less than value
- `in(field,(value1,value2))` - Field contains any of the values

### Logical Operators
- `and(expr1,expr2,...)` - AND expressions together
- `or(expr1,expr2,...)` - OR expressions together

### Query Modifiers
- `keyword(value)` - Full-text search
- `select(field1,field2)` - Return only specified fields
- `sort([+|-]field)` - Sort results (+ ascending, - descending)
- `limit(count,offset)` - Limit and offset results

### Examples

**Find Salmonella genomes with specific fields:**
```
eq(organism,Salmonella)&select(genome_id,organism,strain,dna_size)&limit(10,0)
```

**Search for antibiotic-resistant Salmonella:**
```
and(eq(organism,Salmonella),eq(amr_phenotype,resistant))&select(genome_id,organism,antibiotic)&limit(20,0)
```

**Full-text search across features:**
```
keyword(virulence)&select(feature_id,product)&limit(15,0)
```

## Python Usage

You can also use the server programmatically:

```python
import asyncio
from client import BVBRCClient

async def main():
    client = BVBRCClient()
    
    # Query genomes
    results = await client.query(
        "genome",
        "eq(organism,Salmonella)&select(genome_id,organism)",
        limit=10
    )
    
    # Get a specific record
    record = await client.get_by_id("genome", "1234567.890")

asyncio.run(main())
```

## Error Handling

The server handles common errors gracefully:

- **Invalid data types**: Returns error message
- **Network errors**: Returns connection error details
- **Invalid queries**: API returns error information
- **Missing records**: Returns 404 error message

## Performance Considerations

- Default limit is 10 records; use `offset` for pagination
- Large result sets may take longer to retrieve
- Use specific filters to reduce result size
- RQL queries are optimized server-side for efficiency

## Authentication

The BV-BRC public API requires no authentication. However, if you have private data access:

1. Set the `BVBRC_API_TOKEN` environment variable with your token
2. The client will automatically include it in requests

```bash
export BVBRC_API_TOKEN="your-token-here"
python bvbrc.py
```

## API Documentation

For complete BV-BRC API documentation, visit:
- [BV-BRC API Documentation](https://www.bv-brc.org/api/doc/)
- [BV-BRC Website](https://www.bv-brc.org/)
- [BV-BRC Command Line Interface](https://www.bv-brc.org/docs/cli_tutorial/index.html)

## Architecture

The server consists of three main modules:

- **bvbrc.py**: Main MCP server with tool definitions and orchestration
- **client.py**: HTTP client for BV-BRC API interactions
- **data_types.py**: Data type definitions and metadata

## Development

### Running Tests

```bash
pytest tests/
```

### Code Style

```bash
black bvbrc.py client.py data_types.py
isort bvbrc.py client.py data_types.py
```

### Type Checking

```bash
mypy bvbrc.py client.py data_types.py
```

## License

MIT License - See LICENSE file for details

## Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

## Support

For issues with this MCP server, please open a GitHub issue.

For questions about the BV-BRC API itself, visit the [BV-BRC help documentation](https://www.bv-brc.org/).

---

**Note**: This MCP server is an independent tool and is not officially affiliated with or endorsed by BV-BRC.