Rosetta Context

Design e modelagem de proteínas Rosetta para agentes

Documentação

Servidor MCP Rosetta

Autor: Ariel J. Ben-Sasson

Um servidor Model Context Protocol (MCP) que permite ao Cursor (ou qualquer cliente MCP) trabalhar com Rosetta, PyRosetta e Biotite: executar RosettaScripts, validar protocolos XML, traduzir entre Rosetta e Biotite, pontuar estruturas e consultar documentação — tudo a partir do seu assistente de codificação com IA.

Novidades na v1.3.0 (vs v1.1.8 no npm)

Novo: Integração com Biotite

rosetta_to_biotite — Encontre o equivalente em Biotite para qualquer função Rosetta com código de exemplo funcional (21 mapeamentos cobrindo I/O de estrutura, SASA, RMSD, superposição, estrutura secundária, contatos, ligações de hidrogênio, fatores B, ângulos e mais)
biotite_to_rosetta — Busca reversa: encontre o equivalente em Rosetta para uma função Biotite
translate_rosetta_script_to_biotite — Traduza RosettaScripts XML inteiros ou código PyRosetta para Python Biotite. Operações de design/otimização são sinalizadas como exclusivas da Rosetta.
Busca difusa com aliases de palavras-chave ("contatos", "energia de ligação", "área de superfície", "alinhar", etc.)

Melhorado: Tradutor de XML para PyRosetta

37 tipos de elementos suportados (antes eram 6): 11 movers, 9 filtros, 10 seletores, 7 operações de tarefa
Tratamento completo de atributos: repeats, disable_design, cartesian, tolerance, threshold, distance e mais
Suporte a elementos filhos: MoveMap (com Span), Reweight, ScoreFunction
Relata elementos não reconhecidos para que você saiba o que precisa de trabalho manual

Melhorado: Ajuda e documentação

get_rosetta_help agora aceita qualquer tópico: movers por nome ("FastRelax"), conceitos ("constraints", "docking") ou funções de pontuação ("ref2015") — busca automaticamente documentação ao vivo em rosettacommons.org
Fallback de search_rosetta_web_docs: quando DuckDuckGo está com limite de taxa, testa URLs diretas da documentação Rosetta
get_cached_docs com cache automático: não é necessário chamar cache_cli_docs primeiro
Ajuda estática expandida para score_functions, movers, filtros, xml e parâmetros

Melhorado: Pontuação

pyrosetta_score: nova opção per_residue retorna detalhamento de energia por resíduo
Parâmetro scorefxn agora funciona (era ignorado na v1.1.8)
Mensagens de erro adequadas para arquivos ausentes em vez de {} silencioso

Melhorado: Validação

validate_xml: nova opção validate_against_schema verifica nomes de elementos contra o esquema XSD da Rosetta (detecta erros de digitação como FastRleax)

Correções de conformidade com a especificação MCP

Respostas de tools/call agora usam o formato correto de { content: [{ type: "text", text }] }
Erros de ferramentas retornam isError: true (não erros JSON-RPC)
Códigos de erro JSON-RPC padrão (-32601, -32700, -32603)
Removida a publicidade falsa de capacidade resources

Correções de segurança

Entrada do usuário não é mais interpolada em código Python (usa variáveis de ambiente / stdin)
Arquivos temporários gravados em os.tmpdir() (não no diretório do módulo)

Limpeza

Removidas 3 ferramentas redundantes: list_functions (mesclada em get_rosetta_info), search_pyrosetta_wheels, cache_cli_docs (cache automático em get_cached_docs)
Removidos caminhos pessoais codificados
Corrigidas variáveis sombreadas, anti-padrões assíncronos, código morto
18 ferramentas (antes eram 21), todas com descrições melhoradas orientadas a agentes

Exemplo: fazendo uma pergunta ingênua

Isto é o que torna o servidor MCP poderoso — um agente de IA pode responder perguntas de domínio chamando as ferramentas certas automaticamente:

Usuário pergunta no Cursor: "Como eu relaxo minha proteína e qual é o equivalente em Biotite?"

O agente chama duas ferramentas MCP nos bastidores:

1. get_rosetta_help("FastRelax") retorna mais de 6000 caracteres de documentação ao vivo:

FastRelax realiza relaxamento de todos os átomos usando o protocolo FastRelax. Parâmetros incluem configuração de scorefxn, repeats, cartesian, disable_design, MoveMap...

2. rosetta_to_biotite("FastRelax") retorna:

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

O agente sintetiza: "FastRelax é o protocolo de relaxamento de todos os átomos da Rosetta. Aqui está como usá-lo... Nota: Biotite é apenas para análise e não tem equivalente — você precisa de PyRosetta para otimização de estrutura."

Sem o MCP, o agente adivinharia a partir dos dados de treinamento e provavelmente erraria nomes de parâmetros ou assinaturas de API.

O que você obtém (18 ferramentas)

Descoberta e Ajuda

Ferramenta	Descrição
`get_rosetta_info`	Todas as funções de pontuação, movers, filtros, seletores e parâmetros disponíveis
`get_rosetta_help`	Ajuda para qualquer tópico — aceita nomes de movers, conceitos ou funções de pontuação
`pyrosetta_introspect`	Busca ao vivo na API PyRosetta com documentação e assinaturas

