Rosetta Context

Diseño y modelado de proteínas Rosetta para agentes

Documentación

Servidor MCP de Rosetta

Autor: Ariel J. Ben-Sasson

Un servidor de Protocolo de Contexto de Modelo (MCP) que permite a Cursor (o cualquier cliente MCP) trabajar con Rosetta, PyRosetta y Biotite: ejecutar RosettaScripts, validar protocolos XML, traducir entre Rosetta y Biotite, puntuar estructuras y consultar documentación, todo desde tu asistente de codificación con IA.

Novedades en v1.3.0 (vs v1.1.8 en npm)

Nuevo: Integración con Biotite

rosetta_to_biotite -- Encuentra el equivalente en Biotite de cualquier función de Rosetta con código de ejemplo funcional (21 mapeos que cubren E/S de estructuras, SASA, RMSD, superposición, estructura secundaria, contactos, enlaces de hidrógeno, factores B, ángulos y más)
biotite_to_rosetta -- Búsqueda inversa: encuentra el equivalente en Rosetta de una función de Biotite
translate_rosetta_script_to_biotite -- Traduce RosettaScripts XML completos o código PyRosetta a Python de Biotite. Las operaciones de diseño/optimización se marcan como exclusivas de Rosetta.
Búsqueda difusa con alias de palabras clave ("contactos", "energía de unión", "área superficial", "alinear", etc.)

Mejorado: Traductor de XML a PyRosetta

37 tipos de elementos compatibles (antes 6): 11 movers, 9 filtros, 10 selectores, 7 operaciones de tarea
Manejo completo de atributos: repeats, disable_design, cartesian, tolerance, threshold, distance y más
Soporte de elementos hijos: MoveMap (con Span), Reweight, ScoreFunction
Informa elementos no reconocidos para que sepas qué necesita trabajo manual

Mejorado: Ayuda y documentación

get_rosetta_help ahora acepta cualquier tema: movers por nombre ("FastRelax"), conceptos ("constraints", "docking") o funciones de puntuación ("ref2015") -- obtiene automáticamente documentación en vivo de rosettacommons.org
Respaldo de search_rosetta_web_docs: cuando DuckDuckGo está limitado por tasa, sondea URLs directas de documentación de Rosetta
get_cached_docs auto-cachea: no es necesario llamar a cache_cli_docs primero
Ayuda estática ampliada para score_functions, movers, filtros, xml y parámetros

Mejorado: Puntuación

pyrosetta_score: nueva opción per_residue devuelve desglose de energía por residuo
El parámetro scorefxn ahora funciona (se ignoraba en v1.1.8)
Mensajes de error adecuados para archivos faltantes en lugar de {} silencioso

Mejorado: Validación

validate_xml: nueva opción validate_against_schema verifica nombres de elementos contra el esquema XSD de Rosetta (detecta errores tipográficos como FastRleax)

Correcciones de cumplimiento de especificación MCP

Las respuestas de tools/call ahora usan el formato { content: [{ type: "text", text }] } correcto
Los errores de herramientas devuelven isError: true (no errores JSON-RPC)
Códigos de error JSON-RPC estándar (-32601, -32700, -32603)
Se eliminó la publicidad falsa de capacidad resources

Correcciones de seguridad

La entrada del usuario ya no se interpola en código Python (usa variables de entorno / stdin)
Los archivos temporales se escriben en os.tmpdir() (no en el directorio del módulo)

Limpieza

Se eliminaron 3 herramientas redundantes: list_functions (fusionada en get_rosetta_info), search_pyrosetta_wheels, cache_cli_docs (auto-cache en get_cached_docs)
Se eliminaron rutas personales codificadas
Se corrigieron variables sombreadas, anti-patrones asíncronos, código muerto
18 herramientas (antes 21), todas con descripciones mejoradas orientadas a agentes

Ejemplo: hacer una pregunta ingenua

Esto es lo que hace poderoso al servidor MCP: un agente de IA puede responder preguntas de dominio llamando automáticamente a las herramientas correctas:

El usuario pregunta en Cursor: "¿Cómo relajo mi proteína y cuál es el equivalente en Biotite?"

El agente llama a dos herramientas MCP en segundo plano:

1. get_rosetta_help("FastRelax") devuelve más de 6000 caracteres de documentación en vivo:

FastRelax realiza relajación de todos los átomos usando el protocolo FastRelax. Los parámetros incluyen configuración de scorefxn, repeats, cartesian, disable_design, MoveMap...

2. rosetta_to_biotite("FastRelax") devuelve:

{
  "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."
  }]
}

El agente sintetiza: "FastRelax es el protocolo de relajación de todos los átomos de Rosetta. Así es como se usa... Nota: Biotite es solo de análisis y no tiene equivalente -- necesitas PyRosetta para optimización de estructuras."

Sin el MCP, el agente adivinaría a partir de datos de entrenamiento y probablemente obtendría nombres de parámetros o firmas de API incorrectos.

Lo que obtienes (18 herramientas)

Descubrimiento y Ayuda

Herramienta	Descripción
`get_rosetta_info`	Todas las funciones de puntuación, movers, filtros, selectores y parámetros disponibles
`get_rosetta_help`	Ayuda para cualquier tema -- acepta nombres de movers, conceptos o funciones de puntuación
`pyrosetta_introspect`	Búsqueda en vivo de API de PyRosetta con documentación y firmas

