使用说明
raspa mcp
一夜之间，将任何人工智能代理变成分子模拟专家。
raspa-mcp 是一个 模型上下文协议（MCP） 包装服务器 RASPA2 --多孔材料的金标准分子模拟引擎——变成一个干净、对试剂友好的工具层。输入CIF文件和分子名称；剩下的就交给你的代理人处理。
为什么是raspa mcp？
正确运行RASPA2需要深厚的专业知识：选择正确的集成、设置晶胞复制、选择力场、验证埃瓦尔德求和参数以及解析Fortran风格的输出文件。从历史上看，这种知识只存在于计算化学家的头脑中，而不存在于其他任何地方。
raspa-mcp 将该专业知识编码为 20个结构化MCP工具 --涵盖RASPA2支持的每种主要仿真类型，以便LLM代理 羽状流 可以在没有人为干预的情况下自主设计、验证、执行和解释分子模拟。
功能概览
模拟模板（12种类型）
| 模板 | 目的 |
|---|---|
GCMC |
大正则蒙特卡罗吸附等温线 |
Widom |
Widom试验粒子插入——无限稀释下的亨利系数 |
VoidFraction |
氦气空隙率（GCMC的先决条件） |
NVT-MC |
固定N蒙特卡罗——组态采样，RDF |
NPT-MC |
可变体积MC——平衡密度，柔性电池 |
MD |
NVT分子动力学——扩散、传输 |
NPT-MD |
恒压MD——热膨胀 |
NVE-MD |
微正则MD——节能标杆 |
GCMCMixture |
二元混合物GCMC——共吸附、选择性 |
CBMC |
构型偏差MC——链/柔性分子（C4+） |
TI |
热力学积分——自由能ΔA |
FlexibleMD |
柔性框架MD--呼吸、开门 |
输出解析（7个解析器）
- 吸附负荷 --mol/kg，mg/g，cm³（STP）/g，分子/uc，±误差
- 等位热Qst --能量波动[kJ/mol]
- 亨利系数&μ_ex --从Widom插入，−RT ln（W）
- 氦空隙率 --直接提取
- 径向分布函数g（r） --全r/g（r）阵列峰值检测
- MSD → 扩散系数 --通过爱因斯坦关系（NumPy线性拟合，后50%的轨迹）计算自D_s和集体D_c
- 三维密度网格 --从中提取二维切片
.grid文件 - 热力学积分 --梯形∫⟨∂U/∃λ⟩dλ→ ΔA[kJ/mol]
- 多组分混合物 --具有向后兼容性的每个组件加载
分析工具
- 选择性S_AB —
(x_A/x_B) / (y_A/y_B)来自混合物载荷 - 等温绘图 --单和多MOF比较PNG（matplotlib）
- 密度切片绘图 --基于3D网格数据的热图PNG
内置知识库
- 6个分子：CO2、N2、CH4、H2O、氦气、正丁烷（TraPPE/SPC-E）
- 5个力场：TraPPE-CO2/N2/CH4/H2O、UFF——具有混合规则、伪原子定义
- 输入验证器 --RASPA2运行前捕获20多个常见错误
- 环境检查器 --在服务器启动时报告RASPA2准备就绪
安装
0.安装uv（如果还没有）
# Linux / macOS
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
紫外线 是一个快速的Python包管理器。它取代了
pip+venv使用单个工具自动处理Python版本。
1.克隆并安装Python包
git clone https://github.com/lichman0405/raspa-mcp
cd raspa-mcp
uv sync
uv sync 在下面创建虚拟环境 .venv/，固定Python版本（3.11+），并安装所有依赖项——无需手动 venv 或 pip 需要。
2.编译和配置RASPA2（一次性设置）
uv run python -m raspa_mcp.installer
这个命令：
- 检查生成工具(
git,gcc,make,autoconf,automake,libtool)以及 自动安装任何缺失的内容 通过apt-get/dnf/yum/brew等等 - 克隆 RASPA2来自GitHub 并从源代码编译
- 安装到
~/.local/raspa2默认情况下（用覆盖--prefix) - 写入
RASPA_DIR和PATH自动导出到shell RC文件
# custom install prefix:
uv run python -m raspa_mcp.installer --prefix /opt/raspa2
# force reinstall even if already present:
uv run python -m raspa_mcp.installer --force
命令执行完毕后，重新加载shell：
source ~/.bashrc # or ~/.zshrc, ~/.profile, etc.
兼容性：在Ubuntu 24.04（GCC 14）上测试。安装程序会自动应用
-std=gnu11以及其他编译器标志，以解决现代GCC版本上RASPA2源代码树中的已知问题。
RASPA2来源： https://github.com/iRASPA/RASPA2
参考文献：D.Dubbeldam、S.Calero、D.E.Ellis、R.Q.Snurr， 西蒙分子。 42, 81–101 (2016)
快速入门——羽毛流
使用一个命令注册raspa-mcp（在featherflow项目目录中运行）：
featherflow config mcp add raspa2 \
--command uv \
--arg run \
--arg --directory \
--arg /path/to/raspa-mcp \
--arg raspa-mcp \
--lazy \
--description "RASPA2 molecular simulation: GCMC, MD, adsorption isotherms, force fields, output parsing" \
--timeout 600
--lazy：raspa-mcp公开了20个工具——懒惰模式注册了一个网关入口点，而不是预先注册所有工具，从而降低了每次调用LLM令牌的成本。
--timeout 600RASPA2模拟可能需要几分钟；featherflow建议科学计算MCP服务器使用300-600秒。
验证：
featherflow config mcp list
您的代理现在可以自主地：
User: Study CO2 adsorption in ZIF-8 at 298 K from 0.1 to 50 bar.
Agent:
1. raspa-mcp.get_simulation_template("VoidFraction") → run RASPA2
2. raspa-mcp.parse_raspa_output(...) → void fraction = 0.47
3. raspa-mcp.get_simulation_template("GCMC") → fill placeholders × 7 pressures
4. raspa-mcp.validate_simulation_input(...) → clean
5. shell_exec → RASPA2 × 7
6. raspa-mcp.parse_raspa_output(...) → isotherm data
7. raspa-mcp.plot_isotherm(...) → ZIF-8_CO2.png
8. feishu-mcp.upload_file_and_share(...) → report delivered
不需要人为干预。
MCP工具参考
| 工具 | 类别 |
|---|---|
list_simulation_types |
发现 |
get_simulation_template |
输入生成 |
get_parameter_docs |
输入生成 |
list_available_forcefields |
力场 |
get_forcefield_files |
力场 |
recommend_forcefield |
力场 |
list_available_molecules |
分子 |
get_molecule_definition |
分子 |
create_workspace |
工作区 |
validate_simulation_input |
验证 |
parse_raspa_output |
输出解析 |
parse_rdf_output |
输出解析 |
parse_msd_output |
输出解析 |
parse_ti_output |
输出解析 |
parse_density_grid |
输出解析 |
calculate_selectivity |
分析 |
plot_isotherm |
可视化 |
plot_isotherm_comparison |
可视化 |
plot_density_slice |
可视化 |
check_raspa2_environment |
环境 |
generate_force_field_def |
自定义工作流 |
generate_force_field_mixing_rules_def |
自定义工作流 |
generate_pseudo_atoms_def |
自定义工作流 |
generate_molecule_def |
自定义工作流 |
inspect_cif |
自定义工作流 |
recommend_supercell |
自定义工作流 |
preflight_workspace |
自定义工作流 |
get_workflow_recipe |
自定义工作流 |
自定义所有工作流程
当你携带自己的CIF、力场和分子时 定义，上面的工具为每个RASPA2文件提供了安全的构建器 预期：
inspect_cif(cif) → formula, cell, charges, overlap warnings
recommend_supercell(cif, 12) → UnitCells line + ChargeMethod hint
create_workspace(work, name, cif)
generate_force_field_def(work) # safe "3 zeros" overwrite file
generate_force_field_mixing_rules_def(work, atom_types=[...]) # LJ ε/σ
generate_pseudo_atoms_def(work, atoms=[...]) # atom registry
generate_molecule_def(work, "MyAdsorbate", ...) # per-molecule .def
preflight_workspace(work) # cross-file sanity
force_field.def≠force_field_mixing_rules.def. 第一个文件是 覆盖规则 （几乎使用“3个零”的最小值 每一份工作）。第二个文件是Lennard Jonesε/σ所在的位置。把它们混合起来 是导致神秘感的最常见原因:#解析RASPA2中的错误。 生成器为两者发出正确的格式。
进行端到端的配方调用 get_workflow_recipe("custom_mof_gcmc").
所有写入操作都在沙盒中 RASPA_MCP_WORKSPACE_BASE
（默认值 ~/raspa_workspaces)--拒绝该根以外的路径。
测试
uv run pytest tests/ -q # 41 tests, ~1.5 s
uv run ruff check raspa_mcp/ tests/
建筑
raspa-mcp/
├── raspa_mcp/
│ ├── server.py # 20 MCP tools (FastMCP, stdio transport)
│ ├── parser.py # Output parsers (loading, RDF, MSD, TI, density)
│ ├── validator.py # Input validator (20+ rule checks)
│ ├── installer.py # RASPA2 env detection + source build + raspa-mcp-setup CLI
│ └── data/
│ ├── templates.py # 12 simulation.input templates
│ ├── molecules.py # 6 molecule definitions + metadata
│ └── forcefields.py # 5 force field file sets
├── tests/
│ └── test_server.py # 41 unit tests
└── docs/
└── workflow.md # Full autonomous research workflow walkthrough
完整的业务工作流程
看 docs/workflow.md 使用featherflow+raspa mcp+RASPA2+feishu mcp对自主MOF筛查研究进行完整的端到端演练，从单个聊天消息到交付给feishu的排名报告——大约120-140次工具调用，零人工步骤。
许可证
麻省理工学院
致谢
建在上面 RASPA2 由Dubbeldam、Calero、Ellis&Snurr撰写。力场参数来自 TraPPE 家族（Martin、Siepmann等人）和 通用力场 （Rappé等人）。
