ont qc MCP

ONT QC MCP

模型上下文协议服务器为Oxford Nanopore FASTQ和BAM/CRAM输入提供轻量级QC/EDA助手。服务器封装了常见的CLI工具，并为教育和实践工作流程返回机器可读的摘要。

特性

• FASTQ读取电平QC nanoq （读取计数、长度/N50、GC、q核/长度直方图）。
• BAM/CRAM对齐质量控制 cramino （映射分解、身份、MAPQ历史）。
• 覆盖深度 mosdepth.
• 通过读取过滤/修剪 chopper.
• 可选绘图助手（长度/qscore直方图） matplotlib 已安装。
• 所需CLI工具的环境验证。
• 通过MCP资源提供每工具运行时指导，以帮助LLM工具选择。
• 非阻塞执行：CLI调用被卸载到具有可配置超时和线程默认值的工作线程。

需求

• Python>=3.10
• CLI工具已打开 PATH （通过env变量覆盖）：

- NANOQ （默认值 nanoq) - CRAMINO （默认值 cramino) - MOSDEPTH （默认值 mosdepth) - CHOPPER （默认值 chopper) - SAMTOOLS （默认值 samtools)用于错误分析和BAM操作 - BCFTOOLS （默认值 bcftools)用于VCF/BCF变体QC

安装CLI工具

使用conda/mamba（推荐）：

mamba create -n ont-qc-mcp python=3.11 chopper cramino mosdepth samtools bcftools -c conda-forge -c bioconda
conda activate ont-qc-mcp
cargo install --locked nanoq  # nanoq via Rust toolchain

使用系统包管理器：

# Ubuntu/Debian
sudo apt install samtools bcftools

# macOS (Homebrew)
brew install samtools bcftools

# nanoq requires Rust toolchain
cargo install --locked nanoq

对于 chopper, cramino，以及 mosdepthconda/mamba是最简单的安装方法。

IGV快照工具（可选）

• 容器运行时：Docker（首选）或Apptainer/Singularity
• 超时/运行时控制： MCP_TIMEOUT_IGV （默认600秒）和 MCP_IGV_CONTAINER_IMAGE / MCP_IGV_SIF_PATH

预建多拱图像（推荐）

docker pull aganezov/igv_snapper:0.2

此图像支持两者 linux/amd64 和 linux/arm64 本地。Docker会自动提取正确的架构。

本地构建（可选）

cd docker/igv_snapper
./build-multiarch.sh igv_snapper 0.2
export MCP_IGV_CONTAINER_IMAGE=igv_snapper:0.2

该镜像使用Ubuntu 24.04+OpenJDK 21+IGV 2.19.7。

Apptainer/HPC用户

apptainer pull igv_snapper.sif docker://aganezov/igv_snapper:0.1
export MCP_IGV_SIF_PATH=/path/to/igv_snapper.sif

保存IGV测试快照

• 集 IGV_SNAPSHOT_DIR IGV集成测试将生成的快照复制到可写目录。

快速启动

pip install -e .
ont-qc-mcp  # launches the MCP stdio server

测试/工具的一致环境

• 使用 scripts/with-env.sh 为所有命令设置PATH和venv： scripts/with-env.sh pytest.
• 它激活 .venv （如果存在），并可选择通过以下方式添加工具链路径：

- MCP_TOOLCHAIN_PATH （包含nanoq/斩波器/cramino/mosdeth/samtools的目录） - CONDA_PREFIX （前置 /bin 激活时） - CARGO_HOME 或 ~/.cargo/bin （货物安装工具）

• 保持 .venv 在回购根目录中；如果缺失，脚本会发出警告并继续。

MCP工具（高级）

环境和元数据

• env_status：检查所需CLI工具的可用性。
• header_metadata_tool：提取BAM/CRAM/VCF标头元数据（重叠、样本、程序）以及简明摘要。

读电平QC（FASTQ）

• qc_reads_fastq_tool：nanoq读取级别QC（计数、长度、qscore直方图）。
• filter_reads_fastq_tool：斩波滤波/修整；返回命令+统计信息。
• read_length_distribution_fastq_tool：百分位数+nanoq的直方图。
• qscore_distribution_fastq_tool：每次读取nanoq的q核直方图。

对齐质量控制（BAM/CRAM）

