rosetta-mcp-server

Rosetta MCP Server

作者：Ariel J. Ben-Sasson

一个模型上下文协议（MCP）服务，可让 Cursor（或任何 MCP 客户端）使用 Rosetta、PyRosetta 和 Biotite：运行 RosettaScripts、验证 XML 协议、在 Rosetta 和 Biotite 之间进行转换、为结构评分，以及查询文档——所有操作都可通过 AI 编码助手完成。

v1.3.0 新增内容（与 npm 上的 v1.1.8 相比）

新增：Biotite 集成

• rosetta_to_biotite —— 查找任意 Rosetta 函数对应的 Biotite 函数，并提供可运行的示例代码（涵盖 21 种映射，包括结构 I/O、SASA、RMSD、叠合、二级结构、接触、氢键、B 因子、角度等）
• biotite_to_rosetta —— 反向查找：查找 Biotite 函数对应的 Rosetta 函数
• translate_rosetta_script_to_biotite —— 将完整的 RosettaScripts XML 或 PyRosetta 代码转换为 Biotite Python。设计／优化操作会标记为仅支持 Rosetta。
• 模糊搜索支持关键词别名（“contacts”“binding energy”“surface area”“align”等）

改进：XML 到 PyRosetta 转换器

• 支持 37 种元素类型（原为 6 种）：11 种 mover、9 种 filter、10 种 selector、7 种 task operation
• 完整的属性处理：repeats、disable_design、cartesian、tolerance、threshold、distance 等
• 支持子元素：MoveMap（含 Span）、Reweight、ScoreFunction
• 报告无法识别的元素，方便了解哪些部分需要手动处理

改进：帮助和文档

• get_rosetta_help 现在接受任意主题：按名称查询 mover（“FastRelax”）、概念（“constraints”“docking”）或评分函数（“ref2015”）——自动从 rosettacommons.org 获取实时文档
• search_rosetta_web_docs 回退机制：DuckDuckGo 限流时，会尝试直接访问 Rosetta 文档 URL
• get_cached_docs 自动缓存：无需先调用 cache_cli_docs
• 扩充了 score_functions、movers、filters、xml 和 parameters 的静态帮助内容

改进：评分

• pyrosetta_score：新增 per_residue 选项，可返回逐残基能量明细
• scorefxn 参数现在可以正常工作（在 v1.1.8 中会被忽略）
• 文件缺失时会显示恰当的错误消息，而不再静默返回 {}

MCP 规范合规性修复

• tools/call 响应现在使用正确的 { content: [{ type: "text", text }] } 格式
• 工具错误会返回 isError: true（而非 JSON-RPC 错误）
• 使用标准 JSON-RPC 错误代码（-32601、-32700、-32603）
• 移除了错误的 resources 能力声明

安全修复

• 不再将用户输入插入 Python 代码（改用环境变量／stdin）
• 临时文件写入 os.tmpdir()（而非模块目录）

清理

• 移除了 3 个冗余工具：list_functions（合并到 get_rosetta_info）、search_pyrosetta_wheels、cache_cli_docs（在 get_cached_docs 中自动缓存）
• 移除了硬编码的个人路径
• 修复了变量遮蔽、异步反模式和死代码
• 18 个工具（原为 21 个），描述均已改进，更适合 Agent 使用

---

示例：提出一个简单的问题

这正是 MCP 服务强大的地方——AI Agent 可以通过自动调用合适的工具来回答领域问题：

用户在 Cursor 中提问： “如何对我的蛋白质进行松弛？对应的 Biotite 方法是什么？”

Agent 在后台调用两个 MCP 工具：

1. get_rosetta_help("FastRelax") 返回 6000 多个字符的实时文档：

FastRelax 使用 FastRelax 协议执行全原子松弛。参数包括 scorefxn、repeats、cartesian、disable_design、MoveMap 配置……

2. rosetta_to_biotite("FastRelax") 返回：

{
  "found": true,
  "results": [{
    "rosetta": { "name": "FastRelax", "example": ["relax = FastRelax()", "relax.set_scorefxn(get_score_function('ref2015'))", "relax.apply(pose)"] },
    "biotite": null,
    "equivalence": "none_from_biotite",
    "notes": "Biotite does NOT perform structure optimization. These are Rosetta-specific capabilities."
  }]
}

