Snakemake MCP Server

零食网站API

Snakemake Web API为远程执行Snakemakewrappers和完整的Snakemae工作流提供了强大的端点。这允许将基于Snakemakes的生物信息学管道灵活集成到更大的系统或应用程序中。

主要特点

• FastAPI REST API： 用于发现和执行Snakemakewrappers和工作流的高性能REST端点，带有自动OpenAPI文档。
• 异步作业处理： 提交长时间运行的任务，并通过标准作业状态API监控其进度。
• 元数据缓存： 预解析Snakemakewrappers和工作流，以提供对工具信息和可执行演示的快速访问。
• 动态配置： 支持工作流的动态修改 config.yaml 以及包装器参数。
• 灵活的环境管理： 无缝处理Conda和容器（奇点）环境。

安装

先决条件

• 安装 uv 包管理器来自
• 确保您已安装Python 3.12+

安装步骤

1. 克隆存储库：

   git clone https://github.com/excelwang/snakemake-web-api.git
   cd snakemake-web-api

1. 安装项目依赖关系：

   uv sync

1. 激活虚拟环境：

   source .venv/bin/activate  # On Linux/macOS
   # or
   .venv\Scripts\activate     # On Windows

环境变量

设置 snakebase 目录

这 snakemake-web-api 依赖于特定的目录结构来定位Snakemakewrappers和工作流。此基本目录称为 snakebase默认情况下，服务器会查找名为的目录 snakebase 在当前工作目录中。此目录的位置可以通过设置 SNAKEBASE_DIR 环境变量。

这 snakebase 目录必须包含以下子目录：

• snakemake-wrappers：此目录应该是Snakemakewrappers官方存储库的克隆。
• snakemake-workflows：此目录应包含要通过服务器公开的Snakemake工作流。

1. 创建 snakebase 目录：

   mkdir snakebase
   cd snakebase

1. 克隆 snakemake-wrappers 存储库：

   git clone https://github.com/snakemake/snakemake-wrappers.git

1. 添加您的Snakemakes工作流：

创建一个名为的目录 snakemake-workflows 并将您的工作流目录放入其中。例如：

   mkdir snakemake-workflows
   cd snakemake-workflows
   git clone https://github.com/excelwang/rna-seq-star-deseq2
   git clone https://github.com/snakemake-workflows/dna-seq-varlociraptor
   git clone https://github.com/excelwang/StainedGlass
   # etc.

快速测试演练

本节将指导您快速测试系统，以验证一切是否正常工作。

1.解析包装

首先，解析并缓存所有包装器元数据：

export SNAKEBASE_DIR=~/snakebase # optional
swa parse

这将扫描您的 snakemake-wrappers 目录和缓存元数据，以加快服务器启动速度。

2.启动REST API服务器

启动REST API服务器以访问web终结点：

swa rest --host 127.0.0.1 --port 8082

3.验证服务器状态

检查您的服务器是否正在运行：

curl http://127.0.0.1:8082/health

您应该得到一个指示服务器健康的响应。

4.列出可用工具

获取可用Snakemakes包装的列表：

curl http://127.0.0.1:8082/tools

5.运行演示包装器

要自动运行演示包装器，请使用所提供的从API执行演示案例的脚本：

# Make sure the script is executable
chmod +x run_demo_wrapper.sh

# Run the demo wrapper
./run_demo_wrapper.sh

此脚本将：

1. 从以下位置获取演示案例 /demo-case 端点
2. 通过执行包装器 /tool-processes REST API终结点
3. 轮询作业状态，直到完成
4. 验证最终作业状态

API终结点摘要

• GET /tools：列出所有可用的Snakemakes包装。
• GET /workflows：列出所有可用工作流。
• POST /tool-processes：提交异步包装器执行作业。
• POST /workflow-processes：提交异步工作流执行作业。
• GET /tool-processes/{job_id}：检查特定作业的状态。
• GET /demos/wrappers/{wrapper_id}：获取特定包装器的可执行演示有效负载。
• GET /demos/workflows/{workflow_id}：获取特定工作流的可执行演示有效负载。

发现和使用演示

API通过分析Snakemake包装器存储库和 demos/ 工作流目录。

1.获取包装演示

了解如何使用有效的测试数据调用特定的包装器：

curl http://localhost:8082/demos/wrappers/bio/fastp

这将返回一个对象列表，其中包含 method, endpoint，以及预填充 payload 您可以直接发送至 /tool-processes.

2.获取工作流演示

请参阅特定工作流的示例配置：

curl http://localhost:8082/demos/workflows/rna-seq-star-deseq2

这将返回各种配置预设（例如，“小型测试数据集”、“人类基因组配置”），可用于 config a领域 /workflow-processes 提交。

使用工作流

工作流API允许您管理和执行复杂的Snakemake管道。

1.列出可用工作流

检索在您的数据库中找到的所有工作流的列表 snakemake-workflows 目录：

