MeSH MCP

Instructions

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,
      }