protein-mcp-server

Servidor público alojado: https://protein.caseyjhand.com/mcp

Herramientas

Siete herramientas que abarcan el arco de la investigación estructural — descubrir, obtener, encontrar homólogos, rastrear ligandos, comparar, perfilar el corpus y anotar — sobre estructuras experimentales (PDB) y predichas (AlphaFold) desde una única superficie:

protein_search_structures

Búsqueda federada en estructuras experimentales (PDB) y predichas (modelos computados) mediante RCSB Search v2.

• Filtros de texto libre, secuencia de proteína (activa una búsqueda de similitud mmseqs2) y organismo / método / resolución

• content_type limita la búsqueda a experimental, predicted o all — el valor predeterminado all es una unión genuina de ambos universos, por lo que los modelos computados aparecen junto a las entradas de PDB

• Cada resultado indica su source; los resultados experimentales se enriquecen con título, método, resolución y organismo, mientras que los modelos computados llevan el acceso de UniProt extraído de su ID

• Las facets opcionales devuelven un desglose por método / organismo / año de publicación junto con los resultados sin llamadas adicionales, y cada una informa de cuántas coincidencias no tienen valor para esa dimensión; cada dimensión puede aparecer una sola vez

• Encadena los IDs de los resultados directamente en protein_get_structure

protein_get_structure

Obtiene estructuras con metadatos y URL de archivos de coordenadas, resolviendo entre proveedores mediante source.

• source: experimental acepta IDs de entradas de PDB, agrupados en una única llamada GraphQL de RCSB; también resuelve los IDs de modelos computados que devuelve la búsqueda (AF_* / MA_*), que vuelven como source: predicted atribuidos a su proveedor de modelado

• source: predicted acepta accesos de UniProt y devuelve el modelo AlphaFold con la confianza pLDDT/PAE

• source: best_available acepta accesos de UniProt y devuelve el mejor modelo federado (experimental si existe, si no, la mejor predicción)

• Éxito parcial por ID — los IDs no resueltos se listan en failed[], no como error a nivel de lote

• include_coords incluye el contenido de coordenadas; cuando un lote supera el presupuesto de respuesta, devuelve un esquema de tamaño por estructura, para que puedas volver a llamar con sections: [ids] para estructuras concretas

• Cada respuesta incluye un bloque attribution que nombra las licencias y citas de los datos de origen (consulta Licencias de datos de origen)

protein_find_similar

Encuentra proteínas relacionadas estructural o evolutivamente, por secuencia o por plegamiento.

• by: sequence ejecuta una búsqueda síncrona mmseqs2 de RCSB; by: structure ejecuta una búsqueda asíncrona de Foldseek contra bases de datos experimentales y predichas

• Consulta desde una secuencia de una letra sin procesar, un ID de PDB o un acceso de UniProt

• Los objetivos de Foldseek son por defecto pdb100 + afdb50; se pueden sobrescribir mediante databases (p. ej. afdb-swissprot, BFVD)

• Los trabajos asíncronos que superan el presupuesto de sondeo devuelven status: computing con un ticketId — vuelve a llamar con ticket_id establecido a ese valor para sondear el mismo trabajo en lugar de reenviarlo

• Cada resultado indica el motor y la base de datos de origen de la que proviene

protein_track_ligands

Descubrimiento de ligandos y análisis de sitios de unión en todo el PDB.

• mode: find_ligand resuelve un nombre o fórmula a IDs de componentes químicos con fórmula, peso, SMILES e InChIKey

• mode: structures_with_ligand devuelve entradas de PDB que contienen un ligando por ID de componente exacto

• mode: binding_site devuelve los residuos de proteína que recubren la cavidad de un ligando en una estructura, con distancias de contacto

• Los sitios de unión son solo experimentales — se calculan a partir de coordenadas depositadas (los modelos predichos no llevan ligandos unidos)

protein_compare_structures

Alineación estructural de múltiples estructuras (hasta el límite configurado PROTEIN_MAX_COMPARE_STRUCTURES) mediante el servicio de Comparación Estructural de RCSB.

• Métodos: tm-align, fatcat-rigid, fatcat-flexible

• reference: first alinea cada estructura con la primera; reference: all_pairs calcula la matriz completa por pares

• El chain opcional por estructura restringe la alineación a una única cadena

• Una estructura repetida en structures[] se compara una sola vez — la repetición solo añadiría una autoalineación y un par reflejado, que el mecanismo de reanudación no puede distinguir del original

• Cada par es un trabajo asíncrono independiente, distribuido con un límite de concurrencia y éxito parcial por par — un par que aún se está calculando cuando expira el presupuesto devuelve status: computing con su uuid de trabajo, y un par fallido degrada su fila sin hundir a los demás

• Vuelve a llamar con una entrada { a, b, uuid } coincidente en resume[] (copiada de pairs[] de una respuesta anterior) para sondear el trabajo de un par en cálculo en lugar de reenviarlo

• Devuelve TM-score, RMSD y el recuento de residuos alineados por par, además de modeledResidues y coverage — cada uno una tupla [a, b], con coverage como porcentaje de 0 a 100 del recuento propio de residuos modelados de esa estructura

protein_analyze_collection

Perfila el PDB en distribuciones y tendencias sobre una consulta de alcance opcional — respaldado por el motor de facetas del lado del servidor de RCSB (una llamada, buckets compactos, sin extracción de filas).

• 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 a la segunda); una dimensión repetida se rechaza

