protein-mcp-server

---

Visão Geral

Estruturas de proteínas experimentais (PDB) e previstas (AlphaFold), federadas atrás de uma única superfície. Pesquise, busque, alinhe, compare e anote estruturas e seus ligantes em RCSB, AlphaFold DB, 3D-Beacons, UniProt, InterPro e Foldseek — tudo sem chave. Executa como um processo stdio, um servidor HTTP Streamable local ou o endpoint público hospedado acima.

Ferramentas

Ferramenta	Descrição
protein_search_structures	Pesquise estruturas experimentais e previstas por texto livre, sequência ou filtros de organismo/método/resolução, com opção de detalhamento por facetas.
protein_get_structure	Busque metadados e URLs de arquivos de coordenadas por ID — experimental (PDB), previsto (AlphaFold) ou melhor disponível — com sucesso parcial em lote e opção de inclusão de coordenadas.
protein_find_similar	Encontre homólogos de sequência (RCSB mmseqs2) ou homólogos de dobramento (Foldseek) a partir de uma sequência, ID PDB ou acesso UniProt.
protein_track_ligands	Resolva nomes/fórmulas de ligantes para IDs de componentes, encontre estruturas contendo um ligante ou mapeie resíduos de sítios de ligação.
protein_compare_structures	Alinhe estruturalmente múltiplas estruturas (TM-align / jFATCAT) a uma referência ou como uma matriz completa de pares.
protein_analyze_collection	Perfile o PDB em distribuições e tendências com facetas no servidor — contagens, histogramas, linhas do tempo e tabelas cruzadas.
protein_get_annotations	Busque recursos UniProt e variantes naturais, além de associações de domínios/famílias InterPro com termos GO.

Recursos

Recurso	Descrição
pdb://{entry_id}	Resumo de estrutura experimental para uma entrada PDB — título, método, resolução, organismo, ligantes ligados e IDs de cadeias por entidade nos namespaces do autor (authAsymIds) e do rótulo mmCIF (labelAsymIds).
af://{uniprot}	Resumo de estrutura prevista para um acesso UniProt do AlphaFold DB — pLDDT médio, frações de faixas de confiança, URLs de modelos e versão.

Todos os dados de recursos também são acessíveis via ferramentas — pdb://{entry_id} espelha protein_get_structure para source: experimental, e af://{uniprot} o espelha para source: predicted. Muitos clientes MCP são apenas de ferramentas e não exibem recursos; os resumos permanecem acessíveis através das ferramentas.

Referência de capacidades

protein_search_structures _ferramenta

• Texto livre, sequência de proteína (aciona uma busca de similaridade mmseqs2) e filtros de organismo / método / resolução
• content_type limita a busca a experimental, predicted ou all (padrão) — all é uma união genuína, então modelos computados aparecem ao lado de entradas PDB
• Cada resultado nomeia seu source; resultados de sequência em qualquer universo expõem uma entrada encadeável id além do polímero correspondente entityId; resultados experimentais trazem título, método, resolução e enriquecimento de organismo, e modelos AlphaFold seu acesso UniProt analisado
• start e limit paginam resultados classificados; nextStart é retornado enquanto outra página permanece, e uma página vazia além do fim nomeia o deslocamento em notice em vez de relatar nenhuma correspondência
• facets opcionais retornam um detalhamento por método / organismo / ano de liberação junto aos resultados — cada dimensão pode ser listada uma vez e relata quantas correspondências não possuem valor para ela; uma dimensão limitada é nomeada em notice, com protein_analyze_collection (maior bucket_limit) como rota para a cauda longa
• IDs de resultados de cadeia diretamente em protein_get_structure

---

protein_get_structure _ferramenta

