Skip to main content
Glama
molcraft

molcraft

by Fugueh
README.md
# molcraft

基于 RDKit 的分子及子结构几何操作工具,用来搭建量化计算的初始构型(构型初猜)。附带 MCP 服务器,可以让 agent 通过自然语言调用。

当前版本 **v0.3.0**。开发计划见 [ROADMAP.md](ROADMAP.md),版本记录见 [CHANGELOG.md](CHANGELOG.md)。

## 设计

```
Agent / MCP / JS
  ↓  分子名 + 选择器(JSON)+ 数值参数
──────── semantic boundary ────────
  ↓
selector.resolve()
  ↓  原子序号(RDKit 原生顺序)
──────── numeric boundary ─────────
  ↓
Conformer 坐标
  ↓
NumPy 几何(geom.py)
```

- **选择器只是参数。** 它描述"选什么",在操作内部对照当前分子解析成原子序号;序号不在边界外传递。
- **操作是纯函数。** 输入分子不被修改,返回 `(新分子, 报告)`。新分子拓扑与原子序号不变,只有坐标改变。
- **一个 Mol 就是一个 motif。** 两个分子的相对位置只体现在坐标里(同一个笛卡尔坐标系),摆放时不必合并;需要整体处理(导出、力场清理)时才用 `build.combine` 合并。
- **序号就是原子身份。** 同一个分子的所有版本序号相同;合并写到新分子,并记录 `frag`(来源分子)、`src_idx`(来源序号)。
- **尽量复用 RDKit 原生结构**:Mol、Conformer、Atom/Bond 属性、`GetSubstructMatches` 的有序元组、`RingInfo.AtomRings()`、`rdMolTransforms.TransformConformer`。

## 模块

| 模块 | 层 | 内容 |
|---|---|---|
| `selector` | 语义边界 | 选择器解析 `resolve()`、命名基团 `GROUPS`、关键原子、键的一侧 |
| `annotate` | 语义 | 刚性/柔性标注(写进原子/键属性) |
| `transform` | 数值边界 | 纯函数操作:平移、旋转、向量对齐、设定二面角、双分子摆放;测量与比较 |
| `geom` | 数值 | 纯 numpy 几何内核,不依赖 RDKit |
| `build` | — | SMILES → 3D(ETKDG + MMFF/UFF);读 xyz;合并两个分子 |
| `export` | — | 导出 xyz |
| `tools` | agent | 会话工具层:分子名 → 版本列表,几何操作生成新版本,可撤销 |
| `mcp_server` | agent | 把 `tools` 注册成 MCP 工具 |

## 安装

```bash
cd molcraft
pip install -e ".[mcp,dev]"
pytest                      # 没装 RDKit 时,RDKit 相关测试会自动跳过
```

## 选择器

```python
{"group": "benzothiazole"}                  # 命名基团
{"group": "phenyl", "match": 2}             # 第 3 组匹配(从 0 开始)
{"group": "ether_O", "all_matches": True}   # 所有匹配的并集
{"smarts": "[c:1][S:2][CX4:3][CX4:4]"}      # 自定义 SMARTS,映射号标关键原子及顺序
{"ring": 0}                                 # RingInfo.AtomRings() 的第 0 个环(按环上顺序)
{"prop": "frag", "value": "inh"}            # 按原子属性
{"indices": [3, 4, 5]}                      # 显式序号
# 简写:[3, 4, 5] 等价于 {"indices": [...]};"benzothiazole" 等价于 {"group": ...}
# 可附加:key_only(默认 True)、with_h
```

**顺序规则**:单组 SMARTS 匹配保持查询顺序(有映射号时按映射号顺序),`ring` 保持环上顺序,`indices` 保持给定顺序;多个条件取交集时以第一个条件(优先级 indices > ring > group/smarts > prop)的顺序为准;`with_h` 的氢追加在末尾。测二面角、设二面角时,用单组匹配或 indices 写选择器即可。

**关键原子**:命名基团的 SMARTS 用原子映射号标出关键原子,如 `"thioether_S": "[SX2;!R:1]([#6])[#6]"`。默认 `key_only=True` 只返回关键原子(S 本身),`key_only=False` 返回整个匹配。

