@cyanheads/pubmed-mcp-server 2.10.21 → 2.10.22

package/AGENTS.md

@@ -1,8 +1,8 @@
 # Agent Protocol
 
 **Server:** @cyanheads/pubmed-mcp-server
-**Version:** 2.10.21
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.14`
+**Version:** 2.10.22
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.15`
 **Engines:** Bun ≥1.4.0, Node ≥24.0.0
 
 > **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.

package/CLAUDE.md

@@ -1,8 +1,8 @@
 # Agent Protocol
 
 **Server:** @cyanheads/pubmed-mcp-server
-**Version:** 2.10.21
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.14`
+**Version:** 2.10.22
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.15`
 **Engines:** Bun ≥1.4.0, Node ≥24.0.0
 
 > **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.

package/Dockerfile

@@ -10,7 +10,7 @@
 # the deps stage cross-installs the runtime dependencies per target. Emulating
 # this stage aborts `tsc` on a source tree this size.
 # ==============================================================================
-FROM --platform=$BUILDPLATFORM oven/bun:1.4.2 AS build
+FROM --platform=$BUILDPLATFORM oven/bun:1.4.3 AS build
 
 WORKDIR /usr/src/app
 
@@ -44,7 +44,7 @@ RUN bun run build
 # A clean image rather than `FROM build`: the build stage's node_modules holds
 # devDependencies.
 # ==============================================================================
-FROM --platform=$BUILDPLATFORM oven/bun:1.4.2 AS deps
+FROM --platform=$BUILDPLATFORM oven/bun:1.4.3 AS deps
 
 WORKDIR /usr/src/app
 
@@ -111,7 +111,7 @@ RUN rm -rf node_modules/@socketsecurity/bun-security-scanner
 # dependencies and build artifacts. Its only Bun invocations are HEALTHCHECK
 # and CMD, which run on the real target at container start.
 # ==============================================================================
-FROM oven/bun:1.4.2-slim AS production
+FROM oven/bun:1.4.3-slim AS production
 
 WORKDIR /usr/src/app
 

package/README.md

