tooluniverse-metabolomics

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Metabolomics Research

代谢组学研究

Comprehensive metabolomics research skill that identifies metabolites, analyzes studies, and searches metabolomics databases. Generates structured research reports with annotated metabolite information, study details, and database statistics.

一款综合性代谢组学研究技能，可识别代谢物、分析研究并搜索代谢组学数据库。生成包含注释化代谢物信息、研究详情及数据库统计数据的结构化研究报告。

Use Case

使用场景

Use this skill when asked to:

Identify or annotate metabolites (HMDB IDs, chemical properties, pathways)
Retrieve metabolomics study information from MetaboLights or Metabolomics Workbench
Search for metabolomics studies by keywords or disease
Analyze metabolite profiles or datasets
Generate comprehensive metabolomics research reports

Example queries:

"What is the HMDB ID and pathway information for glucose?"
"Get study details for MTBLS1"
"Find metabolomics studies related to diabetes"
"Analyze these metabolites: glucose, lactate, pyruvate"

在以下场景中使用本技能：

识别或注释代谢物（包括HMDB ID、化学性质、代谢通路）
从MetaboLights或Metabolomics Workbench获取代谢组学研究信息
按关键词或疾病搜索代谢组学研究
分析代谢物谱或数据集
生成综合性代谢组学研究报告

示例查询：

"葡萄糖的HMDB ID和通路信息是什么？"
"获取MTBLS1的研究详情"
"查找与糖尿病相关的代谢组学研究"
"分析这些代谢物：葡萄糖、乳酸、丙酮酸"

Databases Covered

覆盖的数据库

Primary metabolite databases:

HMDB (Human Metabolome Database): 220,000+ metabolites with structures, pathways, and biological roles
MetaboLights: Public metabolomics repository with thousands of studies
Metabolomics Workbench: NIH Common Fund metabolomics data repository
PubChem: Chemical properties and bioactivity data (fallback)

主要代谢物数据库：

HMDB（人类代谢组数据库）：包含22万+种代谢物，提供结构、通路及生物学功能信息
MetaboLights：公开的代谢组学研究存储库，包含数千项研究
Metabolomics Workbench：美国国立卫生研究院共同基金支持的代谢组学数据存储库
PubChem：化学性质与生物活性数据（备选数据源）

Research Workflow

研究工作流

The skill executes a 4-phase analysis pipeline:

本技能执行一个四阶段分析流程：

Phase 1: Metabolite Identification & Annotation

阶段1：代谢物识别与注释

For each metabolite in the input list:

Search HMDB by metabolite name
Retrieve HMDB ID, chemical formula, molecular weight
Get detailed metabolite information (description, pathways)
Fallback to PubChem for CID and chemical properties if HMDB unavailable

针对输入列表中的每个代谢物：

按代谢物名称搜索HMDB
获取HMDB ID、化学式、分子量
获取详细代谢物信息（描述、通路）
若HMDB无结果，从PubChem获取CID及化学性质作为备选

Phase 2: Study Details Retrieval

阶段2：研究详情检索

For provided study IDs:

Detect database type (MTBLS = MetaboLights, ST = Metabolomics Workbench)
Retrieve study metadata (title, description, organism, status)
Extract experimental design and data availability

针对提供的研究ID：

检测数据库类型（MTBLS对应MetaboLights，ST对应Metabolomics Workbench）
获取研究元数据（标题、描述、生物、状态）
提取实验设计与数据可用性信息

Phase 3: Study Search

阶段3：研究搜索

For keyword searches:

Search MetaboLights studies by query term
Return matching study IDs with preview information
Report total number of results

针对关键词搜索：

按查询词搜索MetaboLights研究
返回匹配的研究ID及预览信息
报告结果总数

Phase 4: Database Overview

阶段4：数据库概览

Always included in reports:

Sample recent studies from MetaboLights
Database statistics and availability
Integration information for all databases

报告中始终包含以下内容：

MetaboLights的近期研究样本
数据库统计数据与可用性
所有数据库的整合信息

Usage Patterns

使用模式

