fiss MCP

特拉。生物MCP服务器

  

目录

• 可用工具

- 只读工具（始终可用） - 写访问工具（要求--允许写标志）

• 技能（程序工作流）
• 用例

- 示例用法

• 数据隐私和安全考虑
• 安装
• 用法

- 运行服务器（开发） - 运行服务器（生产） - Claude桌面集成 - Claude代码集成

• 测试
• 发展

- 项目结构 - 添加新工具

• 未来的增强功能
• 建筑
• 故障排除
• 贡献
• 许可证
• 资源

可用工具

此MCP服务器提供16个与Terra交互的工具。生物工作空间：

只读工具（始终可用）

这些工具在只读模式（默认）和启用写访问时都可用：

工作区和数据发现

• list_workspaces -列出经过身份验证的用户可访问的所有Terra工作区
• get_workspace_data_tables -列出工作区中具有行数的数据表（实体类型）
• get_entities -从Terra数据表中读取实体数据以进行工作流输入

工作流监控和状态

• list_submissions -列出工作区中所有工作流提交的状态和元数据
• get_submission_status -获取工作流提交的详细状态（支持可自定义的工作流限制）
• get_job_metadata -通过可选过滤获取特定工作流的克伦威尔元数据
• get_workflow_logs -通过可选的GCS内容提取和智能截断获取工作流日志
• get_workflow_outputs -从已完成的工作流中获取输出文件和值
• get_workflow_cost -获取工作流执行的成本信息
• get_batch_job_status -通过Google Batch API调试基础设施故障（docker pull errors，抢占，OOM）

工作流配置（只读）

• get_method_config -获取方法配置详细信息，包括WDL版本和输入/输出映射

写访问工具（必需 --allow-writes 旗帜）

⚠️ 这些工具需要启用写访问权限。 默认情况下，为了安全起见，服务器以只读模式运行。要使用这些工具，您必须使用以下命令启动服务器 --allow-writes 标志（见下面的集成部分）。

工作流配置管理

• update_method_config -更新方法配置（例如，更改WDL版本以匹配开发分支）
• copy_method_config -创建用于测试或开发的方法配置副本

工作流执行控制

• submit_workflow -为单个实体或批处理启动WDL工作流
• abort_submission -取消正在运行的工作流提交

数据管理

• upload_entities -上传或更新Terra数据表中的实体数据，并进行验证

技能（程序工作流）

此MCP服务器提供记录常见工作流程和最佳实践的技能。通过MCP资源提供技能，以提供未来的客户支持。

技能包括循序渐进的程序、最佳实践和反模式。

注： Claude Code和类似的代理目前不会自动使用MCP服务技能。程序知识也包含在工具文档字符串中。为未来的MCP客户支持提供技能，并作为参考文件。

用例

• WDL管道开发：使用Claude Code开发和调试WDL管道时，监控Terra工作流的运行
• 回归测试：在Terra上对基准数据集运行自动化测试
• 作业监控：跟踪提交状态、解释日志和调试工作流失败

示例用法

配置后，您可以与Terra交互。克劳德传记：

Human: List all my Terra workspaces

Claude: I'll list your accessible Terra workspaces.
[Claude calls list_workspaces tool]
You have access to 3 workspaces:
1. broad-firecloud-testing/demo-workspace (created by user@broad.io on 2024-01-15)
2. my-billing/analysis-workspace (created by user@broad.io on 2024-02-01)
...

Human: Show me the data tables in my analysis workspace

Claude: I'll retrieve the data tables from your analysis workspace.
[Claude calls get_workspace_data_tables with namespace="my-billing", name="analysis-workspace"]
The workspace has 2 data tables:
- participants: 150 rows
- samples: 450 rows

Human: Check the status of submission abc-123-def

Claude: I'll check the status of that submission.
[Claude calls get_submission_status with submission_id="abc-123-def"]
Submission abc-123-def is currently Running with 10 workflows:
- Succeeded: 7 workflows
- Running: 2 workflows
- Failed: 1 workflow

Human: Can you fetch the logs for the failed workflow and help me debug it?

Claude: I'll fetch the stderr logs for the failed workflow.
[Claude calls get_workflow_logs with workflow_id="wf-789", fetch_content=True]
The task "AlignReads" failed with this error at the end of the log:

OutOfMemory错误：Java堆空间 htsjdk.samtools。BAMRecord解码器（）

This is a memory issue. The task needs more RAM allocated. You can increase the memory in your WDL using the runtime attribute: `memory: "32 GB"`