@@ -7,7 +7,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-2.10.21-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/pubmed-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.2.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/pubmed-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/pubmed-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.2-blueviolet.svg?style=flat-square)](https://bun.sh/)
+[![Version](https://img.shields.io/badge/Version-2.10.22-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/pubmed-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.3.1-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/pubmed-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/pubmed-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.3-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
 </div>
 
@@ -39,7 +39,7 @@ Biomedical literature from PubMed, PubMed Central, and Europe PMC. Search it, fe
 | `pubmed_fetch_articles` | Fetch article metadata by PMID: abstract, authors, journal, MeSH terms, grants, a collective author's investigators on request, linked retraction and correction notices |
 | `pubmed_fetch_fulltext` | Fetch full text by PMID, PMCID, or DOI, falling back from PMC to Europe PMC to Unpaywall |
 | `pubmed_europepmc_search` | Search Europe PMC for preprints, patents, Agricola, and open-access records PubMed doesn't carry |
-| `pubmed_europepmc_fetch` | Fetch complete Europe PMC records, including the untruncated abstract, by `source` + `epmcId` |
+| `pubmed_europepmc_fetch` | Fetch complete Europe PMC records, including the untruncated abstract, as `records: [{ source, epmcId }]` |
 | `pubmed_format_citations` | Format citations in APA 7th, MLA 9th, BibTeX, RIS, or Vancouver (ICMJE/NLM), with linked retraction and correction notices |
 | `pubmed_find_related` | Find similar articles, citing articles, or references for a PMID |
 | `pubmed_spell_check` | Correct a misspelled PubMed query via NCBI ESpell |
@@ -74,6 +74,7 @@ Biomedical literature from PubMed, PubMed Central, and Europe PMC. Search it, fe
 
 - Up to 200 PMIDs per call; misses are listed in `unavailablePmids`
 - Abstract, authors, journal, DOI, publication types, linked retraction/erratum/comment notices, and links; MeSH terms on by default, grants via `includeGrants`, and the members of a collective author (its `InvestigatorList`, thousands on some consortium trials) via `includeInvestigators`
+- A retracted, corrected, or questioned article opens with the same notice block as `pubmed_format_citations`, directly under its title
 - `recordType` separates journal articles from Bookshelf chapters and books; opt-in `maxResponseCharacters` defers overflow to `deferred.ids`
 
 ---
@@ -90,13 +91,14 @@ Biomedical literature from PubMed, PubMed Central, and Europe PMC. Search it, fe
 
 - Adds preprints (`PPR`), patents (`PAT`), and Agricola (`AGR`) to `MED` and `PMC`; defaults to `MED`, `PMC`, `PPR`
 - Cursor pagination via `cursorMark` / `nextCursorMark`, up to 100 per page; abstracts arrive as 400-character snippets
+- Optional `sort` of comma-separated `<field> asc|desc` keys; `relevance` is the default order, and a sort Europe PMC cannot use fails as `europepmc_invalid_input`
 - Not registered when `EUROPEPMC_ENABLED=false`
 
 ---
 
 ### `pubmed_europepmc_fetch` <sub>tool</sub>
 
-- Up to 25 records per call, addressed by a search hit's `source` + `epmcId`, with the full abstract; unresolved ids land in `notFound`; opt-in `maxResponseCharacters` defers overflow to `deferred.records`
+- Up to 25 records per call as `records: [{ source, epmcId }]`, each pair copied from a search hit, with the full abstract; unresolved ids land in `notFound`; opt-in `maxResponseCharacters` defers overflow to `deferred.records`
 - Not registered when `EUROPEPMC_ENABLED=false`
 
 ---
@@ -118,15 +120,15 @@ Biomedical literature from PubMed, PubMed Central, and Europe PMC. Search it, fe
 
 ### `pubmed_spell_check` <sub>tool</sub>
 
-- Returns `original`, `corrected`, and `hasSuggestion`, fixing every misspelled token in one call
+- Returns `original`, `corrected`, and `hasSuggestion`; corrections land in place, so field tags, operators, spacing, and gene symbols stay as written
 - Run it after a zero-hit or thin search, then retry `pubmed_search_articles` with `corrected`
 
 ---
 
 ### `pubmed_lookup_mesh` <sub>tool</sub>
 
-- Descriptors by name or free-text term, with an exact heading match pinned first; up to 50 per page, continued via `nextOffset`
-- Records carry `meshId`; `includeDetails` (default on) adds tree numbers, scope notes, and entry terms
+- Descriptors by name or free-text term, with an exact heading match pinned first (the descriptor, for a drug-class heading); up to 50 per page, continued via `nextOffset`
+- Records carry their MeSH unique ID (`meshId`, e.g. `D000072657`) beside the Entrez UID; `includeDetails` (default on) adds tree numbers, scope notes, and entry terms
 
 ---
 

package/changelog/2.10.x/2.10.22.md

@@ -0,0 +1,44 @@
+---
+summary: "Author name suffixes carry through records, citations, and full text; citation formatting, full-text cleanup, in-place spell-check corrections, and Europe PMC sort errors are fixed."
+breaking: false
+security: false
+---
+
+# 2.10.22 — 2026-10-12
+
+## Added
+
+- **Author `suffix`** ([#226](https://github.com/cyanheads/pubmed-mcp-server/issues/226)) — `pubmed_fetch_articles` authors, investigators, and book editors, and `pubmed_fetch_fulltext` authors carry the generational suffix verbatim (`Jr`, `2nd`, `IV`). Every citation style prints it, and full-text references keep it.
+- **`pubmed_fetch_articles` notice block** ([#237](https://github.com/cyanheads/pubmed-mcp-server/issues/237)) — a retracted, corrected, or questioned article opens with the same notice lines as `pubmed_format_citations`, directly under its title.
+- **Europe PMC lower-case source codes** ([#244](https://github.com/cyanheads/pubmed-mcp-server/issues/244)) — `pubmed_europepmc_fetch` `records[].source` and `pubmed_europepmc_search` `sources` accept lower-case codes (`med`, `pmc`). Search hint text, tool descriptions, and server instructions name the `records: [{ source, epmcId }]` input shape.
+
+## Changed
+
+- **`pubmed_spell_check` corrects in place** ([#241](https://github.com/cyanheads/pubmed-mcp-server/issues/241)) — `corrected` applies ESpell's replacements to the caller's query, keeping field tags, operators, spacing, and words in capitals or with digits (gene symbols) as written. `hasSuggestion` is true only when one was applied; otherwise the text reads `No correction applied — query "…" is returned as written.`
+- **`pubmed_lookup_mesh` IDs** ([#238](https://github.com/cyanheads/pubmed-mcp-server/issues/238)) — `meshId` is the MeSH unique ID from eSummary 2.0 (`D…`, `C…`, `Q…`), including records the Entrez UID does not encode. It is omitted when eSummary returns no record for the UID.
+- **`pubmed_lookup_mesh` pinning** ([#247](https://github.com/cyanheads/pubmed-mcp-server/issues/247)) — an exact heading that matches a pharmacological-action record pins its descriptor instead; `treeNumbers` leaves out the record's own UI.
+- **Deferral notices** ([#236](https://github.com/cyanheads/pubmed-mcp-server/issues/236)) — `pubmed_fetch_articles`, `pubmed_fetch_fulltext`, and `pubmed_europepmc_fetch` share one notice naming the ceiling for re-calling the deferred items and the one for repeating the call. `nextDeferredCharacters` is described as the continuation ceiling.
+- **`pubmed_fetch_fulltext` ordering** ([#235](https://github.com/cyanheads/pubmed-mcp-server/issues/235)) — `articles`, `truncation.articles`, and the section-filter notice follow routing order (`pmcids`, then `pmids`, then `dois`, request order within each), so a `maxResponseCharacters` cut is the same on every call.
+- **Europe PMC `sort`** ([#239](https://github.com/cyanheads/pubmed-mcp-server/issues/239)) — `relevance` and a whitespace-only sort are sent as no sort, `FIRST_IDATE_D` joins the documented fields, and a sort without a field plus `asc`/`desc` per key fails as `europepmc_invalid_input` before any request. A second HTTP 503 to a sorted search that the unsorted query survives names the sort.
+- **Framework 0.13.15 adoption** — `framework-skills/` sync.
+
+## Fixed
+
+- **Citation journal names** ([#227](https://github.com/cyanheads/pubmed-mcp-server/issues/227)) — APA and MLA drop NLM's place, year, and edition qualifier (`Lancet (London, England)` → `Lancet`) and keep an edition the ISO abbreviation also names.
+- **Citation page ranges** ([#228](https://github.com/cyanheads/pubmed-mcp-server/issues/228)) — BibTeX `pages` writes each range in full, and RIS `SP`/`EP` take the first and last page of a list (`1308, 1310-4` → `1308`/`1314`).
+- **Article numbers** ([#231](https://github.com/cyanheads/pubmed-mcp-server/issues/231)) — a dashless page that equals the locator with its hyphens removed (`e0364621` beside `e03646-21`) cites as the locator.
+- **Citation whitespace** ([#233](https://github.com/cyanheads/pubmed-mcp-server/issues/233)) — line breaks inside titles, names, keywords, and abstracts collapse to one space in every style, so RIS stays one tagged line per value. `pubmed_format_citations` escapes Markdown in the title line.
+- **Literal `None` page** ([#248](https://github.com/cyanheads/pubmed-mcp-server/issues/248)) — NCBI's `None` placeholder is no longer read as a page.
+- **Invisible characters** ([#224](https://github.com/cyanheads/pubmed-mcp-server/issues/224)) — U+FEFF, U+00AD, and U+200B are dropped from NCBI XML responses and Europe PMC full-text XML before parsing, ending split words in full text (`hepatopulmonary s yndrome`).
+- **Space before punctuation** ([#225](https://github.com/cyanheads/pubmed-mcp-server/issues/225)) — a line break between a formula or other element and the closing punctuation after it no longer leaves a space (`L<0 .` → `L<0.`).
+- **MathML `<semantics>`** ([#230](https://github.com/cyanheads/pubmed-mcp-server/issues/230)) — reads one rendering of the expression, never the TeX, MathType, or Content annotations beside it.
+- **Body footnotes** ([#229](https://github.com/cyanheads/pubmed-mcp-server/issues/229)) — a `<fn>` or `<fn-group>` in a body section reads one paragraph per footnote, as it does in back matter.
+- **Table and asset labels** ([#240](https://github.com/cyanheads/pubmed-mcp-server/issues/240)) — one trailing `.`, `|`, or `:` is dropped (`Table 1.` → `Table 1`), and a bare-number label is named with its type in `omittedAssetNames` and asset headings (`Supplementary material 1`).
+- **Rendered dates** ([#242](https://github.com/cyanheads/pubmed-mcp-server/issues/242)) — a one-digit numeric month or day is zero-padded in the rendered date; the structured parts stay as deposited.
+
+## Dependencies
+
+- `@cyanheads/mcp-ts-core` ^0.13.14 → ^0.13.15
+- `@types/node` ^26.6.4 → ^26.6.5
+- `@hono/node-server` override ^2.0.11 → ^2.1.4
+- Bun 1.4.2 → 1.4.3 (`Dockerfile`, `packageManager`)

package/dist/index.js

@@ -42,7 +42,7 @@ await createApp({
     tools,
     resources: [databaseInfoResource],
     prompts: [researchPlanPrompt],
-    instructions: "Use the pubmed_* tools to search PubMed and PubMed Central, fetch article metadata and full text, format citations, and find related articles via NCBI's E-utilities. Articles are keyed by PMID (integer); PMC full text by PMCID (`PMC` prefix); most also carry a DOI. Typical flow: `pubmed_search_articles` → `pubmed_fetch_articles` → `pubmed_fetch_fulltext`. When PubMed itself comes up empty (preprints, EPMC-only OA), broaden via `pubmed_europepmc_search`, then `pubmed_europepmc_fetch` with a hit's `source` + `epmcId` for its complete abstract. Prefer deterministic resolvers when inputs are structured: `pubmed_lookup_citation` for partial references, `pubmed_convert_ids` to crosswalk IDs. Refine queries with `pubmed_lookup_mesh` and `pubmed_spell_check`.",
+    instructions: "Use the pubmed_* tools to search PubMed and PubMed Central, fetch article metadata and full text, format citations, and find related articles via NCBI's E-utilities. Articles are keyed by PMID (integer); PMC full text by PMCID (`PMC` prefix); most also carry a DOI. Typical flow: `pubmed_search_articles` → `pubmed_fetch_articles` → `pubmed_fetch_fulltext`. When PubMed itself comes up empty (preprints, EPMC-only OA), broaden via `pubmed_europepmc_search`, then `pubmed_europepmc_fetch` with `records: [{ source, epmcId }]` copied from a hit for its complete abstract. Prefer deterministic resolvers when inputs are structured: `pubmed_lookup_citation` for partial references, `pubmed_convert_ids` to crosswalk IDs. Refine queries with `pubmed_lookup_mesh` and `pubmed_spell_check`.",
     landing: {
         requireAuth: false,
         tagline: 'Search PubMed, fetch articles, generate citations, explore MeSH terms, and discover related research.',

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,0DAA0D,CAAC;AAC9F,OAAO,EAAE,oBAAoB,EAAE,MAAM,8DAA8D,CAAC;AACpG,OAAO,EAAE,cAAc,EAAE,MAAM,oDAAoD,CAAC;AACpF,OAAO,EAAE,iBAAiB,EAAE,MAAM,uDAAuD,CAAC;AAC1F,OAAO,EAAE,iBAAiB,EAAE,MAAM,uDAAuD,CAAC;AAC1F,OAAO,EAAE,eAAe,EAAE,MAAM,qDAAqD,CAAC;AACtF,OAAO,EAAE,mBAAmB,EAAE,MAAM,yDAAyD,CAAC;AAC9F,OAAO,EAAE,kBAAkB,EAAE,MAAM,wDAAwD,CAAC;AAC5F,OAAO,EAAE,cAAc,EAAE,MAAM,oDAAoD,CAAC;AACpF,OAAO,EAAE,wBAAwB,EAAE,MAAM,+DAA+D,CAAC;AACzG,OAAO,EAAE,yBAAyB,EAAE,MAAM,gEAAgE,CAAC;AAC3G,OAAO,EAAE,kBAAkB,EAAE,MAAM,wDAAwD,CAAC;AAC5F,OAAO,EAAE,cAAc,EAAE,MAAM,oDAAoD,CAAC;AACpF,OAAO,EAAE,oBAAoB,EAAE,MAAM,6CAA6C,CAAC;AACnF,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,OAAO,EAAE,mBAAmB,EAAE,MAAM,yCAAyC,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAEjF,MAAM,MAAM,GAAG,eAAe,EAAE,CAAC;AACjC,MAAM,KAAK,GAAG;IACZ,kBAAkB;IAClB,iBAAiB;IACjB,iBAAiB;IACjB,mBAAmB;IACnB,eAAe;IACf,cAAc;IACd,cAAc;IACd,kBAAkB;IAClB,cAAc;IACd,GAAG,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,yBAAyB,EAAE,wBAAwB,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;CAC1F,CAAC;AAEF,MAAM,SAAS,CAAC;IACd,IAAI,EAAE,mBAAmB;IACzB,KAAK,EAAE,mBAAmB;IAC1B,WAAW,EAAE,WAAW;IACxB,KAAK;IACL,SAAS,EAAE,CAAC,oBAAoB,CAAC;IACjC,OAAO,EAAE,CAAC,kBAAkB,CAAC;IAC7B,YAAY,EACV,2vBAA2vB;IAC7vB,OAAO,EAAE;QACP,WAAW,EAAE,KAAK;QAClB,OAAO,EACL,uGAAuG;QACzG,QAAQ,EAAE,gDAAgD;QAC1D,KAAK,EAAE;YACL,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,kCAAkC,EAAE,QAAQ,EAAE,IAAI,EAAE;YAC7E;gBACE,KAAK,EAAE,kBAAkB;gBACzB,IAAI,EAAE,8CAA8C;gBACpD,QAAQ,EAAE,IAAI;aACf;YACD;gBACE,KAAK,EAAE,qBAAqB;gBAC5B,IAAI,EAAE,gDAAgD;gBACtD,QAAQ,EAAE,IAAI;aACf;YACD,EAAE,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,4BAA4B,EAAE,QAAQ,EAAE,IAAI,EAAE;SAC9E;QACD,UAAU,EAAE;YACV,YAAY,EAAE,mBAAmB;YACjC,gBAAgB,EAAE,iBAAiB;YACnC,eAAe,EAAE,iBAAiB;SACnC;KACF;IACD,KAAK;QACH,eAAe,EAAE,CAAC;QAClB,oBAAoB,EAAE,CAAC;QACvB,oBAAoB,EAAE,CAAC;QACvB,mBAAmB,EAAE,CAAC;IACxB,CAAC;CACF,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,0DAA0D,CAAC;AAC9F,OAAO,EAAE,oBAAoB,EAAE,MAAM,8DAA8D,CAAC;AACpG,OAAO,EAAE,cAAc,EAAE,MAAM,oDAAoD,CAAC;AACpF,OAAO,EAAE,iBAAiB,EAAE,MAAM,uDAAuD,CAAC;AAC1F,OAAO,EAAE,iBAAiB,EAAE,MAAM,uDAAuD,CAAC;AAC1F,OAAO,EAAE,eAAe,EAAE,MAAM,qDAAqD,CAAC;AACtF,OAAO,EAAE,mBAAmB,EAAE,MAAM,yDAAyD,CAAC;AAC9F,OAAO,EAAE,kBAAkB,EAAE,MAAM,wDAAwD,CAAC;AAC5F,OAAO,EAAE,cAAc,EAAE,MAAM,oDAAoD,CAAC;AACpF,OAAO,EAAE,wBAAwB,EAAE,MAAM,+DAA+D,CAAC;AACzG,OAAO,EAAE,yBAAyB,EAAE,MAAM,gEAAgE,CAAC;AAC3G,OAAO,EAAE,kBAAkB,EAAE,MAAM,wDAAwD,CAAC;AAC5F,OAAO,EAAE,cAAc,EAAE,MAAM,oDAAoD,CAAC;AACpF,OAAO,EAAE,oBAAoB,EAAE,MAAM,6CAA6C,CAAC;AACnF,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,OAAO,EAAE,mBAAmB,EAAE,MAAM,yCAAyC,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAEjF,MAAM,MAAM,GAAG,eAAe,EAAE,CAAC;AACjC,MAAM,KAAK,GAAG;IACZ,kBAAkB;IAClB,iBAAiB;IACjB,iBAAiB;IACjB,mBAAmB;IACnB,eAAe;IACf,cAAc;IACd,cAAc;IACd,kBAAkB;IAClB,cAAc;IACd,GAAG,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,yBAAyB,EAAE,wBAAwB,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;CAC1F,CAAC;AAEF,MAAM,SAAS,CAAC;IACd,IAAI,EAAE,mBAAmB;IACzB,KAAK,EAAE,mBAAmB;IAC1B,WAAW,EAAE,WAAW;IACxB,KAAK;IACL,SAAS,EAAE,CAAC,oBAAoB,CAAC;IACjC,OAAO,EAAE,CAAC,kBAAkB,CAAC;IAC7B,YAAY,EACV,ixBAAixB;IACnxB,OAAO,EAAE;QACP,WAAW,EAAE,KAAK;QAClB,OAAO,EACL,uGAAuG;QACzG,QAAQ,EAAE,gDAAgD;QAC1D,KAAK,EAAE;YACL,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,kCAAkC,EAAE,QAAQ,EAAE,IAAI,EAAE;YAC7E;gBACE,KAAK,EAAE,kBAAkB;gBACzB,IAAI,EAAE,8CAA8C;gBACpD,QAAQ,EAAE,IAAI;aACf;YACD;gBACE,KAAK,EAAE,qBAAqB;gBAC5B,IAAI,EAAE,gDAAgD;gBACtD,QAAQ,EAAE,IAAI;aACf;YACD,EAAE,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,4BAA4B,EAAE,QAAQ,EAAE,IAAI,EAAE;SAC9E;QACD,UAAU,EAAE;YACV,YAAY,EAAE,mBAAmB;YACjC,gBAAgB,EAAE,iBAAiB;YACnC,eAAe,EAAE,iBAAiB;SACnC;KACF;IACD,KAAK;QACH,eAAe,EAAE,CAAC;QAClB,oBAAoB,EAAE,CAAC;QACvB,oBAAoB,EAAE,CAAC;QACvB,mBAAmB,EAAE,CAAC;IACxB,CAAC;CACF,CAAC,CAAC"}

package/dist/mcp-server/tools/definitions/_budget.d.ts

@@ -1,8 +1,9 @@
 /**
  * @fileoverview Whole-response character budgeting shared by the retrieval
- * tools: how many whole items fit under a character ceiling, in order. The
- * sibling of `_text.ts`, which shortens the *inside* of one item's text —
- * nothing here ever cuts into an item. (#99, #100)
+ * tools: how many whole items fit under a character ceiling, in order, and the
+ * notice that tells a caller how to retrieve the rest. The sibling of
+ * `_text.ts`, which shortens the *inside* of one item's text — nothing here
+ * ever cuts into an item. (#99, #100, #236)
  * @module src/mcp-server/tools/definitions/_budget
  */
 /**
@@ -22,12 +23,40 @@ export interface WholeItemFit<T> {
     keptCharacters: number;
     /**
      * Size of the next deferred item — `deferred[0]`, the one the cut stopped
-     * at. Because the cut is a prefix cut, that item is the ceiling a caller must
-     * clear to make progress: a smaller item further down the tail is unreachable
-     * until the one in front of it fits. Absent when nothing was deferred.
+     * at. Because the cut is a prefix cut, it is the continuation ceiling: a call
+     * for `deferred` alone returns nothing under it, and a smaller item further
+     * down the tail is unreachable until the one in front of it fits. Repeating
+     * the same call needs `keptCharacters` + this to return that item as well.
+     * Absent when nothing was deferred.
      */
     nextDeferredCharacters?: number;
 }
+/** The budget state a deferral notice reports — the fields every tool's `deferred` carries. */
+export interface DeferralState {
+    deferredCount: number;
+    maxResponseCharacters: number;
+    nextDeferredCharacters: number;
+    returnedCharacters: number;
+}
+/** How one tool names what it deferred and how to ask for it again. */
+export interface DeferralWording {
+    /** The deferred items as the caller re-sends them, already joined. */
+    ids: string;
+    /** One deferred item: `article`, `record`. */
+    noun: string;
+    /** The re-call after its verb — the tool and how the ids go back in. */
+    recall: string;
+}
+/**
+ * Compose the recovery notice for items the whole-response budget withheld, so
+ * a caller reading only `content[]` can resume without inspecting `deferred`.
+ * Each ceiling is named with the call it applies to: re-calling for the
+ * deferred items needs `nextDeferredCharacters`; repeating this call needs
+ * `returnedCharacters + nextDeferredCharacters`. Both exceed the current
+ * ceiling whenever they are named, so the notice never asks for a raise to a
+ * value at or below it. (#100, #236)
+ */
+export declare function buildDeferralNotice(state: DeferralState, wording: DeferralWording): string;
 /**
  * Split an ordered list at the first item that would carry the running
  * character total past `maxCharacters`. That item and everything after it is

package/dist/mcp-server/tools/definitions/_budget.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"_budget.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/_budget.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAE3D;AAED,mEAAmE;AACnE,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,yEAAyE;IACzE,QAAQ,EAAE,CAAC,EAAE,CAAC;IACd,+CAA+C;IAC/C,IAAI,EAAE,CAAC,EAAE,CAAC;IACV,6CAA6C;IAC7C,cAAc,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,aAAa,EAAE,MAAM,EACrB,OAAO,GAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAA6B,GAClD,YAAY,CAAC,CAAC,CAAC,CAuBjB"}
+{"version":3,"file":"_budget.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/_budget.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAE3D;AAED,mEAAmE;AACnE,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,yEAAyE;IACzE,QAAQ,EAAE,CAAC,EAAE,CAAC;IACd,+CAA+C;IAC/C,IAAI,EAAE,CAAC,EAAE,CAAC;IACV,6CAA6C;IAC7C,cAAc,EAAE,MAAM,CAAC;IACvB;;;;;;;OAOG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,+FAA+F;AAC/F,MAAM,WAAW,aAAa;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED,uEAAuE;AACvE,MAAM,WAAW,eAAe;IAC9B,sEAAsE;IACtE,GAAG,EAAE,MAAM,CAAC;IACZ,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,eAAe,GAAG,MAAM,CAa1F;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,aAAa,EAAE,MAAM,EACrB,OAAO,GAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAA6B,GAClD,YAAY,CAAC,CAAC,CAAC,CAuBjB"}

package/dist/mcp-server/tools/definitions/_budget.js

@@ -1,8 +1,9 @@
 /**
  * @fileoverview Whole-response character budgeting shared by the retrieval
- * tools: how many whole items fit under a character ceiling, in order. The
- * sibling of `_text.ts`, which shortens the *inside* of one item's text —
- * nothing here ever cuts into an item. (#99, #100)
+ * tools: how many whole items fit under a character ceiling, in order, and the
+ * notice that tells a caller how to retrieve the rest. The sibling of
+ * `_text.ts`, which shortens the *inside* of one item's text — nothing here
+ * ever cuts into an item. (#99, #100, #236)
  * @module src/mcp-server/tools/definitions/_budget
  */
 /**
@@ -14,6 +15,28 @@
 export function serializedCharacters(value) {
     return JSON.stringify(value)?.length ?? 0;
 }
+/**
+ * Compose the recovery notice for items the whole-response budget withheld, so
+ * a caller reading only `content[]` can resume without inspecting `deferred`.
+ * Each ceiling is named with the call it applies to: re-calling for the
+ * deferred items needs `nextDeferredCharacters`; repeating this call needs
+ * `returnedCharacters + nextDeferredCharacters`. Both exceed the current
+ * ceiling whenever they are named, so the notice never asks for a raise to a
+ * value at or below it. (#100, #236)
+ */
+export function buildDeferralNotice(state, wording) {
+    const { maxResponseCharacters: max, nextDeferredCharacters: next } = state;
+    const { ids, noun, recall } = wording;
+    const listed = `${state.deferredCount} resolved ${noun}(s) were deferred whole: ${ids}.`;
+    if (state.returnedCharacters === 0) {
+        return `The first ${noun} alone exceeds the requested maxResponseCharacters of ${max}, so none were returned. ${listed} Re-call ${recall} and maxResponseCharacters ≥ ${next}, the size of that first ${noun}.`;
+    }
+    const continuation = next <= max
+        ? `To continue, re-call ${recall} at the current maxResponseCharacters of ${max}, which already fits the next deferred ${noun} (${next} characters).`
+        : `To continue, re-call ${recall} and maxResponseCharacters ≥ ${next}, the size of the next deferred ${noun}.`;
+    const repeat = `To return the next deferred ${noun} in this response instead, repeat this call with maxResponseCharacters ≥ ${state.returnedCharacters + next}.`;
+    return `Response character budget reached: ${state.returnedCharacters} of ${max} characters returned. ${listed} ${continuation} ${repeat}`;
+}
 /**
  * Split an ordered list at the first item that would carry the running
  * character total past `maxCharacters`. That item and everything after it is

package/dist/mcp-server/tools/definitions/_budget.js.map

@@ -1 +1 @@
-{"version":3,"file":"_budget.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/_budget.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAc;IACjD,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,MAAM,IAAI,CAAC,CAAC;AAC5C,CAAC;AAmBD;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAC3B,KAAmB,EACnB,aAAqB,EACrB,OAAO,GAAwB,oBAAoB;IAEnD,MAAM,IAAI,GAAQ,EAAE,CAAC;IACrB,IAAI,cAAc,GAAG,CAAC,CAAC;IACvB,IAAI,GAAG,GAAG,KAAK,CAAC,MAAM,CAAC;IAEvB,KAAK,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;QAC5C,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QAC3B,IAAI,cAAc,GAAG,IAAI,GAAG,aAAa,EAAE,CAAC;YAC1C,GAAG,GAAG,KAAK,CAAC;YACZ,MAAM;QACR,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAChB,cAAc,IAAI,IAAI,CAAC;IACzB,CAAC;IAED,MAAM,QAAQ,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAClC,MAAM,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC;IACxB,OAAO;QACL,IAAI;QACJ,QAAQ;QACR,cAAc;QACd,GAAG,CAAC,IAAI,KAAK,SAAS,IAAI,EAAE,sBAAsB,EAAE,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;KACrE,CAAC;AACJ,CAAC"}
+{"version":3,"file":"_budget.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/_budget.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAc;IACjD,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,MAAM,IAAI,CAAC,CAAC;AAC5C,CAAC;AAuCD;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAoB,EAAE,OAAwB;IAChF,MAAM,EAAE,qBAAqB,EAAE,GAAG,EAAE,sBAAsB,EAAE,IAAI,EAAE,GAAG,KAAK,CAAC;IAC3E,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IACtC,MAAM,MAAM,GAAG,GAAG,KAAK,CAAC,aAAa,aAAa,IAAI,4BAA4B,GAAG,GAAG,CAAC;IACzF,IAAI,KAAK,CAAC,kBAAkB,KAAK,CAAC,EAAE,CAAC;QACnC,OAAO,aAAa,IAAI,yDAAyD,GAAG,4BAA4B,MAAM,YAAY,MAAM,gCAAgC,IAAI,4BAA4B,IAAI,GAAG,CAAC;IAClN,CAAC;IACD,MAAM,YAAY,GAChB,IAAI,IAAI,GAAG;QACT,CAAC,CAAC,wBAAwB,MAAM,4CAA4C,GAAG,0CAA0C,IAAI,KAAK,IAAI,eAAe;QACrJ,CAAC,CAAC,wBAAwB,MAAM,gCAAgC,IAAI,mCAAmC,IAAI,GAAG,CAAC;IACnH,MAAM,MAAM,GAAG,+BAA+B,IAAI,4EAA4E,KAAK,CAAC,kBAAkB,GAAG,IAAI,GAAG,CAAC;IACjK,OAAO,sCAAsC,KAAK,CAAC,kBAAkB,OAAO,GAAG,yBAAyB,MAAM,IAAI,YAAY,IAAI,MAAM,EAAE,CAAC;AAC7I,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAC3B,KAAmB,EACnB,aAAqB,EACrB,OAAO,GAAwB,oBAAoB;IAEnD,MAAM,IAAI,GAAQ,EAAE,CAAC;IACrB,IAAI,cAAc,GAAG,CAAC,CAAC;IACvB,IAAI,GAAG,GAAG,KAAK,CAAC,MAAM,CAAC;IAEvB,KAAK,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;QAC5C,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QAC3B,IAAI,cAAc,GAAG,IAAI,GAAG,aAAa,EAAE,CAAC;YAC1C,GAAG,GAAG,KAAK,CAAC;YACZ,MAAM;QACR,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAChB,cAAc,IAAI,IAAI,CAAC;IACzB,CAAC;IAED,MAAM,QAAQ,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAClC,MAAM,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC;IACxB,OAAO;QACL,IAAI;QACJ,QAAQ;QACR,cAAc;QACd,GAAG,CAAC,IAAI,KAAK,SAAS,IAAI,EAAE,sBAAsB,EAAE,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;KACrE,CAAC;AACJ,CAAC"}

package/dist/mcp-server/tools/definitions/_notices.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @fileoverview The linked-notice block `pubmed_format_citations` and
+ * `pubmed_fetch_articles` both open a record with: the retraction, erratum, and
+ * expression-of-concern links NCBI attaches to it, under a warning when one is a
+ * retraction. (#215, #237)
+ * @module src/mcp-server/tools/definitions/_notices
+ */
+import { type CitationNoticeType } from '../../../services/ncbi/formatting/citation-formatter.js';
+/** One NCBI comments-and-corrections link as a tool's output carries it. */
+interface NoticeLink {
+    note?: string | undefined;
+    pmid?: string | undefined;
+    refSource: string;
+    refType: string;
+}
+/**
+ * The links that qualify the record itself — it was retracted, corrected, or
+ * questioned — in NCBI's order. Comment, update, and `…Of`/`…For` links, which
+ * point from a notice back to what it concerns, are not among them.
+ */
+export declare function noticeLinks<T extends NoticeLink>(links: readonly T[] | undefined): (T & {
+    refType: CitationNoticeType;
+})[];
+/**
+ * The `content[]` lines for one record's notices, opening on a warning when it
+ * was retracted. Each entry takes the form the record's full "Comments and
+ * Corrections" list gives the same link.
+ */
+export declare function noticeLines(notices: readonly (NoticeLink & {
+    refType: CitationNoticeType;
+})[]): string[];
+export {};
+//# sourceMappingURL=_notices.d.ts.map

package/dist/mcp-server/tools/definitions/_notices.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_notices.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/_notices.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,kDAAkD,CAAC;AAG1D,4EAA4E;AAC5E,UAAU,UAAU;IAClB,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAID;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,UAAU,EAC9C,KAAK,EAAE,SAAS,CAAC,EAAE,GAAG,SAAS,GAC9B,CAAC,CAAC,GAAG;IAAE,OAAO,EAAE,kBAAkB,CAAA;CAAE,CAAC,EAAE,CAIzC;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,SAAS,CAAC,UAAU,GAAG;IAAE,OAAO,EAAE,kBAAkB,CAAA;CAAE,CAAC,EAAE,GACjE,MAAM,EAAE,CAYV"}

package/dist/mcp-server/tools/definitions/_notices.js

@@ -0,0 +1,35 @@
+/**
+ * @fileoverview The linked-notice block `pubmed_format_citations` and
+ * `pubmed_fetch_articles` both open a record with: the retraction, erratum, and
+ * expression-of-concern links NCBI attaches to it, under a warning when one is a
+ * retraction. (#215, #237)
+ * @module src/mcp-server/tools/definitions/_notices
+ */
+import { CITATION_NOTICE_TYPES, } from '../../../services/ncbi/formatting/citation-formatter.js';
+import { escapeMarkdownInline } from './_text.js';
+const NOTICE_TYPES = new Set(CITATION_NOTICE_TYPES);
+/**
+ * The links that qualify the record itself — it was retracted, corrected, or
+ * questioned — in NCBI's order. Comment, update, and `…Of`/`…For` links, which
+ * point from a notice back to what it concerns, are not among them.
+ */
+export function noticeLinks(links) {
+    return (links ?? []).filter((link) => NOTICE_TYPES.has(link.refType));
+}
+/**
+ * The `content[]` lines for one record's notices, opening on a warning when it
+ * was retracted. Each entry takes the form the record's full "Comments and
+ * Corrections" list gives the same link.
+ */
+export function noticeLines(notices) {
+    const retracted = notices.some((notice) => notice.refType === 'RetractionIn' || notice.refType === 'RetractedandRepublishedIn');
+    return [
+        retracted ? '**Retracted:** NCBI links a retraction notice to this article.' : '**Notices:**',
+        ...notices.map((notice) => {
+            const pmid = notice.pmid ? ` — PMID ${notice.pmid}` : '';
+            const note = notice.note ? ` — Note: ${escapeMarkdownInline(notice.note)}` : '';
+            return `- **${notice.refType}:** ${escapeMarkdownInline(notice.refSource)}${pmid}${note}`;
+        }),
+    ];
+}
+//# sourceMappingURL=_notices.js.map

package/dist/mcp-server/tools/definitions/_notices.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_notices.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/_notices.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,qBAAqB,GAEtB,MAAM,kDAAkD,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAUlD,MAAM,YAAY,GAAwB,IAAI,GAAG,CAAC,qBAAqB,CAAC,CAAC;AAEzE;;;;GAIG;AACH,MAAM,UAAU,WAAW,CACzB,KAA+B;IAE/B,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAA+C,EAAE,CAChF,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAC/B,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CACzB,OAAkE;IAElE,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,CAC5B,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,KAAK,cAAc,IAAI,MAAM,CAAC,OAAO,KAAK,2BAA2B,CAChG,CAAC;IACF,OAAO;QACL,SAAS,CAAC,CAAC,CAAC,gEAAgE,CAAC,CAAC,CAAC,cAAc;QAC7F,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE;YACxB,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,WAAW,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACzD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,YAAY,oBAAoB,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAChF,OAAO,OAAO,MAAM,CAAC,OAAO,OAAO,oBAAoB,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,IAAI,GAAG,IAAI,EAAE,CAAC;QAC5F,CAAC,CAAC;KACH,CAAC;AACJ,CAAC"}

package/dist/mcp-server/tools/definitions/_schemas.d.ts

@@ -37,4 +37,18 @@ export declare const pmcidStringSchema: z.ZodString;
  * carrying one is read upstream as two identifiers rather than one DOI.
  */
 export declare const doiStringSchema: z.ZodString;
+/**
+ * A Europe PMC source code as a tool accepts it: a lower-case code (`med`,
+ * `pmc`) is folded to the code itself before the enum check, since Europe PMC
+ * matches `SRC:` case-insensitively and search hits always carry the upper-case
+ * form. A value that is no code (`pubmed`) is still rejected. The fold stays off
+ * the advertised schema, which remains the plain enum. (#244)
+ */
+export declare const europePmcSourceInputSchema: z.ZodPreprocess<z.ZodEnum<{
+    AGR: "AGR";
+    MED: "MED";
+    PAT: "PAT";
+    PMC: "PMC";
+    PPR: "PPR";
+}>, unknown>;
 //# sourceMappingURL=_schemas.d.ts.map

package/dist/mcp-server/tools/definitions/_schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"_schemas.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/_schemas.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAE3C;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,aAK1B,CAAC;AAEJ;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB,aAK3B,CAAC;AAEJ;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,aAKzB,CAAC"}
+{"version":3,"file":"_schemas.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/_schemas.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAG3C;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,aAK1B,CAAC;AAEJ;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB,aAK3B,CAAC;AAEJ;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,aAKzB,CAAC;AAEJ;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B;;;;;;YAGtC,CAAC"}

package/dist/mcp-server/tools/definitions/_schemas.js

@@ -4,6 +4,7 @@
  * @module src/mcp-server/tools/definitions/_schemas
  */
 import { z } from '@cyanheads/mcp-ts-core';
+import { EUROPEPMC_ALL_SOURCES } from '../../../services/europe-pmc/types.js';
 /**
  * Zod string schema for a single PubMed ID. Accepts only digit characters.
  * The message is intentionally actionable so callers can self-correct without
@@ -45,4 +46,12 @@ export const pmcidStringSchema = z
 export const doiStringSchema = z
     .string()
     .regex(/^10\.[^\s,]+\/[^\s,]+$/, 'DOI must start with "10." and contain a "/" (e.g. "10.1093/nar/gks1195"). Remove any whitespace or commas — provide each DOI separately.');
+/**
+ * A Europe PMC source code as a tool accepts it: a lower-case code (`med`,
+ * `pmc`) is folded to the code itself before the enum check, since Europe PMC
+ * matches `SRC:` case-insensitively and search hits always carry the upper-case
+ * form. A value that is no code (`pubmed`) is still rejected. The fold stays off
+ * the advertised schema, which remains the plain enum. (#244)
+ */
+export const europePmcSourceInputSchema = z.preprocess((value) => (typeof value === 'string' ? value.toUpperCase() : value), z.enum(EUROPEPMC_ALL_SOURCES));
 //# sourceMappingURL=_schemas.js.map

package/dist/mcp-server/tools/definitions/_schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"_schemas.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/_schemas.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAE3C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC;KAC9B,MAAM,EAAE;KACR,KAAK,CACJ,OAAO,EACP,6IAA6I,CAC9I,CAAC;AAEJ;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,OAAO,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;AACvC,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC;KAC/B,MAAM,EAAE;KACR,KAAK,CACJ,gBAAgB,EAChB,2JAA2J,CAC5J,CAAC;AAEJ;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC;KAC7B,MAAM,EAAE;KACR,KAAK,CACJ,wBAAwB,EACxB,0IAA0I,CAC3I,CAAC"}
+{"version":3,"file":"_schemas.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/_schemas.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAC3C,OAAO,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AAEvE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC;KAC9B,MAAM,EAAE;KACR,KAAK,CACJ,OAAO,EACP,6IAA6I,CAC9I,CAAC;AAEJ;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,OAAO,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;AACvC,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC;KAC/B,MAAM,EAAE;KACR,KAAK,CACJ,gBAAgB,EAChB,2JAA2J,CAC5J,CAAC;AAEJ;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC;KAC7B,MAAM,EAAE;KACR,KAAK,CACJ,wBAAwB,EACxB,0IAA0I,CAC3I,CAAC;AAEJ;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC,UAAU,CACpD,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,EACpE,CAAC,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAC9B,CAAC"}

package/dist/mcp-server/tools/definitions/fetch-articles.tool.d.ts

@@ -28,6 +28,7 @@ export declare const fetchArticlesTool: import("@cyanheads/mcp-ts-core").ToolDef
             lastName: z.ZodOptional<z.ZodString>;
             firstName: z.ZodOptional<z.ZodString>;
             initials: z.ZodOptional<z.ZodString>;
+            suffix: z.ZodOptional<z.ZodString>;
             collectiveName: z.ZodOptional<z.ZodString>;
             affiliationIndices: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
             orcid: z.ZodOptional<z.ZodString>;
@@ -36,6 +37,7 @@ export declare const fetchArticlesTool: import("@cyanheads/mcp-ts-core").ToolDef
             lastName: z.ZodOptional<z.ZodString>;
             firstName: z.ZodOptional<z.ZodString>;
             initials: z.ZodOptional<z.ZodString>;
+            suffix: z.ZodOptional<z.ZodString>;
             affiliationIndices: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
             orcid: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
@@ -72,6 +74,7 @@ export declare const fetchArticlesTool: import("@cyanheads/mcp-ts-core").ToolDef
                 lastName: z.ZodOptional<z.ZodString>;
                 firstName: z.ZodOptional<z.ZodString>;
                 initials: z.ZodOptional<z.ZodString>;
+                suffix: z.ZodOptional<z.ZodString>;
                 collectiveName: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>>>;
             accession: z.ZodOptional<z.ZodString>;

package/dist/mcp-server/tools/definitions/fetch-articles.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fetch-articles.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/fetch-articles.tool.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAoWjE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAWhB,yBAAyB;;mBAE3B,sEAAsE;uBAE1E,qFAAqF;;;;EA6T3F,CAAC"}
+{"version":3,"file":"fetch-articles.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/fetch-articles.tool.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAuXjE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAWhB,yBAAyB;;mBAE3B,sEAAsE;uBAE1E,qFAAqF;;;;EAyU3F,CAAC"}

package/dist/mcp-server/tools/definitions/fetch-articles.tool.js

@@ -10,8 +10,9 @@ import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
 import { NCBI_SERVICE_ERRORS } from '../../../services/error-contracts.js';
 import { getNcbiService } from '../../../services/ncbi/ncbi-service.js';
 import { parseArticleSet } from '../../../services/ncbi/parsing/article-parser.js';
-import { fitWholeItems } from './_budget.js';
+import { buildDeferralNotice, fitWholeItems } from './_budget.js';
 import { conceptMeta, EDAM_DATA_RETRIEVAL, EDAM_PUBMED_ID, SCHEMA_SCHOLARLY_ARTICLE, } from './_concepts.js';
+import { noticeLines, noticeLinks } from './_notices.js';
 import { normalizePmid, pmidStringSchema } from './_schemas.js';
 import { escapeMarkdownInline } from './_text.js';
 const AuthorSchema = z
@@ -19,6 +20,10 @@ const AuthorSchema = z
     lastName: z.string().optional().describe('Last name'),
     firstName: z.string().optional().describe('First/given name'),
     initials: z.string().optional().describe('Author initials'),
+    suffix: z
+        .string()
+        .optional()
+        .describe('Generational name suffix verbatim from NCBI `Suffix` (e.g. "Jr", "2nd", "3rd"), never normalized. Absent when NCBI gives none.'),
     collectiveName: z
         .string()
         .optional()
@@ -35,6 +40,10 @@ const InvestigatorSchema = z
     lastName: z.string().optional().describe('Last name'),
     firstName: z.string().optional().describe('First/given name'),
     initials: z.string().optional().describe('Initials'),
+    suffix: z
+        .string()
+        .optional()
+        .describe('Generational name suffix verbatim from NCBI `Suffix` (e.g. "Jr", "2nd"). Absent when NCBI gives none.'),
     affiliationIndices: z
         .array(z.number())
         .optional()
@@ -84,6 +93,10 @@ const BookEditorSchema = z
         .string()
         .optional()
         .describe('Editor initials with no separators (e.g. "MP"). Absent when NCBI supplies none, or on a group editor.'),
+    suffix: z
+        .string()
+        .optional()
+        .describe('Editor generational name suffix verbatim from NCBI `Suffix` (e.g. "Jr"). Absent when NCBI supplies none, or on a group editor.'),
     collectiveName: z
         .string()
         .optional()
@@ -260,7 +273,7 @@ const DeferredSchema = z
         .describe('PMIDs of the deferred articles, in response order. Re-call `pubmed_fetch_articles` with these as `pmids` and the same other inputs to retrieve them. Never contains a PMID from `unavailablePmids`.'),
     nextDeferredCharacters: z
         .number()
-        .describe('Serialized size of the next deferred article — the first entry in `ids`, where the response stopped. Raise `maxResponseCharacters` to at least this to make progress; a smaller article further down `ids` cannot be reached until this one fits.'),
+        .describe('Serialized size of the next deferred article — the first entry in `ids`, where the response stopped — and the continuation ceiling: re-calling with the deferred PMIDs needs `maxResponseCharacters` ≥ this to return anything, and a smaller article further down `ids` cannot be reached until this one fits. Repeating this same call needs `maxResponseCharacters` ≥ `returnedCharacters` + this to return this article as well.'),
 })
     .describe('Continuation state for articles the whole-response budget withheld. Present only when `maxResponseCharacters` deferred at least one article.');
 export const fetchArticlesTool = tool('pubmed_fetch_articles', {
@@ -377,7 +390,11 @@ export const fetchArticlesTool = tool('pubmed_fetch_articles', {
         }
         if (deferred) {
             ctx.enrich({ truncated: true });
-            ctx.enrich.notice(buildDeferralNotice(deferred));
+            ctx.enrich.notice(buildDeferralNotice(deferred, {
+                noun: 'article',
+                ids: deferred.ids.join(', '),
+                recall: 'pubmed_fetch_articles with those PMIDs',
+            }));
         }
         return {
             articles: returned,
@@ -399,6 +416,12 @@ export const fetchArticlesTool = tool('pubmed_fetch_articles', {
             // Render-time only — `structuredContent.articles[].title` keeps the
             // plain-text value the NCBI parser produced. (#102)
             lines.push(`\n### ${escapeMarkdownInline(a.title ?? a.pmid ?? 'Unknown')}`);
+            // A retraction or correction qualifies everything below it, so it leads,
+            // ahead of name lists that grow with the record. The full list further
+            // down keeps NCBI's order and repeats these entries. (#237)
+            const notices = noticeLinks(a.commentsCorrections);
+            if (notices.length > 0)
+                lines.push('', ...noticeLines(notices));
             if (a.authors?.length) {
                 lines.push(`\n**Authors (${a.authors.length}):**`);
                 for (const au of a.authors) {
@@ -562,18 +585,6 @@ export const fetchArticlesTool = tool('pubmed_fetch_articles', {
         return [{ type: 'text', text: lines.join('\n') }];
     },
 });
-/**
- * Compose the recovery notice for a response the whole-response budget bounded.
- * Names what was spent, which PMIDs are still retrievable, and the ceiling the
- * next call has to clear — so a caller reading only `content[]` can resume
- * without inspecting `deferred`. (#99)
- */
-function buildDeferralNotice(deferred) {
-    const spent = deferred.returnedCharacters === 0
-        ? `The first article alone exceeds the requested maxResponseCharacters of ${deferred.maxResponseCharacters}, so none were returned.`
-        : `Response character budget reached: ${deferred.returnedCharacters} of ${deferred.maxResponseCharacters} characters returned.`;
-    return `${spent} ${deferred.deferredCount} resolved article(s) were deferred whole: ${deferred.ids.join(', ')}. Re-call pubmed_fetch_articles with those PMIDs to retrieve them, or raise maxResponseCharacters to at least ${deferred.nextDeferredCharacters} — the size of the next deferred article.`;
-}
 function formatAuthor(au) {
     const parts = [];
     if (au.collectiveName)
@@ -583,6 +594,8 @@ function formatAuthor(au) {
         parts.push(name);
     else if (au.initials)
         parts.push(au.initials);
+    if (au.suffix)
+        parts.push(au.suffix);
     if (au.initials && name)
         parts.push(`(${au.initials})`);
     if (au.affiliationIndices?.length) {