Documentación

Herramienta	Descripción
`search_rosetta_web_docs`	Buscar documentación en rosettacommons.org
`get_rosetta_web_doc`	Obtener y leer una página específica de documentación
`get_cached_docs`	Buscar ayuda de CLI en caché (auto-cachea en el primer uso)

Ejecución y Puntuación

Herramienta	Descripción
`run_rosetta_scripts`	Ejecutar un protocolo XML de RosettaScripts en un PDB
`pyrosetta_score`	Puntuar un PDB con desglose opcional por residuo

Traducción

Herramienta	Descripción
`xml_to_pyrosetta`	XML a Python de PyRosetta (37 tipos de elementos)
`rosetta_to_biotite`	Encontrar el equivalente en Biotite de una función de Rosetta
`biotite_to_rosetta`	Encontrar el equivalente en Rosetta de una función de Biotite
`translate_rosetta_script_to_biotite`	Traducir scripts completos de Rosetta a Biotite

Validación y Esquema

Herramienta	Descripción
`validate_xml`	Verificar sintaxis XML + validación de esquema opcional
`rosetta_scripts_schema`	Generar esquema XSD y extraer nombres de elementos

Entorno

Herramienta	Descripción
`python_env_info`	Versión de Python y paquetes instalados
`check_pyrosetta`	Verificar que PyRosetta esté disponible
`install_pyrosetta_installer`	Auto-instalar PyRosetta (10-30 min)
`find_rosetta_scripts`	Localizar el binario rosetta_scripts

Inicio rápido

1. Instalar desde npm

npm install -g rosetta-mcp-server

2. Configurar el entorno de 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()"

O salta este paso -- PyRosetta se auto-instala en el primer uso (toma 10-30 min).

3. Configurar tu cliente 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"
      }
    }
  }
}

Variables de entorno:

Variable	Requerida	Descripción
`ROSETTA_BIN`	No	Ruta al binario `rosetta_scripts` o su directorio. Si no se establece, busca en rutas comunes y PATH.
`PYTHON_BIN`	No	Intérprete de Python con PyRosetta/Biotite. Por defecto es `python3`.
`MCP_DEBUG`	No	Establecer a `1` para registro de depuración en stderr.

4. Reiniciar tu editor

Abre Configuración -> MCP. El servidor "rosetta" debería aparecer en verde con 18 herramientas.

Ejemplo de traducción de XML a PyRosetta

XML de entrada:

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

Código PyRosetta generado:

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}")

Cobertura de mapeo Rosetta <-> Biotite

Categoría	Rosetta	Biotite	Equivalencia
E/S de Estructuras	`pose_from_pdb`	`PDBFile.read`	Completa
E/S de Estructuras	`pose.dump_pdb`	`PDBFile.write`	Completa
E/S de Estructuras	`pose_from_file` (CIF)	`CIFFile.read`	Completa
Análisis de Superficie	`SasaMetric`	`biotite.structure.sasa`	Completa
Alineación	`SuperimposeMover`	`biotite.structure.superimpose`	Completa
RMSD	`all_atom_rmsd`	`biotite.structure.rmsd`	Completa
Estructura Secundaria	`DsspMover`	`annotate_sse`	Parcial
Secuencia	`pose.sequence()`	`get_residues`	Completa
Distancia	`AtomPairConstraint`	`biotite.structure.distance`	Completa
Ángulos	`pose.phi/psi/omega`	`biotite.structure.dihedral`	Completa
Interfaz	`InterfaceAnalyzerMover`	`sasa` + selección	Parcial
Base de Datos	`rcsb.pose_from_rcsb`	`rcsb.fetch`	Completa
Selección	`ChainSelector` etc.	indexación booleana numpy	Completa
Contactos	matrices de distancia	`CellList`	Parcial
Ramachandran	`pose.phi/psi`	`dihedral_backbone`	Parcial
Enlaces H	`HBondSet`	`biotite.structure.hbond`	Parcial
Factores B	`pdb_info().bfactor`	`AtomArray.b_factor`	Completa
Centro de Masa	`center_of_mass`	`mass_center`	Completa
Puntuación	`ScoreFunction`	Ninguno	Solo Rosetta
Optimización	`FastRelax`	Ninguno	Solo Rosetta
Diseño	`FastDesign`	Ninguno	Solo Rosetta

Solución de problemas

El servidor aparece en rojo en Cursor: Reinicia Cursor. Usa ruta absoluta en la configuración (p. ej., /opt/homebrew/bin/rosetta-mcp-server). Asegúrate de tener Node 14+ y Python 3.8+.
run_rosetta_scripts falla: Verifica que ROSETTA_BIN apunte a un binario válido. Prueba "$ROSETTA_BIN" -help.
Las herramientas de PyRosetta dicen "no disponible": Instala vía pip install pyrosetta-installer y luego ejecuta el instalador, o deja que el servidor MCP auto-instale en el primer uso.
Las herramientas de Biotite no devuelven resultados: Instala Biotite en el mismo entorno de Python: pip install biotite
get_rosetta_help devuelve "No detailed help": Prueba con el nombre exacto de la clase de Rosetta (p. ej., "FastRelax" no "relax"). La herramienta resuelve alias comunes pero puede no detectar nombres inusuales.

Verificar desde la línea de comandos

# 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']]"

Desarrollo

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