Validate draft MeSH headings against NLM’s authority

Stage three of skill-pipeline-subject-indexing for MeSH: look up every candidate heading of a draft (a preferred heading, an entry term, or a descriptor id, with an optional qualifier) in NLM’s MeSH authority at id.nlm.nih.gov, current year. Each candidate comes back resolved (in the preferred form), qualifier-not-allowed (descriptor kept, qualifier dropped), ambiguous (options listed for a person) or not-found (dropped). It never adds a heading the draft did not propose and never emits one the authority lacks.

Skills it satisfies

A skill states the capability; this Tool is one way to exercise it. Each skill’s declared input and output contract follows, where it has one.

mesh-subject-indexing

Assign Medical Subject Headings (MeSH) to a work as a DRAFT for a person to review, in the four stages of skill-pipeline-subject-indexing: over-generate concepts, filter them by NLM’s own rules, validate every heading against NLM’s MeSH authority with Tool mesh-authority, and write the reviewed list. Never emits a heading the authority does not hold.

Source: folio-assistant-core/skills/library/cataloguing/mesh-subject-indexing.md.

The skill declares no I/O contract (schemas/skills/mesh-subject-indexing/{input,output}.schema.json).

Inputs and outputs

Each port names a shared type by IRI, so two Tools for one skill can be checked for interchangeability.

porttyperequireddescriptionconstraint
indraftRepoPathyesA JSON file: { "candidates": [{ "label"?, "descriptor"?, "qualifier"?, "why"? }] }, in the order stage two ranked them.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
injsonFlagPrint the full report as JSON instead of the review table.boolean · A boolean switch — projects to a bare flag, with no value word
outreportTextA review table with one row per candidate, or with --json the report: results per candidate and validated, the headings a reviewer sees.string · A short single-line human string. Not admissible as a command-line argument.

Processes and tasks

No process step names a skill this Tool satisfies.

How it is deployed and reached

  • Command line. From the repository root: bun run folio-assistant-core/scripts/mesh-authority.ts validate.
  • GitHub Actions. No workflow in this checkout runs its command.

As an API: its operation in the OpenAPI document and the MCP tool list of its layer.

installnone
runtimebun
networkyes

When a host it reaches is refused:

host / errorremedy
id.nlm.nih.govnone: The authority is NLM’s. Without it no candidate can be validated, and the skill emits nothing rather than unvalidated headings.
when to choose it
whenA draft list of MeSH headings from stages one and two of mesh-subject-indexing is ready to be checked against the authority.
limitsChecks existence, preferred form and allowable qualifiers only. It does not judge whether a heading fits the work, and applies none of NLM’s rules on heading count or major topics.
costTwo or three HTTPS requests per candidate to id.nlm.nih.gov; about a second for a short draft.

What it is made of

Linked data

The Tool is published as its own JSON-LD document at its IRI, https://litlfred.github.io/folio-assistant/folio-assistant-core/tools/mesh-authority.jsonld, partOf its layer’s document. The node below is the definition this page was drawn from, and is embedded in the page as application/ld+json.

{
  "@context": "https://litlfred.github.io/folio-assistant/folio-assistant-core/folio-assistant-core.context.jsonld",
  "@id": "https://litlfred.github.io/folio-assistant/folio-assistant-core/tools/mesh-authority.jsonld",
  "@type": "https://litlfred.github.io/cat-harness/v0/ns/Tool",
  "partOf": "https://litlfred.github.io/folio-assistant/folio-assistant-core/folio-assistant-core.jsonld",
  "name": "mesh-authority",
  "title": "Validate draft MeSH headings against NLM's authority",
  "description": "Stage three of `skill-pipeline-subject-indexing` for MeSH: look up every candidate heading of a draft (a preferred heading, an entry term, or a descriptor id, with an optional qualifier) in NLM's MeSH authority at id.nlm.nih.gov, current year. Each candidate comes back `resolved` (in the preferred form), `qualifier-not-allowed` (descriptor kept, qualifier dropped), `ambiguous` (options listed for a person) or `not-found` (dropped). It never adds a heading the draft did not propose and never emits one the authority lacks.",
  "install": {
    "none": true
  },
  "invoke": {
    "shell": "bun run folio-assistant-core/scripts/mesh-authority.ts validate"
  },
  "io": {
    "inputs": [
      {
        "name": "draft",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "A JSON file: `{ \"candidates\": [{ \"label\"?, \"descriptor\"?, \"qualifier\"?, \"why\"? }] }`, in the order stage two ranked them.",
        "required": true,
        "arg": {
          "positional": 0
        }
      },
      {
        "name": "json",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Flag",
        "description": "Print the full report as JSON instead of the review table.",
        "required": false,
        "arg": {
          "flag": "--json"
        }
      }
    ],
    "outputs": [
      {
        "name": "report",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Text",
        "description": "A review table with one row per candidate, or with `--json` the report: `results` per candidate and `validated`, the headings a reviewer sees."
      }
    ]
  },
  "satisfies": [
    "mesh-subject-indexing"
  ],
  "requirements": {
    "runtime": [
      "bun"
    ],
    "network": true
  },
  "remedies": [
    {
      "host": "id.nlm.nih.gov",
      "none": "The authority is NLM's. Without it no candidate can be validated, and the skill emits nothing rather than unvalidated headings."
    }
  ],
  "selection": {
    "when": "A draft list of MeSH headings from stages one and two of `mesh-subject-indexing` is ready to be checked against the authority.",
    "limits": "Checks existence, preferred form and allowable qualifiers only. It does not judge whether a heading fits the work, and applies none of NLM's rules on heading count or major topics.",
    "cost": "Two or three HTTPS requests per candidate to id.nlm.nih.gov; about a second for a short draft."
  }
}

folio-assistant — code under the Apache License 2.0, documentation under CC BY 3.0. Generated schema and API references are rebuilt from source on every push to main.

deployed dev