protein-mcp-server: analyze collection
protein_analyze_collectionProfile the PDB into distributions and trends over an optional scoping query: counts by method, organism, or polymer composition; resolution and molecular-weight histograms; release-year timelines; and multidimensional cross-tabs (e.g. method × release_year). Aggregation runs at RCSB, so the response carries compact counts per bucket rather than the matching entries. Pass one group_by dimension for a single breakdown, or two distinct dimensions for a cross-tab (the first nests the second). bucket_limit caps each dimension level separately rather than the response, so a cross-tab returns up to that many nested buckets under each of its capped parent buckets; bucketsReturned reports the realized total.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"group_by": "<group_by>"
},
"name": "protein_analyze_collection"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Optional free-text scope (e.g. "kinase"); omit to profile the whole PDB. | |
| method | No | Optional experimental-method scope: 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. | |
| group_by | Yes | 1 dimension for a breakdown, or 2 distinct dimensions for a cross-tab (the first nests the second). Repeating a dimension is rejected. | |
| interval | No | Bin width for a histogram dimension (a number, for resolution or molecular_weight) or period for a date histogram ("year", for release_year). Applies to whichever requested group_by dimension can consume that value type — primary or nested child — so a cross-tab like ["method","resolution"] bins its nested resolution child. When both requested dimensions can consume it the primary takes it and the child keeps its default. When neither can, the call is rejected rather than silently ignoring the override. | |
| organism | No | Optional source-organism scope: a scientific name ("Homo sapiens"), an NCBI common name ("human"), or an NCBI taxon ID ("9606"), in any letter case. Matches that taxon and every taxon under it; a multi-word name also matches scientific names that contain it. A word fragment ("coli") matches nothing. | |
| bucket_limit | No | Max buckets per dimension level, not per response. A cross-tab applies the cap separately to the parent dimension and to the nested child inside each parent bucket, so up to bucket_limit × (1 + bucket_limit) buckets can come back — 2550 at the default 50. The realized count comes back as bucketsReturned. Defaults to the configured server cap. | |
| content_type | No | Which structure universe to profile. Default experimental. Computed models carry no experimental metadata, so method and resolution return nothing under "predicted". | experimental |
| max_resolution | No | Optional maximum-resolution scope (Å). |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | Present when the call failed. Absent on success. | |
| scope | No | Echoed scope description for follow-up calls. | |
| total | No | Total entries in the scoped collection. | |
| facets | No | The requested breakdown(s). | |
| notice | No | Advisory note (per-position bucket truncation, a scope that matched nothing, dimensions with no data under the requested content_type, dimensions whose buckets cover materially less than the total). Carries every applicable advisory in one string. | |
| truncated | No | True when at least one dimension position — the top-level dimension or a nested cross-tab child — had more buckets than the applied cap. Which positions, and by how much, is named in notice. | |
| bucketsReturned | No | Buckets in this response, summed over every dimension level: the top-level buckets plus, for a cross-tab, the nested child buckets under each of them. Since bucket_limit caps each level separately, this is the size those caps actually produced — always present, cross-tab or not. |