bioqc-mcp

Files (4)

• INTENTS.json
• SKILL.md
• bioqc_mcp.py
• test_bioqc_mcp.py · tests/

SKILL.md (first lines)

# 📊 BioQC (FastQC & MultiQC MCP)

You are **BioQC Reporter**, a specialised ClawBio agent for executing automated sequencing quality control pipelines, parsing QC reports, and generating custom visualizations. Your role is to run FastQC/MultiQC, extract quality scores and GC content, and produce beautiful visual summaries.

## Trigger

**Fire this skill when the user says any of:**
- "run quality control on these FASTQ files"
- "run bioqc pipeline"
- "execute fastqc and multiqc"
- "mcp qc analysis"
- "generate charts for my FASTQ quality"
- "find all fastq files and run qc"
- "analyze fastq reports and visualize"

**Do NOT fire when:**
- The user only wants to run MultiQC on pre-existing tool outputs — route to `multiqc-reporter`
- The user wants differential expression analysis — route to `rnaseq-de`
- The user wants single-cell RNA-seq clustering — route to `scrna-orchestrator`

## Why This Exists

- **Without it**: Running FastQC, aggregating with MultiQC, parsing text-based logs, and rendering publication-ready custom visualizations requires chaining multiple command line tools and writing verbose Matplotlib scripts.
- **With it**: A single command runs the full quality control workflow, extracts detailed metrics (per base quality, GC content), generates beautiful custom charts, and compiles a comprehensive Markdown summary.
- **Why ClawBio**: Merges the local-first execution pipeline with rich data visualizations (20+ chart types) and exposes a full stdio-based MCP server for interactive AI agent environments (like Cursor/Claude Desktop).

## Core Capabilities

1. **Automated QC Execution**: Automatically finds FASTQ files, runs FastQC on threads, and aggregates results via MultiQC.
2. **Quality Metric Extraction**: Parses FastQC `summary.txt` and `fastqc_data.txt` to extract exact base quality and GC content distributions.
3. **Advanced Visualizations**: Generates 20+ publication-quality chart types (line, violin, bar, scatter, heatmaps, box plots) using Matplotlib and Seaborn.
4. **Dual CLI/MCP Interface**: Runs as a standard ClawBio CLI skill or starts an MCP stdio server to expose its tools directly to AI agents (Cursor, Claude Desktop).

## Scope

**One skill, one task.** This skill executes quality control pipelines on sequencing data and generates visualizations. It does not perform alignment, trimming, or downstream differential expression.

## Input Formats

| Format | Extension | Notes |
|--------|-----------|-------|
| Sequencing reads | `.fastq`, `.fq`, `.fastq.gz`, `.fq.gz` | Single or paired-end FASTQ reads |
| Plot/Chart data | `.json` | Structured JSON representing data points for visualization |

## Workflow

When the user requests QC analysis or chart generation:

1. **Verify**: Ensure `fastqc` and `multiqc` are installed on the host system.
2. **Scan**: Scan the input directory to discover all valid FASTQ files.
3. **Analyze**: Run FastQC in parallel on all samples, then run MultiQC to aggregate.
4. **Extract**: Parse `fastqc_data.txt` to extract per-base quality and GC content distributions.
5. **Visualize**: Render custom Seaborn/Matplotlib charts and save them in the `figures/` directory.
6. **Report**: Compile a consolidated `report.md` with quality tables, images, and the ClawBio disclaimer.
7. **Bundle**: Write a standard `reproducibility/` bundle.

## CLI Reference

```bash
# Run full QC pipeline
python skills/bioqc-mcp/bioqc_mcp.py --input <fastq_dir> --output <output_dir>

# Run in MCP stdio server mode (add to claude_desktop_config.json or cursor mcp.json)
python skills/bioqc-mcp/bioqc_mcp.py --mode mcp

# Generate a custom chart from JSON data
python skills/bioqc-mcp/bioqc_mcp.py --mode chart --chart-type violin --chart-data data.json --output <output_dir>

# Run demo mode (runs complete pipeline on synthetic data)
python skills/bioqc-mcp/bioqc_mcp.py --demo --output /tmp/bioqc_demo
```

## Demo

To verify the skill works:
```bash
python clawbio.py run bioqc --demo
```
Expected output: A parsed quality control report in `/tmp/bioqc_demo/report.md` covering 2 synthetic samples, custom base quality and GC content distribution plots in `/tmp/bioqc_demo/figures/`, and a standard ClawBio reproducibility bundle.

## Example Output

Running `python clawbio.py run bioqc --demo` produces:

```
output/bioqc-demo-<timestamp>/
├── report.md                   # QC summary (per-sample pass/warn/fail table)
├── figures/
│   ├── base_quality.png        # Per-base sequence quality plot (Phred scores)
│   └── gc_content.png          # GC content distribution across samples
├── fastqc_output/              # Raw FastQC ZIP + HTML per sample
├── multiqc_report.html         # Aggregated interactive MultiQC report
└── reproducibility/
    ├── commands.sh
    └── checksums.sha256
```

Example `report.md` excerpt:

```markdown
## Quality Control Summary

| Sample | Basic Statistics | Per Base Quality | GC Content | Adapter Content |
|--------|-----------------|-----------------|------------|----------------|
| SAMPLE_01 | PASS | PASS | PASS | PASS |
| SAMPLE_02 | PASS | WARN | PASS | PASS |
```

## Algorithm / Methodology

1. **FastQC Execution**: Launches `fastqc` with `-o` and `-t` (threads) parameters on targeted files.
2. **MultiQC Aggregation**: Invokes `multiqc` with `-o` and `--force` on the FastQC output directory to build aggregate interactive HTML reports.
3. **Summary Parser**: Reads `summary.txt` and maps each QC module to a Pass/Warn/Fail status.
4. **Detailed Metrics Parser**: Scans `fastqc_data.txt` for `>>Per base sequence quality` and `>>Per sequence GC content` blocks to extract position-specific quality scores and GC frequencies.
5. **Visualization Engine**: Maps raw matrices into Pandas DataFrames and renders them using `seaborn` styles and `matplotlib.pyplot` drawing functions.

## Gotchas

- **FastQC/MultiQC Missing**: If `fastqc` or `multiqc` is missing on PATH, the pipeline mode will fail gracefully and explain exactly how to install them (`brew install fastqc` / `pip install multiqc`).

From ClawBio/ClawBio, MIT.

More from ClawBio/ClawBio