rcsb-mcp 0.1.0__tar.gz

rcsb_mcp-0.1.0/.dockerignore

@@ -0,0 +1,14 @@
+.git
+.gitignore
+.idea
+.claude
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+.DS_Store
+prompts/
+scripts/
+Dockerfile
+.dockerignore

rcsb_mcp-0.1.0/.github/workflows/_workflow-docker.yaml

@@ -0,0 +1,20 @@
+# Docker build and push workflow
+
+name: Run CI/CD Docker Workflow
+
+# Reusable workflow — invoked by publish.yaml (and runnable manually). It does
+# not trigger on push directly; the release pipeline calls it via `uses:`.
+on:
+  workflow_call:
+  workflow_dispatch:
+
+jobs:
+  run-workflow:
+    name: "Run automated docker workflow"
+    if: github.event_name != 'pull_request'
+    uses: rcsb/devops-cicd-github-actions/.github/workflows/workflow-docker.yaml@master
+    with:
+      repo_project: "rcsb"  # REQUIRED. The name of the project or organization in the remote Docker image repository.
+      docker_image_name: "rcsb-mcp"  # REQUIRED. The name of the Docker image to create.
+      docker_build_context: "."  # The path location of the docker build context, relative to the project root. Defaults to the project root.
+      mainline_branch: "master"

rcsb_mcp-0.1.0/.github/workflows/publish.yaml

@@ -0,0 +1,125 @@
+name: CI Pipeline
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+  release:
+    types: [published]
+
+jobs:
+
+  hatch-test:
+    name: Test on Python ${{ matrix.python-version }}
+    runs-on: ["self-hosted", "buildchain"]
+    timeout-minutes: 20
+    strategy:
+      matrix:
+        python-version: ["3.10"]
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install Hatch
+        run: pip install hatch
+
+      - name: Run tests
+        run: hatch test
+
+  hatch-build:
+    name: Build to PyPI
+    needs:
+      - hatch-test
+    runs-on: ubuntu-latest
+    if: github.event_name == 'release'
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.10
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.10"
+
+      - name: Install Hatch
+        run: pip install hatch
+
+      - name: Build distribution
+        run: hatch build
+
+      - name: Store the distribution packages
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  push-image:
+    needs:
+      - hatch-build
+    name: Push image to harbor
+    uses: ./.github/workflows/_workflow-docker.yaml
+    secrets: inherit
+
+  publish-to-pypi:
+    name: >-
+      Publish Python 🐍 distribution 📦 to PyPI
+    if: github.event_name == 'release'
+    needs:
+      - hatch-build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/rcsb-mcp
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download all the dists
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish distribution 📦 to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  publish-to-registry:
+    name: Publish to MCP Registry
+    if: github.event_name == 'release'
+    needs:
+      # The PyPI package must exist first — the registry validates that the
+      # version in server.json is published and carries the mcp-name marker.
+      - publish-to-pypi
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # OIDC token for github-oidc auth to the registry
+      contents: read
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Verify server.json version matches the package
+        run: |
+          server_version=$(jq -r .version server.json)
+          pkg_version=$(grep -E '^version *=' pyproject.toml | head -1 | sed -E 's/.*"([^"]+)".*/\1/')
+          echo "server.json=$server_version  pyproject.toml=$pkg_version"
+          if [ "$server_version" != "$pkg_version" ]; then
+            echo "::error::server.json version ($server_version) != pyproject.toml ($pkg_version). Bump both before releasing."
+            exit 1
+          fi
+
+      - name: Install mcp-publisher
+        run: |
+          curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
+
+      - name: Authenticate to MCP Registry (GitHub OIDC)
+        run: ./mcp-publisher login github-oidc
+
+      - name: Publish server to MCP Registry
+        run: ./mcp-publisher publish

rcsb_mcp-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+/.claude/
+/.idea/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+build/
+dist/

