protein-mcp-server

---

Resumen

Estructuras de proteínas experimentales (PDB) y predichas (AlphaFold), federadas detrás de una única superficie. Busca, obtén, alinea, compara y anota estructuras y sus ligandos en RCSB, AlphaFold DB, 3D-Beacons, UniProt, InterPro y Foldseek — todo sin claves. Se ejecuta como proceso stdio, como servidor HTTP Streamable local, o en el endpoint público alojado anterior.

Herramientas

Herramienta	Descripción
protein_search_structures	Busca estructuras experimentales y predichas por texto libre, secuencia, o filtros de organismo/método/resolución, con desgloses opcionales por facetas.
protein_get_structure	Obtiene metadatos y URLs de archivos de coordenadas por ID — experimental (PDB), predicho (AlphaFold), o el mejor disponible — con éxito parcial por lotes e inclusión opcional de coordenadas.
protein_find_similar	Encuentra homólogos de secuencia (RCSB mmseqs2) o de plegamiento (Foldseek) a partir de una secuencia, ID de PDB, o acceso de UniProt.
protein_track_ligands	Resuelve nombres/fórmulas de ligandos a IDs de componentes, encuentra estructuras que contienen un ligando, o mapea residuos del sitio de unión.
protein_compare_structures	Alinea estructuralmente múltiples estructuras (TM-align / jFATCAT) contra una referencia o como matriz completa por pares.
protein_analyze_collection	Perfila el PDB en distribuciones y tendencias con facetas del lado del servidor — conteos, histogramas, líneas de tiempo y tablas cruzadas.
protein_get_annotations	Obtiene características de UniProt y variantes naturales, además de membresías de dominios/familias de InterPro con términos GO.

Recursos

Recurso	Descripción
pdb://{entry_id}	Resumen de estructura experimental para una entrada de PDB — título, método, resolución, organismo, ligandos unidos e IDs de cadenas por entidad tanto en el espacio de nombres del autor (authAsymIds) como en el de etiquetas mmCIF (labelAsymIds).
af://{uniprot}	Resumen de estructura predicha para un acceso de UniProt desde AlphaFold DB — pLDDT medio, fracciones de bandas de confianza, URLs de modelos y versión.

Todos los datos de recursos también son accesibles vía herramientas — pdb://{entry_id} refleja protein_get_structure para source: experimental, y af://{uniprot} lo refleja para source: predicted. Muchos clientes MCP son solo de herramientas y no muestran recursos; los resúmenes siguen siendo accesibles a través de las herramientas.

Referencia de capacidades

protein_search_structures _herramienta

• Filtros de texto libre, secuencia de proteínas (dispara una búsqueda de similitud mmseqs2), y organismo / método / resolución
• content_type limita la búsqueda a experimental, predicted, o all (predeterminado) — all es una unión genuina, por lo que los modelos computados aparecen junto a las entradas de PDB
• Cada resultado nombra su source; los resultados de secuencia en cualquiera de los universos exponen una entrada encadenable id más el polímero coincidente entityId; los resultados experimentales llevan título, método, resolución y enriquecimiento de organismo, y los modelos AlphaFold su acceso UniProt parseado
• start y limit paginan a través de resultados clasificados; nextStart se devuelve mientras queda otra página, y una página vacía más allá del final nombra el desplazamiento en notice en lugar de reportar sin coincidencias
• facets opcionales devuelven un desglose por método / organismo / año de liberación junto a los resultados — cada dimensión puede listarse una vez y reporta cuántas coincidencias no tienen valor para ella; una dimensión limitada se nombra en notice, con protein_analyze_collection (mayor bucket_limit) como ruta a la cola larga
• Los IDs de resultados de cadena van directo a protein_get_structure

---

protein_get_structure _herramienta

