protein-mcp-server

Öffentlich gehosteter Server: https://protein.caseyjhand.com/mcp

Tools

Sieben Tools, die den gesamten Bogen der Strukturforschung abdecken — entdecken, abrufen, Homologe finden, Liganden verfolgen, vergleichen, den Bestand profilieren und annotieren — über experimentelle (PDB) und vorhergesagte (AlphaFold) Strukturen von einer einzigen Oberfläche aus:

protein_search_structures

Föderierte Suche über experimentelle (PDB) und vorhergesagte (berechnete Modelle) Strukturen via RCSB Search v2.

• Freitext-, Proteinsequenz- (löst eine mmseqs2-Ähnlichkeitssuche aus) und Organismus-/Methode-/Auflösungsfilter

• content_type begrenzt die Suche auf experimental, predicted oder all — der Standardwert all ist eine echte Vereinigung beider Universen, sodass berechnete Modelle neben PDB-Einträgen erscheinen

• Jeder Treffer nennt seine source; experimentelle Treffer sind mit Titel, Methode, Auflösung und Organismus angereichert, während berechnete Modelle die aus ihrer ID geparste UniProt-Accession tragen

• Optionale facets liefern eine Aufschlüsselung nach Methode / Organismus / Veröffentlichungsjahr zusammen mit den Treffern ohne zusätzlichen Aufruf, wobei jeweils gemeldet wird, wie viele Treffer für diese Dimension keinen Wert haben; jede Dimension darf einmal aufgeführt werden

• Treffer-IDs direkt in protein_get_structure weiterreichen

protein_get_structure

Ruft Strukturen mit Metadaten und Koordinatendatei-URLs ab und löst dabei anbieterübergreifend über source auf.

• source: experimental akzeptiert PDB-Eintrags-IDs, gebündelt in einem einzigen RCSB-GraphQL-Aufruf; es löst auch die von der Suche zurückgegebenen berechneten Modell-IDs (AF_* / MA_*) auf, die als source: predicted zurückkommen und ihrem Modellierungsanbieter zugeschrieben werden

• source: predicted akzeptiert UniProt-Accessions und gibt das AlphaFold-Modell mit pLDDT/PAE-Konfidenz zurück

• source: best_available akzeptiert UniProt-Accessions und gibt das beste föderierte Modell zurück (experimentell, falls vorhanden, sonst die beste Vorhersage)

• Partieller Erfolg pro ID — nicht aufgelöste IDs werden in failed[] aufgeführt, nicht als Fehler auf Batchebene

• include_coords bettet Koordinateninhalt ein; wenn ein Batch das Antwortbudget überschreitet, wird eine Größenübersicht pro Struktur zurückgegeben, sodass Sie mit sections: [ids] für bestimmte Strukturen erneut aufrufen können

• Jede Antwort enthält einen attribution-Block, der die Upstream-Datenlizenzen und Zitationen nennt (siehe Upstream-Datenlizenzierung)

protein_find_similar

Findet strukturell oder evolutionär verwandte Proteine, nach Sequenz oder nach Faltung.

• by: sequence führt eine synchrone RCSB-mmseqs2-Suche aus; by: structure führt eine asynchrone Foldseek-Suche gegen experimentelle und vorhergesagte Datenbanken aus

• Abfrage über eine rohe Einbuchstabensequenz, eine PDB-ID oder eine UniProt-Accession

• Foldseek-Ziele sind standardmäßig pdb100 + afdb50; überschreibbar über databases (z. B. afdb-swissprot, BFVD)

• Asynchrone Jobs, die das Poll-Budget überschreiten, geben status: computing mit einer ticketId zurück — erneuter Aufruf mit gesetzter ticket_id pollt denselben Job, statt ihn neu einzureichen

• Jeder Treffer nennt die Engine und die Quelldatenbank, aus der er stammt

protein_track_ligands

Ligandenentdeckung und Bindungstaschenanalyse über die gesamte PDB.

• mode: find_ligand löst einen Namen oder eine Formel in chemische Komponenten-IDs mit Formel, Gewicht, SMILES und InChIKey auf