• interval establece el ancho de bin para histogramas de valores o el período para histogramas de fechas (year / month / quarter)

• Acota 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 a la dimensión principal y al hijo anidado dentro de cada bucket principal, por lo que se devuelven hasta bucket_limit × (1 + bucket_limit) buckets. Cada nivel señala su propia truncación, y bucketsReturned indica el total realizado

• Cada dimensión informa de missingValueCount — coincidencias dentro del alcance que no tienen valor para ese atributo y que, por tanto, no caen en ningún bucket (un desglose por resolution no cubre las entradas de NMR, y ni method ni resolution cubren los modelos computados)

protein_get_annotations

Anotación de secuencia y funcional para una proteína.

• Características de UniProt (dominios, sitios de unión, PTM) y variantes naturales de secuencia

• Membresías de dominios/familias de InterPro (Pfam, PROSITE, …) con términos GO asociados

• Proporciona un acceso de UniProt directamente, o un ID de PDB — resuelto a un acceso de UniProt mediante la referencia cruzada de secuencia de la estructura

• Una entrada de PDB con varias cadenas puede asignarse a varios accesos; el valor predeterminado es la elección determinista de la cadena de autor más baja, con las alternativas listadas en ambiguity. Pasa chain (un ID de cadena de autor, p. ej. A) para seleccionar una concreta

• include limita qué clases de anotación se obtienen: features, domains, variants o all

• Cada respuesta incluye un bloque attribution que nombra las licencias y citas de los datos de origen (consulta Licencias de datos de origen)

Related MCP server: UniProt MCP Server

Recursos

Todos los datos de recursos también son accesibles mediante las 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.

Características

Construido sobre @cyanheads/mcp-ts-core:

• Definiciones declarativas de herramientas y recursos: un archivo por primitiva, el framework se encarga del registro y la validación

• Manejo de errores unificado: los handlers lanzan, el framework captura, clasifica y formatea

• Autenticación conectable: none, jwt, oauth

• Backends de almacenamiento intercambiables: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1

• Registro estructurado con trazado OpenTelemetry opcional

• Transportes STDIO y HTTP Streamable

Específico de proteínas:

• Una superficie federada sobre estructuras experimentales (PDB) y predichas (AlphaFold / 3D-Beacons): búsqueda, obtención y comparación tratan ambos universos por igual

• Sin claves en todos los proveedores: RCSB, AlphaFold DB, 3D-Beacons, UniProt, InterPro y Foldseek, sin necesidad de aprovisionar claves API

• Análisis de corpus ejecutado en el servidor con el motor de facetas de RCSB: distribuciones, histogramas y tablas cruzadas en una sola llamada, sin extracción de filas ni espacio de trabajo SQL

• Alineamiento asíncrono y trabajos de Foldseek que se consultan dentro de un presupuesto limitado y devuelven un ticket de trabajo (ticketId / uuid por par) en lugar de bloquear: vuelve 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 / recuento 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[], status por par) en lugar de fallar toda la solicitud, cada una con texto de recuperación accionable

• Contratos de salida discriminados: uniones tipadas de source y status, resultados computing con tickets de reanudación y esquemas de desbordamiento de presupuesto permiten a los llamadores ramificar según los datos, no según el análisis de cadenas

Primeros pasos

Instancia pública alojada

Hay una instancia pública disponible en https://protein.caseyjhand.com/mcp — no requiere instalación. Apunta cualquier cliente MCP a ella mediante HTTP Streamable:

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

Autoalojado

Añade lo siguiente al archivo de configuración de tu cliente MCP. No se requiere clave API — todos los proveedores son sin clave.

{
  "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 (no se requiere 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 HTTP Streamable, configura el transporte e inicia 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.3.2 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 clave.

Instalación

1. Clona el repositorio:

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

2. Navega al directorio:

cd protein-mcp-server

3. Instala las dependencias:

bun install

Configuración

Todos los proveedores son sin clave, por lo que el servidor funciona sin configuración. Cada variable a continuación es opcional.

Consulta .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 comprobaciones 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 opcionales de OpenTelemetry se instalan por defecto: compila con --build-arg OTEL_ENABLED=false para omitirlas.

Estructura del proyecto

Guía de desarrollo

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

• Los handlers lanzan, el framework captura: sin try/catch en la lógica de herramientas

• Usa ctx.log para registro con ámbito de solicitud, ctx.state para almacenamiento con ámbito de tenant

• Registra nuevas herramientas y recursos mediante los barriles en src/mcp-server/*/definitions/index.ts

• Envuelve las llamadas a API externas: valida datos sin procesar → normaliza al tipo de dominio → devuelve el esquema de salida; nunca inventes campos faltantes

Contribuir

Las incidencias y solicitudes de extracción son bienvenidas. Ejecuta comprobaciones y pruebas antes de enviar:

bun run devcheck
bun run test

Licencia de datos ascendentes

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

best_available federated predicted models through 3D-Beacons, so the attribution block credits the actual contributing provider (AlphaFold DB, SWISS-MODEL, BFVD, …); a provider without a curated license entry carries a See provider terms fallback pointing back to 3D-Beacons rather than a fabricated license. InterPro's own domain/family classifications are CC0; the GO terms carried alongside them are separately CC BY 4.0, so each is credited independently only when it actually contributes. Full citations for each source travel in the attribution block of the relevant tool responses. This covers upstream data licensing — the server's own code is licensed separately (see License).

Licencia

Apache-2.0 — consulta LICENSE para más detalles.