Documentação

Ferramenta	Descrição
`search_rosetta_web_docs`	Busca na documentação de rosettacommons.org
`get_rosetta_web_doc`	Busca e lê uma página específica de documentação
`get_cached_docs`	Busca ajuda de CLI em cache (cache automático no primeiro uso)

Execução e Pontuação

Ferramenta	Descrição
`run_rosetta_scripts`	Executa um protocolo RosettaScripts XML em um PDB
`pyrosetta_score`	Pontua um PDB com detalhamento opcional por resíduo

Tradução

Ferramenta	Descrição
`xml_to_pyrosetta`	XML para Python PyRosetta (37 tipos de elementos)
`rosetta_to_biotite`	Encontra o equivalente em Biotite de uma função Rosetta
`biotite_to_rosetta`	Encontra o equivalente em Rosetta de uma função Biotite
`translate_rosetta_script_to_biotite`	Traduz scripts completos de Rosetta para Biotite

Validação e Esquema

Ferramenta	Descrição
`validate_xml`	Verifica sintaxe XML + validação opcional de esquema
`rosetta_scripts_schema`	Gera esquema XSD e extrai nomes de elementos

Ambiente

Ferramenta	Descrição
`python_env_info`	Versão do Python e pacotes instalados
`check_pyrosetta`	Verifica se PyRosetta está disponível
`install_pyrosetta_installer`	Instala PyRosetta automaticamente (10-30 min)
`find_rosetta_scripts`	Localiza o binário rosetta_scripts

Início rápido

1. Instalar a partir do npm

npm install -g rosetta-mcp-server

2. Configurar o ambiente 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()"

Ou pule esta etapa — PyRosetta instala automaticamente no primeiro uso (leva 10-30 min).

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

Variáveis de ambiente:

Variável	Obrigatória	Descrição
`ROSETTA_BIN`	Não	Caminho para o binário `rosetta_scripts` ou seu diretório. Se não definido, busca em caminhos comuns e no PATH.
`PYTHON_BIN`	Não	Interpretador Python com PyRosetta/Biotite. Padrão é `python3`.
`MCP_DEBUG`	Não	Defina como `1` para registro de depuração em stderr.

4. Reinicie seu editor

Abra Configurações -> MCP. O servidor "rosetta" deve aparecer verde com 18 ferramentas.

Exemplo de tradução de XML para 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 gerado:

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 mapeamento Rosetta <-> Biotite

Categoria	Rosetta	Biotite	Equivalência
I/O de Estrutura	`pose_from_pdb`	`PDBFile.read`	Completa
I/O de Estrutura	`pose.dump_pdb`	`PDBFile.write`	Completa
I/O de Estrutura	`pose_from_file` (CIF)	`CIFFile.read`	Completa
Análise de Superfície	`SasaMetric`	`biotite.structure.sasa`	Completa
Alinhamento	`SuperimposeMover`	`biotite.structure.superimpose`	Completa
RMSD	`all_atom_rmsd`	`biotite.structure.rmsd`	Completa
Estrutura Secundária	`DsspMover`	`annotate_sse`	Parcial
Sequência	`pose.sequence()`	`get_residues`	Completa
Distância	`AtomPairConstraint`	`biotite.structure.distance`	Completa
Ângulos	`pose.phi/psi/omega`	`biotite.structure.dihedral`	Completa
Interface	`InterfaceAnalyzerMover`	`sasa` + seleção	Parcial
Banco de Dados	`rcsb.pose_from_rcsb`	`rcsb.fetch`	Completa
Seleção	`ChainSelector` etc.	indexação booleana numpy	Completa
Contatos	matrizes de distância	`CellList`	Parcial
Ramachandran	`pose.phi/psi`	`dihedral_backbone`	Parcial
Ligações H	`HBondSet`	`biotite.structure.hbond`	Parcial
Fatores B	`pdb_info().bfactor`	`AtomArray.b_factor`	Completa
Centro de Massa	`center_of_mass`	`mass_center`	Completa
Pontuação	`ScoreFunction`	Nenhum	Somente Rosetta
Otimização	`FastRelax`	Nenhum	Somente Rosetta
Design	`FastDesign`	Nenhum	Somente Rosetta

Solução de problemas

Servidor mostra vermelho no Cursor: Reinicie o Cursor. Use caminho absoluto na configuração (ex.: /opt/homebrew/bin/rosetta-mcp-server). Garanta Node 14+ e Python 3.8+.
run_rosetta_scripts falha: Verifique se ROSETTA_BIN aponta para um binário válido. Tente "$ROSETTA_BIN" -help.
Ferramentas PyRosetta dizem "não disponível": Instale via pip install pyrosetta-installer e depois execute o instalador, ou deixe o servidor MCP instalar automaticamente no primeiro uso.
Ferramentas Biotite retornam sem resultados: Instale Biotite no mesmo ambiente Python: pip install biotite
get_rosetta_help retorna "Sem ajuda detalhada": Tente o nome exato da classe Rosetta (ex.: "FastRelax" não "relax"). A ferramenta resolve aliases comuns, mas pode não reconhecer nomes incomuns.

Verificar a partir da linha de comando

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

Desenvolvimento

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