• mode: structures_with_ligand gibt PDB-Einträge zurück, die einen Liganden mit exakter Komponenten-ID enthalten

• mode: binding_site gibt die Proteinreste zurück, die die Tasche eines Liganden in einer Struktur auskleiden, mit Kontaktabständen

• Bindungstaschen sind nur experimentell — berechnet aus hinterlegten Koordinaten (vorhergesagte Modelle tragen keine gebundenen Liganden)

protein_compare_structures

Strukturelles Alignment mehrerer Strukturen (bis zum konfigurierten PROTEIN_MAX_COMPARE_STRUCTURES-Limit) über den RCSB-Strukturvergleichsdienst.

• Methoden: tm-align, fatcat-rigid, fatcat-flexible

• reference: first aligniert jede Struktur gegen die erste; reference: all_pairs berechnet die vollständige paarweise Matrix

• Optionale chain pro Struktur schränkt das Alignment auf eine einzelne Kette ein

• Eine in structures[] wiederholte Struktur wird nur einmal verglichen — die Wiederholung würde nur ein Selbst-Alignment und ein gespiegeltes Paar hinzufügen, das der Resume-Mechanismus nicht vom Original unterscheiden kann

• Jedes Paar ist ein unabhängiger asynchroner Job, der mit einem Nebenläufigkeitslimit und partiellem Erfolg pro Paar ausgefächert wird — ein Paar, das bei Ablauf des Budgets noch rechnet, gibt status: computing mit seiner Job-uuid zurück, und ein fehlgeschlagenes Paar degradiert seine Zeile, ohne die anderen zu beeinträchtigen

• Erneuter Aufruf mit einem passenden { a, b, uuid }-Eintrag in resume[] (kopiert aus den pairs[] einer früheren Antwort) pollt den Job eines rechnenden Paars, statt ihn neu einzureichen

• Gibt TM-Score, RMSD und Anzahl alignierter Reste pro Paar zurück, plus modeledResidues und coverage — jeweils ein [a, b]-Tupel, wobei coverage ein Prozentsatz von 0–100 der eigenen modellierten Reste dieser Struktur ist

protein_analyze_collection

Profiliert die PDB in Verteilungen und Trends über eine optionale eingrenzende Abfrage — unterstützt durch RCSBs serverseitige Facetten-Engine (ein Aufruf, kompakte Buckets, kein Zeilenabruf).

• Gruppierung nach method, organism, polymer_type, resolution, release_year oder molecular_weight

• Eine group_by-Dimension für eine Aufschlüsselung oder zwei verschiedene Dimensionen für eine Kreuztabelle (die erste verschachtelt die zweite); eine wiederholte Dimension wird abgelehnt

• interval setzt die Bin-Breite für Werthistogramme oder den Zeitraum für Datumshistogramme (year / month / quarter)

• Eingrenzung mit einer Freitext-query, organism, method oder max_resolution; content_type wählt das Strukturuniversum

• bucket_limit begrenzt Buckets pro Dimensionsebene, nicht pro Antwort — eine Kreuztabelle wendet es separat auf die übergeordnete Dimension und auf das verschachtelte Kind innerhalb jedes übergeordneten Buckets an, sodass bis zu bucket_limit × (1 + bucket_limit) Buckets zurückkommen. Jede Ebene kennzeichnet ihre eigene Abschneidung, und bucketsReturned gibt die tatsächlich erreichte Gesamtzahl an

• Jede Dimension meldet missingValueCount — Treffer im Geltungsbereich ohne Wert für dieses Attribut, die daher in keinen Bucket fallen (eine resolution-Aufschlüsselung deckt keine NMR-Einträge ab, und weder method noch resolution decken berechnete Modelle ab)

protein_get_annotations

Sequenz- und Funktionsannotation für ein Protein.

• UniProt-Features (Domänen, Bindungsstellen, PTMs) und natürliche Sequenzvarianten

• InterPro-Domänen-/Familienzugehörigkeiten (Pfam, PROSITE, …) mit zugehörigen GO-Termen