• source: experimental agrupa IDs de entradas PDB (também resolvendo IDs de modelos computados como AF_*/MA_* da busca, marcados source: predicted com seu provedor); source: predicted aceita acessos UniProt para modelos AlphaFold com pLDDT/PAE; source: best_available aceita acessos UniProt e retorna o melhor modelo federado (experimental de maior resolução se existir, senão a melhor previsão)
• Sucesso parcial por ID — IDs não resolvidos caem em failed[]; requested/processed revelam IDs descartados além do limite do lote, e cada aviso (limite, falha, estouro) junta-se em um único notice
• Registros buscados com source: experimental, incluindo modelos computados, também carregam polymerEntities (tanto authAsymIds quanto labelAsymIds), ligands, molecularWeight e releaseDate
• coordinateUrls lista apenas arquivos que existem: BinaryCIF vem do ModelServer da RCSB, o formato PDB é omitido para entradas grandes apenas-mmCIF, e os arquivos de um modelo computado vêm de seu provedor (todos os três formatos do AlphaFold DB, mmCIF do ModelArchive) — um modelo AlphaFold cuja consulta ao provedor falha mantém apenas seu BinaryCIF da RCSB, nomeado em notice
• include_coords inclui conteúdo de coordenadas, sujeito a um orçamento de resposta — um lote acima do orçamento retorna um esboço de tamanho por estrutura (rechame com sections: [ids]), e um único arquivo superdimensionado é retido com um ponteiro para seu coordinateUrls
• Cada resposta carrega um bloco attribution nomeando licenças de dados upstream e citações

---

protein_find_similar _ferramenta

• by: sequence executa uma busca síncrona RCSB mmseqs2; by: structure executa uma busca assíncrona Foldseek contra bancos de dados experimentais e previstos — consulte a partir de uma sequência bruta, um ID PDB ou um acesso UniProt
• Ambos os modos aceitam start/limit e relatam totalCount, ecoando start e retornando nextStart enquanto outra página permanece; uma página vazia além do fim nomeia o deslocamento em notice, distinto de uma busca sem correspondências
• Os alvos Foldseek padrão são pdb100 + afdb50; substitua via databases (ex.: afdb-swissprot, BFVD)
• Um trabalho assíncrono que excede o orçamento de sondagem retorna status: computing com um ticketId — rechame com ticket_id para retomar; uma busca de estrutura concluída retorna o mesmo ticket, então um novo start pagina o trabalho finalizado
• Foldseek busca cada cadeia de uma estrutura multicadeia como sua própria consulta: uma resposta de estrutura cobre uma consulta (query, baseado em 0, padrão 0) e relata queryCount, com um notice nomeando as outras consultas; passe query com ticket_id para ler os resultados de outra cadeia do mesmo trabalho. Um query fora do intervalo é rejeitado (query_out_of_range), não respondido com uma lista vazia
• Resultados de estrutura são classificados melhor primeiro por score em cada banco de dados buscado (resultados sem pontuação por último, empates por banco e depois alvo) antes da paginação start/limit
• Cada modo lê apenas seus próprios controles (sequence, max_evalue, min_identity sob by: sequence; ticket_id, databases, query sob by: structure) — um campo que o modo selecionado não pode consumir é rejeitado, não ignorado
• Cada resultado nomeia o mecanismo e o banco de dados de origem de onde veio

---

protein_track_ligands _ferramenta

• mode: find_ligand resolve um nome ou fórmula para IDs de componentes químicos com fórmula, peso, SMILES e InChIKey — classificados por frequência de deposição, correspondência mais comum primeiro
• totalCount e candidatesConsidered relatam quantos componentes corresponderam e quantos foram classificados; um nome amplo cujas correspondências excedem o pool de candidatos recebe um notice para restringir a consulta
• Um query em formato de fórmula corresponde por composição exata, com espaços (C29 H31 N7 O) ou sem; qualquer outra coisa (incluindo um ID de componente) corresponde por nome e sinônimos
• mode: structures_with_ligand retorna entradas PDB contendo um ligante por ID de componente exato, com paginação start/limit e nextStart enquanto outra página permanece; uma página além do fim nomeia o deslocamento em notice em vez de relatar nenhuma entrada
• mode: binding_site retorna os resíduos de proteína que revestem o bolsão de um ligante em uma estrutura, com distâncias de contato; instâncias de ligantes paginam com start/limit como structures_with_ligand
• Resíduos de bolsão carregam tanto a numeração de rótulo mmCIF (asymId, seqId) quanto a numeração do autor (authAsymId, authSeqId) — o bolsão de imatinibe de 1IEP lista o rótulo THR93 como autor THR315; a instância do ligante relata sua própria cadeia de autor e número de resíduo
• Sítios de ligação são apenas experimentais — computados a partir de coordenadas depositadas; modelos previstos não carregam ligantes ligados

---

protein_compare_structures _ferramenta

