<p align="center">
  <img src="logo.jpg" alt="BioVis-MCP Logo" width="600">
</p>

<p align="center">
  <a href="https://pypi.org/project/biovis-mcp/">
    <img src="https://img.shields.io/pypi/v/biovis-mcp.svg" alt="PyPI Version">
  </a>
  <a href="https://pypi.org/project/biovis-mcp/">
    <img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python Versions">
  </a>
  <a href="https://pypi.org/project/biovis-mcp/">
    <img src="https://img.shields.io/pypi/l/biovis-mcp.svg" alt="License">
  </a>
</p>

# 🧬 BioVis-MCP: Automated Bioinformatics Visualization

> **"From raw data to publication-ready figures in seconds."**

`BioVis-MCP` is a high-performance Model Context Protocol (MCP) server that empowers Large Language Models (like Claude) with the ability to generate **publication-quality (300 DPI)** bioinformatics visualizations directly from raw biological data.

No more manual Matplotlib tweaking. Just send the data, and get a verified, manuscript-ready image path.

---

## ✨ Features (Phases 1-3)

### 📊 Visualization Suite
*   **Volcano Plots**: High-resolution visualization of differential expression, with automated significance highlighting (Up/Down regulated).
*   **PCA Plots**: Principal Component Analysis for sample relationship and variance insights.
*   **Expression Heatmaps**: Professional heatmaps with hierarchical clustering and customizable colormaps.
*   **MA Plots**: Classic M-versus-A plots for global genomic trends.
*   **Pathway Enrichment**: Horizontal bar charts and dynamic Bubble Charts (Gene Count vs. Significance).

### 📝 Reporting & AI Integration
*   **Smart Figure Captions**: Context-aware, statistically accurate scientific captions generated automatically.
*   **Comprehensive Reports**: Multi-figure assembly into professional **PDF** and **DOCX** documents.
*   **High DPI Standards**: All figures are generated at **300 DPI** using `bbox_inches='tight'` for Q1 journal compliance.

---

## 🛠️ Tech Stack
- **Framework**: FastMCP
- **Libraries**: Pandas, Scikit-learn, Scipy, Matplotlib, Seaborn
- **Export Formats**: PNG (Figures), PDF & DOCX (Reports)

---

## 🚀 Installation & Claude Integration

BioVis-MCP can be added to **Claude Desktop** using one of the following methods. 

### Method 1: Using `uvx` (Recommended)
This is the fastest way to run BioVis-MCP without manual installation. Ensure you have [uv](https://github.com/astral-sh/uv) installed.

Add this to your `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "BioVis-MCP": {
      "command": "uvx",
      "args": ["biovis-mcp"]
    }
  }
}
```

### Method 2: Using `pip`
If you prefer a standard installation:

```bash
pip install biovis-mcp
```

Then add this to your `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "BioVis-MCP": {
      "command": "python",
      "args": [
        "-m",
        "biovis_mcp.server"
      ]
    }
  }
}
```

---

## 🛠️ Development & Contributing

If you want to contribute or modify the server locally:

### 1. Clone the Repository
```bash
git clone https://github.com/ZaEyAsa/biovis-mcp.git
cd biovis-mcp
```

### 2. Install for Development
```bash
pip install -e .[dev]
```

### 3. Developer Configuration (Claude Desktop)
For local development, point directly to your `server.py`:

```json
"BioVis-MCP-Dev": {
  "command": "C:/path/to/python.exe",
  "args": [
    "C:/path/to/biovis-mcp/src/biovis_mcp/server.py"
  ],
  "env": {
    "PYTHONPATH": "C:/path/to/biovis-mcp/src"
  }
}
```

> [!TIP]
> Use absolute paths for both `python.exe` and `server.py` on Windows.

---

## 📖 Available Tools

*   `generate_volcano_plot(data, title, fc_threshold, pval_threshold)`
*   `generate_bar_enrichment(data, title, top_n, color)`
*   `generate_heatmap_plot(data, title, cluster, cmap)`
*   `generate_pca_plot(data, metadata, title, group_col)`
*   `generate_bubble_enrichment(data, title, top_n)`
*   `generate_ma_plot(data, title, pval_threshold)`
*   `get_figure_caption(tool_type, stats)`
*   `create_report(figures_with_captions, format, report_name)`

---

## 📁 Output Structure
- `/figures`: High-resolution PNG files.
- `/reports`: Formatted PDF and DOCX documents.

---

*Developed by ZaEyAsa — Your Advanced Agentic Bio-Visualization Assistant.*

---

<p align="center">
  <b>Built for the global research community, BioVis-MCP transforms how AI assistants interact with biological data. Accelerating discovery, one high-resolution figure at a time.</b>
</p>