--- 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 ```bash # Run full QC pipeline python skills/bioqc-mcp/bioqc_mcp.py --input --output # 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 # 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-/ ├── 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`). - **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). --- Source attribution: ClawBio Original project: https://github.com/ClawBio/ClawBio License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice MIT License Copyright (c) 2026 Gabriel Moreira Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Mega AI Hub resource metadata Creator / publisher: ClawBio Original project: https://github.com/ClawBio/ClawBio Attribution basis: Upstream repository explicitly recorded in package mirror path Fields of work: Data & Analytics, Design, Education & Research, Product Management Roles: Business Intelligence Analyst, Data Scientist, Product Manager, Researcher, UX Designer Specialties: API, Testing Tools: Fastqc, Matplotlib, Multiqc, Seaborn Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: ad1de0cdd2ac348b3245f361ab721c264bc522fc68af4d2dead72d90909263dd