curl http://localhost:8082/workflows

2.获取工作流元数据

获取特定工作流的详细信息，包括其默认配置和参数架构：

curl http://localhost:8082/workflows/my-cool-pipeline

3.提交工作流作业

通过提供工作流的ID和可选的配置覆盖来执行工作流。服务器执行 深度合并 你的 config 将对象添加到工作流的基础中 config.yaml.

curl -X POST http://localhost:8082/workflow-processes \
     -H "Content-Type: application/json" \
     -d '{
           "workflow_id": "rna-seq-star-deseq2",
           "config": {
             "samples": "samples.tsv",
             "params": {
               "star": { "index": "", "align": "" }
             }
           },
           "target_rule": "all"
         }'

4.Kubernetes和S3执行（最佳实践）

在分布式K8s+S3环境中运行工作流时，请记住以下几点：

• 数据预配置：如果您的服务器以 --prefill SWA将在执行之前自动将您的本地隔离工作目录（包括符号链接的输入数据）同步到S3。
• 工作流本地化：始终使用 完整的本地化工作流代码.避免使用遥控器 include Snakefiles中的指令（例如指向GitHub的URL）。Snakemakes的Kubernetes执行器可能会失败 TypeError 当尝试存档Pod分发的远程源文件时。确保所有 .smk 规则存在于工作流目录中。
• 动态前缀：SWA根据以下内容自动生成唯一的S3前缀 job_id 以防止并发运行之间的数据冲突。

5.配置Snakemakes配置文件

配置文件允许您以可重用的方式定义执行策略（如Kubernetes、SLURM或本地）和存储设置。

个人资料搜索优先级

SWA查找由指定的配置文件 --workflow-profile 按照以下顺序：

1. 特定于工作流: {workflow_dir}/workflow/profiles/{profile_name}/
2. 全球SWA: ~/.swa/profiles/{profile_name}/ （建议跨工作流共享K8s配置）
3. 系统默认：Snakemakes的标准路径（例如。， ~/.config/snakemake/)

演示配置文件： k3s-s3

要在带有S3存储的Kubernetes上运行工作流，请创建一个目录 ~/.swa/profiles/k3s-s3/ 并添加a config.yaml 文件。

稳定性说明：我们强烈建议使用带有预安装存储插件的自定义映像，以避免运行缓慢 pip install 可能导致超时的步骤。

# ~/.swa/profiles/k3s-s3/config.yaml

# 1. 使用 K3s (Kubernetes) 执行器
executor: kubernetes
jobs: 10

# 2. 设置默认的 S3 存储提供商
default-storage-provider: s3
default-storage-prefix: s3://whj/

# 3. 将 S3/MinIO 凭证和服务器地址注入到 K3s Pods 中
envvars:
  - AWS_ACCESS_KEY_ID
  - AWS_SECRET_ACCESS_KEY
  - AWS_ENDPOINT_URL

# 4. 使用 Conda 环境
use-conda: true
conda-frontend: mamba

# 5. 其他配置
latency-wait: 120
rerun-incomplete: true
rerun-triggers: mtime
show-failed-logs: false
printshellcmds: true
keep-going: false

# 6. Kubernetes Pod 配置
container-image: snakemake/snakemake:v9.11.2
storage-s3-endpoint-url: http://10.3.217.200:20480
storage-s3-max-requests-per-second: 100
kubernetes-namespace: default
# 保持 pod 以便调试 (生产环境可设为 false)
kubernetes-omit-job-cleanup: true

# 7. 全局稳定性设置
# 增加重试次数以应对集群 API 波动
retries: 10

# 8. 使用自定义 Kubernetes Job 模板以设置 backoffLimit
# 这能极大地提高在高负载 K8s 环境下的运行成功率
kubernetes-job-template: job-template.yaml

配置 job-template.yaml

要在Kubernetes作业级别启用自动重试，您必须提供一个名为 job-template.yaml 在同一简档目录内（例如。， ~/.swa/profiles/k3s-s3/job-template.yaml).

创建包含以下内容的文件：

apiVersion: batch/v1
kind: Job
metadata:
  generateName: snakejob-
spec:
  template:
    spec:
      containers:
      - name: snakemake
  # This allows the Pod to retry within the same Job before failing
  backoffLimit: 3

6.监控工作流进度

轮询您提交的作业的状态：

curl http://localhost:8082/workflow-processes/{job_id}

状态可以是 accepted, running, completed，或 failed.

详细的故障排除可以在 故障排除指南.

运行服务器

服务器根据您的需求提供不同的模式：

REST API服务器

要启动REST API服务器，请执行以下操作：

swa rest --host 127.0.0.1 --port 8082

解析包装器

要解析和缓存所有可用Snakemakewrappers的元数据，请执行以下操作：

swa parse

验证安装

要验证您的安装是否正常工作：

swa verify

有关选项的完整列表，请参阅 CLI命令指南.