# rnaseq-mcp

Server MCP per l'analisi di dati Bulk RNA-seq tramite agenti LLM.
Permette di interrogare un dataset in linguaggio naturale. Esegue
codice R e Python in un container Docker isolato, con anonimizzazione
automatica dei campioni e controllo sulla privacy degli output.

## Prerequisiti

- Docker
- Python ≥ 3.11
- Un client MCP compatibile (es. Claude Code, Mistral Vibe o qualsiasi
  agente che supporti il protocollo MCP)

## Quickstart

### 1. Build del container

```bash
cd container
docker build -t rnaseq-executor:latest .
```

Nel container vengono installati pacchetti di R  (DESeq2, edgeR, limma, clusterProfiler, fgsea)  e le librerie di annotazione (`org.Hs.eg.db`, `org.Mm.eg.db`) per garantire funzionalita offline.

### 2. Installazione del server

```bash
pip install -e .
```

### 3. Configurazione del client MCP

Registra il server nel tuo client MCP con questi parametri:

| Parametro       | Valore                             |
|-----------------|------------------------------------|
| Comando         | `rnaseq-mcp`                       |
| `COUNTS_FILE`   | percorso assoluto a `counts.csv`   |
| `METADATA_FILE` | percorso assoluto a `metadata.csv` |

I file di input consistono in 2 CSV:
- `counts.csv` — matrice geni × campioni (gene ID come indice di riga)
- `metadata.csv` — tabella campioni × variabili (stesso indice di `counts.csv`)

### 4. Utilizzo

Una volta connesso il server, i tool disponibili sono:

| Tool               | Descrizione                                  |
|--------------------|----------------------------------------------|
| `list_data_files`  | Elenca i file in `/data`                     |
| `read_table`       | Anteprima di un CSV                          |
| `execute_r`        | Esegue codice R (sessione persistente)       |
| `execute_python`   | Esegue codice Python (namespace persistente) |
| `get_outputs`      | Recupera i risultati da `/output`            |
| `describe_session` | Stato della sessione e pacchetti disponibili |
| `reset_session`    | Azzera container, stato e output             |

Esempio di sessione:

```
Analizza i dati RNA-seq in /data confrontando treated vs control,
correggi per batch e genera volcano plot e heatmap.
```

Viene fornito un esempio prompt di sistema in [`prompts/system_prompt.md`](prompts/system_prompt.md).

## Privacy

All'avvio, il server:
1. Rimuove le colonne di metadati con identificatori personali (nomi, ID campione, barcode, ecc.)
2. Rinomina i campioni con alias anonimi `S1, S2, ..., SN`
3. Blocca l'esportazione di matrici per-campione (count, PCA) come CSV

### Mappatura dei campioni

La corrispondenza `S1 → nome_reale` viene scritta su host nel file:

```
/tmp/rnaseq-<session_id>/host_only/sample_mapping.json
```

Il file non è montato nel container e non è accessibile tramite i tool MCP — il modello non può mai risalire ai nomi originali. Il formato è:

```json
{ "S1": "nome_originale_1", "S2": "nome_originale_2", ... }
```

**Il file viene eliminato alla chiusura del server** (o alla chiamata di `reset_session`). Per conservarlo, copialo manualmente prima di terminare la sessione:

```bash
cp /tmp/rnaseq-*/host_only/sample_mapping.json ./sample_mapping.json
```

## Output

I file scritti in `/output` dal codice R/Python sono montati su host nella directory:

```
/tmp/rnaseq-<session_id>/output/
```

Sono accessibili direttamente dal filesystem dell'host durante tutta la sessione, senza dover passare per il tool `get_outputs`. Quest'ultimo è utile principalmente per restituire i risultati al modello (ad es. per leggere una tabella CSV o visualizzare un plot nel contesto della conversazione).

I file vengono eliminati alla chiusura del server o alla chiamata di `reset_session`. Per conservarli:

```bash
cp -r /tmp/rnaseq-*/output/ ./risultati/
```

## Pacchetti R disponibili

DESeq2, edgeR, limma, ggplot2, pheatmap, ComplexHeatmap, EnhancedVolcano,
clusterProfiler, fgsea, msigdbr, org.Hs.eg.db, org.Mm.eg.db, AnnotationDbi

## Licenza

MIT License — Copyright (c) 2026 Stefano Barbi