• source: experimental agrupa IDs de entradas de PDB (también resuelve IDs de modelos computados como AF_*/MA_* de búsqueda, etiquetados source: predicted con su proveedor); source: predicted toma accesos de UniProt para modelos AlphaFold con pLDDT/PAE; source: best_available toma accesos de UniProt y devuelve el mejor modelo federado (el experimental de mayor resolución si existe, si no la mejor predicción)
• Éxito parcial por ID — los IDs no resueltos caen en failed[]; requested/processed revelan IDs descartados más allá del límite del lote, y cada aviso (límite, fallo, desbordamiento) se une en un único notice
• Los registros obtenidos con source: experimental, incluidos los modelos computados, también llevan polymerEntities (tanto authAsymIds como labelAsymIds), ligands, molecularWeight y releaseDate
• coordinateUrls lista solo archivos que existen: BinaryCIF viene del ModelServer de RCSB, el formato PDB se omite para entradas grandes solo-mmCIF, y los archivos de un modelo computado vienen de su proveedor (los tres formatos de AlphaFold DB, mmCIF de ModelArchive) — un modelo AlphaFold cuyo proveedor falla conserva solo su BinaryCIF de RCSB, nombrado en notice
• include_coords incluye contenido de coordenadas, sujeto a un presupuesto de respuesta — un lote que excede el presupuesto devuelve un esquema de tamaño por estructura (re-llamada con sections: [ids]), y un archivo único sobredimensionado se retiene con un puntero a su coordinateUrls
• Cada respuesta lleva un bloque attribution que nombra las licencias de datos upstream y citas

---

protein_find_similar _herramienta

• by: sequence ejecuta una búsqueda síncrona RCSB mmseqs2; by: structure ejecuta una búsqueda asíncrona Foldseek contra bases de datos experimentales y predichas — consulta desde una secuencia cruda, un ID de PDB o un acceso de UniProt
• Ambos modos aceptan start/limit y reportan totalCount, haciendo eco de start y devolviendo nextStart mientras queda otra página; una página vacía más allá del final nombra el desplazamiento en notice, distinto de una búsqueda sin coincidencias
• Los objetivos de Foldseek por defecto son pdb100 + afdb50; se anulan vía databases (p. ej. afdb-swissprot, BFVD)
• Un trabajo asíncrono que excede el presupuesto de sondeo devuelve status: computing con un ticketId — re-llamada con ticket_id para reanudar; una búsqueda de estructura completada devuelve el mismo ticket para que un nuevo start pagine el trabajo terminado
• Foldseek busca cada cadena de una estructura multicadena como su propia consulta: una respuesta de estructura cubre una consulta (query, basado en 0, predeterminado 0) y reporta queryCount, con un notice nombrando las otras consultas; pasa query con ticket_id para leer los resultados de otra cadena del mismo trabajo. Un query fuera de rango se rechaza (query_out_of_range), no se responde con una lista vacía
• Los resultados de estructura se clasifican mejor primero por score en cada base de datos buscada (resultados sin puntuación al final, empates por base de datos luego objetivo) antes del paginado start/limit
• Cada modo lee solo sus propios controles (sequence, max_evalue, min_identity bajo by: sequence; ticket_id, databases, query bajo by: structure) — un campo que el modo seleccionado no puede consumir se rechaza, no se ignora
• Cada resultado nombra el motor y la base de datos fuente de la que proviene

---

protein_track_ligands _herramienta

• mode: find_ligand resuelve un nombre o fórmula a IDs de componentes químicos con fórmula, peso, SMILES e InChIKey — clasificados por frecuencia de depósito, coincidencia más común primero
• totalCount y candidatesConsidered reportan cuántos componentes coincidieron y cuántos fueron clasificados; un nombre amplio cuyas coincidencias exceden el grupo de candidatos recibe un notice para estrechar la consulta
• Un query con forma de fórmula coincide en composición exacta, espaciada (C29 H31 N7 O) o sin espaciar; cualquier otra cosa (incluido un ID de componente) coincide en nombre y sinónimos
• mode: structures_with_ligand devuelve entradas de PDB que contienen un ligando por ID de componente exacto, con paginado start/limit y nextStart mientras queda otra página; una página más allá del final nombra el desplazamiento en notice en lugar de reportar sin entradas
• mode: binding_site devuelve los residuos de proteína que recubren el bolsillo de un ligando en una estructura, con distancias de contacto; las instancias de ligando se paginan con start/limit como structures_with_ligand
• Los residuos del bolsillo llevan tanto numeración de etiquetas mmCIF (asymId, seqId) como numeración del autor (authAsymId, authSeqId) — el bolsillo de imatinib de 1IEP lista la etiqueta THR93 como autor THR315; la instancia del ligando reporta su propia cadena de autor y número de residuo
• Los sitios de unión son solo experimentales — calculados a partir de coordenadas depositadas; los modelos predichos no llevan ligandos unidos