Human: I have a large submission running as the most recent submission in workspace my_lab/my_workspace.
Can you summarize where each workflow is in the pipeline?

Claude: I'll check the submission status and analyze the running workflows.
[Claude calls list_submissions with namespace="my_lab", name="my_workspace", limit=1]
[Claude calls get_submission_status with submission_id="abc-123-def"]
[Claude calls get_job_metadata for running workflows to identify current task]

Submission abc-123-def has 500 workflows with this breakdown:
- Succeeded: 312 workflows (complete)
- Running: 156 workflows
  - 45 in "align_reads" (earliest stage)
  - 78 in "call_variants" (middle stage)
  - 33 in "annotate_vcf" (final stage)
- Failed: 12 workflows (see next for details)
- Queued: 20 workflows (waiting to start)

The running workflows are progressing normally through the pipeline.

Human: My submission had 32 workflow failures. Can you categorize what went wrong?

Claude: I'll analyze the failed workflows to identify failure patterns.
[Claude calls get_submission_status to identify failed workflow IDs]
[Claude calls get_job_metadata (summary mode) for each failed workflow]
[Claude calls get_batch_job_status for infrastructure failures]

Failure Analysis for 32 failed workflows:

| Category | Count | Root Cause |
|----------|-------|------------|
| OOM errors | 19 | call_variants task exceeded 16GB memory limit |
| Disk exhaustion | 10 | Temporary files filled disk in align_reads |
| Docker pull failures | 2 | Rate-limited pulling image from Docker Hub |
| Input data errors | 1 | Malformed BAM file (sample_47) |

Recommendations:
1. Increase memory to 32GB for call_variants task
2. Increase disk size to 200GB for align_reads
3. Consider using a private container registry to avoid Docker Hub rate limits
4. Check sample_47 BAM file integrity before resubmitting

Human: I ran our new optimized code as submission abc-123-new and the baseline as xyz-789-old
on the same 200 samples. Can you verify the outputs match and check if runtime improved?

Claude: I'll compare both submissions for correctness and performance.
[Claude calls get_submission_status for both submissions]
[Claude calls get_job_metadata for sample of workflows from each]
[Claude calls get_workflow_outputs to compare output files]
[Claude calls get_workflow_cost for both]

**Regression Test Results: New Code vs Baseline**

Correctness (200 samples):
- Output files match: 198/200 samples (99%)
- Minor differences: 2 samples have VCF annotation order differences (functionally equivalent)
- No data quality regressions detected

Performance (call_variants step):
- Baseline avg runtime: 47 minutes
- New code avg runtime: 31 minutes
- Improvement: 34% faster

Cost:
- Baseline total: $156.40
- New code total: $118.20
- Savings: 24% reduction

Conclusion: The optimization is successful. Outputs are equivalent and the
call_variants step shows the expected ~35% runtime improvement. Safe to merge.

Human: this is great, please post your findings as a comment on the open PR on this git branch.

数据隐私和安全考虑

⚠️ 此MCP服务器为Claude提供了从Terra工作区读取数据的能力。处理敏感、受限或受监管的数据时要格外小心。

❌ 请勿使用此工具：

1. 提取法律限制的基因组数据

- 不要检索实际的基因组序列、基因型或其他个体水平的遗传数据 - 不要让克劳德分析原始基因组数据文件（FASTQ、BAM、VCF等） - 不要从受控访问数据库复制受限的研究数据

1. 与免费层LLM共享受保护的健康信息（PHI）

- 免费和消费者LLM服务（包括Claude.ai免费版）可能会使用您的对话进行培训 - 未经适当的数据使用协议，不得共享患者标识符、临床数据或其他PHI - 在处理敏感数据之前，始终验证LLM服务的数据保留和使用策略

1. 违反数据使用协议或IRB协议

- Terra工作区通常包含具有严格使用限制的数据 - 请勿以违反贵机构IRB协议或数据使用协议的方式使用此工具 - 不要在批准的研究团队之外共享受控访问数据

✅ 安全使用案例：

• 元数据分析：查询工作区组织、工作流配置、提交状态
• 日志调试：分析错误消息和执行日志（通常不包含敏感数据）
• 工作流程优化：查看管道配置、资源使用和成本信息
• 去标识数据：使用符合所有适用法规的正确去标识或合成数据集
• 安全计算环境：在符合NIST-800-171标准的计算边界内运行时，与受限数据一起使用（例如，在具有适当安全控制的授权Google Cloud项目中的Vertex AI）

监管参考

