MCP Frogs

MCP青蛙🐸

一个 MCP服务器 （模型上下文协议），允许LLM（Claude）协调扩增宏基因组分析管道 青蛙 以对话和异步的方式。

______________________________________________________________________

目录

• 青蛙怎么了？
• MCP服务器如何工作？
• 建筑
• 先决条件
• 安装
• 配置
• 启动服务器
• MCP工具可用
• 使用类型
• 积分技巧

______________________________________________________________________

青蛙怎么了？

青蛙 （使用Galaxy Solution快速查找OTU）是一个扩增子分析管道（宏基因组学16S/ITS/18S），包括： 28个Python脚本 其顺序执行。每个脚本可以持续几分钟到几个小时。

______________________________________________________________________

MCP服务器如何工作？

MCP服务器充当 编排层 克劳德和青蛙工具之间：

1. 克劳德打电话给一个 MCP工具 （例如。 submit_pipeline_step).
2. 服务器通过以下方式运行相应的Frogs脚本： subprocess.Popen （非阻塞）并返回 job_id 立即。
3. 一个 线程守护进程 (JobPoller）每10秒监视一次后台进程，并在数据库中更新其状态 SQLite.
4. Claude可以通过以下方式查询状态： get_job_status(job_id) 任何时候。
5. 一旦步骤完成， get_pipeline_recommendations 使用以下方法自动计算下一步的输入文件： 流动规则 (FLOW_RULES），并提供命令 submit_pipeline_step 准备工作。

Claude  ──tool call──►  MCP Server  ──Popen──►  FROGS script (env frogs)
                             │
                        JobPoller (thread)
                             │
                          SQLite DB  ◄──── get_job_status / get_pipeline_recommendations

______________________________________________________________________

建筑

MCP-Frogs/
├── .mcp.json                     # Configuration MCP pour Claude Code
├── FROGS/                        # Pipeline FROGS existant (non modifié)
│   ├── tools/                    # 28 scripts Python (un par outil)
│   ├── lib/                      # Bibliothèques partagées (frogsUtils.py, ...)
│   └── libexec/                  # Binaires externes (swarm, vsearch, ...)
├── workspaces/                   # Créé automatiquement — sorties des jobs
│   └── 
//    # Répertoire isolé par job
└── mcp_server/
    ├── server.py                 # Point d'entrée FastMCP — 14 outils MCP
    ├── job_manager.py            # Soumission subprocess + thread poller
    ├── pipeline.py               # Résolution automatique des inputs/outputs
    ├── tools_registry.py         # Catalogue des 28 outils FROGS
    ├── database.py               # Toutes les opérations SQLite
    ├── config.py                 # Chemins et constantes
    ├── requirements.txt          # mcp[cli], pydantic
    └── frogs_jobs.db             # Créé automatiquement au premier démarrage

两个独立的Python环境

这种分离允许隔离MCP服务器的依赖项（mcp[cli], pydantic）青蛙（Numpy、Biopython等）。

______________________________________________________________________

先决条件

• Python≥3.10 在MCP环境中
• 康达 或 小曼巴 管理环境
• 青蛙 安装和运行（具有自己的Conda环境）
• 克劳德代码 （CLI）通过以下方式使用服务器： .mcp.json

______________________________________________________________________

安装

1.克隆存储库

git clone https://github.com/Mronanmag/MCP-Frogs.git
cd MCP-Frogs

2.创建MCP环境

micromamba create -n mcp_frogs python=3.11
micromamba activate mcp_frogs

3.安装MCP服务器依赖项

pip install -r mcp_server/requirements.txt

依赖性最小： mcp[cli]>=1.0.0 和 pydantic>=2.0.0.

4.检查Frogs环境的Python路径

micromamba activate frogs   # ou conda activate frogs
which python3               # noter ce chemin pour la configuration
micromamba deactivate

______________________________________________________________________

配置

.mcp.json （在项目的根源）

存储库现在提供配置 便携的 避免绝对路径（/home/...)打开包装外壳(scripts/run_mcp_server.sh).

{
  "mcpServers": {
    "frogs": {
      "command": "bash",
      "args": ["-lc", "./scripts/run_mcp_server.sh"],
      "env": {
        "MCP_FROGS_PYTHON": "python3",
        "FROGS_PYTHON": "python3"
      }
    }
  }
}

您可以在不更改JSON的情况下重载Python二进制文件：

export MCP_FROGS_PYTHON=/chemin/vers/python_mcp
export FROGS_PYTHON=/chemin/vers/python_frogs
claude

mcp_server/config.py

青蛙路径从仓库位置自动推断。如果您的Frogs安装在不同的文件夹中，请更改 config.py :

FROGS_TOOLS_DIR  = "/chemin/vers/FROGS/tools"
FROGS_LIB_DIR    = "/chemin/vers/FROGS/lib"
FROGS_BIN_DIR    = "/chemin/vers/FROGS/libexec"

______________________________________________________________________

解决 Failed to reconnect to frogs

如果克劳德展示 frogs: ✗ failed启动：

claude --debug

然后在调试日志中检查：

1. 已执行命令 （必须是 ./scripts/run_mcp_server.sh en模式本地，ou http://mcp-server:8000/sse 在Docker 2容器模式下）。
2. Python导入错误 (ModuleNotFoundError）→检查 PYTHONPATH.
3. 找不到Python二进制错误 (No such file or directory 或 exec: python3: not found) → 出口商 MCP_FROGS_PYTHON/FROGS_PYTHON 走向正确的道路。
4. 启动时服务器崩溃 →手动测试：

./scripts/run_mcp_server.sh

如果此测试失败，则终端消息是要修复的根本原因。

1. 错误 TypeError: FastMCP.run() got an unexpected keyword argument "host"

- 原因：版本不兼容 mcp （方法 run() 不接受 host/port 争论）。 - 应用的修正： mcp_server/http_entrypoint.py 配置 mcp.settings.host / mcp.settings.port 然后打电话 mcp.run(transport="sse").

______________________________________________________________________

启动服务器

Via Claude代码（推荐）

Claude代码自动检测 .mcp.json 并启动服务器：

cd ~/Projet/MCP_FROGS
claude

通过MCP检查器（在浏览器中调试）

cd ~/Projet/MCP_FROGS/mcp_server
mcp dev server.py

然后在web界面中，更改命令 uv 走向环境Python mcp_frogs.

命令行直接测试

cd ~/Projet/MCP_FROGS/mcp_server
PYTHONPATH=. python server.py

______________________________________________________________________

Docker部署（快速）

存储库包括两种Docker模式：

1. 推荐模式 ：包含Claude代码、MCP服务器和两个青蛙环境的单个容器。
2. 两个容器模式 (--profile multi）：MCP服务器和Claude代码的单独容器，如果您想独立重新启动MCP服务器，这很有用。

Docker文件

推荐模式

# Prérequis : ANTHROPIC_API_KEY dans l'environnement
export ANTHROPIC_API_KEY=sk-ant-...

# Construire l'image
make build
# ou : docker compose build all-in-one

# Lancer Claude Code (MCP server démarre automatiquement en fond)
make run
# ou : docker compose run --rm all-in-one claude

# Ouvrir un shell de debug (MCP server également actif)
make shell
# ou : docker compose run --rm all-in-one bash

乐脚本 docker/entrypoint.sh 自动启动MCP服务器 http://localhost:8000 在启动Claude代码之前。文件 docker/all-in-one/.mcp.json 安装在 /app/.mcp.json 以便Claude Code连接到本地服务器。

双容器模式（替代）

export ANTHROPIC_API_KEY=sk-ant-...

make multi-build
make multi-up    # démarre mcp-server en arrière-plan
make multi-run   # lance claude-code connecté au mcp-server

实用说明

• 乐音量 ./workspaces 安装以保持作业输出。
• La base SQLite mcp_server/frogs_jobs.db 通过命名卷持久化 mcp-db.
• 在多功能模式下，MCP服务器监听 127.0.0.1:8000 （仅限本地）。
• 在2容器模式下，MCP服务器暴露在 http://localhost:8000 来自主人。
• HTTP控制变量： MCP_HOST, MCP_PORT, MCP_DISABLE_DNS_REBINDING_PROTECTION.

______________________________________________________________________

MCP工具可用

服务器公开 14工具 可由克劳德使用。

工作管理

编排管道

实用程序

______________________________________________________________________

使用类型

以下是完整16S分析的顺序：

1. list_tools()
   → Liste les 28 outils disponibles

2. create_project("Etude_16S_Sol_2024")
   → project_id: "a1b2c3d4"

3. get_pipeline_recommendations("a1b2c3d4")
   → Affiche : prochaine étape = reads_processing
     Paramètres requis : sequencer, min_amplicon_size, max_amplicon_size,
                         five_prim_primer, three_prim_primer, input_archive

4. submit_pipeline_step("a1b2c3d4", "reads_processing", {
     "sequencer": "illumina",
     "process": "swarm",
     "min_amplicon_size": 44,
     "max_amplicon_size": 490,
     "five_prim_primer": "GGCGVACGGGTGAGTAA",
     "three_prim_primer": "GTGCCAGCNGCNGCGG",
     "R1_size": 267,
     "R2_size": 266,
     "input_archive": "/data/reads.tar.gz"
   })
   → job_id: "uuid-xxx" (retourné immédiatement)

5. get_job_status("uuid-xxx")
   → status: "running", elapsed_seconds: 142

6. [... attente ...]
   get_job_status("uuid-xxx")
   → status: "completed"

7. get_pipeline_recommendations("a1b2c3d4")
   → Prochaine étape : remove_chimera
     Inputs auto-résolus :
       input_fasta = /workspaces/a1b2c3d4/uuid-xxx/reads_processing.fasta
       input_biom  = /workspaces/a1b2c3d4/uuid-xxx/reads_processing_abundance.biom
     Aucun paramètre supplémentaire requis.

8. submit_pipeline_step("a1b2c3d4", "remove_chimera", {})
   → Les inputs sont résolus automatiquement depuis l'étape précédente
   → Continuer ainsi jusqu'à phyloseq_alpha_diversity

______________________________________________________________________

积分技巧

解锁

submit_job() 返回一个 job_id 几毫秒内。Frogs脚本在后台运行 subprocess.Popen.

坚持

SQLite en模式WAL(PRAGMA journal_mode=WAL）允许并发访问（线程轮询器+MCP调用）共存，并在服务器重新启动之间保留所有作业的状态。

隔离工作

每个作业都有一个专用目录 workspaces/ // 用于其输出文件、日志和stderr。

自动文件解析

34条规则 FLOW_RULES 在 pipeline.py 对步骤之间的数据流进行编码。它们存储为元组列表（而不是dict），以支持多对多关系，例如 .rdata 的 phyloseq_import 馈送6个不同的步骤。

年金本身

cancel_job() 发送 SIGTERMFrogs脚本拦截此信号，并在终止前清除临时文件。

管道步骤

12个主要步骤（强制性）： reads_processing → remove_chimera → cluster_filters → taxonomic_affiliation → affiliation_postprocess → affiliation_filters → affiliation_report → tree → normalisation → phyloseq_import → phyloseq_composition → phyloseq_alpha_diversity

16个可选步骤： demultiplex, clustering, itsx, biom_to_tsv, tsv_to_biom, biom_to_stdBiom, cluster_asv_report, phyloseq_beta_diversity, phyloseq_clustering, phyloseq_structure, phyloseq_manova, deseq2_preprocess, deseq2_visualisation, frogsfunc_placeseqs, frogsfunc_functions, frogsfunc_pathways