rcsb_mcp-0.1.0/AGENTS.md

@@ -0,0 +1,93 @@
+# AGENTS.md — working on the rcsb-mcp repo
+
+Guidance for AI coding agents (and humans) modifying this repository. This is an
+MCP server that lets an LLM **interrogate Protein Data Bank structures** across
+three RCSB APIs: Search (REST), Data (GraphQL), and Sequence Coordinates (GraphQL).
+
+> The runtime *assistant* persona and output format are **not** here — they live
+> in [`prompts/pdb-assistant.md`](prompts/pdb-assistant.md), which is pasted into a
+> project as a system prompt. Keep that split (see "Two layers" below).
+
+## Layout
+
+```
+src/rcsb_mcp/
+  server.py                  MCP server: @mcp.tool() tools, HTTP calls, schema introspection
+  queries.py                 PURE request-body builders (no network) + the DATA_OBJECTS registry
+  graphql_queries.py         Large GraphQL field-selection constants (ENTRY_ANNOTATIONS, ...)
+  search_attributes.py       SEARCH_ATTRIBUTES catalog (structure search schema)
+  chemical_search_attributes.py  CHEMICAL_SEARCH_ATTRIBUTES catalog — auto-generated (see scripts/)
+tests/
+  test_queries.py            Network-free unit tests for the query builders
+```
+
+## Architecture & conventions
+
+- **Pure builders vs. I/O.** `queries.py` builds request bodies and contains **no
+  network code**, so it stays unit-testable. `server.py` does the HTTP and exposes
+  the tools. Keep new query-construction logic in `queries.py`.
+- **The `DATA_OBJECTS` registry** (`queries.py`) drives every Data API `rcsb_get_*` tool:
+  one entry per GraphQL root field (root field, id arg, batch/single, default field
+  selection). **Adding a Data API object is ideally a one-line registry entry.**
+- **Compact defaults + escape hatches.** Each `rcsb_get_*`/`rcsb_seqcoord_*` tool returns a
+  curated compact field selection but accepts a `fields=` override; `rcsb_describe_data_object`
+  / `rcsb_describe_seqcoord_object` introspect the live schema for discovery; `rcsb_data_graphql` /
+  `rcsb_seqcoord_graphql` are raw passthroughs. Don't try to make defaults exhaustive.
+- **Server `instructions` = tool-usage guidance only** (routing, chaining, return
+  types). Do **not** put application/presentation policy there — it's always-on for
+  every client. That belongs in the project prompt.
+
+## Dev workflow
+
+```bash
+# Unit tests (no network) — run after touching queries.py / graphql_queries.py
+hatch test                       # or: python tests/test_queries.py
+
+# Syntax check both core modules
+python -m py_compile src/rcsb_mcp/server.py src/rcsb_mcp/queries.py
+
+# Run the server over stdio (entry point: rcsb_mcp.server:main, console script `rcsb-mcp`)
+python -m rcsb_mcp.server
+
+# Inspect interactively
+npx @modelcontextprotocol/inspector python -m rcsb_mcp.server
+```
+
+The package is installed editable, so source edits take effect on the next process
+start. The test file lives at `tests/test_queries.py`.
+
+## The golden rule: validate against the live API before changing field selections
+
+Before editing any default field selection or query body, **run the proposed
+selection against the live endpoint** and confirm it returns data. This is how real
+bugs were caught in this repo (a non-existent `auth_asym_id` field, id case
+sensitivity, `[null]` rows for unknown ids). Pattern:
+
+```python
+import asyncio; from rcsb_mcp import server, queries
+body = queries.build_data_query("entries", "4HHB", "rcsb_id <your new fields>")
+print(asyncio.run(server._graphql_field(body, "entries")))
+```
+
+After validating, add/adjust the default and re-run `test_queries.py`.
+
+## Gotchas
+
+- **GraphQL endpoints return HTTP 200 even on query errors** — the error is in the
+  `errors` array, not the status code. `_graphql_field` already raises on it.
+- **ID case sensitivity.** Entry/entity/chem ids are upper-cased; group and
+  `group_provenance` ids are case-sensitive opaque tokens (the `upper=False` flag in
+  `DATA_OBJECTS`). Don't blanket-uppercase.
+- **Unknown ids** are either dropped or returned as `null` depending on the field;
+  batch handling filters `None` and reports `not_found`.
+- **Sequence Coordinates: PDB ids must be entity/instance-level** (`4HHB_1`, not
+  `4HHB`); only this API cross-references NCBI.
+- **Claude Desktop caches MCP processes.** After code changes, fully quit & relaunch
+  (⌘Q) — it does not hot-reload, and stale/duplicate processes have caused confusion.
+
+## Two layers (don't merge them)
+
+- **Server `instructions`** (in `server.py`) → how to *drive the tools*; reusable
+  across every client/project.
+- **`prompts/pdb-assistant.md`** → assistant persona + output format (HTML report,
+  columns, conventions); application-specific, pasted as project instructions.