• Alinha de 2 até o limite configurado (padrão 10, máx. 25) estruturas por chamada, via tm-align, fatcat-rigid ou fatcat-flexible; chain opcional por estrutura restringe o alinhamento a uma única cadeia de rótulo mmCIF
• reference: first alinha cada estrutura à primeira; reference: all_pairs calcula a matriz completa de pares; uma estrutura repetida em structures[] é comparada uma vez
• Cada par é um trabalho assíncrono independente com sucesso parcial por par — um par ainda calculando quando o orçamento de sondagem expira retorna status: computing com um uuid de trabalho; um par com falha degrada apenas sua própria linha
• Rechame com uma entrada { a, b, uuid } correspondente em resume[] para sondar um par em cálculo em vez de reenviar; um par retomado relata a/b na ordem em que seu trabalho foi enviado, qualquer que seja a ordem atual de structures[], e uma retomada sob um method diferente é rejeitada
• Retorna TM-score, RMSD e contagem de resíduos alinhados por par, além do modeledResidues de cada estrutura e coverage de 0–100, ordenados [a, b]; TM-score é normalizado pelo comprimento de a, então o mesmo par pontua de forma diferente quando invertido

---

protein_analyze_collection _ferramenta

• Agrupe por method, organism, polymer_type, resolution, release_year ou molecular_weight
• Uma dimensão group_by para um detalhamento, ou duas dimensões distintas para uma tabela cruzada (a primeira aninha a segunda); uma dimensão repetida é rejeitada
• interval define uma largura de bin de histograma (um número, para resolution ou molecular_weight) ou período de histograma de data (year, o único que a RCSB aceita) — aplica-se a qualquer dimensão solicitada que possa consumir esse tipo; rejeitado quando nenhuma pode
• Escopo com query de texto livre, organism, method ou max_resolution; content_type seleciona o universo de estruturas
• bucket_limit limita buckets por nível de dimensão, não por resposta — uma tabela cruzada o aplica separadamente ao pai e a cada filho aninhado, até bucket_limit × (1 + bucket_limit) buckets; notice nomeia cada posição limitada e bucketsReturned dá o total realizado
• Cada dimensão relata missingValueCount — correspondências sem valor para esse atributo (ex.: um detalhamento resolution exclui entradas NMR; modelos computados não têm nem method nem resolution)

---

protein_get_annotations _tool

• Recursos UniProt (domínios, sítios de ligação, PTMs) e variantes naturais, além de associações de domínio/família InterPro (Pfam, PROSITE, …) com termos GO associados
• Forneça um acesso UniProt diretamente, ou um ID PDB — resolvido via referência cruzada da sequência da estrutura
• Uma entrada PDB com múltiplas cadeias pode mapear para vários acessos; o padrão é a escolha determinística da cadeia de menor autor, com alternativas listadas em ambiguity — passe chain (um ID de cadeia de autor) para selecionar uma específica
• include define quais classes são buscadas (features, domains, variants, all); limit limita cada classe independentemente (1–200, padrão 50), com uma classe truncada divulgada em notice
• Cada resposta carrega um bloco attribution nomeando as licenças de dados upstream e citações (veja Licenciamento de dados upstream)

---

pdb://{entry_id} _resource

• Resumo de estrutura experimental como application/json — título, método, resolução, organismo, ligantes ligados e IDs de cadeia por entidade nos namespaces de autor (authAsymIds) e de rótulo mmCIF (labelAsymIds)
• Espelha protein_get_structure para source: experimental; entry_id é um ID de entrada PDB (ex.: 4HHB)

---

af://{uniprot} _resource

• Resumo de estrutura prevista como application/json — pLDDT médio, frações de faixa de confiança, URLs de modelo (cif/pdb/bcif) e versão do modelo AlphaFold
• uniprot aceita um acesso UniProt ou um ID de entrada AlphaFold DB (ex.: AF-P69905-F1); espelha protein_get_structure para source: predicted

Recursos

Construído sobre @cyanheads/mcp-ts-core: transportes stdio e Streamable HTTP, autenticação plugável (none / jwt / oauth), armazenamento intercambiável (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), registro estruturado com rastreamento OpenTelemetry opcional.

Específicos de PDB / AlphaFold:

