protein-mcp-server: search structures
protein_search_structuresSearch experimental (PDB) and predicted (computed-model) protein structures by free text, protein sequence (triggers an mmseqs2 similarity search), and/or organism, method, resolution, and bound-ligand filters. Returns ranked hits; the experimental page is enriched with title, method, resolution, and source organisms (for a sequence hit, those of the matched entity), and every sequence hit carries its identity, E-value, bit score, and aligned range against the query. Chain hit IDs into protein_get_structure. Optionally returns a facet breakdown (counts by method / organism / release year / …) alongside the hits in the same response. Facets count the filtered result set, so an active organism or method filter also constrains its own facet: the facet lists only the values found in the matching entries (other organisms in the same complexes, other methods deposited with the same entries), never the alternatives the filter excluded. Numeric histogram buckets (resolution, molecular weight) carry explicit rangeFrom/rangeTo bounds so a boundary label is unambiguous.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "protein_search_structures"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum hits to return (1–100). | |
| query | No | Free-text query (protein name, gene, keyword, PDB title terms). | |
| start | No | Zero-based result offset. Combine with limit to retrieve later pages. | |
| facets | No | Optional dimensions to summarize as a facet breakdown alongside the hits. Each dimension at most once; repeating one is rejected. | |
| ligand | No | Filter by bound ligand: an exact chemical component ID (e.g. "STI" for imatinib, "HEM"), in any letter case. Keeps structures holding the component as a bound (non-polymer) copy, not as a residue inside a polymer chain. Resolve a ligand name to its ID with protein_track_ligands mode "find_ligand". Computed models carry no ligands, so under content_type "predicted" this filter matches nothing. | |
| method | No | Filter by experimental method: X-RAY DIFFRACTION, ELECTRON MICROSCOPY, SOLUTION NMR, SOLID-STATE NMR, ELECTRON CRYSTALLOGRAPHY, NEUTRON DIFFRACTION, FIBER DIFFRACTION, POWDER DIFFRACTION, SOLUTION SCATTERING, EPR, FLUORESCENCE TRANSFER, INFRARED SPECTROSCOPY, THEORETICAL MODEL (any letter case), or an alias: cryo-EM / cryoEM / EM → ELECTRON MICROSCOPY; X-ray / xray → X-RAY DIFFRACTION; NMR → SOLUTION NMR + SOLID-STATE NMR. Any other value is rejected. Computed models carry no method, so under content_type "predicted" this filter matches nothing. | |
| organism | No | Filter by source organism: a scientific name ("Homo sapiens"), an NCBI common name ("human", "E. coli"), or an NCBI taxon ID ("9606"), in any letter case. Matches that taxon and every taxon under it (strains, subspecies); a multi-word name also matches scientific names that contain it, such as "Escherichia coli (strain K12)". A word fragment ("coli") matches nothing. | |
| sequence | No | Protein sequence for RCSB mmseqs2: at least 10 residues in A–I or K–Z (J excluded; B/O/U/X/Z accepted). Whitespace is removed and ASCII lowercase normalized. | |
| max_evalue | No | Maximum E-value for a sequence search. Requires sequence — supplying it without one is rejected, since the threshold filters only a sequence search. Default 1. | |
| content_type | No | Which structure universe to search: experimental (PDB), predicted (computed models), or all. With a sequence, all searches each universe on its own and merges the hits by bit score. | all |
| min_identity | No | Minimum sequence identity (0–1) for a sequence search. Requires sequence — supplying it without one is rejected, since the threshold filters only a sequence search. Default 0. | |
| max_resolution | No | Maximum resolution in Å (lower is sharper); applies to experimental structures. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| hits | No | Ranked structure hits. | |
| error | No | Present when the call failed. Absent on success. | |
| start | No | Zero-based offset of the returned page. | |
| facets | No | Optional facet breakdown when requested — one flat dimension per requested facet. Cross-tabs (a dimension nested inside another) are protein_analyze_collection territory. | |
| notice | No | Advisory note (empty results, predicted-search caveats, truncation, facet dimensions whose buckets cover materially less than totalCount, a universe a sequence search left out because its search failed, a sequence search at RCSB's 2,000-hit ceiling). Carries every applicable advisory in one string. | |
| nextStart | No | Offset for the next page; absent on the final or past-end page. | |
| totalCount | No | Total matches upstream before pagination. | |
| queryLength | No | Length in residues of the query sequence that every hit's queryStart and queryEnd index into (sequence searches whose hits carry an alignment). | |
| effectiveQuery | No | Echoed text query for follow-up calls. |