rcsb_mcp-0.1.0/Dockerfile

@@ -0,0 +1,30 @@
+# syntax=docker/dockerfile:1
+FROM python:3.11-slim
+
+ENV PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1
+
+WORKDIR /app
+
+# Create an unprivileged user up front (uid/gid 1000 to match the Helm
+# podSecurityContext: runAsUser / runAsGroup / fsGroup = 1000).
+RUN groupadd --gid 1000 appuser \
+    && useradd --create-home --uid 1000 --gid 1000 appuser
+
+# Install the package and its dependencies. Copy build metadata + source only
+# (keeps the layer cache friendly and the image lean).
+COPY pyproject.toml README.md ./
+COPY src ./src
+RUN pip install .
+
+USER appuser
+
+EXPOSE 8080
+
+# Liveness: confirm the server is accepting connections on the port.
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD python -c "import socket,sys; s=socket.socket(); s.settimeout(2); s.connect(('127.0.0.1',8080)); s.close()" || exit 1
+
+# Serve the MCP over the streamable-HTTP transport (endpoint: POST /mcp).
+# create_app is the FastMCP streamable-HTTP ASGI app factory (--factory builds it on start).
+CMD ["uvicorn", "rcsb_mcp.server:create_app", "--factory", "--host", "0.0.0.0", "--port", "8080"]

