@cyanheads/pubmed-mcp-server 2.10.5 → 2.10.7

package/AGENTS.md

@@ -1,8 +1,8 @@
 # Agent Protocol
 
 **Server:** @cyanheads/pubmed-mcp-server
-**Version:** 2.10.5
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.12.5`
+**Version:** 2.10.7
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.12.7`
 **Engines:** Bun ≥1.3.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.
@@ -181,7 +181,7 @@ Handlers receive a unified `ctx` object. Key properties:
 
 Handlers throw — the framework catches, classifies, and formats.
 
-**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable? }]` on `tool()` / `resource()` to receive a typed `ctx.fail(reason, …)` keyed by the declared reason union. TypeScript catches `ctx.fail('typo')` at compile time, `data.reason` is auto-populated for observability, and the linter enforces conformance against the handler body. The `recovery` field is required (≥ 5 words, lint-validated) — it's the single source of truth for the recovery hint. Spread `ctx.recoveryFor('reason')` into `data` to mirror the contract recovery onto the wire (the framework mirrors `data.recovery.hint` into `content[]` text); pass an explicit `recovery: { hint: '...' }` when runtime context matters. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) bubble freely and don't need declaring.
+**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable? }]` on `tool()` / `resource()` to receive a typed `ctx.fail(reason, …)` keyed by the declared reason union. TypeScript catches `ctx.fail('typo')` at compile time, `data.reason` is auto-populated for observability, and the linter enforces conformance against the handler body. The `recovery` field is required (≥ 5 words, lint-validated) — it's the single source of truth for the recovery hint. Spread `ctx.recoveryFor('reason')` into `data` to mirror the contract recovery onto the wire (the framework mirrors `data.recovery.hint` into `content[]` text); pass an explicit `recovery: { hint: '...' }` when runtime context matters. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) bubble freely and don't need declaring.
 
 ```ts
 errors: [
@@ -354,7 +354,7 @@ Directory-based, grouped by minor series via the `.x` semver-wildcard convention
 
 `agent-notes` is an optional free-form field consumed by agents running the `maintenance` skill downstream — adoption instructions that don't fit the human-facing sections. Omit entirely when there's nothing to say.
 
-**Section order** (Keep a Changelog): Added, Changed, Deprecated, Removed, Fixed, Security. Include only sections with entries.
+**Section order:** the Keep a Changelog sequence — Added, Changed, Deprecated, Removed, Fixed, Security — then `Dependencies` last. Include only sections with entries.
 
 **Tag annotations** render as GitHub Release bodies via `--notes-from-tag`. They must be structured markdown — never a flat comma-separated string. Subject omits the version number (GitHub prepends it). See `changelog/template.md` for the full format reference.
 

package/CLAUDE.md

@@ -1,8 +1,8 @@
 # Agent Protocol
 
 **Server:** @cyanheads/pubmed-mcp-server
-**Version:** 2.10.5
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.12.5`
+**Version:** 2.10.7
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.12.7`
 **Engines:** Bun ≥1.3.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.
@@ -181,7 +181,7 @@ Handlers receive a unified `ctx` object. Key properties:
 
 Handlers throw — the framework catches, classifies, and formats.
 
-**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable? }]` on `tool()` / `resource()` to receive a typed `ctx.fail(reason, …)` keyed by the declared reason union. TypeScript catches `ctx.fail('typo')` at compile time, `data.reason` is auto-populated for observability, and the linter enforces conformance against the handler body. The `recovery` field is required (≥ 5 words, lint-validated) — it's the single source of truth for the recovery hint. Spread `ctx.recoveryFor('reason')` into `data` to mirror the contract recovery onto the wire (the framework mirrors `data.recovery.hint` into `content[]` text); pass an explicit `recovery: { hint: '...' }` when runtime context matters. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) bubble freely and don't need declaring.
+**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable? }]` on `tool()` / `resource()` to receive a typed `ctx.fail(reason, …)` keyed by the declared reason union. TypeScript catches `ctx.fail('typo')` at compile time, `data.reason` is auto-populated for observability, and the linter enforces conformance against the handler body. The `recovery` field is required (≥ 5 words, lint-validated) — it's the single source of truth for the recovery hint. Spread `ctx.recoveryFor('reason')` into `data` to mirror the contract recovery onto the wire (the framework mirrors `data.recovery.hint` into `content[]` text); pass an explicit `recovery: { hint: '...' }` when runtime context matters. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) bubble freely and don't need declaring.
 
 ```ts
 errors: [
@@ -354,7 +354,7 @@ Directory-based, grouped by minor series via the `.x` semver-wildcard convention
 
 `agent-notes` is an optional free-form field consumed by agents running the `maintenance` skill downstream — adoption instructions that don't fit the human-facing sections. Omit entirely when there's nothing to say.
 
-**Section order** (Keep a Changelog): Added, Changed, Deprecated, Removed, Fixed, Security. Include only sections with entries.
+**Section order:** the Keep a Changelog sequence — Added, Changed, Deprecated, Removed, Fixed, Security — then `Dependencies` last. Include only sections with entries.
 
 **Tag annotations** render as GitHub Release bodies via `--notes-from-tag`. They must be structured markdown — never a flat comma-separated string. Subject omits the version number (GitHub prepends it). See `changelog/template.md` for the full format reference.
 

package/README.md

@@ -9,7 +9,7 @@
 
 
 
-[![Version](https://img.shields.io/badge/Version-2.10.5-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.0.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.0-blueviolet.svg?style=flat-square)](https://bun.sh/)
+[![Version](https://img.shields.io/badge/Version-2.10.7-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.0.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.0-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
 </div>
 
@@ -72,6 +72,7 @@ Fetch full article metadata by PubMed IDs.
 - Direct links to PubMed and PubMed Central (when available)
 - Optional MeSH terms, grant information, and publication types
 - Handles PubMed's inconsistent XML (structured abstracts, missing fields, varying date formats)
+- Opt-in whole-response ceiling: `maxResponseCharacters` keeps complete article records in response order until the next one would cross it, then defers the rest whole and lists their PMIDs in `deferred.ids`. Re-call with those PMIDs to resume exactly where the response stopped — no article is split, skipped, or duplicated. Each article is measured as the JSON record it is returned as, so a ceiling under the first article returns zero articles, the full deferred list, and the size to clear
 
 ---
 
@@ -84,10 +85,12 @@ Fetch full-text articles via a three-stage chain: NCBI PMC EFetch → Europe PMC
 - Europe PMC layer (enabled by default; disable with `EUROPEPMC_ENABLED=false`) recovers PMC-counterpart records that NCBI PMC EFetch missed, and resolves DOI input to PMC counterparts when one exists. EPMC's `fullTextXML` is PMC-keyed, so preprints (PPR), patents (PAT), and Agricola (AGR) are reachable via `pubmed_europepmc_search` for metadata but have no full text via this chain.
 - Unpaywall layer (enabled by setting `UNPAYWALL_EMAIL`) resolves DOIs to legal OA copies; extracts HTML landing pages to Markdown via Defuddle or PDFs to text via unpdf
 - Discriminated output contract — `source: "pmc"` (structured sections, regardless of whether it came from PMC or EPMC) or `source: "unpaywall"` (best-effort body + `contentFormat`: `html-markdown` or `pdf-text`)
-- Structured unavailable reasons (`not-found`, `no-pmc-fallback-disabled`, `no-epmc-fulltext`, `no-doi`, `no-oa`, `fetch-failed`, `parse-failed`, `service-error`) so callers can retry or explain to users without parsing text
+- Structured unavailable reasons (`not-found`, `no-pmc-fallback-disabled`, `no-epmc-fulltext`, `no-body`, `no-doi`, `no-oa`, `fetch-failed`, `parse-failed`, `service-error`) so callers can retry or explain to users without parsing text
+- An `unavailable` entry also carries `unqueriedTiers` when the chain skipped a tier this deployment has not configured and that tier could have served the id — the search was incomplete, and a deployment with those tiers configured may still resolve it
 - Each `unavailable` entry carries `idType` (`pmid` / `pmcid` / `doi`) and `triedTiers` — per-tier outcomes (`not-attempted`, `miss`, `no-fulltext`, `service-error`, …) in execution order, so callers can see which stage failed and why
 - Section filtering by title (case-insensitive match, e.g. `["methods", "results"]`) and configurable max sections apply to PMC output
 - Character budgets keep context size predictable: `maxCharacters` caps body text per article (PMC sections and subsections, or the Unpaywall body), `maxCharactersPerSection` caps a single PMC section, and `overflowMode` picks between `truncate` (fill sections in document order) and `outline` (split the budget evenly so every heading survives with an excerpt). Budgets run after the semantic filters, and a `truncation` object reports per-article and per-section character counts whenever anything was shortened
+- `maxResponseCharacters` bounds the whole response instead of each body: every field of a returned record counts (abstract, references, metadata, body), one ledger across PMC-, Europe PMC-, and Unpaywall-served articles. Articles past the ceiling are deferred whole, with their ids — in the branch they were requested under — in `deferred.ids` for a follow-up call
 - Up to 10 articles per request
 
 ---
@@ -136,6 +139,7 @@ Find articles related to a source article via ELink.
 - Three relationship types: `similar` (content similarity), `cited_by`, `references`
 - Results enriched with title, authors, publication date, and source via ESummary
 - Results returned in NCBI's relevance order
+- Falls back to Europe PMC, then OpenAlex, when NCBI cannot answer; the response names which provider served it. A request no provider can answer fails with a typed `all_providers_failed` error instead of an empty result
 
 ---
 

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

@@ -0,0 +1,42 @@
+/**
+ * @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)
+ * @module src/mcp-server/tools/definitions/_budget
+ */
+/**
+ * Characters an item contributes to the response, measured as the JSON form it
+ * is serialized into for `structuredContent` — every field the record carries,
+ * keys included. `JSON.stringify` returns `undefined` for values with no JSON
+ * form (`undefined`, a function), which contribute nothing.
+ */
+export declare function serializedCharacters(value: unknown): number;
+/** How an ordered list of items divides at a character ceiling. */
+export interface WholeItemFit<T> {
+    /** Items withheld to stay under the ceiling, in their original order. */
+    deferred: T[];
+    /** Items that fit, in their original order. */
+    kept: T[];
+    /** Characters the kept items account for. */
+    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.
+     */
+    nextDeferredCharacters?: number;
+}
+/**
+ * Split an ordered list at the first item that would carry the running
+ * character total past `maxCharacters`. That item and everything after it is
+ * deferred whole; no item is ever shortened, reordered, or skipped over.
+ *
+ * The cut is a prefix cut on purpose: skipping a too-large item to fit a later
+ * smaller one would leave the caller with a non-contiguous remainder and no way
+ * to resume from the deferred list alone. Keeping the cut contiguous makes
+ * re-calling with `deferred` exactly equivalent to continuing the first call.
+ */
+export declare function fitWholeItems<T>(items: readonly T[], maxCharacters: number, measure?: (item: T) => number): WholeItemFit<T>;
+//# sourceMappingURL=_budget.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,49 @@
+/**
+ * @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)
+ * @module src/mcp-server/tools/definitions/_budget
+ */
+/**
+ * Characters an item contributes to the response, measured as the JSON form it
+ * is serialized into for `structuredContent` — every field the record carries,
+ * keys included. `JSON.stringify` returns `undefined` for values with no JSON
+ * form (`undefined`, a function), which contribute nothing.
+ */
+export function serializedCharacters(value) {
+    return JSON.stringify(value)?.length ?? 0;
+}
+/**
+ * Split an ordered list at the first item that would carry the running
+ * character total past `maxCharacters`. That item and everything after it is
+ * deferred whole; no item is ever shortened, reordered, or skipped over.
+ *
+ * The cut is a prefix cut on purpose: skipping a too-large item to fit a later
+ * smaller one would leave the caller with a non-contiguous remainder and no way
+ * to resume from the deferred list alone. Keeping the cut contiguous makes
+ * re-calling with `deferred` exactly equivalent to continuing the first call.
+ */
+export function fitWholeItems(items, maxCharacters, measure = serializedCharacters) {
+    const kept = [];
+    let keptCharacters = 0;
+    let cut = items.length;
+    for (const [index, item] of items.entries()) {
+        const size = measure(item);
+        if (keptCharacters + size > maxCharacters) {
+            cut = index;
+            break;
+        }
+        kept.push(item);
+        keptCharacters += size;
+    }
+    const deferred = items.slice(cut);
+    const [next] = deferred;
+    return {
+        kept,
+        deferred,
+        keptCharacters,
+        ...(next !== undefined && { nextDeferredCharacters: measure(next) }),
+    };
+}
+//# sourceMappingURL=_budget.js.map

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

@@ -0,0 +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"}

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

@@ -1,6 +1,7 @@
 /**
- * @fileoverview Text-cutting helper shared by the tool definitions that bound
- * returned text to a character budget.
+ * @fileoverview Text helpers shared by the tool definitions: the surrogate-safe
+ * character cut used to bound returned text to a budget, and the render-time
+ * Markdown escape applied to upstream strings interpolated into `format()`.
  * @module src/mcp-server/tools/definitions/_text
  */
 /**
@@ -19,4 +20,28 @@
  * than assume the allowance was spent exactly. (#93)
  */
 export declare function sliceCodeUnits(text: string, limit: number): string;
+/**
+ * Escape the Markdown-significant characters in an upstream string that is
+ * about to be interpolated *inline* into a `format()` line — a `### `/`#### `
+ * heading or a `**Label:** ` line. Render-time only: the escaped form must
+ * never be written back into `structuredContent`, which is a contract over the
+ * plain-text value. (#102)
+ *
+ * Minimal by design, judged on what the reader actually sees rendered. Every
+ * Markdown construct here needs a partner delimiter to form, so a delimiter is
+ * escaped only when its partner is present: a lone `*` in `5*g`, a lone `~` in
+ * `~250`, and an intraword `_` in `TP53_mutant` are inert and stay legible.
+ * Escaping them would cost a reader of the raw text a stray backslash and buy
+ * nothing. What is escaped: a tag-shaped `<` (raw HTML and autolinks),
+ * pairable `` ` ``/`*`/`~`/`_`, every `[` and `]`, and the backslash itself,
+ * without which a trailing one in the source would neutralize the escape after
+ * it. Brackets get no pairing test: sibling label lines render as one
+ * paragraph, so a lone `[` in one field and a lone `]` in the next would still
+ * form a link.
+ *
+ * Line breaks collapse to a space. That is what keeps the value inline, and
+ * with it the reason `#`, `>`, and `-` need no escaping: they are structural
+ * only at the start of a line, and the value never reaches one.
+ */
+export declare function escapeMarkdownInline(text: string): string;
 //# sourceMappingURL=_text.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"_text.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/_text.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAMlE"}
+{"version":3,"file":"_text.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/_text.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAMlE;AA2CD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAazD"}

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

@@ -1,6 +1,7 @@
 /**
- * @fileoverview Text-cutting helper shared by the tool definitions that bound
- * returned text to a character budget.
+ * @fileoverview Text helpers shared by the tool definitions: the surrogate-safe
+ * character cut used to bound returned text to a budget, and the render-time
+ * Markdown escape applied to upstream strings interpolated into `format()`.
  * @module src/mcp-server/tools/definitions/_text
  */
 const HIGH_SURROGATE_FIRST = 0xd800;
@@ -29,4 +30,79 @@ export function sliceCodeUnits(text, limit) {
     const splitsPair = last >= HIGH_SURROGATE_FIRST && last <= HIGH_SURROGATE_LAST;
     return text.slice(0, splitsPair ? limit - 1 : limit);
 }
+/** Any line break, including the Unicode line and paragraph separators. */
+const LINE_BREAK_RE = /[\r\n\u2028\u2029]+/g;
+/**
+ * A `<` that opens something a Markdown renderer will read as raw HTML or an
+ * autolink: a tag-name start, then a body carrying no further angle bracket,
+ * then a closing `>`. Deliberately the same shape as `MARKUP_TAG_RE` in
+ * `text-helpers.ts` — a `<` with no `>` after it (`n<N`) or one followed by a
+ * digit (`P<0.001`) cannot open a tag and is left alone.
+ */
+const HTML_TAG_OPENER_RE = /<(?=[A-Za-z/!?][^<>]*>)/g;
+/** A character that makes an adjacent `_` intraword, where it cannot emphasize. */
+const WORD_CHAR_RE = /[0-9A-Za-z]/;
+function countOf(text, character) {
+    return text.split(character).length - 1;
+}
+function escapeEvery(text, pattern) {
+    return text.replace(pattern, (match) => `\\${match}`);
+}
+/**
+ * Positions of the `_` characters that could open or close emphasis. CommonMark
+ * forbids intraword `_` emphasis, so an underscore flanked by alphanumerics on
+ * both sides (`TP53_mutant`) is inert and stays unescaped.
+ */
+function pairableUnderscores(text) {
+    const positions = new Set();
+    for (let i = text.indexOf('_'); i !== -1; i = text.indexOf('_', i + 1)) {
+        const previous = text[i - 1];
+        const next = text[i + 1];
+        const intraword = previous !== undefined &&
+            next !== undefined &&
+            WORD_CHAR_RE.test(previous) &&
+            WORD_CHAR_RE.test(next);
+        if (!intraword)
+            positions.add(i);
+    }
+    return positions;
+}
+/**
+ * Escape the Markdown-significant characters in an upstream string that is
+ * about to be interpolated *inline* into a `format()` line — a `### `/`#### `
+ * heading or a `**Label:** ` line. Render-time only: the escaped form must
+ * never be written back into `structuredContent`, which is a contract over the
+ * plain-text value. (#102)
+ *
+ * Minimal by design, judged on what the reader actually sees rendered. Every
+ * Markdown construct here needs a partner delimiter to form, so a delimiter is
+ * escaped only when its partner is present: a lone `*` in `5*g`, a lone `~` in
+ * `~250`, and an intraword `_` in `TP53_mutant` are inert and stay legible.
+ * Escaping them would cost a reader of the raw text a stray backslash and buy
+ * nothing. What is escaped: a tag-shaped `<` (raw HTML and autolinks),
+ * pairable `` ` ``/`*`/`~`/`_`, every `[` and `]`, and the backslash itself,
+ * without which a trailing one in the source would neutralize the escape after
+ * it. Brackets get no pairing test: sibling label lines render as one
+ * paragraph, so a lone `[` in one field and a lone `]` in the next would still
+ * form a link.
+ *
+ * Line breaks collapse to a space. That is what keeps the value inline, and
+ * with it the reason `#`, `>`, and `-` need no escaping: they are structural
+ * only at the start of a line, and the value never reaches one.
+ */
+export function escapeMarkdownInline(text) {
+    let escaped = text.replace(LINE_BREAK_RE, ' ').replace(/\\/g, '\\\\');
+    escaped = escaped.replace(HTML_TAG_OPENER_RE, '\\<');
+    if (countOf(text, '`') >= 2)
+        escaped = escapeEvery(escaped, /`/g);
+    escaped = escapeEvery(escaped, /[[\]]/g);
+    if (countOf(text, '*') >= 2)
+        escaped = escapeEvery(escaped, /\*/g);
+    if (countOf(text, '~') >= 2)
+        escaped = escapeEvery(escaped, /~/g);
+    const pairable = pairableUnderscores(escaped);
+    if (pairable.size < 2)
+        return escaped;
+    return escaped.replace(/_/g, (underscore, index) => pairable.has(index) ? `\\${underscore}` : underscore);
+}
 //# sourceMappingURL=_text.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"_text.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/_text.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,oBAAoB,GAAG,MAAM,CAAC;AACpC,MAAM,mBAAmB,GAAG,MAAM,CAAC;AAEnC;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,KAAa;IACxD,IAAI,KAAK,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IAC1B,IAAI,KAAK,IAAI,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACtC,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;IACxC,MAAM,UAAU,GAAG,IAAI,IAAI,oBAAoB,IAAI,IAAI,IAAI,mBAAmB,CAAC;IAC/E,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;AACvD,CAAC"}
+{"version":3,"file":"_text.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/_text.ts"],"names":[],"mappings":"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"}

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

@@ -9,6 +9,7 @@ export declare const fetchArticlesTool: import("@cyanheads/mcp-ts-core").ToolDef
     pmids: z.ZodArray<z.ZodString>;
     includeMesh: z.ZodDefault<z.ZodBoolean>;
     includeGrants: z.ZodDefault<z.ZodBoolean>;
+    maxResponseCharacters: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>, z.ZodObject<{
     articles: z.ZodArray<z.ZodObject<{
         pmid: z.ZodOptional<z.ZodString>;
@@ -69,6 +70,13 @@ export declare const fetchArticlesTool: import("@cyanheads/mcp-ts-core").ToolDef
     }, z.core.$strip>>;
     totalReturned: z.ZodNumber;
     unavailablePmids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    deferred: z.ZodOptional<z.ZodObject<{
+        maxResponseCharacters: z.ZodNumber;
+        returnedCharacters: z.ZodNumber;
+        deferredCount: z.ZodNumber;
+        ids: z.ZodArray<z.ZodString>;
+        nextDeferredCharacters: z.ZodNumber;
+    }, z.core.$strip>>;
 }, z.core.$strip>, readonly [{
     readonly reason: 'queue_full';
     readonly code: JsonRpcErrorCode.RateLimited;
@@ -106,5 +114,6 @@ export declare const fetchArticlesTool: import("@cyanheads/mcp-ts-core").ToolDef
     readonly recovery: 'Retry once; if it persists, NCBI returned malformed data — try fewer PMIDs at once.';
 }], {
     readonly notice: z.ZodOptional<z.ZodString>;
+    readonly truncated: z.ZodOptional<z.ZodBoolean>;
 }>;
 //# sourceMappingURL=fetch-articles.tool.d.ts.map

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;;;;GAIG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AA8GjE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAWhB,yBAAyB;;mBAE3B,sEAAsE;uBAE1E,qFAAqF;;;EAsK3F,CAAC"}
+{"version":3,"file":"fetch-articles.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/fetch-articles.tool.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AA0IjE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAWhB,yBAAyB;;mBAE3B,sEAAsE;uBAE1E,qFAAqF;;;;EAqO3F,CAAC"}

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

@@ -9,8 +9,10 @@ import { NCBI_SERVICE_ERRORS } from '../../../services/error-contracts.js';
 import { getNcbiService } from '../../../services/ncbi/ncbi-service.js';
 import { parseFullArticle } from '../../../services/ncbi/parsing/article-parser.js';
 import { ensureArray } from '../../../services/ncbi/parsing/xml-helpers.js';
+import { fitWholeItems } from './_budget.js';
 import { conceptMeta, EDAM_DATA_RETRIEVAL, EDAM_PUBMED_ID, SCHEMA_SCHOLARLY_ARTICLE, } from './_concepts.js';
 import { pmidStringSchema } from './_schemas.js';
+import { escapeMarkdownInline } from './_text.js';
 const AuthorSchema = z
     .object({
     lastName: z.string().optional().describe('Last name'),
@@ -97,8 +99,27 @@ const FetchedArticleSchema = z
     articleDates: z.array(ArticleDateSchema).optional().describe('Article dates'),
 })
     .describe('Parsed PubMed article');
+const DeferredSchema = z
+    .object({
+    maxResponseCharacters: z
+        .number()
+        .describe('The `maxResponseCharacters` ceiling this response was budgeted against'),
+    returnedCharacters: z
+        .number()
+        .describe('Serialized characters the returned article records account for'),
+    deferredCount: z
+        .number()
+        .describe('Articles that resolved but were withheld to stay under the ceiling'),
+    ids: z
+        .array(z.string())
+        .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('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', {
-    description: 'Fetch full article metadata by PubMed IDs. Returns detailed article information including abstract, authors, journal, MeSH terms.',
+    description: 'Fetch full article metadata by PubMed IDs. Returns detailed article information including abstract, authors, journal, MeSH terms. Set `maxResponseCharacters` to bound the whole response: articles past the ceiling are deferred whole and listed in `deferred.ids` for a follow-up call.',
     annotations: { readOnlyHint: true, openWorldHint: true },
     _meta: conceptMeta([SCHEMA_SCHOLARLY_ARTICLE, EDAM_DATA_RETRIEVAL, EDAM_PUBMED_ID]),
     sourceUrl: 'https://github.com/cyanheads/pubmed-mcp-server/blob/main/src/mcp-server/tools/definitions/fetch-articles.tool.ts',
@@ -115,22 +136,37 @@ export const fetchArticlesTool = tool('pubmed_fetch_articles', {
         pmids: z.array(pmidStringSchema).min(1).max(200).describe('PubMed IDs to fetch'),
         includeMesh: z.boolean().default(true).describe('Include MeSH terms'),
         includeGrants: z.boolean().default(false).describe('Include grant information'),
+        maxResponseCharacters: z
+            .number()
+            .int()
+            .min(1)
+            .max(1_000_000)
+            .optional()
+            .describe('Opt-in ceiling for the whole response, in characters. Each article is measured as the JSON record it is returned as — title, abstract, authors, journal, MeSH terms, grants, identifiers, every field it carries. Articles are kept in response order until the next one would cross the ceiling; that article and the rest are deferred whole (never partially populated) and listed in `deferred.ids`. Response envelope fields — counts, `unavailablePmids`, `deferred` itself — are not counted. Omit to return every resolved article.'),
     }),
     output: z.object({
         articles: z.array(FetchedArticleSchema).describe('Parsed articles'),
-        totalReturned: z.number().describe('Number of articles returned'),
+        totalReturned: z
+            .number()
+            .describe('Number of articles in this response. Under a `maxResponseCharacters` budget this counts the kept articles only; `deferred.deferredCount` covers the rest.'),
         unavailablePmids: z
             .array(z.string())
             .optional()
-            .describe('PMIDs that returned no article data'),
+            .describe('PMIDs that returned no article data. Reported in full regardless of where a `maxResponseCharacters` cutoff lands — these are misses, not deferrals, and re-requesting them returns nothing.'),
+        deferred: DeferredSchema.optional(),
     }),
-    // Recovery guidance when no articles are returned — agent-facing context, surfaced via
-    // ctx.enrich.notice() to both structuredContent and content[]; absent on success.
+    // Recovery guidance for two cases — no articles returned at all, and articles
+    // the whole-response budget deferred (#99). Agent-facing context surfaced via
+    // ctx.enrich to both structuredContent and content[]; absent on a plain success.
     enrichment: {
         notice: z
             .string()
             .optional()
-            .describe('Optional guidance when no articles were returned — points to discovery tools. Absent on successful fetches.'),
+            .describe('Optional guidance when no articles were returned — points to discovery tools — or when `maxResponseCharacters` deferred articles, naming how to retrieve them. Absent on successful unbudgeted fetches.'),
+        truncated: z
+            .boolean()
+            .optional()
+            .describe('True when `maxResponseCharacters` withheld at least one resolved article. Absent when the response carries every article that resolved. The continuation state is in `deferred`.'),
     },
     async handler(input, ctx) {
         ctx.log.info('Executing pubmed_fetch', { pmidCount: input.pmids.length });
@@ -157,17 +193,46 @@ export const fetchArticlesTool = tool('pubmed_fetch_articles', {
         });
         const returnedPmids = new Set(articles.map((a) => a.pmid).filter(Boolean));
         const unavailable = input.pmids.filter((id) => !returnedPmids.has(id));
+        // Whole-response budget: fill with complete records in response order and
+        // hand the remainder back as PMIDs the caller can re-submit. Without
+        // `maxResponseCharacters` nothing is measured and the response is exactly
+        // what it was before the budget existed. (#99)
+        const ceiling = input.maxResponseCharacters;
+        const fit = ceiling === undefined ? undefined : fitWholeItems(articles, ceiling);
+        const returned = fit?.kept ?? articles;
+        const nextDeferredCharacters = fit?.nextDeferredCharacters;
+        // A record whose PMID never parsed is already reported in `unavailablePmids`
+        // and is not something a caller can re-request, so it is not deferrable —
+        // the count is the list's length so the two can never disagree.
+        const deferredIds = (fit?.deferred ?? []).map((a) => a.pmid).filter((id) => id.length > 0);
+        const deferred = ceiling !== undefined && fit && nextDeferredCharacters !== undefined
+            ? {
+                maxResponseCharacters: ceiling,
+                returnedCharacters: fit.keptCharacters,
+                deferredCount: deferredIds.length,
+                ids: deferredIds,
+                nextDeferredCharacters,
+            }
+            : undefined;
         ctx.log.info('pubmed_fetch completed', {
             requested: input.pmids.length,
-            returned: articles.length,
+            returned: returned.length,
+            ...(deferred && { deferred: deferred.deferredCount }),
         });
+        // Keyed on what resolved, not on what the budget kept: a batch emptied by a
+        // small ceiling is a budget outcome, not a batch of invalid PMIDs.
         if (articles.length === 0) {
             ctx.enrich.notice('No articles were returned. These PMIDs may be invalid, unpublished, or withdrawn. Try pubmed_search_articles to discover valid PMIDs.');
         }
+        if (deferred) {
+            ctx.enrich({ truncated: true });
+            ctx.enrich.notice(buildDeferralNotice(deferred));
+        }
         return {
-            articles,
-            totalReturned: articles.length,
+            articles: returned,
+            totalReturned: returned.length,
             ...(unavailable.length > 0 && { unavailablePmids: unavailable }),
+            ...(deferred && { deferred }),
         };
     },
     format: (result) => {
@@ -175,8 +240,14 @@ export const fetchArticlesTool = tool('pubmed_fetch_articles', {
         if (result.unavailablePmids?.length) {
             lines.push(`**Unavailable PMIDs:** ${result.unavailablePmids.join(', ')}`);
         }
+        if (result.deferred) {
+            const d = result.deferred;
+            lines.push(`**Deferred by the response budget:** ${d.deferredCount} article(s) — ${d.returnedCharacters} of ${d.maxResponseCharacters} budgeted characters returned; next deferred article ${d.nextDeferredCharacters} characters`, `Re-call \`pubmed_fetch_articles\` with these PMIDs: ${d.ids.join(', ')}`);
+        }
         for (const a of result.articles) {
-            lines.push(`\n### ${a.title ?? a.pmid ?? 'Unknown'}`);
+            // 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')}`);
             if (a.authors?.length) {
                 lines.push(`\n**Authors (${a.authors.length}):**`);
                 for (const au of a.authors) {
@@ -262,6 +333,18 @@ 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
+        ? `No article fits 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)