{
  "markdown": "<p align=\"center\">\n  <img src=\"./assets/banner2.png\" width=\"100%\" alt=\"Rosetta MCP Server\" />\n</p>\n\n# Rosetta MCP Server\n\nAuthor: Ariel J. Ben-Sasson\n\nA Model Context Protocol (MCP) server that lets Cursor (or any MCP client) work with Rosetta, PyRosetta, and Biotite: run RosettaScripts, validate XML protocols, translate between Rosetta and Biotite, score structures, and query documentation -- all from your AI coding assistant.\n\n## What's new in v1.3.0 (vs v1.1.8 on npm)\n\n### New: Biotite integration\n- **`rosetta_to_biotite`** -- Find the Biotite equivalent of any Rosetta function with working example code (21 mappings covering structure I/O, SASA, RMSD, superimposition, secondary structure, contacts, hydrogen bonds, B-factors, angles, and more)\n- **`biotite_to_rosetta`** -- Reverse lookup: find the Rosetta equivalent of a Biotite function\n- **`translate_rosetta_script_to_biotite`** -- Translate entire RosettaScripts XML or PyRosetta code to Biotite Python. Design/optimization operations are flagged as Rosetta-only.\n- Fuzzy search with keyword aliases (\"contacts\", \"binding energy\", \"surface area\", \"align\", etc.)\n\n### Improved: XML to PyRosetta translator\n- **37 element types** supported (was 6): 11 movers, 9 filters, 10 selectors, 7 task operations\n- **Full attribute handling**: `repeats`, `disable_design`, `cartesian`, `tolerance`, `threshold`, `distance`, and more\n- **Child element support**: `MoveMap` (with `Span`), `Reweight`, `ScoreFunction`\n- Reports unrecognized elements so you know what needs manual work\n\n### Improved: Help and documentation\n- **`get_rosetta_help` now accepts any topic**: movers by name (\"FastRelax\"), concepts (\"constraints\", \"docking\"), or score functions (\"ref2015\") -- auto-fetches live docs from rosettacommons.org\n- **`search_rosetta_web_docs` fallback**: when DuckDuckGo is rate-limited, probes direct Rosetta docs URLs\n- **`get_cached_docs` auto-caches**: no need to call `cache_cli_docs` first\n- Expanded static help for score_functions, movers, filters, xml, and parameters\n\n### Improved: Scoring\n- **`pyrosetta_score`**: new `per_residue` option returns per-residue energy breakdown\n- **`scorefxn` parameter** now works (was ignored in v1.1.8)\n- Proper error messages for missing files instead of silent `{}`\n\n### Improved: Validation\n- **`validate_xml`**: new `validate_against_schema` option checks element names against the Rosetta XSD schema (catches typos like `FastRleax`)\n\n### MCP spec compliance fixes\n- `tools/call` responses now use correct `{ content: [{ type: \"text\", text }] }` format\n- Tool errors return `isError: true` (not JSON-RPC errors)\n- Standard JSON-RPC error codes (-32601, -32700, -32603)\n- Removed false `resources` capability advertisement\n\n### Security fixes\n- User input no longer interpolated into Python code (uses env vars / stdin)\n- Temp files written to `os.tmpdir()` (not module directory)\n\n### Cleanup\n- Removed 3 redundant tools: `list_functions` (merged into `get_rosetta_info`), `search_pyrosetta_wheels`, `cache_cli_docs` (auto-cache in `get_cached_docs`)\n- Removed hardcoded personal paths\n- Fixed shadowed variables, async anti-patterns, dead code\n- **18 tools** (was 21), all with improved agent-oriented descriptions\n\n---\n\n## Example: asking a naive question\n\nThis is what makes the MCP server powerful -- an AI agent can answer domain questions by calling the right tools automatically:\n\n**User asks in Cursor:** *\"How do I relax my protein and what's the Biotite equivalent?\"*\n\nThe agent calls two MCP tools behind the scenes:\n\n**1. `get_rosetta_help(\"FastRelax\")` returns 6000+ chars of live documentation:**\n> FastRelax performs all-atom relaxation using the FastRelax protocol. Parameters include `scorefxn`, `repeats`, `cartesian`, `disable_design`, `MoveMap` configuration...\n\n**2. `rosetta_to_biotite(\"FastRelax\")` returns:**\n```json\n{\n  \"found\": true,\n  \"results\": [{\n    \"rosetta\": { \"name\": \"FastRelax\", \"example\": [\"relax = FastRelax()\", \"relax.set_scorefxn(get_score_function('ref2015'))\", \"relax.apply(pose)\"] },\n    \"biotite\": null,\n    \"equivalence\": \"none_from_biotite\",\n    \"notes\": \"Biotite does NOT perform structure optimization. These are Rosetta-specific capabilities.\"\n  }]\n}\n```\n\nThe agent synthesizes: *\"FastRelax is Rosetta's all-atom relaxation protocol. Here's how to use it... Note: Biotite is analysis-only and has no equivalent -- you need PyRosetta for structure optimization.\"*\n\nWithout the MCP, the agent would guess from training data and likely get parameter names or API signatures wrong.\n\n---\n\n## What you get (18 tools)\n\n### Discovery & Help\n| Tool | Description |\n|------|-------------|\n| `get_rosetta_info` | All available score functions, movers, filters, selectors, parameters |\n| `get_rosetta_help` | Help for any topic -- accepts mover names, concepts, or score functions |\n| `pyrosetta_introspect` | Live PyRosetta API search with docs and signatures |\n\n### Documentation\n| Tool | Description |\n|------|-------------|\n| `search_rosetta_web_docs` | Search rosettacommons.org documentation |\n| `get_rosetta_web_doc` | Fetch and read a specific docs page |\n| `get_cached_docs` | Search cached CLI help (auto-caches on first use) |\n\n### Execution & Scoring\n| Tool | Description |\n|------|-------------|\n| `run_rosetta_scripts` | Run a RosettaScripts XML protocol on a PDB |\n| `pyrosetta_score` | Score a PDB with optional per-residue breakdown |\n\n### Translation\n| Tool | Description |\n|------|-------------|\n| `xml_to_pyrosetta` | XML to PyRosetta Python (37 element types) |\n| `rosetta_to_biotite` | Find Biotite equivalent of a Rosetta function |\n| `biotite_to_rosetta` | Find Rosetta equivalent of a Biotite function |\n| `translate_rosetta_script_to_biotite` | Translate full scripts from Rosetta to Biotite |\n\n### Validation & Schema\n| Tool | Description |\n|------|-------------|\n| `validate_xml` | Check XML syntax + optional schema validation |\n| `rosetta_scripts_schema` | Generate XSD schema and extract element names |\n\n### Environment\n| Tool | Description |\n|------|-------------|\n| `python_env_info` | Python version and installed packages |\n| `check_pyrosetta` | Verify PyRosetta is available |\n| `install_pyrosetta_installer` | Auto-install PyRosetta (10-30 min) |\n| `find_rosetta_scripts` | Locate the rosetta_scripts binary |\n\n---\n\n## Quick start\n\n### 1. Install from npm\n```bash\nnpm install -g rosetta-mcp-server\n```\n\n### 2. Set up Python environment\n```bash\n# Create a venv with PyRosetta and Biotite\nuv venv ~/.venvs/rosetta-mcp\n~/.venvs/rosetta-mcp/bin/pip install pyrosetta-installer biotite\n~/.venvs/rosetta-mcp/bin/python -c \"import pyrosetta_installer as I; I.install_pyrosetta()\"\n```\n\nOr skip this step -- PyRosetta auto-installs on first use (takes 10-30 min).\n\n### 3. Configure your MCP client\n\n**Cursor** (`~/.cursor/mcp.json`):\n```json\n{\n  \"mcpServers\": {\n    \"rosetta\": {\n      \"command\": \"rosetta-mcp-server\",\n      \"args\": [],\n      \"env\": {\n        \"ROSETTA_BIN\": \"/path/to/rosetta_scripts.default.macosclangrelease\",\n        \"PYTHON_BIN\": \"/path/to/.venvs/rosetta-mcp/bin/python\"\n      }\n    }\n  }\n}\n```\n\n**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):\n```json\n{\n  \"mcpServers\": {\n    \"rosetta\": {\n      \"command\": \"rosetta-mcp-server\",\n      \"env\": {\n        \"ROSETTA_BIN\": \"/path/to/rosetta_scripts.default.macosclangrelease\",\n        \"PYTHON_BIN\": \"/path/to/.venvs/rosetta-mcp/bin/python\"\n      }\n    }\n  }\n}\n```\n\n**Environment variables:**\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `ROSETTA_BIN` | No | Path to `rosetta_scripts` binary or its directory. If not set, searches common paths and PATH. |\n| `PYTHON_BIN` | No | Python interpreter with PyRosetta/Biotite. Defaults to `python3`. |\n| `MCP_DEBUG` | No | Set to `1` for debug logging to stderr. |\n\n### 4. Restart your editor\nOpen Settings -> MCP. The \"rosetta\" server should appear green with 18 tools.\n\n---\n\n## XML to PyRosetta translation example\n\n**Input XML:**\n```xml\n<ROSETTASCRIPTS>\n  <SCOREFXNS>\n    <ScoreFunction name=\"ref\" weights=\"ref2015\"/>\n  </SCOREFXNS>\n  <RESIDUE_SELECTORS>\n    <Chain name=\"chainA\" chains=\"A\"/>\n  </RESIDUE_SELECTORS>\n  <MOVERS>\n    <FastRelax name=\"relax\" scorefxn=\"ref\" repeats=\"5\" cartesian=\"true\"/>\n  </MOVERS>\n  <PROTOCOLS>\n    <Add mover=\"relax\"/>\n  </PROTOCOLS>\n</ROSETTASCRIPTS>\n```\n\n**Generated PyRosetta code:**\n```python\nimport pyrosetta\nfrom pyrosetta import pose_from_pdb\nfrom pyrosetta.rosetta.core.scoring import get_score_function\nfrom pyrosetta.rosetta.core.select.residue_selector import *\nfrom pyrosetta.rosetta.protocols.relax import *\n\npyrosetta.init(\"-mute all\")\n\npose = pose_from_pdb(\"your_protein.pdb\")\n\n# Residue Selectors\nchainSelector = ChainSelector()\nchainSelector.set_chain_strings(\"A\")\n\n# Movers\nfastRelax = FastRelax()\nfastRelax.set_scorefxn(get_score_function(\"ref\"))\nfastRelax.set_default_repeats(5)\nfastRelax.cartesian(True)\n\nsfxn = get_score_function(\"ref2015\")\n\n# Apply movers\nfastRelax.apply(pose)\n\npose.dump_pdb(\"output.pdb\")\nscore = pose.energies().total_energy()\nprint(f\"Final score: {score}\")\n```\n\n---\n\n## Rosetta <-> Biotite mapping coverage\n\n| Category | Rosetta | Biotite | Equivalence |\n|----------|---------|---------|-------------|\n| Structure I/O | `pose_from_pdb` | `PDBFile.read` | Full |\n| Structure I/O | `pose.dump_pdb` | `PDBFile.write` | Full |\n| Structure I/O | `pose_from_file` (CIF) | `CIFFile.read` | Full |\n| Surface Analysis | `SasaMetric` | `biotite.structure.sasa` | Full |\n| Alignment | `SuperimposeMover` | `biotite.structure.superimpose` | Full |\n| RMSD | `all_atom_rmsd` | `biotite.structure.rmsd` | Full |\n| Secondary Structure | `DsspMover` | `annotate_sse` | Partial |\n| Sequence | `pose.sequence()` | `get_residues` | Full |\n| Distance | `AtomPairConstraint` | `biotite.structure.distance` | Full |\n| Angles | `pose.phi/psi/omega` | `biotite.structure.dihedral` | Full |\n| Interface | `InterfaceAnalyzerMover` | `sasa` + selection | Partial |\n| Database | `rcsb.pose_from_rcsb` | `rcsb.fetch` | Full |\n| Selection | `ChainSelector` etc. | numpy boolean indexing | Full |\n| Contacts | distance matrices | `CellList` | Partial |\n| Ramachandran | `pose.phi/psi` | `dihedral_backbone` | Partial |\n| H-bonds | `HBondSet` | `biotite.structure.hbond` | Partial |\n| B-factors | `pdb_info().bfactor` | `AtomArray.b_factor` | Full |\n| Center of Mass | `center_of_mass` | `mass_center` | Full |\n| Scoring | `ScoreFunction` | *None* | Rosetta only |\n| Optimization | `FastRelax` | *None* | Rosetta only |\n| Design | `FastDesign` | *None* | Rosetta only |\n\n---\n\n## Troubleshooting\n\n- **Server shows red in Cursor**: Restart Cursor. Use absolute path in config (e.g., `/opt/homebrew/bin/rosetta-mcp-server`). Ensure Node 14+ and Python 3.8+.\n- **`run_rosetta_scripts` fails**: Verify `ROSETTA_BIN` points to a valid binary. Try `\"$ROSETTA_BIN\" -help`.\n- **PyRosetta tools say \"not available\"**: Install via `pip install pyrosetta-installer` then run the installer, or let the MCP server auto-install on first use.\n- **Biotite tools return no results**: Install Biotite in the same Python env: `pip install biotite`\n- **`get_rosetta_help` returns \"No detailed help\"**: Try the exact Rosetta class name (e.g., \"FastRelax\" not \"relax\"). The tool resolves common aliases but may miss unusual names.\n\n## Verify from the command line\n```bash\n# Check version\necho '{\"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'])\"\n\n# List all tools\necho '{\"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']]\"\n```\n\n## Development\n```\nrosetta-mcp-server/\n├── rosetta_mcp_wrapper.js   # Node MCP server (protocol + all 18 tools)\n├── rosetta_mcp_server.py    # Python helper (static Rosetta data)\n├── install_pyrosetta.js     # Standalone PyRosetta installer\n├── package.json             # npm package config\n└── README.md\n```\n\n## License and attribution\n- MIT for this repository\n- Rosetta/PyRosetta: see RosettaCommons licenses; commercial use requires the appropriate license\n- Biotite: BSD 3-Clause license\n",
  "bytes": 12315,
  "sha": "705107fb831a42bad29426f65c1c6783f1e25d2e7a57b6967b8c22e558f15c04",
  "repo_slug": "arielbs/rosetta-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_arielbs_rosetta_mcp_server_480d5dfa/readme"
}