protein-mcp-server: track ligands
protein_track_ligandsLigand discovery and binding-site analysis across the PDB. mode "find_ligand" resolves a name or formula to chemical component IDs with metadata (formula, weight, SMILES), ranked by deposition frequency — most-deposited component first, so the top hit is the most common match for the name, not necessarily an exact name-string match. The ranking runs in blocks of max(limit, 25) candidates in RCSB's name-match order: start pages through the ranked blocks (keep limit fixed while paging), and totalCount and candidatesConsidered report how many components matched and how many the page ranked. mode "structures_with_ligand" returns PDB entries holding a bound copy of a ligand (by exact component ID — get the ID from find_ligand first), highest-resolution first, each with its resolution in Å, title, method, and the polymer entities whose chains carry the ligand. This mode and find_ligand's depositionCount count bound copies only: a component present only as a residue inside a polymer chain (e.g. MSE in a selenomethionine protein) or a sugar inside a branched glycan is not counted. mode "binding_site" returns the polymer residues lining a ligand's pocket in a given structure — amino acids, or nucleotides where the ligand binds DNA or RNA — with contact distances, each numbered in both the mmCIF label namespace (asymId, seqId) and the author namespace (authAsymId, authSeqId) used by deposited coordinates and most literature. Binding sites are experimental-only (computed from deposited coordinates; predicted models carry no bound ligands) and cover non-polymer ligands only: a peptide-like ligand deposited as a polymer chain (a BIRD molecule such as cyclosporin A in 1CWA) has none, and a miss names the components and polymer-chain ligands the entry does hold.
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": {
"mode": "<mode>"
},
"name": "protein_track_ligands"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | Yes | Operation: resolve a ligand, find structures containing it, or analyze its binding site. | |
| limit | No | Maximum results to return (1–100). | |
| query | No | Ligand name or formula (mode find_ligand). | |
| start | No | Zero-based result offset: find_ligand pages its ranked candidates, structures_with_ligand its entries, binding_site its ligand instances. | |
| pdb_id | No | PDB entry ID (mode binding_site). | |
| comp_id | No | Exact chemical component ID (modes structures_with_ligand and binding_site). |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Echoed mode. | |
| error | No | Present when the call failed. Absent on success. | |
| start | No | Zero-based offset of the result page. | |
| notice | No | Advisory note: a find_ligand page whose ranked blocks hold fewer candidates than the upstream match count, or whose start is past the end; a structures_with_ligand page that is empty because no entry holds a bound copy of the component (saying whether the ID is a chemical component at all) or because start is past the end; or a binding_site page that leaves instances for a later start or starts past the last instance. | |
| ligands | No | Resolved chemical components (find_ligand). | |
| nextStart | No | Offset for the next page; absent on the final or past-end page. | |
| structures | No | PDB entries holding a bound (non-polymer) copy of the ligand, highest-resolution first (structures_with_ligand). | |
| totalCount | No | Total upstream matches before any local narrowing: PDB entries holding a bound (non-polymer) copy of the component (structures_with_ligand), chemical components matching the query (find_ligand), or ligand instances with pocket contacts (binding_site). | |
| bindingSites | No | Ligand instances and their pocket residues (binding_site), in a fixed order — ligands by entity number, then the instances of each ligand by author chain and author residue number — so start/limit pages read every instance exactly once. | |
| resolvedCompId | No | The chemical component ID used to query. | |
| candidatesConsidered | No | Chemical components the find_ligand page ranked by deposition frequency: the one or two blocks of max(limit, 25) name matches holding the page. Below totalCount when the matches run past those blocks; the ranking then covers only these candidates. |