---

protein_compare_structures _herramienta

• Alinea de 2 al límite configurado (predeterminado 10, máximo 25) estructuras por llamada, vía tm-align, fatcat-rigid o fatcat-flexible; un chain opcional por estructura restringe la alineación a una sola cadena de etiqueta mmCIF
• reference: first alinea cada estructura contra la primera; reference: all_pairs calcula la matriz completa por pares; una estructura repetida en structures[] se compara una vez
• Cada par es un trabajo asíncrono independiente con éxito parcial por par — un par aún calculando cuando el presupuesto de sondeo se agota devuelve status: computing con un uuid de trabajo; un par fallido degrada solo su propia fila
• Re-llamada con una entrada { a, b, uuid } coincidente en resume[] para sondear un par en cálculo en lugar de reenviar; un par reanudado reporta a/b en el orden en que su trabajo fue enviado, cualquiera que sea el orden actual de structures[], y una reanudación bajo un method diferente se rechaza
• Devuelve TM-score, RMSD y conteo de residuos alineados por par, más el modeledResidues de cada estructura y coverage de 0–100, ordenados [a, b]; el TM-score se normaliza por la longitud de a, por lo que el mismo par puntúa diferente al invertirse

---

protein_analyze_collection _herramienta

• Agrupa por method, organism, polymer_type, resolution, release_year o molecular_weight
• Una dimensión group_by para un desglose, o dos dimensiones distintas para una tabla cruzada (la primera anida la segunda); una dimensión repetida se rechaza
• interval establece un ancho de bin de histograma (un número, para resolution o molecular_weight) o un período de histograma de fechas (year, el único que RCSB acepta) — se aplica a la dimensión solicitada que pueda consumir ese tipo; se rechaza cuando ninguna puede
• Alcance con un query de texto libre, organism, method o max_resolution; content_type selecciona el universo de estructuras
• bucket_limit limita los buckets por nivel de dimensión, no por respuesta — una tabla cruzada lo aplica por separado al padre y a cada hijo anidado, hasta bucket_limit × (1 + bucket_limit) buckets; notice nombra cada posición limitada y bucketsReturned da el total realizado
• Cada dimensión reporta missingValueCount — coincidencias sin valor para ese atributo (p. ej. un desglose resolution excluye entradas NMR; los modelos computados no tienen ni method ni resolution)

---

protein_get_annotations _tool

• Características de UniProt (dominios, sitios de unión, modificaciones postraduccionales) y variantes naturales, además de membresías de dominios/familias de InterPro (Pfam, PROSITE, …) con términos GO asociados
• Proporcione un acceso directo de UniProt, o un ID de PDB — resuelto mediante la referencia cruzada de la secuencia de la estructura
• Una entrada PDB de múltiples cadenas puede mapearse a varios accesos; el predeterminado es la selección determinista de la cadena de menor autoridad, con alternativas listadas bajo ambiguity — pase chain (un ID de cadena de autor) para seleccionar una específica
• include define qué clases se obtienen (features, domains, variants, all); limit limita cada clase de forma independiente (1–200, predeterminado 50), con una clase truncada revelada en notice
• Cada respuesta incluye un bloque attribution que nombra las licencias de datos upstream y las citas (ver Licencias de datos upstream)

---

pdb://{entry_id} _resource

• Resumen de estructura experimental como application/json — título, método, resolución, organismo, ligandos unidos e IDs de cadena por entidad tanto en el espacio de nombres del autor (authAsymIds) como en la etiqueta mmCIF (labelAsymIds)
• Espejo de protein_get_structure para source: experimental; entry_id es un ID de entrada PDB (p. ej. 4HHB)

---

af://{uniprot} _resource

• Resumen de estructura predicha como application/json — pLDDT medio, fracciones de bandas de confianza, URL de modelos (cif/pdb/bcif) y versión del modelo AlphaFold
• uniprot acepta un acceso de UniProt o un ID de entrada de AlphaFold DB (p. ej. AF-P69905-F1); espejo de protein_get_structure para source: predicted