• qc_alignment_tool：克拉米诺比对质量控制（身份、MAPQ历史；使用 use_scaled 用于基本加权箱）。
• coverage_stats_tool：最深入的报道摘要。
• alignment_error_profile_tool：错误率分析自 samtools stats.
• alignment_summary_tool：聚合cramino+mosdepth（+错误配置文件）。
• read_length_distribution_bam_tool：流式samtools fastq->nanoq长度统计。
• qscore_distribution_bam_tool：流式采样工具fastq->nanoq-qscore直方图。
• targeted_coverage_tool：使用mosdepth计算基因组区域的目标覆盖率（通过GFF3支持基因名称，位置字符串如 chr1:1000-2000，或BED文件；提供1x/10x/20x的平均深度和覆盖阈值百分比）。

变体QC（VCF/BCF）

• qc_variants_tool：通过bcftools统计数据（SNP/indel计数、TS/TV比率、单例）进行VCF/BCF质量控制统计。

测序运行质量控制

• sequencing_summary_tool：解析ONT测序摘要文件（产量、N50、Q-scores、每小时产量窗口）。

文件验证

• qc_bed_tool：验证和质量控制BED文件（格式验证、协调检查、问题报告）。

IGV快照

• igv_snapshot_tool：为基因组区域生成IGV屏幕截图（需要Docker或Apptainer）。

资源与指导

• 指导资源： tool://guidance/{tool} 返回运行时提示、默认值（线程/超时）和标记模式/配方的链接，以帮助编排层决定是否调用工具。
• 空/空语义：直方图/百分位数字段为 null 当上游工具省略它们时；空列表意味着该工具显式返回了一个空块。默认情况下，Provenance是轻量级的，可以扩展为 MCP_INCLUDE_PROVENANCE=1.

执行默认值和可配置性

• CLI调用在工作线程中执行，以避免阻塞MCP事件循环。
• 默认值是保守的，可以通过环境变量进行覆盖：

- MCP_THREADS_DEFAULT / MCP_THREADS_ （例如。， MCP_THREADS_NANOQ) - MCP_TIMEOUT_DEFAULT / MCP_TIMEOUT_ （秒；例如。， MCP_TIMEOUT_MOSDEPTH) - MCP_NANOQ_AUX_STATS=1 （默认）通过nanoq计算FASTQ/BAM长度/qscore直方图 --read-lengths/--read-qualities （可能会为大量输入生成大型临时文件；设置为 0 禁用） - MCP_STDIO_TRANSPORT=anyio|compat （默认值 anyio)要控制stdio MCP服务器如何读取/写入JSON-RPC（使用 compat 在使用异步文件包装器挂起的受限/沙盒环境中） - MCP_BLOCKING_MODE=auto|executor|sync （默认值 auto)控制阻塞工作的执行方式； auto 当线程唤醒可靠并回退到 sync 否则

• 每个工具的默认值也反映在由返回的指导资源和工具描述中 list_tools默认情况下，线程应用于除nanoq（set）之外的所有工具 MCP_THREADS_NANOQ 以覆盖）。
• 大多数 MCP_* 在服务器启动时读取环境变量；更改它们需要重新启动MCP服务器。每次调用的覆盖可通过工具参数/标志获得（例如。， output_dir 为了 igv_snapshot_tool).如果多个客户端需要不同的默认值，请运行单独的服务器实例。
• 可通过以下方式选择覆盖低深度标记 low_cov_threshold；摘要中的错误配置文件收集可通过以下方式选择加入 include_error_profile.

发展

pip install -e ".[dev]"           # tests + linting/coverage helpers
pip install -e ".[plots]"         # add matplotlib for PNG histograms
pip install -e ".[all]"           # everything above in one go
scripts/with-env.sh pytest

有用的包装纸

• scripts/with-env.sh ：激活 .venv （如果存在）并在前面添加可选的工具链路径。它尊重：

- MCP_TOOLCHAIN_PATH （包含nanoq/斩波器/cramino/mosdeth/samtools的目录） - CONDA_PREFIX （前置 /bin 激活时） - CARGO_HOME 或 ~/.cargo/bin （货物安装工具）

常见工作流程

• 运行MCP服务器： python -m ont_qc_mcp.app_server （或 ont-qc-mcp 入口点）
• 仅限单元测试： scripts/with-env.sh pytest
• PATH上带有外部CLI的完整测试套件： scripts/with-env.sh pytest -m integration （安装CLI后）
• 通过MCP检查真实文件（将JSON写入stdout或 --out): scripts/with-env.sh python scripts/mcp_smoke_real.py --dir /path/to/test_dir
• 重新生成记录的工具输出：请参阅 docs/tool-output-examples.md 对于单层衬里

备注

• 输出首先是JSON，以便与下游管道很好地配合。
• 绘图助手发出文件路径（PNG）；不返回base64有效载荷。