• Uma superfície federada sobre estruturas experimentais (PDB) e previstas (AlphaFold / 3D-Beacons) — busca, obtenção e comparação tratam ambos os universos da mesma forma
• Sem chaves em todos os upstreams — RCSB, AlphaFold DB, 3D-Beacons, UniProt, InterPro e Foldseek, sem necessidade de provisionar chaves de API
• Análises de corpus executadas no mecanismo de facetas do RCSB — distribuições, histogramas e tabelas cruzadas retornam como contagens compactas de buckets, não as entradas correspondentes
• Trabalhos assíncronos de alinhamento e Foldseek são consultados dentro de um orçamento limitado e devolvem um ticket de trabalho (ticketId / por par uuid) em vez de bloquear — re-chame com ticket_id ou uma entrada resume[] para consultar o mesmo trabalho em vez de reenviar

Saída amigável para agentes:

• Proveniência em cada resposta — cada resultado carrega um source (experimental / predicted), o mecanismo e banco de dados que o produziram, e ecos de consulta-efetiva / contagem-total para que agentes possam raciocinar sobre cobertura
• Falha parcial graciosa — buscas em lote e comparações em pares retornam linhas por item (failed[], por par status) em vez de falhar a solicitação inteira, cada uma com texto de recuperação acionável
• Contratos de saída discriminados — uniões tipadas source e status, resultados computing com tickets de retomada e esboços de estouro de orçamento permitem que chamadores ramifiquem com base em dados, não em análise de strings

Primeiros passos

Instância Pública Hospedada

Uma instância pública está disponível em https://protein.caseyjhand.com/mcp — sem necessidade de instalação. Aponte qualquer cliente MCP para ela via Streamable HTTP:

{
  "mcpServers": {
    "protein": {
      "type": "streamable-http",
      "url": "https://protein.caseyjhand.com/mcp"
    }
  }
}

Auto-hospedado / Local

Adicione o seguinte ao arquivo de configuração do seu cliente MCP. Nenhuma chave de API é necessária — todos os provedores upstream são sem chave.

