关键词

Terra.Bio基因组数据工作流管理生物信息学LLM集成

项目简介

Terra.Bio MCP 服务器是一个基于 Model Context Protocol (MCP) 构建的后端应用，旨在帮助大型语言模型（如Claude）与 Terra.Bio 计算平台进行交互。它通过封装 Terra 的 FISS API，向 LLM 提供一系列工具，实现对 Terra 工作空间的管理、工作流的监控与执行、以及数据表的读写操作。默认运行在只读模式，确保数据安全。

主要功能点

该MCP服务器提供了15个工具，涵盖Terra.Bio平台的多个方面：

  • 工作空间与数据探索
    • 'list_workspaces': 列出所有可访问的Terra工作空间。
    • 'get_workspace_data_tables': 获取工作空间中所有数据表的名称及行数。
    • 'get_entities': 读取特定类型实体（如样本、参与者）的数据。
  • 工作流监控与状态
    • 'list_submissions': 列出工作空间中的所有工作流提交，支持按状态、提交者、工作流名称过滤和分页。
    • 'get_submission_status': 获取特定工作流提交的详细状态，包括其中各个工作流的运行情况。
    • 'get_job_metadata': 获取特定工作流的Cromwell元数据，用于深入分析运行细节。
    • 'get_workflow_logs': 获取工作流的执行日志（标准输出和错误输出），可选择从Google Cloud Storage (GCS) 拉取实际日志内容并进行智能截断。
    • 'get_workflow_outputs': 获取已完成工作流的输出文件路径和结果值。
    • 'get_workflow_cost': 获取工作流执行的成本信息。
  • 工作流配置（需要启用写入权限）
    • 'get_method_config': 获取方法配置的详细信息，包括WDL版本和输入/输出映射。
    • 'update_method_config': 更新方法配置，例如更改WDL版本。
    • 'copy_method_config': 复制现有方法配置以创建新的版本或进行测试。
  • 工作流执行控制（需要启用写入权限）
    • 'submit_workflow': 提交WDL工作流进行执行，支持单个实体或批量处理。
    • 'abort_submission': 取消正在运行的工作流提交。
  • 数据管理（需要启用写入权限）
    • 'upload_entities': 上传或更新Terra数据表中的实体数据。

重要安全提示：默认情况下，服务器以只读模式运行，禁止任何修改操作。若需使用写入工具，必须在启动服务器时明确启用 '--allow-writes' 标志。

安装步骤

  1. 先决条件:

    • Python 3.10 或更高版本。
    • 已配置用于 Terra.Bio 访问的 Google 凭据（通常通过 'gcloud' 命令行工具或 'GOOGLE_APPLICATION_CREDENTIALS' 环境变量）。
    • 一个有效的 Terra.Bio 账户，并拥有对目标工作空间的访问权限。

  2. 克隆仓库:

    git clone https://github.com/broadinstitute/fiss-mcp.git
cd fiss-mcp

  3. 安装依赖: 由于 'firecloud' 包的兼容性要求，需要特殊安装步骤。

    # 首先安装 setuptools 的兼容版本
pip install "setuptools<80"

# 然后安装所有依赖，禁用构建隔离
pip install --no-build-isolation -r requirements.txt

    如果您是开发人员，还需要安装测试依赖：

    pip install pytest-cov ruff

  4. 验证 Google 凭据: 确保您的 Google 凭据已正确配置，可以通过运行以下 Python 代码片段进行验证：

    from firecloud import api as fapi
response = fapi.list_workspaces()
print(response.status_code)  # 应该输出 200

服务器配置（MCP客户端使用）

MCP 服务器的启动命令及其参数需要配置到您的 MCP 客户端（如 Claude Desktop 或 Claude Code）中。以下是配置的关键信息：

1. 对于 Claude Desktop (macOS/Windows)