Pattern 1: Metabolite Identification

模式1：代谢物识别

Input:

Metabolite list: ["glucose", "lactate", "pyruvate"]

Output report includes:

HMDB IDs for each metabolite
Chemical formulas and molecular weights
Biological pathways
PubChem CIDs
SMILES representations

输入：

代谢物列表：["glucose", "lactate", "pyruvate"]

输出报告包含：

每个代谢物的HMDB ID
化学式与分子量
生物学通路
PubChem CID
SMILES表达式

Pattern 2: Study Retrieval

模式2：研究检索

Input:

Study ID: "MTBLS1" or "ST000001"

Output report includes:

Study title and description
Organism information
Study status and release date
Data availability

输入：

研究ID："MTBLS1" 或 "ST000001"

输出报告包含：

研究标题与描述
生物信息
研究状态与发布日期
数据可用性

Pattern 3: Study Search

模式3：研究搜索

Input:

Search query: "diabetes"
Optional organism filter

Output report includes:

Matching study IDs
Study titles and previews
Total result count

输入：

搜索查询词："diabetes"
可选生物过滤条件

输出报告包含：

匹配的研究ID
研究标题与预览
结果总数

Pattern 4: Comprehensive Analysis

模式4：综合分析

Input:

Metabolite list: ["glucose", "pyruvate"]
Study ID: "MTBLS1"
Search query: "diabetes"

Output report includes:

All phases combined (identification, study details, search results, overview)
Cross-referenced information
Complete metabolomics research summary

输入：

代谢物列表：["glucose", "pyruvate"]
研究ID："MTBLS1"
搜索查询词："diabetes"

输出报告包含：

所有阶段内容整合（识别、研究详情、搜索结果、概览）
交叉引用信息
完整的代谢组学研究摘要

Input Parameters

输入参数

metabolite_list (optional)

metabolite_list（可选）

List of metabolite names to identify and annotate.

Format: List of strings

Examples:

["glucose"]

["lactate", "pyruvate", "acetate"]

Note: Common names accepted; HMDB will find standard identifiers

需要识别与注释的代谢物名称列表。

格式：字符串列表

示例：

["glucose"]

["lactate", "pyruvate", "acetate"]

说明：接受常用名称；HMDB会自动匹配标准标识符

study_id (optional)

study_id（可选）

MetaboLights or Metabolomics Workbench study identifier.

Format: String starting with "MTBLS" or "ST"
Examples:
```
"MTBLS1"
```
,
```
"ST000001"
```
Note: Database auto-detected from prefix

MetaboLights或Metabolomics Workbench的研究标识符。

格式：以"MTBLS"或"ST"开头的字符串
示例：
```
"MTBLS1"
```
,
```
"ST000001"
```
说明：会根据前缀自动检测数据库

search_query (optional)

search_query（可选）

Keyword to search metabolomics studies.

Format: String (disease, compound, organism, method)
Examples:
```
"diabetes"
```
,
```
"glucose metabolism"
```
,
```
"LC-MS"
```

用于搜索代谢组学研究的关键词。

格式：字符串（疾病、化合物、生物、方法）
示例：
```
"diabetes"
```
,
```
"glucose metabolism"
```
,
```
"LC-MS"
```

organism (optional)

organism（可选）

Target organism for study filtering.

Format: String (scientific name)
Default:
```
"Homo sapiens"
```

Examples:

"Mus musculus"

"Saccharomyces cerevisiae"

用于过滤研究的目标生物。

格式：字符串（学名）
默认值：
```
"Homo sapiens"
```

示例：

"Mus musculus"

"Saccharomyces cerevisiae"

output_file (optional)

output_file（可选）

Path for the generated markdown report.

Format: String (filename with .md extension)
Default: Auto-generated timestamp-based filename

Examples:

"my_analysis.md"

"metabolomics_report.md"

生成的markdown报告路径。

格式：带.md扩展名的字符串
默认值：自动生成基于时间戳的文件名

示例：

"my_analysis.md"

"metabolomics_report.md"

Output Format

输出格式

All analyses generate a structured markdown report with:

Header section:

Report title and generation timestamp
Input parameters summary (metabolites, study ID, search query, organism)

Phase sections:

Clear section headers (## 1. Metabolite Identification, ## 2. Study Details, etc.)
Subsections for each metabolite or result
Consistent formatting (bold labels, tables for results)

Database overview:

Available databases and statistics
Recent studies sample
Integration information

Error handling:

Graceful error messages for unavailable data
Fallback strategies documented in output
"N/A" for missing fields (not blank)

所有分析都会生成结构化markdown报告，包含：

头部区域：

报告标题与生成时间戳
输入参数摘要（代谢物、研究ID、搜索查询词、生物）

阶段区域：

清晰的章节标题（## 1. 代谢物识别、## 2. 研究详情等）
每个代谢物或结果的子章节
统一格式（粗体标签、结果表格）

数据库概览：

可用数据库与统计数据
近期研究样本
整合信息

错误处理：

针对不可用数据的友好错误提示
输出中记录备选策略
缺失字段显示"N/A"（不留空）

Implementation Notes

实现说明

SOAP Tool Handling

SOAP工具处理

HMDB tools are SOAP-based and require special parameter handling:

```
HMDB_search
```
: Requires
```
operation="search"
```
parameter

HMDB_get_metabolite

: Requires

operation="get_metabolite"

parameter

Do not use
```
endpoint
```
or
```
method
```
parameters (not applicable to SOAP)

HMDB工具基于SOAP协议，需要特殊参数处理：

```
HMDB_search
```
：需要
```
operation="search"
```
参数

HMDB_get_metabolite

：需要

operation="get_metabolite"

参数

不要使用
```
endpoint
```
或
```
method
```
参数（不适用于SOAP协议）

Response Format Variations

响应格式差异

Tools return different response formats - handle all three:

Standard format:

{status: "success", data: [...], metadata: {...}}

Direct list:
```
[...]
```
(e.g., metabolights_list_studies)
Direct dict:
```
{field1: ..., field2: ...}
```
(e.g., some detail endpoints)

Always check response type with

isinstance()

before accessing fields.

工具返回不同的响应格式，需处理以下三种：

标准格式：

{status: "success", data: [...], metadata: {...}}

直接列表：
```
[...]
```
（例如metabolights_list_studies）
直接字典：
```
{field1: ..., field2: ...}
```
（例如部分详情端点）

访问字段前需始终用

isinstance()

检查响应类型。

Fallback Strategy

备选策略

Follow this hierarchy for robustness:

Primary source: Try main database first (HMDB for metabolites, MetaboLights for studies)
Fallback source: Use alternative database if primary fails (PubChem for chemical properties)
Default behavior: Show error message with context, continue with remaining phases

遵循以下层级确保鲁棒性：

主数据源：优先尝试主数据库（代谢物用HMDB，研究用MetaboLights）
备选数据源：主数据库失败时使用备选数据库（化学性质用PubChem）
默认行为：显示带上下文的错误提示，继续执行剩余阶段

Progressive Report Writing

渐进式报告写入

Write report incrementally to avoid memory issues:

Create output file early in pipeline
Append sections as each phase completes
Flush to disk regularly for long analyses
Return file path for user access

采用增量写入报告以避免内存问题：

在流程早期创建输出文件
完成每个阶段后追加章节
长分析时定期刷新到磁盘
返回文件路径供用户访问

Tool Discovery

工具发现

The skill automatically discovers and uses these tools from ToolUniverse:

HMDB Tools:

```
HMDB_search
```
: Search metabolites by name
```
HMDB_get_metabolite
```
: Get detailed metabolite information

MetaboLights Tools:

```
metabolights_list_studies
```
: List available studies
```
metabolights_search_studies
```
: Search studies by keyword
```
metabolights_get_study
```
: Get study details by ID

Metabolomics Workbench Tools:

```
MetabolomicsWorkbench_get_study
```
: Get study information

MetabolomicsWorkbench_search_compound_by_name

: Search compounds

PubChem Tools:

```
PubChem_get_CID_by_compound_name
```
: Get PubChem CID
```
PubChem_get_compound_properties_by_CID
```
: Get chemical properties

No manual tool configuration required - all tools loaded automatically.

本技能会自动从ToolUniverse发现并使用以下工具：

HMDB工具：

```
HMDB_search
```
：按名称搜索代谢物
```
HMDB_get_metabolite
```
：获取详细代谢物信息

MetaboLights工具：

```
metabolights_list_studies
```
：列出可用研究
```
metabolights_search_studies
```
：按关键词搜索研究
```
metabolights_get_study
```
：按ID获取研究详情

Metabolomics Workbench工具：

```
MetabolomicsWorkbench_get_study
```
：获取研究信息

MetabolomicsWorkbench_search_compound_by_name

：搜索化合物

PubChem工具：

```
PubChem_get_CID_by_compound_name
```
：获取PubChem CID
```
PubChem_get_compound_properties_by_CID
```
：获取化学性质

无需手动配置工具 - 所有工具会自动加载。

Common Issues

常见问题

Issue: HMDB returns "Error querying HMDB: 0"

问题：HMDB返回"Error querying HMDB: 0"

Cause: HMDB search returned empty results or index error accessing first result Solution: This is expected for uncommon metabolites; PubChem fallback will be attempted

原因：HMDB搜索无结果或访问第一个结果时出现索引错误 解决方案：这对不常见代谢物是正常情况；会自动尝试PubChem备选

Issue: Study details show "N/A" for all fields

问题：研究详情所有字段显示"N/A"

Cause: Study ID not found or API unavailable Solution: Verify study ID format (MTBLS* or ST*), check if study is public

原因：研究ID不存在或API不可用 解决方案：验证研究ID格式（MTBLS或ST），检查研究是否公开

Issue: Tool not found errors

问题：工具未找到错误

Cause: Missing API keys for some databases Solution: Check

.env.template

, add required API keys to

.env

file (most metabolomics tools work without keys)

原因：部分数据库缺少API密钥 解决方案：查看

.env.template

，将所需API密钥添加到

.env

文件（大多数代谢组学工具无需密钥即可使用）

Issue: Large metabolite lists cause slow execution

问题：大型代谢物列表导致执行缓慢

Cause: Pipeline queries each metabolite individually Solution: Reports limit to first 10 metabolites; consider batching for >20 metabolites

原因：流程会逐个查询每个代谢物 解决方案：报告默认限制前10个代谢物；超过20个时建议分批处理

Tool Parameter Reference

工具参数参考

HMDB Tools (SOAP)

HMDB工具（SOAP）

Tool	Required Parameters	Optional Parameters	Response Format	Notes
`HMDB_search`	`operation="search"` , `query`	-	`{status, data: []}`	SOAP tool - operation required
`HMDB_get_metabolite`	`operation="get_metabolite"` , `hmdb_id`	-	`{status, data: {}}`	SOAP tool - operation required

工具	必填参数	可选参数	响应格式	说明
`HMDB_search`	`operation="search"` , `query`	-	`{status, data: []}`	SOAP工具 - 必须指定operation参数
`HMDB_get_metabolite`	`operation="get_metabolite"` , `hmdb_id`	-	`{status, data: {}}`	SOAP工具 - 必须指定operation参数

MetaboLights Tools (REST)

MetaboLights工具（REST）

Tool	Required Parameters	Optional Parameters	Response Format	Notes
`metabolights_list_studies`	-	`size` (default: 10)	`{status, data: []}` or `[...]`	May return direct list
`metabolights_search_studies`	`query`	-	`{status, data: []}`	Returns study IDs
`metabolights_get_study`	`study_id`	-	`{status, data: {}}`	Full study metadata

工具	必填参数	可选参数	响应格式	说明
`metabolights_list_studies`	-	`size` （默认：10）	`{status, data: []}` 或 `[...]`	可能返回直接列表
`metabolights_search_studies`	`query`	-	`{status, data: []}`	返回研究ID
`metabolights_get_study`	`study_id`	-	`{status, data: {}}`	完整研究元数据

Metabolomics Workbench Tools (REST)

Metabolomics Workbench工具（REST）

Tool	Required Parameters	Optional Parameters	Response Format	Notes
`MetabolomicsWorkbench_get_study`	`study_id`	`output_item` (default: "summary")	`{status, data: {}}`	Data may be text
`MetabolomicsWorkbench_search_compound_by_name`	`compound_name`	-	`{status, data: {}}`	Compound information

工具	必填参数	可选参数	响应格式	说明
`MetabolomicsWorkbench_get_study`	`study_id`	`output_item` （默认："summary"）	`{status, data: {}}`	数据可能为文本格式
`MetabolomicsWorkbench_search_compound_by_name`	`compound_name`	-	`{status, data: {}}`	化合物信息

PubChem Tools (REST)

PubChem工具（REST）

Tool	Required Parameters	Optional Parameters	Response Format	Notes
`PubChem_get_CID_by_compound_name`	`compound_name`	-	`{status, data: {cid}}`	Returns CID
`PubChem_get_compound_properties_by_CID`	`cid`	-	`{status, data: {}}`	Chemical properties

Important: All parameter names and requirements apply to both Python SDK and MCP implementations.

工具	必填参数	可选参数	响应格式	说明
`PubChem_get_CID_by_compound_name`	`compound_name`	-	`{status, data: {cid}}`	返回CID
`PubChem_get_compound_properties_by_CID`	`cid`	-	`{status, data: {}}`	化学性质

重要提示：所有参数名称及要求适用于Python SDK和MCP实现。

Summary

总结

The Metabolomics Research skill provides comprehensive metabolomics analysis through a 4-phase pipeline that:

Identifies metabolites using HMDB (primary) and PubChem (fallback) databases
Retrieves study details from MetaboLights and Metabolomics Workbench repositories
Searches studies by keywords across metabolomics databases
Generates structured reports with all findings in readable markdown format

Key Features:

✅ 100% test coverage with working pipeline
✅ Handles SOAP tools correctly (HMDB requires
```
operation
```
parameter)
✅ Implements fallback strategies (HMDB → PubChem)
✅ Graceful error handling (continues if one phase fails)
✅ Progressive report writing (memory-efficient)
✅ Implementation-agnostic documentation (works with Python SDK and MCP)

Best for:

Metabolite annotation and pathway analysis
Study discovery and data retrieval
Comprehensive metabolomics research reports
Multi-database metabolomics queries

Limitations:

HMDB may not have all metabolites (fallback to PubChem)
Some studies require authentication or are not public
Large metabolite lists (>10) auto-limited in reports
API rate limits may affect large-scale queries

代谢组学研究技能通过四阶段流程提供全面的代谢组学分析：

识别代谢物：使用HMDB（主数据源）和PubChem（备选数据源）
检索研究详情：从MetaboLights和Metabolomics Workbench存储库获取
搜索研究：跨代谢组学数据库按关键词搜索
生成结构化报告：将所有结果以可读的markdown格式呈现

核心特性：

✅ 100%测试覆盖，流程可用
✅ 正确处理SOAP工具（HMDB需要
```
operation
```
参数）
✅ 实现备选策略（HMDB → PubChem）
✅ 友好的错误处理（某一阶段失败仍可继续）
✅ 渐进式报告写入（内存高效）
✅ 与实现无关的文档（适用于Python SDK和MCP）

适用场景：

代谢物注释与通路分析
研究发现与数据检索
综合性代谢组学研究报告
多数据库代谢组学查询

局限性：

HMDB可能不包含所有代谢物（可备选PubChem）
部分研究需要认证或未公开
报告自动限制大型代谢物列表（>10个）
API速率限制可能影响大规模查询

Quick Start

快速开始

See

QUICK_START.md

for:

Python SDK implementation with code examples
MCP integration instructions
Step-by-step tutorial for common workflows
Advanced usage patterns

查看

QUICK_START.md

获取：

带代码示例的Python SDK实现
MCP集成说明
常见工作流分步教程
高级使用模式