{
  "mcpServers": {
    "protein-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/protein-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Ou com npx (sem necessidade de Bun):

{
  "mcpServers": {
    "protein-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/protein-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Ou com Docker:

{
  "mcpServers": {
    "protein-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/protein-mcp-server:latest"]
    }
  }
}

Para Streamable HTTP, defina o transporte e inicie o servidor:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Pré-requisitos

• Bun v1.4.0 ou superior (ou Node.js v24+).
• Sem contas ou chaves de API — RCSB, AlphaFold DB, 3D-Beacons, UniProt, InterPro e Foldseek são todos públicos e sem chave.

Instalação

1. Clone o repositório:

git clone https://github.com/cyanheads/protein-mcp-server.git

2. Navegue para o diretório:

cd protein-mcp-server

3. Instale as dependências:

bun install

Configuração

Todos os provedores upstream são sem chave, então o servidor funciona imediatamente sem configuração. Cada variável abaixo é opcional.

Variável	Descrição	Padrão
PROTEIN_ASYNC_POLL_TIMEOUT_MS	Tempo máximo de relógio para consultar um trabalho assíncrono (alinhamento / Foldseek) antes de retornar um resultado computing.	30000
PROTEIN_MAX_BATCH_IDS	Limite de IDs aceitos por protein_get_structure em um lote (1–100).	25
PROTEIN_MAX_COMPARE_STRUCTURES	Limite de estruturas por chamada protein_compare_structures (2–25).	10
PROTEIN_FACET_BUCKET_CAP	Limite padrão de buckets por dimensão protein_analyze_collection (1–500).	50
PROTEIN_FANOUT_CONCURRENCY	Máximo de solicitações upstream concorrentes para fan-out por ID / por par (1–16).	5
RCSB_SEARCH_BASE_URL	URL base para a API de Busca RCSB v2.	https://search.rcsb.org
ALPHAFOLD_BASE_URL	URL base para a API do Banco de Dados de Estruturas AlphaFold.	https://alphafold.ebi.ac.uk
FOLDSEEK_BASE_URL	URL base para o serviço de busca de similaridade estrutural Foldseek.	https://search.foldseek.com
MCP_TRANSPORT_TYPE	Transporte: stdio ou http.	stdio
MCP_HTTP_PORT	Porta para o servidor HTTP.	3010
MCP_SESSION_MODE	Modo de sessão HTTP: stateless, stateful ou auto. O servidor declara stateless no código; defina isso para substituí-lo.	stateless
MCP_AUTH_MODE	Modo de autenticação: none, jwt ou oauth.	none
MCP_LOG_LEVEL	Nível de registro (RFC 5424).	info
OTEL_ENABLED	Ativar instrumentação OpenTelemetry.	false

Veja .env.example para a lista completa de substituições de URL base do provedor e limites de ajuste.

Executando o servidor

Desenvolvimento local

• Compilar e executar:

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• Executar verificações e testes:

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t protein-mcp-server .
docker run --rm -e MCP_TRANSPORT_TYPE=http -p 3010:3010 protein-mcp-server

O Dockerfile usa transporte HTTP por padrão, modo de sessão sem estado e registra em /var/log/protein-mcp-server. Dependências pares do OpenTelemetry são instaladas por padrão — compile com --build-arg OTEL_ENABLED=false para omiti-las.

Estrutura do projeto

Diretório	Propósito
src/index.ts	Ponto de entrada createApp() — registra ferramentas/recursos e inicializa os serviços do provedor.
src/config	Análise e validação de variáveis de ambiente específicas do servidor com Zod.
src/mcp-server/tools	Definições de ferramentas (*.tool.ts).
src/mcp-server/resources	Definições de recursos (*.resource.ts).
src/services	Camada de serviço do provedor — RCSB (busca, dados, facetas), AlphaFold, 3D-Beacons (melhor disponível), UniProt (incl. InterPro/GO), alinhamento de Comparação Estrutural, Foldseek e auxiliares compartilhados de HTTP/identificador/concorrência.
tests/	Testes unitários e de integração espelhando src/.

Guia de desenvolvimento

Veja CLAUDE.md/AGENTS.md para diretrizes de desenvolvimento e regras arquiteturais. A versão curta:

• Handlers lançam, o framework captura — sem try/catch na lógica de ferramentas
• Use ctx.log para registro com escopo de solicitação, ctx.state para armazenamento com escopo de locatário
• Registre novas ferramentas e recursos via os barrels em src/mcp-server/*/definitions/index.ts
• Encapsule chamadas de API externas: valide bruto → normalize para tipo de domínio → retorne esquema de saída; nunca invente campos ausentes

Licenciamento de dados upstream

Dados de estrutura e anotação vêm de bancos de dados públicos upstream, cada um sob sua própria licença. protein_get_structure e protein_get_annotations carregam um bloco attribution em cada resposta — a licença, citação e página inicial para cada fonte que contribuiu para aquela resposta específica — para que a obrigação de atribuição viaje com os dados para consumidores downstream em vez de viver apenas aqui. Fontes CC BY / CC BY-SA exigem atribuição na redistribuição; fontes CC0 são apenas citação (atribuição incentivada, não obrigatória).

Fonte	Contribui para	Licença
RCSB PDB	protein_get_structure — registros experimentais	CC0 1.0 Universal
AlphaFold DB	protein_get_structure — modelos previstos	CC BY 4.0
ModelArchive	protein_get_structure — modelos computados MA_*	CC BY 4.0
SWISS-MODEL	protein_get_structure — modelos best_available	CC BY-SA 4.0
BFVD	protein_get_structure — modelos best_available	CC BY 4.0
UniProt	protein_get_annotations	CC BY 4.0
InterPro	protein_get_annotations — dados de domínio/família	CC0 1.0 Universal
GO	protein_get_annotations — termos GO	CC BY 4.0

best_available federa modelos previstos através do 3D-Beacons, então o bloco attribution credita o provedor contribuinte real (AlphaFold DB, SWISS-MODEL, BFVD, …); um provedor sem entrada de licença curada carrega um fallback See provider terms apontando de volta ao 3D-Beacons em vez de uma licença fabricada. As classificações de domínio/família do próprio InterPro são CC0; os termos GO carregados junto são separadamente CC BY 4.0, então cada um é creditado independentemente apenas quando realmente contribui. Citações completas para cada fonte viajam no bloco attribution das respostas de ferramentas relevantes. Isso cobre o licenciamento de dados upstream — o código do próprio servidor é licenciado separadamente (veja Licença).

Contribuindo

Issues são bem-vindas. Execute verificações e testes antes de enviar:

bun run devcheck
bun run test

Licença

Apache-2.0 — veja LICENSE para detalhes.