Skip to main content
Glama
molcraft

molcraft

by Fugueh

molcraft

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

当前版本 v0.3.0。开发计划见 ROADMAP.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。

Related MCP server: ypotheto-compchem-mcp

模块

模块

层

内容

selector

语义边界

选择器解析 resolve()、命名基团 GROUPS、关键原子、键的一侧

annotate

语义

刚性/柔性标注(写进原子/键属性)

transform

数值边界

纯函数操作:平移、旋转、向量对齐、设定二面角、双分子摆放;测量与比较

geom

数值

纯 numpy 几何内核,不依赖 RDKit

build

—

SMILES → 3D(ETKDG + MMFF/UFF);读 xyz;合并两个分子

export

—

导出 xyz

tools

agent

会话工具层:分子名 → 版本列表,几何操作生成新版本,可撤销

mcp_server

agent

把 tools 注册成 MCP 工具

安装

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

选择器

{"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 用法

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 服务器

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):

{
  "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 生成新版本。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      B
      quality
      D
      maintenance
      Provides computational chemistry tools for LLMs, enabling molecular operations like SMILES processing and geometry manipulation via a modular agent and tool system.
      9
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables natural language interaction with computational chemistry tools including molecule building, electronic structure calculations, geometry optimization, vibrational spectroscopy, and molecular dynamics, powered by RDKit, PySCF, and ASE.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides an MCP interface for publication-quality chemical structure and reaction rendering from SMILES/InChI/molblock, with validation and name parsing. Enables AI agents to draw molecules and reactions as images.
      50 PyPI
      MIT
    • A
      license
      C
      quality
      F
      maintenance
      Enables LLM agents to draw and edit ChemDraw reaction schemes, parse ELN exports and LCMS/NMR data, and generate publication-ready CDXML files through grounded chemistry tools.
      35
      3
      MIT