• Direkt eine UniProt-Accession angeben oder eine PDB-ID — aufgelöst in eine UniProt-Accession über die Sequenz-Kreuzreferenz der Struktur

• Ein PDB-Eintrag mit mehreren Ketten kann auf mehrere Accessions abbilden; der Standard ist die deterministische Auswahl der Kette mit der niedrigsten Autor-Ketten-ID, wobei die Alternativen unter ambiguity aufgeführt sind. Übergeben Sie chain (eine Autor-Ketten-ID, z. B. A), um eine bestimmte auszuwählen

• include legt fest, welche Annotationsklassen abgerufen werden: features, domains, variants oder all

• Jede Antwort enthält einen attribution-Block, der die Upstream-Datenlizenzen und Zitationen nennt (siehe Upstream-Datenlizenzierung)

Related MCP server: UniProt MCP Server

Ressourcen

Alle Ressourcendaten sind auch über Tools erreichbar — pdb://{entry_id} spiegelt protein_get_structure für source: experimental wider, und af://{uniprot} spiegelt es für source: predicted wider. Viele MCP-Clients sind reine Tool-Clients und zeigen keine Ressourcen an; die Zusammenfassungen bleiben über die Tools erreichbar.

Features

Basierend auf @cyanheads/mcp-ts-core:

• Deklarative Tool- und Ressourcendefinitionen – eine Datei pro Primitive, das Framework übernimmt Registrierung und Validierung

• Einheitliche Fehlerbehandlung – Handler werfen, das Framework fängt, klassifiziert und formatiert

• Plug-in-fähige Authentifizierung: none, jwt, oauth

• Austauschbare Speicher-Backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1

• Strukturierte Protokollierung mit optionalem OpenTelemetry-Tracing

• STDIO- und Streamable-HTTP-Transports

Proteinspezifisch:

• Eine föderierte Oberfläche über experimentelle (PDB) und vorhergesagte (AlphaFold / 3D-Beacons) Strukturen – Suche, Abruf und Vergleich behandeln beide Universen gleich

• Schlüssellos über alle Upstreams hinweg – RCSB, AlphaFold DB, 3D-Beacons, UniProt, InterPro und Foldseek, keine API-Schlüssel erforderlich

• Korpus-Analysen laufen serverseitig auf RCSBs Facetten-Engine – Verteilungen, Histogramme und Kreuztabellen in einem Aufruf, ohne Zeilenabruf und ohne SQL-Arbeitsbereich

• Asynchrone Alignments und Foldseek-Jobs pollen innerhalb eines begrenzten Budgets und geben stattdessen einen Job-Ticket zurück (ticketId / uuid pro Paar) statt zu blockieren – erneut mit ticket_id oder einem resume[]-Eintrag aufrufen, um denselben Job abzufragen, statt ihn erneut zu senden

Agentenfreundliche Ausgabe:

• Herkunft bei jeder Antwort – jeder Treffer trägt eine source (experimental / predicted), die Engine und Datenbank, die ihn erzeugt haben, sowie effektive Abfrage-/Gesamtzahl-Echos, damit Agenten über die Abdeckung nachdenken können

• Sanfter Teilfehler – Batch-Abrufe und paarweise Vergleiche geben zeilenweise Elemente zurück (failed[], status pro Paar), statt die gesamte Anfrage fehlschlagen zu lassen, jeweils mit umsetzbarem Wiederherstellungstext

• Diskriminierte Ausgabeverträge – typisierte source- und status-Unions, computing-Ergebnisse mit Fortsetzungs-Tickets und Budget-Überlauf-Skizzen lassen Aufrufer auf Daten verzweigen, nicht auf String-Parsing

Erste Schritte

Öffentlich gehostete Instanz

Eine öffentliche Instanz ist unter https://protein.caseyjhand.com/mcp verfügbar – keine Installation erforderlich. Richten Sie einen beliebigen MCP-Client über Streamable HTTP darauf aus:

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

Selbst gehostet

