/bioqc-mcp

name: bioqc-mcp
description: Automated sequencing quality control and advanced visualization wrapping FastQC, MultiQC, and custom chart generation. Exposes an MCP stdio server for live AI integration alongside a ClawBio CLI runner.
license: MIT
metadata:
  version: 0.1.0
  author: Dr. Babajan Banaganapalli
  domain: genomics
  tags:
  - qc
  - fastqc
  - multiqc
  - visualization
  - sequencing
  - mcp
  inputs:
  - name: input_dir
    type: directory
    format:
    - any
    description: Directory containing FASTQ files to analyze
    required: true
  outputs:
  - name: report
    type: file
    format:
    - md
    description: ClawBio markdown quality control summary
  - name: html_report
    type: file
    format:
    - html
    description: Interactive MultiQC HTML report
  dependencies:
    python: '>=3.11'
  endpoints:
    cli: python skills/bioqc-mcp/bioqc_mcp.py --input {input_dir} --output {output_dir}
  openclaw:
    requires:
      bins:
      - python3
      - fastqc
      - multiqc
    always: false
    emoji: 📊
    homepage: https://github.com/Babajan-B/BioQC-MCP
    os:
    - darwin
    - linux
    install:
    - kind: pip
      package: multiqc
    trigger_keywords:
    - bioqc
    - fastqc mcp
    - multiqc mcp
    - automated qc pipeline
    - mcp qc
    - fastq quality control
    - sequencing quality control
    - generate chart qc

📊 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