美国国立卫生研究院和其他监管机构发布了关于使用基因组和健康数据生成人工智能的指导：

• 2008年8月25日: NIH资助接受者对生成性人工智能（GenAI）使用的期望
• NIH没有24-157: 美国国立卫生研究院资助的研究人员和申请机构关于生成人工智能（GenAI）工具的补充信息通知
• 法律分析: 生成式人工智能和基因组隐私 -隐私风险的学术分析

如有疑问，在使用此工具处理潜在敏感数据之前，请咨询您所在机构的IRB、数据治理办公室或法律顾问。

安装

先决条件

• Python 3.10或更高版本
• 为Terra配置的Google凭据。生物访问（通过FISS）
• 特拉。具有工作区访问权限的个人帐户

设置

1. 克隆此存储库：

git clone 
cd fiss-mcp

1. 安装依赖项：

备注：The firecloud 由于setuptools的兼容性，该软件包需要特殊安装(裂缝#192):

# Install setuptools dict[str, Any]:
    """Tool description that LLMs will see.

    Detailed description of what this tool does.

    Args:
        workspace_namespace: Description
        workspace_name: Description

    Returns:
        Dictionary with result data
    """
    try:
        ctx.info("Starting operation")
        # Implementation
        return {"result": "data"}
    except ToolError:
        raise
    except Exception as e:
        ctx.error(f"Error: {e}")
        raise ToolError("User-friendly error message")

示例（书写工具）：

@mcp.tool()
async def my_write_tool(
    workspace_namespace: Annotated[str, "Terra workspace namespace"],
    workspace_name: Annotated[str, "Terra workspace name"],
    ctx: Context,
) -> dict[str, Any]:
    """Tool that modifies Terra resources.

    Args:
        workspace_namespace: Description
        workspace_name: Description

    Returns:
        Dictionary with result data
    """
    # Check write access first
    _check_write_access(ctx)

    try:
        ctx.info("Starting write operation")
        # Implementation
        return {"result": "data"}
    except ToolError:
        raise
    except Exception as e:
        ctx.error(f"Error: {e}")
        raise ToolError("User-friendly error message")

未来的增强功能

潜在的扩张领域（见 CLAUDE.md 详细信息）：

• 工作流程分析：自动成本优化建议，呼叫缓存分析
• 增强的错误处理：瞬态故障的自动重试逻辑，速率限制回退
• WDL集成：WDL解析、验证和linting集成
• 批量操作：批量实体操作、工作区克隆
• Terra笔记本：与Terra笔记本电脑操作集成
• 高级过滤：具有复杂过滤器和分页功能的增强实体查询

建筑

设计原则

1. 默认情况下为只读：服务器在安全模式下运行；写操作需要显式 --allow-writes 旗帜
2. 显式工作空间标识：始终需要命名空间+名称（没有隐式的“当前工作区”）
3. 可操作的错误消息：所有错误都为LLM提供了明确的后续步骤
4. 智能日志截断：对于错误日志，返回出现故障的尾部（最后~25K个字符）
5. 两层错误处理：ToolError表示预期失败，掩码异常表示内部错误

关键依赖

• 快速MCP：用于构建MCP服务器的Python框架
• FISS（鞭炮声）：Terra的Python客户端。生物API
• 谷歌云存储：用于从地面军事系统获取工作流日志
• 派丹蒂克：数据验证和模式生成

故障排除

“列出工作区失败”错误

确保您的Google凭据配置正确：

# Check if gcloud is authenticated
gcloud auth list

# Or verify GOOGLE_APPLICATION_CREDENTIALS is set
echo $GOOGLE_APPLICATION_CREDENTIALS

工具未出现在Claude Desktop中

1. 验证MCP服务器是否已在中配置 claude_desktop_config.json
2. 检查到的绝对路径 server.py 是正确的
3. 完全重新启动克劳德桌面
4. 检查克劳德桌面日志： ~/Library/Logs/Claude/mcp*.log （macOS）

运行服务器时出现导入错误

确保您已安装所有依赖项：

pip install -r requirements.txt

或者以可编辑模式安装软件包：

pip install -e .

贡献

欢迎投稿！请确保：

• 遵循既定的代码模式和架构
• 在实现特性之前编写测试（TDD）
• 保持全面的错误处理
• 为LLM消费添加清晰的文档
• 在提交PR之前进行测试和梳理

许可证

看 许可证 文件以获取详细信息。

资源

• 模型上下文协议规范
• FastMCP文档
• FISS Python库
• 特拉。生物平台
• WDL规范