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

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

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.

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 è:

{ "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:

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:

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