Características

Construido sobre @cyanheads/mcp-ts-core: transportes stdio y Streamable HTTP, autenticación conectable (none / jwt / oauth), almacenamiento intercambiable (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), registro estructurado con rastreo opcional de OpenTelemetry.

Específico de PDB / AlphaFold:

• Una superficie federada sobre estructuras experimentales (PDB) y predichas (AlphaFold / 3D-Beacons) — búsqueda, obtención y comparación tratan ambos universos de la misma manera
• Sin claves en todos los upstream — RCSB, AlphaFold DB, 3D-Beacons, UniProt, InterPro y Foldseek, sin necesidad de aprovisionar claves API
• Análisis de corpus ejecutado en el motor de facetas de RCSB — distribuciones, histogramas y tablas cruzadas regresan como conteos de cubos compactos, no como las entradas coincidentes
• Trabajos asíncronos de alineación y Foldseek consultan dentro de un presupuesto limitado y devuelven un ticket de trabajo (ticketId / por par uuid) en lugar de bloquear — vuelva a llamar con ticket_id o una entrada resume[] para consultar el mismo trabajo en lugar de reenviarlo

Salida amigable para agentes:

• Procedencia en cada respuesta — cada resultado lleva un source (experimental / predicted), el motor y la base de datos que lo produjeron, y ecos de consulta efectiva / conteo total para que los agentes puedan razonar sobre la cobertura
• Falla parcial elegante — las obtenciones por lotes y las comparaciones por pares devuelven filas por elemento (failed[], por par status) en lugar de fallar toda la solicitud, cada una con texto de recuperación accionable
• Contratos de salida discriminados — uniones tipadas source y status, resultados computing con tickets de reanudación y resúmenes de desbordamiento de presupuesto permiten a los llamadores ramificar según datos, no análisis de cadenas

Primeros pasos

Instancia pública alojada

Una instancia pública está disponible en https://protein.caseyjhand.com/mcp — sin necesidad de instalación. Apunte cualquier cliente MCP hacia ella mediante Streamable HTTP:

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

Autohospedado / Local

Agregue lo siguiente al archivo de configuración de su cliente MCP. No se requiere clave API — cada proveedor upstream no requiere claves.

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

O con npx (sin necesidad 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"
      }
    }
  }
}

O con 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, configure el transporte e inicie el servidor:

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

Requisitos previos

• Bun v1.4.0 o superior (o Node.js v24+).
• Sin cuentas ni claves API — RCSB, AlphaFold DB, 3D-Beacons, UniProt, InterPro y Foldseek son todos públicos y sin claves.

Instalación

1. Clone el repositorio:

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

2. Navegue al directorio:

cd protein-mcp-server

3. Instale las dependencias:

bun install

Configuración

Todos los proveedores upstream no requieren claves, por lo que el servidor funciona de inmediato sin configuración. Cada variable a continuación es opcional.

Variable	Descripción	Predeterminado
PROTEIN_ASYNC_POLL_TIMEOUT_MS	Tiempo máximo de reloj para consultar un trabajo asíncrono (alineación / Foldseek) antes de devolver un resultado computing.	30000
PROTEIN_MAX_BATCH_IDS	Límite de IDs aceptados por protein_get_structure en un lote (1–100).	25
PROTEIN_MAX_COMPARE_STRUCTURES	Límite de estructuras por llamada protein_compare_structures (2–25).	10
PROTEIN_FACET_BUCKET_CAP	Límite predeterminado de cubos por dimensión protein_analyze_collection (1–500).	50
PROTEIN_FANOUT_CONCURRENCY	Máximo de solicitudes upstream concurrentes para expansión por ID / por par (1–16).	5
RCSB_SEARCH_BASE_URL	URL base para la API de búsqueda RCSB v2.	https://search.rcsb.org
ALPHAFOLD_BASE_URL	URL base para la API de la base de datos de estructuras AlphaFold.	https://alphafold.ebi.ac.uk
FOLDSEEK_BASE_URL	URL base para el servicio de búsqueda de similitud estructural Foldseek.	https://search.foldseek.com
MCP_TRANSPORT_TYPE	Transporte: stdio o http.	stdio
MCP_HTTP_PORT	Puerto para el servidor HTTP.	3010
MCP_SESSION_MODE	Modo de sesión HTTP: stateless, stateful o auto. El servidor declara stateless en código; configúrelo para anularlo.	stateless
MCP_AUTH_MODE	Modo de autenticación: none, jwt o oauth.	none
MCP_LOG_LEVEL	Nivel de registro (RFC 5424).	info
OTEL_ENABLED	Habilitar instrumentación OpenTelemetry.	false

