MCP 集成¶

MiQi 通过 MCP (Model Context Protocol) 集成外部工具服务，由 7 个 git submodule 管理。

MCP 服务列表¶

服务	目录	领域	功能	超时
raspa-mcp	`mcps/raspa-mcp`	材料科学	RASPA2 分子模拟 (GCMC / MD)	6 小时
zeopp-backend	`mcps/zeopp-backend`	材料科学	Zeo++ 多孔材料几何分析	默认
mofstructure-mcp	`mcps/mofstructure-mcp`	材料科学	MOF 晶体结构分析	默认
mofchecker-mcp	`mcps/mofchecker-mcp`	材料科学	MOF 结构验证与修复	默认
pdftranslate-mcp	`mcps/pdftranslate-mcp`	文档处理	学术论文 PDF 翻译	1 小时
miqrophi-mcp	`mcps/miqrophi-mcp`	科学计算	Miqrophi 计算平台接口	默认
feishu-mcp	`mcps/feishu-mcp`	办公协作	飞书消息/文档/日历	默认

架构¶

graph TB AGENT[MiQi Agent] AGENT --> CLIENT[MCP Client - mcp Python SDK] CLIENT --> RM[raspa-mcp<br/>subprocess / streamable-http] CLIENT --> ZO[zeopp-backend<br/>subprocess] CLIENT --> PT[pdftranslate-mcp<br/>subprocess] CLIENT --> MS[mofstructure-mcp] CLIENT --> MC[mofchecker-mcp] CLIENT --> MQ[miqrophi-mcp] CLIENT --> FS[feishu-mcp] RM --> REGISTRY[Tool Registry] ZO --> REGISTRY PT --> REGISTRY MS --> REGISTRY MC --> REGISTRY MQ --> REGISTRY FS --> REGISTRY REGISTRY --> CALLABLE[Agent 可调用 MCP 工具]

MCP 配置¶

{
  "tools": {
    "mcp_servers": {
      "raspa-mcp": {
        "command": "python",
        "args": ["-m", "raspa_mcp"],
        "env": { "RASPA_DIR": "/opt/raspa2" },
        "toolTimeout": 21600
      },
      "pdftranslate-mcp": {
        "command": "python",
        "args": ["-m", "pdftranslate_mcp"],
        "toolTimeout": 3600
      }
    }
  }
}

MCP 工具特性¶

心跳进度报告¶

长时运行的工具通过心跳机制报告进度：

每 15 秒:
MCP Server → { "type": "progress", "current": 45, "total": 100, "message": "Running GCMC..." }
  → Bridge → renderer → Chat UI 进度条

超时控制¶

工具	超时	原因
RASPA2 GCMC 模拟	6 小时	大规模分子模拟计算密集
PDF 翻译	1 小时	大文件处理耗时
其他工具	默认 (5 分钟)	常规计算

延迟加载¶

{
  "lazy": true   // 仅在首次调用时启动 MCP 服务器
}

节省资源，避免启动时加载所有 MCP 服务。

环境变量继承¶

MCP 子进程继承 Agent 进程的环境变量，可通过 env 字段追加自定义变量。

RASPA2 MCP 示例¶

# Agent 调用 RASPA2 GCMC 模拟
from raspa_mcp import create_workspace, get_simulation_template, simulate

# 1. 创建工作区目录结构
create_workspace(
    work_dir="/tmp/sim",
    framework_name="ZIF-8",
    cif_source_path="ZIF-8.cif"
)

# 2. 生成模拟输入
template = get_simulation_template("GCMC_CO2")
simulation_input = fill_template(template, {
    "PRESSURE": "1e5",
    "TEMPERATURE": "298",
    "CYCLES": "10000"
})

# 3. 运行模拟
result = simulate(work_dir="/tmp/sim")
# → 返回吸附量、选择性、等温线

子模块管理¶

# 克隆时包含子模块
git clone --recurse-submodules <repo-url>

# 更新子模块
git submodule update --init --recursive

# 配置超时
./scripts/configure_mcps.sh