Gem Flux MCP

Gem Flux MCP服务器

使用ModelSEEDpy和COBRApy进行基因组尺度代谢建模的模型上下文协议（MCP）服务器

   

通过AI友好的模型上下文协议界面构建、填充和分析代谢模型。

______________________________________________________________________

快速开始

先决条件

• Python 3.11 （不是3.12+）-Python 3.12+打破了scikit-learn依赖关系
• 紫外线 包管理器- 安装指南
• ModelSEED数据库文件 -下载以下说明

1.安装

git clone https://github.com/jplfaria/gem-flux-mcp.git
cd gem-flux-mcp
uv sync

2.下载数据库文件

mkdir -p data/database data/templates

# ModelSEED database (33,993 compounds, 43,775 reactions)
wget -O data/database/compounds.tsv https://raw.githubusercontent.com/ModelSEED/ModelSEEDDatabase/master/Biochemistry/compounds.tsv
wget -O data/database/reactions.tsv https://raw.githubusercontent.com/ModelSEED/ModelSEEDDatabase/master/Biochemistry/reactions.tsv

# Templates (from ModelSEEDpy installation)
cp .venv/lib/python3.11/site-packages/modelseedpy/templates/*.json data/templates/

3.启动服务器

./start-server.sh

预期产量：

[INFO] Loading ModelSEED database from ./data/database
[INFO] Loaded 33,993 compounds, 43,775 reactions
[INFO] Server ready - accepting MCP requests

______________________________________________________________________

特性

核心建模：

• 基于模板的蛋白质序列建模
• 两阶段填补空白（ATP校正+基因组尺度）
• 具有详细通量分布的通量平衡分析
• 从ModelSEED化合物ID创建生长培养基

数据库集成：

• 搜索33993个化合物和43775个反应
• 按名称、公式、EC编号或途径查找
• 交叉引用KEGG、BiGG、MetaCyc、ChEBI

会话管理：

• 内存模型和媒体存储
• 列出、筛选和删除模型
• 预定义的培养基库（葡萄糖、丙酮酸、需氧/厌氧）

______________________________________________________________________

MCP工具

Gem Flux提供11种MCP工具，分为三类：

核心建模工具（4）

1. build_media -从化合物ID创建生长培养基
2. build_model -从蛋白质序列构建代谢模型
3. gapfill_model -添加反应以促进增长
4. run_fba -执行通量平衡分析

数据库查找工具（4）

1. get_compound_name -按ID查找化合物
2. search_compounds -按名称/化学式搜索化合物
3. get_reaction_name -按ID查找反应
4. search_reactions -按名称/EC/途径搜索反应

会话管理工具（3）

1. list_models -列出会话中的所有模型
2. delete_model -从会话中删除模型
3. list_media -列出会话中的所有媒体

详细的工具文档： 看 docs/tools/README.md

______________________________________________________________________

工作流示例

从蛋白质序列到通量预测的完整工作流程：

from gem_flux_mcp.tools import build_model, gapfill_model, run_fba

# 1. Build draft model from protein sequences
model = await build_model(
    protein_sequences={
        "prot_001": "MKLVINLVGNSGLGKSTFTQRLIN...",
        "prot_002": "MKQHKAMIVALERFRKEKRDAALL..."
    },
    template="GramNegative",
    model_name="E_coli_K12"
)
# Returns: model_id="E_coli_K12.draft"

# 2. Gapfill for growth in glucose minimal media
gapfilled = gapfill_model(
    model_id="E_coli_K12.draft",
    media_id="glucose_minimal_aerobic",  # Predefined media
    target_growth_rate=0.01
)
# Returns: model_id="E_coli_K12.draft.gf", reactions_added=5

# 3. Run FBA to predict fluxes
fba = run_fba(
    model_id="E_coli_K12.draft.gf",
    media_id="glucose_minimal_aerobic"
)
# Returns: objective_value=0.874 (growth rate in hr⁻¹)

更多示例： 看 笔记本电脑/ Jupyter笔记本示例

______________________________________________________________________

安装

系统要求

• python 仅限3.11.x（3.12+中断依赖关系）
• 内存： 最低4GB，建议8GB
• 磁盘： 2 GB（包括数据库文件）

为什么选择Python 3.11？

Python 3.12+已删除 distutils，破碎 scikit-learn 1.2.0 （模型SEEDpy依赖关系）。使用Python 3.11.x。

# Check version
python --version  # Must be 3.11.x

# Install Python 3.11
brew install python@3.11          # macOS
sudo apt install python3.11       # Ubuntu/Debian

安装UV

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Verify
uv --version

______________________________________________________________________

用法

启动服务器

# Basic start
./start-server.sh

# Custom host/port
export GEM_FLUX_HOST=0.0.0.0
export GEM_FLUX_PORT=9090
./start-server.sh

# Manual start
uv run python -m gem_flux_mcp.server

连接到服务器

服务器使用 模型上下文协议（MCP） 使用JSON-RPC 2.0传输。

MCP请求示例：

{
  "jsonrpc": "2.0",
  "id": "call_123",
  "method": "tools/call",
  "params": {
    "name": "build_media",
    "arguments": {
      "compounds": ["cpd00027", "cpd00007"],
      "default_uptake": 100.0
    }
  }
}

与StructBioReasoner集成

Gem Flux MCP与 结构调压器，在多智能体蛋白质工程工作流程中实现代谢建模。

快速设置：

1. 将Gem Flux MCP服务器添加到StructBioReasoner配置中
2. 创建MetabolicModeler代理（可选）
3. 使用任何代理的宝石通量工具

完整指南： docs/结构生物推理_集成_指南.md

可选：LLM与Argo集成

通过Argo LLM网关实现自然语言交互：

# Install argo-proxy (separate from gem-flux-mcp)
pip install argo-proxy

# Start proxy
argo-proxy  # Port 8000

# Use ArgoMCPClient
from gem_flux_mcp.argo_client import ArgoMCPClient
client = ArgoMCPClient()
client.initialize_sync()
response = client.chat("Build a model for E. coli genome 83333.1")

注： Argo是可选的。Gem-Flux在Python API和MCP集成中不使用它。

完整指南： docs/ARGO_LLM_可靠性_研究.md

______________________________________________________________________

配置

通过环境变量进行配置：

# Server binding
export GEM_FLUX_HOST="localhost"     # Default: localhost
export GEM_FLUX_PORT="8080"          # Default: 8080

# Resource paths
export GEM_FLUX_DATABASE_DIR="./data/database"
export GEM_FLUX_TEMPLATE_DIR="./data/templates"

# Logging
export GEM_FLUX_LOG_LEVEL="INFO"    # DEBUG, INFO, WARNING, ERROR
export GEM_FLUX_LOG_FILE="./gem-flux.log"

# Storage limits
export GEM_FLUX_MAX_MODELS="100"
export GEM_FLUX_MAX_MEDIA="50"

______________________________________________________________________

发展

运行测试

# All tests (785 tests, 90% coverage)
uv run pytest

# Specific test types
uv run pytest tests/unit/           # Unit tests only
uv run pytest tests/integration/    # Integration tests only

# With coverage
uv run pytest --cov=src --cov-report=html

代码质量

uv run ruff check src/      # Linting
uv run mypy src/            # Type checking
uv run black src/           # Formatting

______________________________________________________________________

故障排除

常见问题

Python 3.12+错误：

ModuleNotFoundError: No module named 'distutils'

解决方案： 使用Python 3.11.x（参见 安装)

找不到数据库：

[ERROR] Database file not found: data/database/compounds.tsv

解决方案： 下载数据库文件（请参阅 快速开始)

找不到模板：

[ERROR] Required template missing: GramNegModelTemplateV6.json

解决方案： 从ModelSEEDpy安装中复制模板

cp .venv/lib/python3.11/site-packages/modelseedpy/templates/*.json data/templates/

填隙不可行：

InfeasibilityError: Cannot find reactions to enable growth

解决：

• 尝试更丰富的介质（更多化合物）
• 降低 target_growth_rate （默认值：0.01）
• 通过以下方式验证媒体组成 list_media()

调试模式：

export GEM_FLUX_LOG_LEVEL=DEBUG
./start-server.sh

______________________________________________________________________

文档

工具文档：

• docs/tools/README.md -完整的工具参考
• docs/tools/build_model.md -模型构建指南
• docs/tools/gapfill_model.md -填隙指南
• docs/tools/run_fba.md -FBA执行指南

集成指南：

• docs/结构生物推理_集成_指南.md
• docs/ARGO_LLM_可靠性_研究.md

规格：

• 规格/001-系统概述.md -建筑
• 规格/002-data格式.md -数据结构
• 规格/ -20种洁净室规格

发展：

• docs/TEST.md -测试指南
• docs/ATP_CORRECTION.md -ATP校正功能
• .claude/claude.md -人工智能开发指南

______________________________________________________________________

贡献

我们欢迎捐款！关键要求：

• Python 3.11 带有类型提示
• 先测试 （TDD）-保持≥80%的覆盖率
• 所有测试均通过 - uv run pytest 返回0
• 代码质量 - ruff check 和 mypy 通过
• 谷歌风格的文档字符串

看 贡献.md 详细指南。

______________________________________________________________________

许可证

MIT许可证-请参阅 许可证

______________________________________________________________________

支持

• 问题： https://github.com/jplfaria/gem-flux-mcp/issues
• 文档： docs/ 和 规格/
• 联系人： 何塞·P·法里亚(jplfaria@anl.gov)

______________________________________________________________________

致谢

内置：

• Modelseedpy -代谢模型构建
• 眼镜蛇 -基于约束的建模
• FastMCP -MCP服务器框架
• 紫外线 -Python包管理器

数据：

• ModelSEED数据库 -生物化学数据库

______________________________________________________________________

状态： 生产就绪MVP v0.1.0 最后更新时间： 2025年11月4日