Consulte .env.example para la lista completa de anulaciones de URL base de proveedores y límites de ajuste.

Ejecutar el servidor

Desarrollo local

• Compilar y ejecutar:

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

• Ejecutar verificaciones y pruebas:

  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

El Dockerfile usa por defecto transporte HTTP, modo de sesión sin estado y registra en /var/log/protein-mcp-server. Las dependencias de pares de OpenTelemetry se instalan por defecto — compile con --build-arg OTEL_ENABLED=false para omitirlas.

Estructura del proyecto

Directorio	Propósito
src/index.ts	Punto de entrada createApp() — registra herramientas/recursos e inicializa los servicios de proveedores.
src/config	Análisis y validación de variables de entorno específicas del servidor con Zod.
src/mcp-server/tools	Definiciones de herramientas (*.tool.ts).
src/mcp-server/resources	Definiciones de recursos (*.resource.ts).
src/services	Capa de servicios de proveedores — RCSB (búsqueda, datos, facetas), AlphaFold, 3D-Beacons (mejor disponible), UniProt (incl. InterPro/GO), alineación de Comparación Estructural, Foldseek y ayudantes compartidos de HTTP/identificador/concurrencia.
tests/	Pruebas unitarias y de integración que reflejan src/.

Guía de desarrollo

Consulte CLAUDE.md/AGENTS.md para pautas de desarrollo y reglas arquitectónicas. La versión corta:

• Los manejadores lanzan, el marco captura — sin try/catch en la lógica de herramientas
• Use ctx.log para registro con ámbito de solicitud, ctx.state para almacenamiento con ámbito de inquilino
• Registre nuevas herramientas y recursos mediante los barriles en src/mcp-server/*/definitions/index.ts
• Envuelva llamadas API externas: valide crudo → normalice a tipo de dominio → devuelva esquema de salida; nunca fabrique campos faltantes

Licencias de datos upstream

Los datos de estructura y anotación provienen de bases de datos públicas upstream, cada una bajo su propia licencia. protein_get_structure y protein_get_annotations llevan un bloque attribution en cada respuesta — la licencia, cita y página de inicio de cada fuente que contribuyó a esa respuesta específica — para que la obligación de atribución viaje con los datos a los consumidores posteriores en lugar de vivir solo aquí. Las fuentes CC BY / CC BY-SA requieren atribución en la redistribución; las fuentes CC0 son solo de cita (atribución recomendada, no requerida).

Fuente	Contribuye a	Licencia
RCSB PDB	protein_get_structure — registros experimentales	CC0 1.0 Universal
AlphaFold DB	protein_get_structure — modelos predichos	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 — datos de dominio/familia	CC0 1.0 Universal
GO	protein_get_annotations — términos GO	CC BY 4.0

best_available federates modelos predichos a través de 3D-Beacons, por lo que el bloque attribution acredita al proveedor contribuyente real (AlphaFold DB, SWISS-MODEL, BFVD, …); un proveedor sin entrada de licencia curada lleva un respaldo See provider terms que apunta de vuelta a 3D-Beacons en lugar de una licencia fabricada. Las clasificaciones de dominio/familia propias de InterPro son CC0; los términos GO que las acompañan son por separado CC BY 4.0, por lo que cada uno se acredita de forma independiente solo cuando realmente contribuye. Las citas completas de cada fuente viajan en el bloque attribution de las respuestas de herramientas relevantes. Esto cubre las licencias de datos upstream — el código del servidor en sí está licenciado por separado (ver Licencia).

Contribuciones

Los problemas son bienvenidos. Ejecute verificaciones y pruebas antes de enviar:

bun run devcheck
bun run test

Licencia

Apache-2.0 — consulte LICENSE para detalles.