Fügen Sie Folgendes zu Ihrer MCP-Client-Konfigurationsdatei hinzu. Kein API-Schlüssel erforderlich – jeder Upstream-Anbieter ist schlüssellos.

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

Oder mit npx (kein Bun erforderlich):

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

Oder mit 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"]
    }
  }
}

Für Streamable HTTP setzen Sie den Transport und starten Sie den Server:

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

Voraussetzungen

• Bun v1.3.2 oder höher (oder Node.js v24+).

• Keine Konten oder API-Schlüssel – RCSB, AlphaFold DB, 3D-Beacons, UniProt, InterPro und Foldseek sind alle öffentlich und schlüssellos.

Installation

1. Repository klonen:

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

2. In das Verzeichnis wechseln:

cd protein-mcp-server

3. Abhängigkeiten installieren:

bun install

Konfiguration

Alle Upstream-Anbieter sind schlüssellos, sodass der Server ohne Konfiguration sofort läuft. Jede unten aufgeführte Variable ist optional.

Siehe .env.example für die vollständige Liste der Basis-URL-Überschreibungen und Tuning-Grenzwerte der Anbieter.

Server ausführen

Lokale Entwicklung

• Erstellen und ausführen:

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

• Checks und Tests ausführen:

  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

Das Dockerfile verwendet standardmäßig HTTP-Transport, zustandslosen Sitzungsmodus und protokolliert nach /var/log/protein-mcp-server. OpenTelemetry-Peer-Abhängigkeiten sind standardmäßig installiert – mit --build-arg OTEL_ENABLED=false bauen, um sie wegzulassen.

Projektstruktur

Entwicklungsleitfaden

Siehe CLAUDE.md/AGENTS.md für Entwicklungsrichtlinien und Architekturregeln. Die Kurzfassung:

• Handler werfen, das Framework fängt – kein try/catch in Tool-Logik

• Verwenden Sie ctx.log für anfragebezogene Protokollierung, ctx.state für mandantenbezogenen Speicher

• Registrieren Sie neue Tools und Ressourcen über die Barrels in src/mcp-server/*/definitions/index.ts

• Externe API-Aufrufe kapseln: roh validieren → in Domänentyp normalisieren → Ausgabeschema zurückgeben; niemals fehlende Felder erfinden

Mitwirken

Issues und Pull-Requests sind willkommen. Führen Sie vor dem Einreichen Checks und Tests aus:

bun run devcheck
bun run test

Lizenzierung der Upstream-Daten

Struktur- und Annotationsdaten stammen aus öffentlichen Upstream-Datenbanken, jede unter ihrer eigenen Lizenz. protein_get_structure und protein_get_annotations tragen in jeder Antwort einen attribution-Block – die Lizenz, das Zitat und die Homepage für jede Quelle, die zu dieser spezifischen Antwort beigetragen hat – sodass die Zuschreibungspflicht mit den Daten zu nachgelagerten Verbrauchern reist, statt nur hier zu leben. CC BY / CC BY-SA-Quellen erfordern Zuschreibung bei Weiterverbreitung; CC0-Quellen sind nur zitatpflichtig (Zuschreibung empfohlen, nicht erforderlich).

best_available föderiert vorhergesagte Modelle über 3D-Beacons, sodass der attribution-Block den tatsächlich beitragenden Anbieter (AlphaFold DB, SWISS-MODEL, BFVD, …) gutschreibt; ein Anbieter ohne kuratierte Lizenzangabe trägt einen Siehe Anbieterbedingungen-Fallback, der auf 3D-Beacons verweist, statt einer erfundenen Lizenz. InterPros eigene Domänen-/Familienklassifikationen sind CC0; die GO-Terme, die daneben getragen werden, sind separat CC BY 4.0, sodass jede nur dann unabhängig gutgeschrieben wird, wenn sie tatsächlich beiträgt. Vollständige Zitate für jede Quelle reisen im attribution-Block der relevanten Tool-Antworten. Dies deckt die Lizenzierung der Upstream-Daten ab – der eigene Code des Servers ist separat lizenziert (siehe Lizenz).

Lizenz

Apache-2.0 – siehe LICENSE für Details.