特拉。生物MCP服务器
A. 模型上下文协议(MCP) 使Claude和Claude Code能够与之交互的服务器 特拉。个人简介 工作空间通过 FISS(Firecloud)API.
目录
- 可用工具
- 只读工具(始终可用)
- 写访问工具(要求--允许写标志)
- 技能(程序工作流)
- 用例
- 示例用法
- 数据隐私和安全考虑
- 安装
- 用法
- 运行服务器(开发)
- 运行服务器(生产)
- 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资源提供技能,以提供未来的客户支持。
| 技能 | 何时使用 |
|---|---|
debug-workflow-failure |
调试失败的工作流提交、识别错误模式、解决基础架构问题 |
extract-workflow-data |
从工作流元数据中提取特定数据,而不加载100K+令牌 |
submit-workflow-safely |
提交前验证以及在单个实体和批处理之间的选择 |
navigate-subworkflows |
使用嵌套的WDL子工作流,查找子工作流ID |
manage-context-size |
通过分散的工作流、大型数据表或冗长的元数据防止上下文耗尽 |
技能包括循序渐进的程序、最佳实践和反模式。
> 注: 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. 克隆此存储库:```bash
git clone
cd fiss-mcp
- 安装依赖项:
备注:The firecloud 由于setuptools的兼容性,该软件包需要特殊安装(裂缝#192):```bash
Install setuptools<80 first (required for firecloud)
pip install "setuptools<80"
Install all dependencies with --no-build-isolation
pip install --no-build-isolation -r requirements.txt
对于开发(包括测试依赖关系):```bash
# Install setuptools<80 first (required for firecloud)
pip install "setuptools<80"
# Install all dependencies with --no-build-isolation
pip install --no-build-isolation -r requirements.txt
# Install additional test/development dependencies
pip install pytest-cov ruff
- 验证您的Google凭据是否已配置为FISS:```python
from firecloud import api as fapi
response = fapi.list_workspaces()
print(response.status_code) # Should be 200
## 用法
### 运行服务器(开发)
在开发模式下测试服务器,并记录详细日志:```bash
# Read-only mode (default)
fastmcp dev src/terra_mcp/server.py
# Write-enabled mode
fastmcp dev src/terra_mcp/server.py -- --allow-writes
这将启动一个交互式开发会话,您可以在其中测试工具。
运行服务器(生产)
使用stdio传输运行服务器(用于Claude Desktop集成):```bash
Read-only mode (default - recommended for safety)
fastmcp run src/terra_mcp/server.py
Write-enabled mode (for active development)
fastmcp run src/terra_mcp/server.py -- --allow-writes
或者直接运行:```bash
# Read-only mode (default)
python src/terra_mcp/server.py
# Write-enabled mode
python src/terra_mcp/server.py --allow-writes
Claude桌面集成
要将此MCP服务器与Claude Desktop一起使用,请将以下内容添加到您的Claude Desktop配置文件中:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
视窗: %APPDATA%\Claude\claude_desktop_config.json
只读模式(默认-出于安全考虑建议使用)
此配置启用所有只读工具(监视、查询、查看),但阻止写入操作:```json
{
"mcpServers": {
"terra": {
"command": "python3",
"args": ["/absolute/path/to/fiss-mcp/src/terra_mcp/server.py"]
}
}
}
#### 写启用模式(用于主动开发)
启用写入操作(`update_method_config`, `copy_method_config`, `submit_workflow`, `abort_submission`, `upload_entities`),添加 `--allow-writes` 标志:```json
{
"mcpServers": {
"terra": {
"command": "python3",
"args": [
"/absolute/path/to/fiss-mcp/src/terra_mcp/server.py",
"--allow-writes"
]
}
}
}
替换 /absolute/path/to/fiss-mcp 使用克隆存储库的实际路径。
备注:如果您在Python虚拟环境中安装了依赖项,请替换 python3 使用venv Python解释器的绝对路径(例如。, /absolute/path/to/venv/bin/python3).
备注:如果您尚未在本地使用Google Cloud进行身份验证,则可能需要添加凭据:```json
{
"mcpServers": {
"terra": {
"command": "python3",
"args": [
"/absolute/path/to/fiss-mcp/src/terra_mcp/server.py",
"--allow-writes"
],
"env": {
"GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/credentials.json"
}
}
}
}
更新配置后,重新启动Claude Desktop。
### Claude代码集成
#### 只读模式(默认-出于安全考虑建议使用)
要以只读模式(监视、查询、仅查看)使用此MCP服务器和Claude Code,请运行:```bash
claude mcp add terra --transport stdio \
-- python3 \
/absolute/path/to/fiss-mcp/src/terra_mcp/server.py
写启用模式(用于主动开发)
启用写入操作(update_method_config, copy_method_config, submit_workflow, abort_submission, upload_entities),添加 --allow-writes 标志:```bash
claude mcp add terra --transport stdio \
-- python3 \
/absolute/path/to/fiss-mcp/src/terra_mcp/server.py \
--allow-writes
替换 `/absolute/path/to/fiss-mcp` 使用克隆存储库的实际路径。
**备注**:如果您在Python虚拟环境中安装了依赖项,请使用venv Python解释器的绝对路径,而不是 `python3`:```bash
# Read-only mode
claude mcp add terra --transport stdio \
-- /absolute/path/to/venv/bin/python3 \
/absolute/path/to/fiss-mcp/src/terra_mcp/server.py
# Write-enabled mode
claude mcp add terra --transport stdio \
-- /absolute/path/to/venv/bin/python3 \
/absolute/path/to/fiss-mcp/src/terra_mcp/server.py \
--allow-writes
如果您需要指定Google Cloud凭据:```bash
Read-only mode with credentials
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
Write-enabled mode with credentials
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 \
--allow-writes
要验证服务器是否已连接:```bash
claude mcp list
要在代码更改后重新连接,请执行以下操作:```bash
claude mcp reconnect terra
## 测试
运行测试套件以验证服务器实现:```bash
# Install dependencies (if not already installed)
pip install "setuptools<80"
pip install --no-build-isolation -r requirements.txt
pip install pytest-cov
# Run tests
PYTHONPATH=src pytest tests/ -v
# Run with coverage
PYTHONPATH=src pytest tests/ --cov=src/terra_mcp --cov-report=term
该测试套件包括93个综合测试:
- 服务器初始化验证
- 工具登记检查(所有16个工具)
- 模拟FISS API响应
- 模拟地面军事系统日志获取和截断
- 错误处理场景(404、403、400、409、API故障、地面军事系统错误)
- 参数验证(max_works、include_keys、fetch_content、truncate、表达式、entity_data等)
- 辅助功能测试(截断逻辑、GCS URL解析)
- 只读模式安全功能测试(7个测试验证写入操作是否被正确阻止)
- 涵盖所有工具类别:工作区发现、监控、工作流管理和数据管理
发展
项目结构```
fiss-mcp/
├── src/terra_mcp/
│ ├── init.py # Package initialization
│ └── server.py # MCP server implementation
├── tests/
│ └── test_server.py # Test suite
├── requirements.txt # Dependencies
├── pyproject.toml # Project configuration
├── CLAUDE.md # Project specification
└── README.md # This file
### 添加新工具
使用额外的Terra扩展服务器。生物功能:
1. 在中添加工具功能 `src/terra_mcp/server.py`
1. 使用 `@mcp.tool()` 装饰器
1. 添加全面的文档字符串(LLM可见)
1. 使用 `Annotated` 参数描述的类型提示
1. 实施两层错误处理(面向用户的错误为ToolError)
1. 如果工具修改Terra资源,则添加写访问检查
1. 在中添加测试 `tests/test_server.py` 遵循TDD原则(使用 `enable_writes` 书写工具夹具)
示例(只读工具):```python
@mcp.tool()
async def my_new_tool(
workspace_namespace: Annotated[str, "Terra workspace namespace"],
workspace_name: Annotated[str, "Terra workspace name"],
ctx: Context,
) -> 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")
示例(书写工具):```python
@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` 旗帜
1. **显式工作空间标识**:始终需要命名空间+名称(没有隐式的“当前工作区”)
1. **可操作的错误消息**:所有错误都为LLM提供了明确的后续步骤
1. **智能日志截断**:对于错误日志,返回出现故障的尾部(最后~25K个字符)
1. **两层错误处理**:ToolError表示预期失败,掩码异常表示内部错误
### 关键依赖
- **快速MCP**:用于构建MCP服务器的Python框架
- **FISS(鞭炮声)**:Terra的Python客户端。生物API
- **谷歌云存储**:用于从地面军事系统获取工作流日志
- **派丹蒂克**:数据验证和模式生成
## 故障排除
### “列出工作区失败”错误
确保您的Google凭据配置正确:```bash
# Check if gcloud is authenticated
gcloud auth list
# Or verify GOOGLE_APPLICATION_CREDENTIALS is set
echo $GOOGLE_APPLICATION_CREDENTIALS
工具未出现在Claude Desktop中
- 验证MCP服务器是否已在中配置
claude_desktop_config.json - 检查到的绝对路径
server.py是正确的 - 完全重新启动克劳德桌面
- 检查克劳德桌面日志:
~/Library/Logs/Claude/mcp*.log(macOS)
运行服务器时出现导入错误
确保您已安装所有依赖项:```bash
pip install -r requirements.txt
或者以可编辑模式安装软件包:```bash
pip install -e .
贡献
欢迎投稿!请确保:
- 遵循既定的代码模式和架构
- 在实现特性之前编写测试(TDD)
- 保持全面的错误处理
- 为LLM消费添加清晰的文档
- 在提交PR之前进行测试和梳理
许可证
看 许可证 文件以获取详细信息。
资源
- 模型上下文协议规范
- FastMCP文档
- FISS Python库
- 特拉。生物平台
- WDL规范