Agent 综合得出：“FastRelax 是 Rosetta 的全原子松弛协议。以下是使用方法……请注意，Biotite 仅用于分析，没有对应功能——你需要使用 PyRosetta 进行结构优化。”

如果没有 MCP，Agent 就会根据训练数据猜测，很可能会弄错参数名称或 API 签名。

---

可用内容（18 个工具）

发现与帮助

工具	描述
get_rosetta_info	所有可用的评分函数、mover、过滤器、选择器和参数
get_rosetta_help	任意主题的帮助——接受 mover 名称、概念或评分函数
pyrosetta_introspect	实时搜索 PyRosetta API，并提供文档和签名

文档

工具	描述
search_rosetta_web_docs	搜索 rosettacommons.org 文档
get_rosetta_web_doc	获取并阅读指定文档页面
get_cached_docs	搜索缓存的 CLI 帮助（首次使用时自动缓存）

执行与评分

工具	描述
run_rosetta_scripts	对 PDB 运行 RosettaScripts XML 协议
pyrosetta_score	对 PDB 评分，并可选择按残基细分

转换

工具	描述
xml_to_pyrosetta	将 XML 转换为 PyRosetta Python 代码（37 种元素类型）
rosetta_to_biotite	查找 Rosetta 函数对应的 Biotite 功能
biotite_to_rosetta	查找 Biotite 函数对应的 Rosetta 功能
translate_rosetta_script_to_biotite	将完整脚本从 Rosetta 转换为 Biotite

验证与架构

工具	描述
validate_xml	检查 XML 语法，并可选择进行架构验证
rosetta_scripts_schema	生成 XSD 架构并提取元素名称

环境

工具	描述
python_env_info	Python 版本和已安装的软件包
check_pyrosetta	确认 PyRosetta 是否可用
install_pyrosetta_installer	自动安装 PyRosetta（10–30 分钟）
find_rosetta_scripts	查找 rosetta_scripts 二进制文件

---

快速开始

1. 从 npm 安装

npm install -g rosetta-mcp-server

2. 设置 Python 环境

# Create a venv with PyRosetta and Biotite
uv venv ~/.venvs/rosetta-mcp
~/.venvs/rosetta-mcp/bin/pip install pyrosetta-installer biotite
~/.venvs/rosetta-mcp/bin/python -c "import pyrosetta_installer as I; I.install_pyrosetta()"

也可以跳过此步骤——首次使用时会自动安装 PyRosetta（需要 10–30 分钟）。

3. 配置 MCP 客户端

Cursor（~/.cursor/mcp.json）：

{
  "mcpServers": {
    "rosetta": {
      "command": "rosetta-mcp-server",
      "args": [],
      "env": {
        "ROSETTA_BIN": "/path/to/rosetta_scripts.default.macosclangrelease",
        "PYTHON_BIN": "/path/to/.venvs/rosetta-mcp/bin/python"
      }
    }
  }
}

Claude Desktop（~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "rosetta": {
      "command": "rosetta-mcp-server",
      "env": {
        "ROSETTA_BIN": "/path/to/rosetta_scripts.default.macosclangrelease",
        "PYTHON_BIN": "/path/to/.venvs/rosetta-mcp/bin/python"
      }
    }
  }
}

环境变量：

变量	必需	描述
ROSETTA_BIN	否	rosetta_scripts 二进制文件或其所在目录的路径。如果未设置，则搜索常见路径和 PATH。
PYTHON_BIN	否	配有 PyRosetta/Biotite 的 Python 解释器。默认为 python3。
MCP_DEBUG	否	设为 1 可将调试日志输出到 stderr。

4. 重启编辑器

打开 Settings -> MCP。“rosetta”服务应显示为绿色，并提供 18 个工具。

---

XML 转换为 PyRosetta 示例

输入 XML：

<ROSETTASCRIPTS>
  <SCOREFXNS>
    <ScoreFunction name="ref" weights="ref2015"/>
  </SCOREFXNS>
  <RESIDUE_SELECTORS>
    <Chain name="chainA" chains="A"/>
  </RESIDUE_SELECTORS>
  <MOVERS>
    <FastRelax name="relax" scorefxn="ref" repeats="5" cartesian="true"/>
  </MOVERS>
  <PROTOCOLS>
    <Add mover="relax"/>
  </PROTOCOLS>
