# 🧬 DeepMap MCP

[![MCP Version](https://img.shields.io/badge/MCP-1.0.0-blue)](https://modelcontextprotocol.io)
[![Python Version](https://img.shields.io/badge/python-3.10%2B-green)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A high-performance **Model Context Protocol (MCP)** server that provides Large Language Models (LLMs) with direct, structured access to the **Broad Institute's DepMap (Cancer Dependency Map)** data. 

Specifically designed for "Therapeutic Target Evidence Collection," this server enables agents to perform functional genomics analysis across 1,000+ cancer cell lines using the latest CRISPR (DepMap 25Q3) datasets.

---

## 🏗️ Architecture & Workflow

The server acts as a low-latency bridge between the raw DepMap CSV datasets and any MCP-compatible client (like Claude Desktop or the Agent4Target orchestrator).

```mermaid
graph TD
    User([User / LLM Client]) <-->|MCP Protocol| Server[DeepMap MCP Server]
    
    subgraph "Internal Engine"
        Server --> Router{Tool Router}
        Router --> S1[search_depmap_gene]
        Router --> S2[get_depmap_gene_dependency_summary]
        Router --> S3[get_depmap_top_cell_line_dependencies]
        
        S1 & S2 & S3 --> Client[DepMapClient Singleton]
        Client --> Cache[(Local CSV Cache)]
        Cache -.->|Initial Setup| Download[DepMap API]
    end
    
    subgraph "Data Output"
        Client --> Pydantic[Pydantic Result Models]
        Pydantic --> Server
    end
```

---

## 🚀 Quick Start

### 1. Installation
```bash
pip install deepmap-mcp
```

### 2. Data Initialization (Mandatory)
DeepMap datasets are large (~300MB). Run the included downloader to fetch the latest CRISPR gene effect file to your local cache:
```bash
deepmap-mcp-download-data
```

### 3. Running the Server
You can run the server over **stdio** (standard for Claude Desktop) or **HTTP SSE**:
```bash
# Run over stdio (Standard)
deepmap-mcp --transport stdio

# Run as local HTTP server (SSE)
deepmap-mcp --port 8001
```

---

## 🛠️ Tools Documentation

### `search_depmap_gene`
Search for valid HGNC gene symbols within the DepMap dataset.
- **Inputs**: `query` (string, e.g., "KR")
- **Use Case**: Resolving partial symbols or verifying if a gene exists in the screen.

### `get_depmap_gene_dependency_summary`
Retrieve global statistical metrics for a specific gene across the entire cell line compendium.
- **Inputs**: `gene_symbol` (string, e.g., "EGFR")
- **Returns**: Meta-analysis including `average_gene_effect`, `strong_dependency_count`, and `confidence_score`.

### `get_depmap_top_cell_line_dependencies`
Identify the specific cancer models most sensitive to the loss of the target gene.
- **Inputs**: `gene_symbol`, `top_n` (default: 15)
- **Use Case**: Critical for Section 3 of Target Evidence Reports.

### `get_depmap_dataset_metadata`
Returns provenance data about the local cache.
- **Use Case**: Ensuring reports cite the correct data release (e.g., "DepMap 25Q3").

---

## ⚙️ Configuration

Set these environment variables to customize behavior:

| Variable | Default | Description |
| :--- | :--- | :--- |
| `DEEPMAP_MCP_DATASET_PATH` | `~/.cache/deepmap-mcp/...` | Path to the CRISPR CSV file. |
| `DEEPMAP_MCP_HTTP_PORT` | `8001` | Port for SSE transport. |
| `DEEPMAP_MCP_TRANSPORT` | `stdio` | `stdio` or `http`. |
| `DEEPMAP_LOG_LEVEL` | `INFO` | Verbosity of server logs. |

---

## 🖥️ Usage in Claude Desktop

Add this to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "deepmap-mcp": {
      "command": "deepmap-mcp",
      "args": ["--transport", "stdio"],
      "env": {
        "DEEPMAP_MCP_DATASET_PATH": "/YOUR/ABSOLUTE/PATH/TO/CRISPRGeneEffect.csv"
      }
    }
  }
}
```

---

## 🧪 Development

Contributions are welcome!

```bash
# Clone and setup
git clone https://github.com/your-org/deepmap-mcp
cd deepmap-mcp
uv sync

# Run tests
uv run pytest
```

---

## 📄 License
MIT © 2026 DeepMap MCP Contributors.