内容
<!-- mcp-name: io.github.wjgoarxiv/ovito-mcp -->
<p align="center"><img src="./cover.png" width="100%" /></p>
<h1 align="center">ovito-mcp</h1>
<p align="center">
<em>用于大语言模型的分子动力学分析工具 — 无头、进程内OVITO，用于GROMACS/LAMMPS轨迹分析，并附带一种其他工具没有的笼状水合物套件。</em>
</p>
<p align="center">
<a href="#快速开始">快速开始</a> · <a href="#为什么选择ovito-mcp">为什么</a> · <a href="#功能">功能</a> · <a href="#工具目录">工具</a> · <a href="#笼状科学">笼状科学</a> · <a href="./README-Ko-KR.md">한국어</a>
</p>
<p align="center">
<img src="https://img.shields.io/badge/license-MIT-blue" />
<img src="https://img.shields.io/badge/python-3.11+-green" />
<img src="https://img.shields.io/badge/OVITO-3.15+-orange" />
<img src="https://img.shields.io/badge/MCP-FastMCP-blueviolet" />
<img src="https://img.shields.io/badge/hydrate-F3%2FF4%20%7C%20cages%20%7C%20occupancy-teal" />
</p>
---
> [!NOTE]
> **ovito-mcp** 将OVITO转化为大型语言模型可以直接驱动的工具。指向GROMACS `.gro`/`.xtc` 或LAMMPS dump文件，并用自然语言询问径向分布函数、结构类型分解、渲染快照或完整的笼状水合物分析。它在进程内无头运行OVITO的Python模块（无GUI，无套接字），因此可以在笔记本电脑、集群和CI上运行。
## 看看它的工作原理
<p align="center"><img src="./assets/demo.gif" width="70%" alt="ovito-mcp 从自然语言提示中识别sII水合物笼" /></p>
<p align="center"><em>实际运行：自然语言提示 → MCP工具调用 → OVITO识别sII笼（<b>128 × 5¹²</b> + <b>64 × 5¹²6⁴</b>，F4 = 0.965）并无头渲染帧 — 引擎中的所有数字和渲染都直接来自引擎（<a href="./demo/">工作原理</a>）。</em></p>
## 为什么选择ovito-mcp？
其他分子可视化MCP都通过**本地套接字运行GUI** — 脆弱、单会话、无法在无头节点上运行。ovito-mcp在进程内导入OVITO，并添加了其他可视化服务器没有的分析层：
| | 套接字到GUI的可视化MCP | **ovito-mcp** |
|---|---|---|
| 执行 | 到活动GUI的TCP桥接 | **无头进程内** — 集群/CI就绪 |
| 安装 | 重型GUI应用程序 | **`pip install ovito`** |
| 分析 | 渲染 + 选择 | **68个原生修饰器** + 轨迹管道 |
| 分子动力学轨迹 | 加载帧 | **原生每帧 + 时间序列** |
| 笼状水合物 | — | **F3/F4，氢键，笼（5¹²/5¹²6²/5¹²6⁴），GRADE，占用率** |
**为什么选择MCP而不是编写OVITO脚本？** 因为这样：
```
"加载hydrate.gro，告诉我结构类型，并按协调性着色渲染。"
```
替换了30行的管道脚本，记忆修饰器API和往返绘图窗口 — 模型可以链接，适应并直接显示渲染图像。
## 功能
- **无头进程内OVITO** — `import ovito`，无GUI，无套接字；在任何Python运行的地方运行。
- **GROMACS 和 LAMMPS 原生** — `.gro`，`.xtc`/`.trr`（LoadTrajectory），LAMMPS dump/data，XYZ，CIF，NetCDF。
- **68种分析修饰器** — RDF，协调性，CNA/PTM/IdentifyDiamond（冰 Ih/Ic），簇，表达式选择。
- **逼真渲染** — **OSPRay** 渲染（环境遮蔽，降噪）采用**正交** 默认值，在暗色场景中；以PNG形式内联返回，无需显示（Tachyon/OpenGL也可选择）。
- **笼状可视化** — `render_cages` 将每个识别的笼绘制为**彩色编码线框多面体**：其成员O顶点 *和* 它们之间的氢键边共享一个笼型颜色（5¹² 青色，5¹²6⁴ 红色，...），宽度匹配，在黄色框内 — 回应ClavisCage查看器美学。
- **笼状水合物套件** — F3/F4顺序参数，氢键网络，笼识别和结构分类（sI/sII/sH）和笼占用率 — 从验证的ClavisCage引擎重用。
- **上下文安全** — 每个工具返回摘要，表格，计数或图像，**绝不返回原始原子数组**。
- **stdio安全** — 永久的fd-1守护进程将OVITO的C++聊天记录从JSON-RPC通道中移除。
## 快速开始
> [!IMPORTANT]
> ovito-mcp 需要 `ovito` Python模块（`pip install ovito`，3.15+）。它完全无头运行。
```bash
# 克隆 + 安装
git clone https://github.com/wjgoarxiv/ovito-mcp.git
cd ovito-mcp
uv venv && uv pip install -e ".[dev]" # 添加 ,md 用于LAMMPS/NetCDF via MDAnalysis
uv run pytest -q # 重用氢氧化物奇偶校验测试
# 在Claude Desktop上注册（claude_desktop_config.json）
```
```json
{
"mcpServers": {
"ovito": {
"command": "uvx",
"args": ["ovito-mcp"],
"env": { "OVITO_DATA_ROOT": "/path/to/your/data" }
}
}
}
```
然后直接询问：
```
打开 /data/sII_hydrate.gro. 它是什么水合物结构，有多少种笼状结构？
按协调数着色渲染。
```
## 工具目录
| 分组 | 工具 | 用途 |
|---|---|---|
| **会话/IO** | `create_session` · `get_trajectory_info` · `load_trajectory` · `export_data` · `list_sessions` · `close_session` | 打开文件，附加轨迹，检查，导出 |
| **分析** | `compute_rdf` · `coordination_analysis` · `structure_identification` · `cluster_analysis` · `select_expression` | 原生OVITO修饰器，总结 |
| **渲染** | `render_snapshot` · `render_cages` · `render_animation` | OSPRay/Ortho PNGs（内联）；笼叠加按类型着色；电影 |
| **水合物** | `order_parameters` · `hbond_network` · `identify_cages` · `classify_structure` · `cage_occupancy` | 笼状水合物套件 |
## 笼状科学
> [!TIP]
> 验证了ClavisCage参考引擎：对于sII测试晶体（222_S2，1088个水分子），ovito-mcp报告 **128 × 5¹² + 64 × 5¹²6⁴ → sII** 和 **F4 = 0.9649**，与参考值匹配。
- **F3 / F4 顺序参数** — F4 ≈ 0.7–0.95 = 水合物，≈ 0 = 液体，≈ −0.4 = 冰 Ih；F3 ≤ 0.04 = 类似水合物。
- **氢键网络** — 几何O–H···O标准（rcut 0.36 nm，角度35°）；一个好的框架是~4协调的。
- **笼识别** — TRACE样式环→笼组装与SEC/Euler验证 → 5¹²，5¹²6²，5¹²6⁴，…
- **结构分类** — GRADE样式：sI / sII / sH / 混合从笼组成。
- **笼占用率** — 将CO₂/CH₄客体分配给笼；按类型报告填充/空。
## 工作原理
```
ovito-mcp 架构
~~~~~~~~~~~~~~~~~~~~~~~
LLM ── JSON-RPC（stdio） ──► FastMCP 服务器
│
┌─────────────┴──────────────┐
│ OVITOEngine（1个工作线程） │ ← 线程安全编组
│ import ovito（无头） │
└─────────────┬──────────────┘
┌───────────┬─────────┴────────┬───────────────┐
原生修饰器 │ 提取 │ 重用分析/ （nm）
（RDF/CNA/PTM/…） │ 缝隙（Å→nm） │ F3/F4 · 氢键 · 笼 · 占用率
│ │
Tachyon 渲染 ──► 内联PNG
```
## 需求
| 依赖 | 需要 | 用途 |
|---|---|---|
| Python 3.11+ | 是 | 运行时 |
| `ovito` 3.15+ | 是 | 无头分析 + 渲染引擎 |
| `fastmcp` 3.4+ | 是 | MCP服务器框架 |
| `numpy`，`scipy` | 是 | 水合物分析层 |
| `MDAnalysis` | 否（`[md]`） | 额外轨迹/格式桥接（LAMMPS/NetCDF） |
## 贡献
问题和PR欢迎。 水合物`analysis/`层与 sibling [pymol-mcp](https://github.com/wjgoarxiv) 共享 — 保持两者同步。
## 许可证
[MIT](./LICENSE).