rcsb_mcp-0.1.0/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License
+
+    Copyright (c) 2026 - now, RCSB PDB and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rcsb_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,244 @@
+Metadata-Version: 2.4
+Name: rcsb-mcp
+Version: 0.1.0
+Summary: An MCP server for interrogating PDB structures — search, inspect, and cross-reference across the RCSB Search, Data, and Sequence Coordinates APIs
+License-File: LICENSE.md
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: uvicorn>=0.30
+Description-Content-Type: text/markdown
+
+<!-- mcp-name: io.github.rcsb/rcsb-mcp -->
+
+# rcsb-mcp
+
+An [MCP](https://modelcontextprotocol.io) server for **interrogating Protein Data
+Bank structures** — discover, inspect, and cross-reference — from LLM clients
+(Claude Desktop, MCP Inspector, Cursor, etc.). It spans three RCSB APIs:
+
+- **Discover** — find structures with the [Search API](https://search.rcsb.org)
+  (keyword, attribute, sequence, chemistry, 3D shape, motif).
+- **Inspect** — fetch entry / entity / assembly / ligand details and annotations
+  from the [Data API](https://data.rcsb.org/graphql).
+- **Relate** — map sequences and positional features across PDB, UniProt, and NCBI
+  with the [Sequence Coordinates API](https://sequence-coordinates.rcsb.org/graphql).
+
+## Tools
+
+### Search (search.rcsb.org)
+
+| Tool | What it does |
+|------|--------------|
+| `rcsb_list_pdb_search_attributes` | Discover searchable attribute paths, types, and operators. `schema="structure"` (default, ~677) or `schema="chemical"` (~57: `chem_comp.*`, `drugbank_info.*`, ...). |
+| `rcsb_find_go_terms` | Resolve a free-text molecular function / biological process / cellular component to Gene Ontology ids (via EBI QuickGO), annotated with PDB entry counts — then search by `rcsb_polymer_entity_annotation.annotation_lineage.id`. |
+| `rcsb_find_interpro_domains` | Resolve a free-text protein domain / family / fold to InterPro ids (via EBI InterPro API), annotated with PDB entry counts — then search by `rcsb_polymer_entity_annotation.annotation_id`. |
+| `rcsb_find_enzyme_classes` | Resolve a free-text enzyme / reaction to Enzyme Commission (EC) numbers (via EBI Search/IntEnz), annotated with PDB entry counts — then search by `rcsb_polymer_entity.rcsb_ec_lineage.id` (hierarchical). |
+| `rcsb_find_disease_terms` | Resolve a free-text disease / condition to MONDO ids (via EBI OLS), annotated with PDB entry counts — then search by `rcsb_uniprot_annotation.annotation_lineage.id` (hierarchical, UniProt-based). |
+| `rcsb_find_organisms` | Resolve a free-text organism / common name / clade to NCBI Taxonomy ids (via UniProt taxonomy), annotated with PDB entry counts — then search by `rcsb_entity_source_organism.taxonomy_lineage.id` (hierarchical: a clade id matches every organism beneath it). |
+| `rcsb_search_fulltext` | Free-text keyword search (e.g. `"CRISPR Cas9"`). |
+| `rcsb_search_by_attribute` | Structured search on an indexed attribute (resolution, organism, release date, ...). Supports `exists`, `negation`, `case_sensitive`, and `chemical=True` (text_chem). |
+| `rcsb_search_combined` | Combine free text + multiple attribute filters (AND/OR) in one query, with optional sort. |
+| `rcsb_search_count` | Return only the **number** of matches — for "how many ..." questions. |
+| `rcsb_search_facets` | Aggregate matches into buckets/statistics (terms, histogram, date_histogram, range, cardinality) — for "distribution / breakdown / per X" questions. |
+| `rcsb_search_by_sequence` | MMseqs2 sequence-similarity search (BLAST-like). |
+| `rcsb_search_by_chemical` | Chemical search by SMILES/InChI descriptor (whole-molecule or substructure) or molecular formula. |
+| `rcsb_search_by_structure` | 3D shape-similarity search against a reference PDB assembly or chain. |
+| `rcsb_search_by_seqmotif` | Short **sequence**-motif search (PROSITE pattern, regex, or simple wildcards). |
+| `rcsb_search_strucmotif` | 3D **structural**-motif search: structures sharing a geometric arrangement of specific residues (e.g. a catalytic triad). |
+| `rcsb_search_advanced` | Escape hatch: run a raw Search API query body (`return_all_hits`, grouped results, deeply nested boolean queries, ...). |
+
+The three text tools (`rcsb_search_fulltext`, `rcsb_search_by_attribute`, `rcsb_search_combined`)
+also take `group_by_identity` (100/95/90/70/50/30) to return one representative
+per sequence-identity cluster — i.e. non-redundant results. To search
+chemical-component attributes, find the path with
+`rcsb_list_pdb_search_attributes(schema="chemical")`, then pass `chemical=True` to
+`rcsb_search_by_attribute` / `rcsb_search_combined` (usually with `return_type="mol_definition"`).
+The chemical catalog is generated from the live metadata schema by
+[`scripts/generate_chemical_attributes.py`](scripts/generate_chemical_attributes.py).
+
+**Paging.** Every search tool that returns hits accepts `limit` (1–100, default
+10) and `offset` (default 0). Each response reports `total_count`, `has_more`,
+and `next_offset`; to fetch the next page, call the tool again with the same
+query and `offset` set to the returned `next_offset`.
+
+### Data (data.rcsb.org/graphql)
+
+There is one tool per Data API GraphQL root field. Each takes a **list of IDs**
+(singular lookups = a one-element list) plus an optional `fields` argument to
+override the curated default selection with your own GraphQL sub-selection.
+Unknown IDs are reported under `not_found`.
+
+| Tool | Object | Example ID                       |
+|------|--------|----------------------------------|
+| `rcsb_get_entries` | PDB entries | `"4HHB"`                         |
+| `rcsb_get_entry_annotations` | Entry biological/functional annotations (GO, domains, disease, ...) | `"4HHB"`                         |
+| `rcsb_get_entry_exp_info` | Entry experimental conditions / determination metadata | `"4HHB"`                         |
+| `rcsb_get_polymer_entities` | Polymer entities (protein/NA) | `"4HHB_1"`                       |
+| `rcsb_get_nonpolymer_entities` | Ligand/cofactor entities | `"4HHB_3"`                       |
+| `rcsb_get_branched_entities` | Carbohydrate entities | `"5FMB_2"`                       |
+| `rcsb_get_polymer_entity_instances` | Polymer chains | `"4HHB.A"`                       |
+| `rcsb_get_nonpolymer_entity_instances` | Bound-ligand instances | `"4HHB.E"`                       |
+| `rcsb_get_branched_entity_instances` | Glycan chains | `"5FMB.C"`                       |
+| `rcsb_get_assemblies` | Biological assemblies | `"4HHB-1"`                       |
+| `rcsb_get_interfaces` | Assembly interfaces | `"1BMV-1.1"`                     |
+| `rcsb_get_chem_comps` | Chemical components / ligands | `"HEM"`, `"ATP"`                 |
+| `rcsb_get_entry_groups` | Entry groups | `"G_1002266"`                    |
+| `rcsb_get_polymer_entity_groups` | Polymer entity groups (seq. clusters) | `"85_70"`                        |
+| `rcsb_get_nonpolymer_entity_groups` | Non-polymer entity groups | `"ATP"`                          |
+| `rcsb_get_uniprot` | UniProt record (single) | `"P69905"`                       |
+| `rcsb_get_pubmed` | PubMed record (single, integer) | `6726807`                        |
+| `rcsb_get_group_provenance` | Grouping provenance (single) | `"provenance_sequence_identity"` |
+| `rcsb_data_graphql` | Escape hatch: run any GraphQL query against the Data API. | —                                |
+
+The Search API only returns identifiers, so the search tools optionally
+**enrich** entry hits with metadata. Enrichment and all Data API tools query
+the GraphQL endpoint, batching every requested ID into one request. All 18
+typed tools are generated from a single registry in
+[`queries.py`](src/rcsb_mcp/queries.py) (`DATA_OBJECTS`), so adding a field or
+endpoint is a one-line change.
+
+### Sequence Coordinates (sequence-coordinates.rcsb.org/graphql)
+
+Maps alignments and positional annotations between sequence reference systems
+(`UNIPROT`, `NCBI_PROTEIN`, `NCBI_GENOME`, `PDB_ENTITY`, `PDB_INSTANCE`). Each
+tool takes an optional `fields` argument to override the default selection; use
+`rcsb_describe_seqcoord_object` to discover what fields are available.
+
+This is the **only** RCSB API that cross-references **NCBI** (RefSeq protein /
+genome) — the Data API only knows UniProt. So "what NCBI proteins map to a PDB
+structure?" is answered by `rcsb_seqcoord_alignments`, not the Data API. PDB query
+ids must be **entity-level** (`4HHB_1`), not a bare entry (`4HHB`); for a whole
+entry, query each polymer entity.
+
+| Tool | What it does |
+|------|--------------|
+| `rcsb_seqcoord_alignments` | Cross-reference a sequence across PDB / UniProt / NCBI with aligned ranges (e.g. `4HHB_1` → NCBI proteins `NP_000508`, `NP_000549`). |
+| `rcsb_seqcoord_annotations` | Positional features for one sequence, from one or more annotation `sources` (`UNIPROT`, `PDB_ENTITY`, `PDB_INSTANCE`, `PDB_INTERFACE`). |
+| `rcsb_seqcoord_group_alignments` | Alignments among members of a sequence group (`MATCHING_UNIPROT_ACCESSION` / `SEQUENCE_IDENTITY`). |
+| `rcsb_seqcoord_group_annotations` | Annotations across a group; `summary=True` returns a positional summary. |
+| `rcsb_seqcoord_graphql` | Escape hatch: run any GraphQL query against the Sequence Coordinates API. |
+| `rcsb_describe_seqcoord_object` | Introspect the live schema to discover fields available on a seqcoord object (for use with `fields=`). |
+
+## Install
+
+```bash
+# run the published package without installing (recommended for clients)
+uvx rcsb-mcp
+# or install it
+pip install rcsb-mcp
+```
+
+`rcsb-mcp` is listed in the [Official MCP Registry](https://registry.modelcontextprotocol.io)
+as `io.github.rcsb/rcsb-mcp`, so registry-aware clients can discover it directly.
+
+For local development, install from the project root instead:
+
+```bash
+pip install -e .
+# or with uv
+uv pip install -e .
+```
+
+## Run / test
+
+```bash
+# unit tests (no network)
+hatch test          # or: python tests/test_queries.py
+
+# run the server over stdio
+python -m rcsb_mcp.server
+# or, after install:
+rcsb-mcp
+
+# inspect interactively
+npx @modelcontextprotocol/inspector python -m rcsb_mcp.server
+```
+
+There is also an end-to-end **evaluation suite** ([`evals/`](evals/)) — 10
+read-only, stable questions that measure how well an LLM can drive these tools to
+answer real PDB questions. See [`evals/README.md`](evals/README.md) to run it.
+
+## Connect to Claude Desktop
+
+Edit `claude_desktop_config.json`:
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "rcsb-mcp": {
+      "command": "uvx",
+      "args": ["rcsb-mcp"]
+    }
+  }
+}
+```
+
+For a local source checkout, point at the module instead:
+
+```json
+{
+  "mcpServers": {
+    "rcsb-mcp": {
+      "command": "python",
+      "args": ["-m", "rcsb_mcp.server"],
+      "cwd": "/absolute/path/to/rcsb-mcp/src"
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The tools appear under the connectors (plug) icon.
+
+## Example prompts
+
+- "Find high-resolution human hemoglobin structures." → `rcsb_search_by_attribute` + `rcsb_search_fulltext`
+- "Human hemoglobin structures better than 2 Å, best resolution first." → `rcsb_search_combined`
+- "What PDB entries match this protein sequence: MTEY..." → `rcsb_search_by_sequence`
+- "Find structures containing a ligand like this SMILES / with formula C8H9NO2." → `rcsb_search_by_chemical`
+- "Which structures have a 3D fold similar to 4HHB?" → `rcsb_search_by_structure`
+- "Find proteins with a zinc-finger motif." → `rcsb_search_by_seqmotif`
+- "Structures of proteins with kinase activity / involved in DNA repair / in the mitochondrial membrane." → `rcsb_find_go_terms` → `rcsb_search_by_attribute` on `rcsb_polymer_entity_annotation.annotation_lineage.id`
+- "Structures containing an SH2 domain / immunoglobulin fold." → `rcsb_find_interpro_domains` → `rcsb_search_by_attribute` on `rcsb_polymer_entity_annotation.annotation_id`
+- "Alcohol dehydrogenase structures / any EC 3.4.21 serine protease." → `rcsb_find_enzyme_classes` → `rcsb_search_by_attribute` on `rcsb_polymer_entity.rcsb_ec_lineage.id`
+- "Structures of proteins associated with cystic fibrosis / breast cancer." → `rcsb_find_disease_terms` → `rcsb_search_by_attribute` on `rcsb_uniprot_annotation.annotation_lineage.id`
+- "Structures from mammals / from a particular organism or clade." → `rcsb_find_organisms` → `rcsb_search_by_attribute` on `rcsb_entity_source_organism.taxonomy_lineage.id`
+- "Non-redundant human kinase structures (90% identity clusters)." → `rcsb_search_fulltext` / `rcsb_search_combined` with `group_by_identity=90`
+- "How many human X-ray structures are there?" → `rcsb_search_count`
+- "Break down ribosome structures by experimental method / by release year." → `rcsb_search_facets`
+- "Find structures with the same catalytic-site geometry as residues 162/193/219 of 2MNR." → `rcsb_search_strucmotif`
+- "Find chemical components under 150 Da." → `rcsb_list_pdb_search_attributes(schema="chemical")` + `rcsb_search_by_attribute` with `chemical=True`
+- "Summarize PDB entries 4HHB, 1MBN and 6VXX." → `rcsb_get_entries`
+- "What's the sequence and organism of entity 4HHB_1?" → `rcsb_get_polymer_entities`
+- "Tell me about the ligand HEM." → `rcsb_get_chem_comps`
+- "What's the composition of the 4HHB biological assembly?" → `rcsb_get_assemblies`
+- "Which PDB entries does P69905 map to?" → `rcsb_get_uniprot`
+- "Which PDB entities align to UniProt P69905, and over what ranges?" → `rcsb_seqcoord_alignments`
+- "What NCBI proteins map to 4HHB?" → `rcsb_seqcoord_alignments` per entity (`4HHB_1`, `4HHB_2`), `to_ref=NCBI_PROTEIN`
+- "Show UniProt features mapped onto PDB entity 4HHB_1." → `rcsb_seqcoord_annotations`
+- "Pull a field GraphQL doesn't expose by default / combine objects." → `rcsb_data_graphql`
+
+## Notes
+
+- Search endpoint: `https://search.rcsb.org/rcsbsearch/v2/query` (POST, JSON body).
+- Data endpoint: `https://data.rcsb.org/graphql` (POST, GraphQL). It returns
+  HTTP 200 even for query errors, reporting them in an `errors` array.
+- Sequence Coordinates endpoint: `https://sequence-coordinates.rcsb.org/graphql`
+  (POST, GraphQL; same HTTP-200-with-`errors` behavior).
+- The `rcsb_find_*` resolvers map free text to ontology ids via EBI services — the non-RCSB
+  dependencies: GO via QuickGO (`.../QuickGO/services/ontology/go/search`), InterPro
+  (`.../interpro/api/entry/interpro/`), EC via EBI Search/IntEnz (`.../ebisearch/ws/rest/intenz`),
+  and disease via OLS/MONDO (`.../ols4/api/search?ontology=mondo`). The resolved ids then drive
+  RCSB annotation searches (`rcsb_polymer_entity_annotation.*`, `rcsb_polymer_entity.rcsb_ec_lineage.id`,
+  `rcsb_uniprot_annotation.annotation_lineage.id`).
+- No API key required; the APIs are public. Be considerate with request volume.
+- A full list of searchable attributes for `rcsb_search_by_attribute` is in the
+  [Search API attribute reference](https://search.rcsb.org/structure-search-attributes.html);
+  the Data API schema is documented at
+  [data.rcsb.org/index.html#gql-api](https://data.rcsb.org/index.html#gql-api).
+
+## Instructions prompt
+
+Use [prompts/pdb-assistant.md](./prompts/pdb-assistant.md) as the instruction prompt for your project.