bioqc-mcp

📊 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

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

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:

## 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).
• Interactive Plots: Custom generated charts are saved as static PNGs. Interactive reports are found in multiqc_report.html.
• Large FASTQ Files: For massive datasets, ensure to specify a reasonable thread count via --threads to prevent high CPU utilization.

Safety

• Local-first: All FastQC and MultiQC processing is performed strictly locally. No genetic data is ever uploaded.
• No code execution: All analysis is performed via explicit subprocess.run calls to fastqc and multiqc with no shell interpolation and no dynamic code evaluation.
• Disclaimer: Every generated report.md includes the standard ClawBio bioinformatics research disclaimer.

Agent Boundary

The agent dispatches parameters and visualizes outcomes. The skill executes the native binaries and processes logs.

Integration with Bio Orchestrator

Trigger conditions: routes here when:

• User mentions "bioqc", "mcp qc", "run fastqc", "fastq quality control".
• Raw FASTQ files are provided as input for pipeline execution.

Chaining partners:

• multiqc-reporter: Can consume raw data generated by the FastQC step.
• seq-wrangler: Can feed upstream raw reads into BioQC.

Citations

• Andrews S. FastQC: A Quality Control Tool for High Throughput Sequence Data (2010). http://www.bioinformatics.babraham.ac.uk/projects/fastqc
• Ewels P, et al. MultiQC: Summarize analysis results for multiple tools and samples in a single report. Bioinformatics (2016).