编辑您的 Claude Desktop 配置文件，通常位于 '~/Library/Application Support/Claude/claude_desktop_config.json' (macOS) 或 '%APPDATA%\Claude\claude_desktop_config.json' (Windows)。您需要在 'mcpServers' 部分添加一个名为 '"terra"' 的服务器条目。

  • 只读模式（推荐）：

    • 'command'：指定 Python 解释器的路径，例如 'python3' 或您的虚拟环境中的绝对路径（如 '/absolute/path/to/venv/bin/python3'）。
    • 'args'：指定 MCP 服务器脚本的绝对路径，例如 '["/absolute/path/to/fiss-mcp/src/terra_mcp/server.py"]'。

  • 启用写入模式（用于开发）：

    • 'command'：同上。
    • 'args'：在只读模式的 'args' 列表末尾添加 '--allow-writes' 标志，例如 '["/absolute/path/to/fiss-mcp/src/terra_mcp/server.py", "--allow-writes"]'。

  • 配置 Google 凭据（可选）： 如果您的 Google 凭据没有全局配置，可以在 'env' 字段中指定 'GOOGLE_APPLICATION_CREDENTIALS' 环境变量： 'env'：一个包含 '{"GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/credentials.json"}' 的字典。

2. 对于 Claude Code

使用 'claude mcp add' 命令来注册服务器。

  • 只读模式（推荐）： 命令示例：

    claude mcp add terra --transport stdio -- python3 /absolute/path/to/fiss-mcp/src/terra_mcp/server.py

  • 启用写入模式（用于开发）： 命令示例：

    claude mcp add terra --transport stdio -- python3 /absolute/path/to/fiss-mcp/src/terra_mcp/server.py --allow-writes

  • 配置 Google 凭据（可选）： 在 'claude mcp add' 命令中添加 '--env' 参数：

    claude mcp add terra --transport stdio --env GOOGLE_APPLICATION_CREDENTIALS=/path/to/your/credentials.json -- python3 /absolute/path/to/fiss-mcp/src/terra_mcp/server.py

注意:

  • 请将上述 '/absolute/path/to/fiss-mcp' 替换为您实际克隆仓库的绝对路径。
  • 如果使用虚拟环境，请将 'python3' 替换为虚拟环境中 Python 解释器的绝对路径。
  • 配置完成后，请务必重启您的 Claude Desktop 应用程序或使用 'claude mcp reconnect terra' 命令。
  • 您可以使用 'claude mcp list' 命令来验证服务器是否已连接。

基本使用方法

配置并启动 MCP 服务器后，您可以通过 Claude 客户端与其进行交互。Claude 会根据您提出的问题和意图，自动选择并调用相应的工具。

示例对话:

  1. 列出工作空间:

    • 用户: "列出我所有的 Terra 工作空间"
    • Claude: 内部调用 'list_workspaces' 工具，然后返回工作空间列表。

  2. 查看数据表:

    • 用户: "显示我分析工作空间中的数据表"
    • Claude: 内部调用 'get_workspace_data_tables' 工具，并根据您的上下文提供工作空间名称和命名空间，然后返回数据表及其行数。

  3. 检查工作流状态:

    • 用户: "检查提交 ID 为 abc-123-def 的状态"
    • Claude: 内部调用 'get_submission_status' 工具，返回提交的总体状态、工作流数量和状态摘要。

  4. 调试失败的工作流:

    • 用户: "能帮我获取失败工作流的日志并调试它吗？"
    • Claude: 内部调用 'get_workflow_logs' 工具，可选择拉取日志内容并智能截断，然后根据日志内容提供调试建议。

数据隐私与安全考虑:

该 MCP 服务器允许 Claude 读取您的 Terra 工作空间数据，因此在使用敏感或受监管数据时请务必谨慎。避免将受限的基因组数据、受保护的健康信息（PHI）暴露给不安全的LLM服务，并始终遵守数据使用协议和IRB协议。建议在受控环境中处理敏感数据。

生产环境运行服务器

除了通过 MCP 客户端启动服务器外，您也可以独立运行：

  • 只读模式: 
    python src/terra_mcp/server.py
  • 启用写入模式: 
    python src/terra_mcp/server.py --allow-writes

开发与测试

如果您计划为该项目贡献代码或进行开发，请遵循项目 'README.md' 中的开发指南，包括添加新工具、编写测试以及遵循架构原则等。

信息

分类

AI与计算

访问项目