**歧义**:匹配到多组而没有给 `match` / `all_matches` 时抛出 `AmbiguousSelection`,附带全部候选,不会默默取第一组。

## Python 用法

```python
from molcraft import build, export, transform

ps  = build.from_smiles("CC(c1ccccc1)CC(c1ccccc1)CC(c1ccccc1)C", seed=1)
inh = build.from_smiles("COCCOCCOCCSc1nc2ccccc2s1", seed=1)

# PS 不动,返回移动后的缓蚀剂复制品;ps、inh 本身都不变
placed, report = transform.stack_on_ring(
    ps, {"group": "phenyl", "match": 1},
    inh, {"group": "benzothiazole"},
    distance=3.5, offset=1.5,
)
print(report)   # 面间距、平面夹角、最短重原子距离……

complex_, offset = build.combine(ps, placed, labels=("PS", "inh"))
export.write_xyz(complex_, "out/complex.xyz")
```

完整示例见 `examples/stack_example.py`。

### 刚性/柔性标注规则

| 标注 | 判据 |
|---|---|
| `rotatable` | 符合 RDKit 的可转动键 SMARTS,两端重原子连接数都 ≥ 2,且不被刚性规则排除 |
| `conj_rotor` | 可转动且共轭(如芳环–S),转动有偏好构象 |
| `rigid_rule` | 被额外刚性规则排除的单键。目前只有 `amide_CN`:所有酰胺 C–N(含叔酰胺) |
| `ring_flexible` | 非芳香环内的单键:环可以变构象,但不能用设定二面角的方式单独转 |
| `rigid_id`(原子) | 切断所有可转动键后所在的刚性片段编号 |

### 其他约定

- 原子序号从 0 开始(RDKit 约定)。导出给 xtb 时如需 1 起始序号,要自己加 1。
- 角度单位为度,距离单位为 Å。
- 分子内碰撞检查跳过拓扑距离 ≤ 3 根键的原子对;重原子间距 < 2.0 Å 时报告中给出 `warning`。
- 不要跨调用保存 RDKit `Atom` 对象,只保存序号,需要时 `mol.GetAtomWithIdx(idx)` 现取。

## MCP 服务器

```bash
python -m molcraft.mcp_server        # 或安装后直接运行 molcraft-mcp
```

同时兼容 MCP Python SDK 2.x(`MCPServer`)和 1.x(`FastMCP`)。

**注册到 Claude Code:** `claude mcp add molcraft -- python -m molcraft.mcp_server`

**注册到 Claude Desktop**(`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "molcraft": { "command": "python", "args": ["-m", "molcraft.mcp_server"] }
  }
}
```

`command` 要指向装了 molcraft 的那个 Python(用虚拟环境时写完整路径)。

### 工具列表

| 工具 | 作用 |
|---|---|
| `load_smiles` / `load_xyz` | 建分子 |
| `copy_molecule` / `combine_molecules` / `list_molecules` | 管理分子 |
| `history` / `undo` | 版本历史与撤销 |
| `describe` | 重原子、邻接、刚性片段、可转动键、环、命名基团 |
| `preview_selection` | 只读:预览选择器解析结果,歧义时列出候选 |
| `measure` / `compare_groups` / `check_clearance` | 测量(可跨分子) |
| `translate` / `rotate` / `set_dihedral` | 单分子操作,生成新版本 |
| `stack_on_ring` / `tshape_on_ring` | 双分子摆放:fixed 不动,mover 生成新版本 |
| `write_xyz` | 把一个或多个分子合并写成 xyz,返回各分子的序号起点 |

会话分子保存在服务器进程内存里,每个分子最多保留 50 个版本,重启服务器后丢失。

### 新增工具

在 `molcraft/tools.py` 写一个函数(参数用简单类型并加类型标注,原子参数用 `dict[str, Any]` 选择器,文档字符串写清用途和单位),加进末尾的 `TOOLS` 列表即可。几何操作通过 `_commit` 生成新版本。