get_mesh_qualifiers
Retrieve allowable MeSH subheading qualifiers for a medical descriptor to refine subject headings in cataloging workflows.
Instructions
Retrieve the allowable subheading qualifiers for a MeSH descriptor.
MeSH qualifiers (subheadings) refine the topical focus of a heading — for example "Diabetes Mellitus/therapy" or "Neoplasms/diagnosis". Only qualifiers designated by NLM as allowable for the given descriptor are returned.
This is the MeSH equivalent of the maySubdivideGeographically check used in the cataloger MCP server for LCSH headings.
Note: The NLM public API does not expose qualifier abbreviations (e.g. /su for surgery). Use the full qualifier label when constructing headings in MARC: $a Diabetes Mellitus $x surgery.
Parameters
descriptor : str The MeSH UI code (e.g. "D003920") or full URI returned by search_mesh. include_annotations : bool If True, fetch each qualifier's .json record to include its indexing annotation. Makes up to 34 additional HTTP requests — use only when you need the annotation text for a specific qualifier. Default False.
Returns
dict Contains: - descriptor : The UI code queried - qualifierCount : Total number of allowable qualifiers - qualifiers : List of {label, ui, uri} dicts sorted alphabetically. If include_annotations=True, each dict also has an 'annotation' key.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| descriptor | Yes | ||
| include_annotations | No |
Implementation Reference
- src/mesh_mcp/server.py:269-337 (handler)The 'get_mesh_qualifiers' function retrieves allowable subheading qualifiers for a MeSH descriptor, processes the response from the NLM API, and optionally fetches annotations for each qualifier.
def get_mesh_qualifiers(descriptor: str, include_annotations: bool = False) -> dict: """ Retrieve the allowable subheading qualifiers for a MeSH descriptor. MeSH qualifiers (subheadings) refine the topical focus of a heading — for example "Diabetes Mellitus/therapy" or "Neoplasms/diagnosis". Only qualifiers designated by NLM as allowable for the given descriptor are returned. This is the MeSH equivalent of the maySubdivideGeographically check used in the cataloger MCP server for LCSH headings. Note: The NLM public API does not expose qualifier abbreviations (e.g. /su for surgery). Use the full qualifier label when constructing headings in MARC: $a Diabetes Mellitus $x surgery. Parameters ---------- descriptor : str The MeSH UI code (e.g. "D003920") or full URI returned by search_mesh. include_annotations : bool If True, fetch each qualifier's .json record to include its indexing annotation. Makes up to 34 additional HTTP requests — use only when you need the annotation text for a specific qualifier. Default False. Returns ------- dict Contains: - descriptor : The UI code queried - qualifierCount : Total number of allowable qualifiers - qualifiers : List of {label, ui, uri} dicts sorted alphabetically. If include_annotations=True, each dict also has an 'annotation' key. """ ui = _normalise_id(descriptor) result = _get(f"{_LOOKUP_BASE}/qualifiers", params={"descriptor": ui}) if "error" in result: return result raw = result["data"] if not isinstance(raw, list): return {"error": "Unexpected response format from NLM qualifiers endpoint", "data": raw} qualifiers = [] for item in raw: q_uri = item.get("resource", "") q_label = item.get("label", "") q_ui = _uri_to_id(q_uri) if q_uri else "" entry = {"label": q_label, "ui": q_ui, "uri": q_uri} if include_annotations and q_ui: ann_result = _get(f"{_BASE}/{q_ui}.json") if "data" in ann_result: ann_text = _text(ann_result["data"].get("annotation", "")) if ann_text: entry["annotation"] = ann_text qualifiers.append(entry) qualifiers.sort(key=lambda x: x["label"]) return { "descriptor": ui, "qualifierCount": len(qualifiers), "qualifiers": qualifiers, }