</ROSETTASCRIPTS>

生成的 PyRosetta 代码：

import pyrosetta
from pyrosetta import pose_from_pdb
from pyrosetta.rosetta.core.scoring import get_score_function
from pyrosetta.rosetta.core.select.residue_selector import *
from pyrosetta.rosetta.protocols.relax import *

pyrosetta.init("-mute all")

pose = pose_from_pdb("your_protein.pdb")

# Residue Selectors
chainSelector = ChainSelector()
chainSelector.set_chain_strings("A")

# Movers
fastRelax = FastRelax()
fastRelax.set_scorefxn(get_score_function("ref"))
fastRelax.set_default_repeats(5)
fastRelax.cartesian(True)

sfxn = get_score_function("ref2015")

# Apply movers
fastRelax.apply(pose)

pose.dump_pdb("output.pdb")
score = pose.energies().total_energy()
print(f"Final score: {score}")

---

Rosetta <-> Biotite 映射覆盖范围

类别	Rosetta	Biotite	等效性
结构 I/O	pose_from_pdb	PDBFile.read	完全
结构 I/O	pose.dump_pdb	PDBFile.write	完全
结构 I/O	pose_from_file（CIF）	CIFFile.read	完全
表面分析	SasaMetric	biotite.structure.sasa	完全
比对	SuperimposeMover	biotite.structure.superimpose	完全
RMSD	all_atom_rmsd	biotite.structure.rmsd	完全
二级结构	DsspMover	annotate_sse	部分
序列	pose.sequence()	get_residues	完全
距离	AtomPairConstraint	biotite.structure.distance	完全
角度	pose.phi/psi/omega	biotite.structure.dihedral	完全
界面	InterfaceAnalyzerMover	sasa + 选择	部分
数据库	rcsb.pose_from_rcsb	rcsb.fetch	完全
选择	ChainSelector 等	numpy 布尔索引	完全
接触	距离矩阵	CellList	部分
Ramachandran	pose.phi/psi	dihedral_backbone	部分
氢键	HBondSet	biotite.structure.hbond	部分
B 因子	pdb_info().bfactor	AtomArray.b_factor	完全
质心	center_of_mass	mass_center	完全
评分	ScoreFunction	无	仅 Rosetta
优化	FastRelax	无	仅 Rosetta
设计	FastDesign	无	仅 Rosetta

---

故障排除

• 服务器在 Cursor 中显示为红色：重启 Cursor。在配置中使用绝对路径（例如，/opt/homebrew/bin/rosetta-mcp-server）。确保 Node 14+ 和 Python 3.8+。
• run_rosetta_scripts 失败：确认 ROSETTA_BIN 指向有效的二进制文件。尝试运行 "$ROSETTA_BIN" -help。
• PyRosetta 工具提示“not available”：通过 pip install pyrosetta-installer 安装，然后运行安装程序；也可以让 MCP 服务在首次使用时自动安装。
• Biotite 工具没有返回结果：在同一个 Python 环境中安装 Biotite：pip install biotite
• get_rosetta_help 返回“No detailed help”：尝试使用准确的 Rosetta 类名（例如，“FastRelax”而不是“relax”）。该工具可以解析常见别名，但可能无法识别不常见的名称。

从命令行验证

# Check version
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05"}}' | rosetta-mcp-server 2>/dev/null | python3 -c "import sys,json; print(json.loads(sys.stdin.readline())['result']['serverInfo'])"

# List all tools
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | rosetta-mcp-server 2>/dev/null | python3 -c "import sys,json; [print(t['name']) for t in json.loads(sys.stdin.readline())['result']['tools']]"

开发

rosetta-mcp-server/
├── rosetta_mcp_wrapper.js   # Node MCP server (protocol + all 18 tools)
├── rosetta_mcp_server.py    # Python helper (static Rosetta data)
├── install_pyrosetta.js     # Standalone PyRosetta installer
├── package.json             # npm package config
└── README.md

许可证和归属

• 本仓库采用 MIT 许可证
• Rosetta/PyRosetta：参见 RosettaCommons 许可证；商业用途需要相应的许可证
• Biotite：BSD 3-Clause 许可证