@cyanheads/pubmed-mcp-server 2.10.16 → 2.10.17

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

@@ -3,39 +3,58 @@
  * three-stage chain: NCBI PMC EFetch → Europe PMC `fullTextXML` → Unpaywall.
  * Accepts three mutually-exclusive input shapes:
  *
- *   - `pmcids` — fetch directly by PMC ID. Articles not in PMC fall through to
- *     EPMC by PMC ID, then to Unpaywall when the DOI is available.
+ *   - `pmcids` — fetch directly by PMC ID, once per record however it is
+ *     spelled (`PMC123`, `pmc123`, `123`, zero-padded `PMC0123`), and reported
+ *     in `PMC<digits>` form. Articles not in PMC fall through to EPMC by PMC ID,
+ *     then to Unpaywall when the DOI is available.
  *   - `pmids` — resolve PMID → PMCID via PMC ID Converter, then run the chain.
  *     A zero-padded PMID runs as the PMID it spells; `unavailable[]` and
  *     `deferred.ids` report it as the caller wrote it.
  *   - `dois` — resolve DOI → PMCID via the PMC ID Converter (mirroring `pmids`),
  *     then run the chain. DOIs with no PMC counterpart fall through to EPMC
  *     search-by-DOI → fullTextXML, then Unpaywall (EPMC-only OA, preprints).
+ *     DOIs are case-insensitive: every casing of one DOI runs the chain once,
+ *     and `unavailable[]` reports each casing as the caller wrote it.
  *
  * Output uses a discriminated union on `source` (`pmc` | `unpaywall`) with an
  * extra `viaSource` discriminator that records which layer produced the
  * content. EPMC's JATS reuses the `pmc` schema shape because it's the same
- * DTD; `viaSource: 'europepmc'` distinguishes it from PMC EFetch output.
+ * DTD; `viaSource: 'europepmc'` distinguishes it from PMC EFetch output. An
+ * Unpaywall article takes its title from Unpaywall's record, else the Europe
+ * PMC record the chain searched, else (HTML only) the page itself.
+ *
+ * Europe PMC and Unpaywall failures are folded into each id's `triedTiers`
+ * rather than thrown, so the declared `errors[]` covers the NCBI ID routing
+ * alone.
  *
  * @module src/mcp-server/tools/definitions/fetch-fulltext.tool
  */
 import { tool, z } from '@cyanheads/mcp-ts-core';
 import { htmlExtractor, pdfParser } from '@cyanheads/mcp-ts-core/utils';
 import { getServerConfig } from '../../../config/server-config.js';
-import { EUROPEPMC_SERVICE_ERRORS, NCBI_SERVICE_ERRORS, UNPAYWALL_SERVICE_ERRORS, } from '../../../services/error-contracts.js';
+import { NCBI_SERVICE_ERRORS } from '../../../services/error-contracts.js';
 import { getEuropePmcService, } from '../../../services/europe-pmc/europe-pmc-service.js';
 import { getNcbiService } from '../../../services/ncbi/ncbi-service.js';
 import { extractDoi, extractPmid } from '../../../services/ncbi/parsing/article-parser.js';
 import { parsePmcArticle } from '../../../services/ncbi/parsing/pmc-article-parser.js';
 import { findAll, findOne } from '../../../services/ncbi/parsing/pmc-xml-helpers.js';
+import { toDisplayText } from '../../../services/ncbi/parsing/text-helpers.js';
 import { ensureArray } from '../../../services/ncbi/parsing/xml-helpers.js';
 import { getUnpaywallService, } from '../../../services/unpaywall/unpaywall-service.js';
 import { fitWholeItems } from './_budget.js';
 import { conceptMeta, EDAM_DATA_RETRIEVAL, SCHEMA_SCHOLARLY_ARTICLE } from './_concepts.js';
 import { doiStringSchema, normalizePmid, pmcidStringSchema, pmidStringSchema } from './_schemas.js';
-import { escapeMarkdownInline, escapeMarkdownTableCell, sliceCodeUnits } from './_text.js';
+import { escapeMarkdownInline, escapeMarkdownTableCell, sliceAtWordBoundary } from './_text.js';
+/**
+ * Canonical digits of a PMC ID {@link pmcidStringSchema} accepted: the `PMC`
+ * prefix dropped in any case, and leading zeros stripped the way
+ * {@link normalizePmid} strips them. PMC EFetch reads `03531190` as PMC3531190
+ * and answers with that record, so every `pmcids` path keys on this form — and
+ * reports it back as `PMC<digits>`. An all-zero ID keeps `0`, which EFetch
+ * still answers with its empty-list envelope. (#170)
+ */
 function normalizePmcId(id) {
-    return id.replace(/^PMC/i, '');
+    return normalizePmid(id.replace(/^PMC/i, ''));
 }
 function withPmcPrefix(id) {
     return id.startsWith('PMC') ? id : `PMC${id}`;
@@ -540,7 +559,18 @@ const UnpaywallArticleSchema = z
     pubmedUrl: z.string().optional().describe('PubMed URL — present when `pmid` is set'),
     doi: z.string().describe('DOI used to locate the open-access copy'),
     sourceUrl: z.string().describe('URL the content was fetched from'),
-    title: z.string().optional().describe('Detected article title when present'),
+    title: z
+        .string()
+        .optional()
+        .describe("Article title, from the first source that carries one: Unpaywall's record for the DOI, then the Europe PMC record when the chain searched Europe PMC for this id, then — for `html-markdown` content only — the title detected on the page. Absent when none of them has a title."),
+    journalName: z
+        .string()
+        .optional()
+        .describe("Journal or repository name from Unpaywall's record for the DOI (e.g. `medRxiv` for a medRxiv preprint). Absent when Unpaywall has none."),
+    year: z
+        .number()
+        .optional()
+        .describe("Publication year from Unpaywall's record for the DOI. Absent when Unpaywall has none."),
     content: z.string().describe('Full article text — Markdown or plain text per `contentFormat`'),
     wordCount: z
         .number()
@@ -619,18 +649,54 @@ const UnavailableSchema = z
 })
     .describe('One identifier that could not be returned, with the full chain it traversed');
 // ─── Character-budget schemas ────────────────────────────────────────────────
+/**
+ * Character accounting for one subsection. Its own type rather than a
+ * self-reference for the reason {@link SubsectionSchema} is inlined: a
+ * `z.lazy()` schema emits `$defs`/`$ref`. The article schema carries sections
+ * two levels deep, so the ledger does too.
+ *
+ * The chain `truncation` → `articles[]` → `sections[]` → `subsections[]` → a
+ * leaf is eight schema hops, the most the `format-parity` sentinel walker
+ * reaches. Re-run `bun run lint:mcp` after any change to this shape. (#143)
+ */
+const TruncatedSubsectionSchema = z
+    .object({
+    title: z.string().optional().describe('Subsection heading, when the subsection carries one'),
+    label: z
+        .string()
+        .optional()
+        .describe('Subsection label as printed (e.g. `2.1`), when the subsection carries one'),
+    originalCharacters: z
+        .number()
+        .describe('Body characters this subsection carried before the budget pass'),
+    returnedCharacters: z
+        .number()
+        .describe('Body characters this subsection carries in the response. Zero means it was dropped in `truncate` mode and counted in `omittedSections`, or kept as a heading-only entry in `outline` mode, marked as such in the rendered text.'),
+    truncated: z
+        .boolean()
+        .describe('True when the subsection returned fewer characters than it originally carried'),
+})
+    .describe('Character accounting for one subsection of a shortened section');
 const TruncatedSectionSchema = z
     .object({
     title: z.string().optional().describe('Section heading, when the section carries one'),
+    label: z
+        .string()
+        .optional()
+        .describe('Section label as printed (e.g. `2`), when the section carries one'),
     originalCharacters: z
         .number()
         .describe('Body characters this section carried before the budget pass'),
     returnedCharacters: z
         .number()
-        .describe('Body characters this section carries in the response. Zero means the section was dropped in `truncate` mode, or kept as a heading-only entry in `outline` mode.'),
+        .describe('Body characters this section carries in the response. Zero means the section was dropped in `truncate` mode, or kept as a heading-only entry in `outline` mode, marked as such in the rendered text.'),
     truncated: z
         .boolean()
         .describe('True when the section returned fewer characters than it originally carried'),
+    subsections: z
+        .array(TruncatedSubsectionSchema)
+        .optional()
+        .describe('Per-subsection accounting for a shortened section, in document order, including subsections dropped for budget — where inside the section the cut landed. Absent when the section was returned whole or carries no subsections.'),
 })
     .describe('Character accounting for one body section of a budgeted article');
 const TruncatedArticleSchema = z
@@ -648,7 +714,7 @@ const TruncatedArticleSchema = z
     sections: z
         .array(TruncatedSectionSchema)
         .optional()
-        .describe('Per-section accounting for `source: pmc` articles, in document order, including sections dropped for budget. Absent for `source: unpaywall`, whose body has no section structure.'),
+        .describe('Per-section accounting for `source: pmc` articles, in document order, including sections dropped for budget; a shortened section lists its subsections. Absent for `source: unpaywall`, whose body has no section structure.'),
     omittedTables: z
         .number()
         .optional()
@@ -685,7 +751,7 @@ const TruncationSchema = z
         .describe('Body characters the shortened articles carry in this response'),
     omittedSections: z
         .number()
-        .describe('Body sections dropped entirely because an article budget was exhausted before reaching them. Always 0 in `outline` mode, which keeps every heading.'),
+        .describe('Body sections and subsections dropped entirely because an article budget was exhausted before reaching them. A dropped section counts once, together with its subsections. Always 0 in `outline` mode, which keeps every heading.'),
     omittedTables: z
         .number()
         .optional()
@@ -786,30 +852,81 @@ function fitWholeNamed(items, allowance, measure, name) {
     };
 }
 /**
- * Rebuild a section subtree from `fitted`, consuming one entry per node in the
- * same document order {@link sectionTextFields} produced them. `cursor` walks
- * the flat list across the whole subtree.
+ * True when the budget emptied a node that had text — which `truncate` mode
+ * drops, at any depth, and `outline` mode keeps as a heading-only entry. A node
+ * that never carried text is kept either way: there was nothing to cut.
+ */
+function isBudgetEmptied(entry) {
+    return entry.returnedCharacters === 0 && entry.originalCharacters > 0;
+}
+/**
+ * Sections and subsections `truncate` mode dropped, read off the ledger. A
+ * dropped node counts once and takes its subtree with it, so its subsections
+ * are not counted again. Shared by the budget pass and the deferral roll-back
+ * so both count by one rule. (#81, #143)
+ */
+function countDroppedSections(entries, mode) {
+    if (mode !== 'truncate')
+        return 0;
+    return entries.reduce((n, entry) => n + (isBudgetEmptied(entry) ? 1 : countDroppedSections(entry.subsections ?? [], mode)), 0);
+}
+/**
+ * Rebuild a section subtree from `fitted` — one entry per node, in the document
+ * order {@link sectionTextFields} produced them, `cursor` walking the flat list
+ * across the whole subtree — together with its ledger entry.
+ *
+ * In `truncate` mode a node the budget emptied is dropped (`kept` is absent) at
+ * every depth, where only a top-level section used to be: a subsection left as
+ * a heading over nothing is a stub, not content. `outline` mode keeps it, and
+ * `format()` marks it. The entry lists its subsections only when this node was
+ * shortened, which is where they say something a whole section's entry does
+ * not. (#81, #143)
  */
-function withFittedTexts(section, fitted, cursor) {
+function fitSectionTree(section, fitted, cursor, mode) {
     const text = fitted[cursor.i++] ?? '';
-    const subsections = section.subsections?.map((sub) => withFittedTexts(sub, fitted, cursor));
-    return { ...section, text, ...(subsections && { subsections }) };
+    const children = (section.subsections ?? []).map((sub) => fitSectionTree(sub, fitted, cursor, mode));
+    const originalCharacters = sectionCharacters(section);
+    const returnedCharacters = children.reduce((n, child) => n + child.entry.returnedCharacters, text.length);
+    const truncated = returnedCharacters < originalCharacters;
+    const entry = {
+        ...(section.title !== undefined && { title: section.title }),
+        ...(section.label !== undefined && { label: section.label }),
+        originalCharacters,
+        returnedCharacters,
+        truncated,
+        ...(truncated && children.length > 0 && { subsections: children.map((c) => c.entry) }),
+    };
+    if (mode === 'truncate' && isBudgetEmptied(entry))
+        return { entry };
+    const { subsections: _replaced, ...rest } = section;
+    const subsections = children.flatMap((child) => (child.kept ? [child.kept] : []));
+    return {
+        entry,
+        kept: { ...rest, text, ...(subsections.length > 0 && { subsections }) },
+    };
 }
 /**
  * Shorten an ordered list of text fields so their combined length fits
- * `allowance`. Fields are filled in order, so earlier fields survive whole and
- * later ones absorb the shortfall — the section's own text before its
- * subsections. Cuts at the character boundary with no appended marker so the
- * reported `returnedCharacters` is exact; `format()` carries the human-visible
- * note. A cut that would split a surrogate pair backs off a code unit, so a
- * field can return one character under its share — counts are measured off the
- * returned text, never off the allowance. (#93)
+ * `allowance`. Fields are filled in order, so earlier fields survive whole — the
+ * section's own text before its subsections — and the first field that does not
+ * fit is cut at the last word boundary inside what is left. Every field after
+ * that cut is past it and returns empty, the way a top-level section past the
+ * budget does, even when the cut left a few characters unspent: handing those
+ * on would open the next subsection with a fragment of its first word. (#143)
+ *
+ * No marker is appended, so the reported `returnedCharacters` is exact;
+ * `format()` carries the human-visible note. Counts are measured off the
+ * returned text, never off the allowance, which stays a ceiling. (#93)
  */
 function fitFields(fields, allowance) {
     let remaining = Math.max(allowance, 0);
     return fields.map((text) => {
-        const kept = sliceCodeUnits(text, remaining);
-        remaining -= kept.length;
+        if (text.length <= remaining) {
+            remaining -= text.length;
+            return text;
+        }
+        const kept = sliceAtWordBoundary(text, remaining);
+        remaining = 0;
         return kept;
     });
 }
@@ -882,10 +999,10 @@ function allotSectionBudgets(sizes, budget) {
  * nothing bounds either list and every entry is kept. (#111, #130)
  *
  * Returns the article untouched (same object identity) when no budget was
- * requested or nothing exceeded it. A section left with zero characters is
- * dropped in `truncate` mode and counted as omitted; `outline` keeps it as a
- * heading-only entry. Dropped sections still appear in the accounting so the
- * caller can see which headings exist. (#81)
+ * requested or nothing exceeded it. A section or subsection left with zero
+ * characters is dropped in `truncate` mode and counted as omitted; `outline`
+ * keeps it as a heading-only entry. Dropped nodes still appear in the accounting
+ * so the caller can see which headings exist. (#81, #143)
  */
 function applyPmcBudget(article, budget) {
     const tables = article.tables ?? [];
@@ -901,25 +1018,16 @@ function applyPmcBudget(article, budget) {
     const allowances = allotSectionBudgets(sizes, budget);
     const kept = [];
     const sectionReports = [];
-    let omittedSections = 0;
     let returnedCharacters = 0;
     article.sections.forEach((section, i) => {
-        const original = sizes[i] ?? 0;
         const fitted = fitFields(sectionTextFields(section), allowances[i] ?? 0);
-        const returned = totalLength(fitted);
-        returnedCharacters += returned;
-        sectionReports.push({
-            ...(section.title !== undefined && { title: section.title }),
-            originalCharacters: original,
-            returnedCharacters: returned,
-            truncated: returned < original,
-        });
-        if (returned === 0 && original > 0 && budget.overflowMode === 'truncate') {
-            omittedSections += 1;
-            return;
-        }
-        kept.push(withFittedTexts(section, fitted, { i: 0 }));
+        const fit = fitSectionTree(section, fitted, { i: 0 }, budget.overflowMode);
+        returnedCharacters += fit.entry.returnedCharacters;
+        sectionReports.push(fit.entry);
+        if (fit.kept)
+            kept.push(fit.kept);
     });
+    const omittedSections = countDroppedSections(sectionReports, budget.overflowMode);
     // Sections are served first, then tables, then assets — each spending whatever
     // `maxCharacters` has left. A bare per-section budget sets no total, so nothing
     // bounds either list.
@@ -960,13 +1068,13 @@ function applyPmcBudget(article, budget) {
  * Apply the character budget to an Unpaywall body. That body is one
  * unstructured blob — HTML-as-Markdown or PDF-as-text — so only `maxCharacters`
  * applies, and `outline` mode has no headings to preserve and behaves like
- * `truncate`. (#81)
+ * `truncate`. The cut ends at a word boundary, as a section cut does. (#81, #143)
  */
 function applyContentBudget(content, budget) {
     const cap = budget.maxCharacters;
     if (cap === undefined || content.length <= cap)
         return { content };
-    const kept = sliceCodeUnits(content, cap);
+    const kept = sliceAtWordBoundary(content, cap);
     return {
         content: kept,
         truncation: { originalCharacters: content.length, returnedCharacters: kept.length },
@@ -1075,17 +1183,6 @@ function buildDeferralNotice(deferred) {
         : `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_fulltext with those ids under \`${deferred.idType}s\` to retrieve them, or raise maxResponseCharacters to at least ${deferred.nextDeferredCharacters} — the size of the next deferred article.`;
 }
-/**
- * Body sections an article's per-article budget dropped, derived from that
- * article's own accounting by the rule {@link applyPmcBudget} counts by:
- * `outline` mode keeps every heading, so it drops none. Used to take a deferred
- * article's contribution back out of the response-level roll-up. (#100)
- */
-function countOmittedSections(entry, mode) {
-    if (mode !== 'truncate')
-        return 0;
-    return (entry.sections ?? []).filter((s) => s.originalCharacters > 0 && s.returnedCharacters === 0).length;
-}
 // ─── Tool Definition ─────────────────────────────────────────────────────────
 /**
  * Compose the tool description for the fallback tiers enabled in this
@@ -1132,11 +1229,11 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
     annotations: { readOnlyHint: true, openWorldHint: true },
     _meta: conceptMeta([SCHEMA_SCHOLARLY_ARTICLE, EDAM_DATA_RETRIEVAL]),
     sourceUrl: 'https://github.com/cyanheads/pubmed-mcp-server/blob/main/src/mcp-server/tools/definitions/fetch-fulltext.tool.ts',
-    errors: [
-        ...NCBI_SERVICE_ERRORS,
-        ...UNPAYWALL_SERVICE_ERRORS,
-        ...EUROPEPMC_SERVICE_ERRORS,
-    ],
+    // Only the ID routing's `idConvert` calls run unwrapped. Every Europe PMC and
+    // Unpaywall call sits behind a catch that folds the failure into
+    // `unavailable[].triedTiers`, so their service reasons never reach a caller
+    // and are not declared here. (#168)
+    errors: [...NCBI_SERVICE_ERRORS],
     input: z
         .object({
         pmcids: z
@@ -1186,7 +1283,7 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
             .min(1)
             .max(1_000_000)
             .optional()
-            .describe('Per-article budget for body text, in characters. Counts `source=pmc` section and subsection text — which carries the inline blocks the parser renders in place, such as lists, definition lists, block quotes, boxed text, preformatted blocks and displayed formulae — plus table label, caption, cell and footnote text and asset label, caption and `href` text; or the `source=unpaywall` `content` body. Titles, abstracts, identifiers, and references are never counted or shortened. The counted unit is that text alone — the Markdown grid `content[]` renders around the cells (pipes, padding, the divider row, headings) is scaffolding this budget does not measure, so a table renders longer than it costs here. Sections are served first, then tables, then assets, each spending what is left, in document order — admission stops at the first entry that does not fit, and every entry from there on is dropped whole rather than cut mid-row or returned with a shortened caption, counted in `truncation.omittedTables` / `truncation.omittedAssets` and named in `truncation.articles[].omittedTableNames` / `omittedAssetNames`. Applied after `sections`, `maxSections`, `includeReferences`, `includeTables`, and `includeAssets`, so semantic filtering is unaffected. This knob alone bounds only bodies: the response-wide ceiling it implies is this value times the number of articles returned, plus every uncounted field. Use `maxResponseCharacters` for a true whole-response ceiling. Omit for the full body.'),
+            .describe('Per-article budget for body text, in characters. Counts `source=pmc` section and subsection text — which carries the inline blocks the parser renders in place, such as lists, definition lists, block quotes, boxed text, preformatted blocks and displayed formulae — plus table label, caption, cell and footnote text and asset label, caption and `href` text; or the `source=unpaywall` `content` body. Titles, abstracts, identifiers, and references are never counted or shortened. Shortened text ends at the last word boundary inside its allowance, so it can come back a few characters under it. The counted unit is that text alone — the Markdown grid `content[]` renders around the cells (pipes, padding, the divider row, headings) is scaffolding this budget does not measure, so a table renders longer than it costs here. Sections are served first, then tables, then assets, each spending what is left, in document order — admission stops at the first entry that does not fit, and every entry from there on is dropped whole rather than cut mid-row or returned with a shortened caption, counted in `truncation.omittedTables` / `truncation.omittedAssets` and named in `truncation.articles[].omittedTableNames` / `omittedAssetNames`. Applied after `sections`, `maxSections`, `includeReferences`, `includeTables`, and `includeAssets`, so semantic filtering is unaffected. This knob alone bounds only bodies: the response-wide ceiling it implies is this value times the number of articles returned, plus every uncounted field. Use `maxResponseCharacters` for a true whole-response ceiling. Omit for the full body.'),
         maxCharactersPerSection: z
             .number()
             .int()
@@ -1204,7 +1301,7 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
         overflowMode: z
             .enum(['truncate', 'outline'])
             .default('truncate')
-            .describe('How to spend `maxCharacters` across an article that exceeds it. truncate: fill sections in document order, so early sections stay whole and sections past the budget are dropped (counted in `truncation.omittedSections`). outline: split the budget evenly so every section keeps its heading, and an excerpt as far as the budget reaches — use it to survey what an article contains before requesting specific `sections`. Ignored when no budget is set, and identical for `source=unpaywall` bodies, which have no headings to preserve.'),
+            .describe('How to spend `maxCharacters` across an article that exceeds it. truncate: fill sections in document order, so early sections stay whole, the section the budget runs out in is cut, and every section or subsection past that point is dropped (counted in `truncation.omittedSections`). outline: split the budget evenly so every section and subsection keeps its heading, and an excerpt as far as the budget reaches — a heading the budget left empty is marked as such in the rendered text. Use it to survey what an article contains before requesting specific `sections`. Ignored when no budget is set, and identical for `source=unpaywall` bodies, which have no headings to preserve.'),
     })
         .refine((v) => [v.pmcids, v.pmids, v.dois].filter((b) => b !== undefined).length === 1, {
         message: 'Provide exactly one of `pmcids`, `pmids`, or `dois` (not zero, not more).',
@@ -1289,10 +1386,18 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
         // carry — a `pmids` request recovers articles keyed by PMCID. (#100)
         const inputIdByArticle = new Map();
         // The caller's own spellings of each chain key, so `unavailable[]` and
-        // `deferred.ids` report what was submitted. Only the `pmids` branch fills
-        // it — a PMID's chain runs on its canonical form — and any other key is its
-        // own spelling. (#161)
+        // `deferred.ids` report what was submitted. The `pmids` branch fills it — a
+        // PMID's chain runs on its canonical form — and so does the `dois` branch,
+        // whose chain runs once per DOI however many casings name it. Both also
+        // fold in an input id that resolves to a PMC record another one already
+        // claimed (see `routeToPmc`). Any other key is its own spelling. (#161, #166)
         const callerIds = new Map();
+        const addCallerId = (key, spelling) => {
+            const spellings = callerIds.get(key) ?? [];
+            if (!spellings.includes(spelling))
+                spellings.push(spelling);
+            callerIds.set(key, spellings);
+        };
         const budget = {
             overflowMode: input.overflowMode,
             ...(input.maxCharacters !== undefined && { maxCharacters: input.maxCharacters }),
@@ -1306,17 +1411,34 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
         let pmidFallbackCandidates = [];
         let pmcidFallbackCandidates = [];
         let doiCandidates = [];
+        // Send a converter-resolved PMCID to PMC EFetch under the input id that
+        // named it. A second input id the converter places on the same PMC record
+        // — two DOIs for one article — joins the first one's chain as another
+        // spelling of it: the record is fetched once, and both ids are recovered,
+        // or reported unavailable with that chain, rather than the later id taking
+        // the PMCID over and leaving the earlier one with an empty chain.
+        const routeToPmc = (inputId, pmcid) => {
+            const normalized = normalizePmcId(pmcid);
+            const prefixed = withPmcPrefix(normalized);
+            const owner = pmcidToInputId.get(prefixed);
+            if (owner === undefined) {
+                pmcIds.push(normalized);
+                pmcidToInputId.set(prefixed, inputId);
+                return;
+            }
+            if (owner === inputId)
+                return;
+            for (const spelling of callerIds.get(inputId) ?? [inputId])
+                addCallerId(owner, spelling);
+            callerIds.delete(inputId);
+            chainByInput.delete(inputId);
+        };
         if (input.pmids) {
             // The ID Converter parses `00000001` as PMID 1 yet reports it "not found
             // in PMC", and every later stage answers with NCBI's own PMID, so the chain
             // runs once per distinct PMID in its canonical form. (#161)
-            for (const id of input.pmids) {
-                const pmid = normalizePmid(id);
-                const spellings = callerIds.get(pmid) ?? [];
-                if (!spellings.includes(id))
-                    spellings.push(id);
-                callerIds.set(pmid, spellings);
-            }
+            for (const id of input.pmids)
+                addCallerId(normalizePmid(id), id);
             const pmids = [...callerIds.keys()];
             for (const id of pmids)
                 chainByInput.set(id, []);
@@ -1328,9 +1450,7 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
                 const pmid = String(r.pmid);
                 seen.add(pmid);
                 if (r.pmcid) {
-                    const normalized = normalizePmcId(String(r.pmcid));
-                    pmcIds.push(normalized);
-                    pmcidToInputId.set(withPmcPrefix(normalized), pmid);
+                    routeToPmc(pmid, String(r.pmcid));
                     pmidContext.set(pmid, { pmid, ...(r.doi && { doi: r.doi }) });
                 }
                 else {
@@ -1354,31 +1474,42 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
             }
         }
         else if (input.pmcids) {
-            for (const id of input.pmcids)
-                chainByInput.set(withPmcPrefix(normalizePmcId(id)), []);
-            pmcIds = input.pmcids.map(normalizePmcId);
+            // `PMC123`, `pmc123`, `123` and `PMC0123` name one record; it runs the
+            // chain once. (#170)
+            pmcIds = [...new Set(input.pmcids.map(normalizePmcId))];
+            for (const id of pmcIds)
+                chainByInput.set(withPmcPrefix(id), []);
         }
         else if (input.dois) {
             // Mirror the `pmids` branch: resolve DOI → PMCID via the PMC ID Converter
             // so PMC-indexed DOIs reach PMC EFetch instead of going straight to the
             // EPMC/Unpaywall fallback (which misses articles whose only OA copy is the
             // PMC JATS). DOIs the converter can't place in PMC seed `doiCandidates`.
-            const requestedDois = new Set(input.dois);
-            for (const doi of input.dois)
+            //
+            // DOIs are case-insensitive, and the converter echoes one casing in
+            // `requested-id` for DOIs that differ only in case, so every casing of a
+            // DOI shares one chain, keyed by the first spelling submitted, and
+            // converter records are matched to it case-insensitively. (#166)
+            const chainKeyByDoi = new Map();
+            for (const doi of input.dois) {
+                const key = chainKeyByDoi.get(doi.toLowerCase()) ?? doi;
+                chainKeyByDoi.set(doi.toLowerCase(), key);
+                addCallerId(key, doi);
+            }
+            const dois = [...callerIds.keys()];
+            for (const doi of dois)
                 chainByInput.set(doi, []);
-            const records = await getNcbiService().idConvert(input.dois, 'doi', ctx.signal ? { signal: ctx.signal } : undefined);
+            const records = await getNcbiService().idConvert(dois, 'doi', ctx.signal ? { signal: ctx.signal } : undefined);
             const seen = new Set();
             for (const r of records) {
-                // The converter echoes the submitted id verbatim in `requested-id`;
-                // match on it, not `r.doi` (DOIs aren't case-stable across the API).
-                const doi = String(r['requested-id']);
-                if (!requestedDois.has(doi))
+                // Match on the echoed `requested-id`, not `r.doi`: the record's own DOI
+                // can be cased differently from anything the caller sent.
+                const doi = chainKeyByDoi.get(String(r['requested-id']).toLowerCase());
+                if (doi === undefined)
                     continue;
                 seen.add(doi);
                 if (r.pmcid) {
-                    const normalized = normalizePmcId(String(r.pmcid));
-                    pmcIds.push(normalized);
-                    pmcidToInputId.set(withPmcPrefix(normalized), doi);
+                    routeToPmc(doi, String(r.pmcid));
                 }
                 else {
                     chainByInput.get(doi)?.push({
@@ -1389,7 +1520,7 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
                     doiCandidates.push({ doi });
                 }
             }
-            for (const requested of input.dois) {
+            for (const requested of dois) {
                 if (!seen.has(requested)) {
                     chainByInput.get(requested)?.push({
                         tier: 'pmc',
@@ -1662,7 +1793,7 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
                     return {
                         pmcId,
                         result: candidate.doi
-                            ? await resolveUnpaywall({ pmcId, doi: candidate.doi, budget }, unpaywall, ctx)
+                            ? await resolveUnpaywall({ pmcId, doi: candidate.doi, epmcTitle: candidate.title, budget }, unpaywall, ctx)
                             : undefined,
                     };
                 }));
@@ -1734,7 +1865,7 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
                 const outcomes = await Promise.all(pmidFallbackCandidates.map(async (candidate) => ({
                     candidate,
                     result: candidate.doi
-                        ? await resolveUnpaywall({ pmid: candidate.pmid, doi: candidate.doi, budget }, unpaywall, ctx)
+                        ? await resolveUnpaywall({ pmid: candidate.pmid, doi: candidate.doi, epmcTitle: candidate.title, budget }, unpaywall, ctx)
                         : undefined,
                 })));
                 for (const { candidate, result } of outcomes) {
@@ -1777,7 +1908,7 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
                 // doesn't reject under normal operation.
                 const outcomes = await Promise.all(doiCandidates.map(async (c) => ({
                     doi: c.doi,
-                    result: await resolveUnpaywall({ doi: c.doi, budget }, unpaywall, ctx),
+                    result: await resolveUnpaywall({ doi: c.doi, epmcTitle: c.title, budget }, unpaywall, ctx),
                 })));
                 for (const { doi, result } of outcomes) {
                     if ('article' in result) {
@@ -1848,8 +1979,9 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
                 if (index === -1)
                     continue;
                 const [dropped] = truncatedArticles.splice(index, 1);
-                if (dropped)
-                    omittedSections -= countOmittedSections(dropped, input.overflowMode);
+                if (dropped) {
+                    omittedSections -= countDroppedSections(dropped.sections ?? [], input.overflowMode);
+                }
             }
         }
         ctx.log.info('pubmed_fetch_fulltext completed', {
@@ -1957,13 +2089,29 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
             lines.push('');
             const t = truncationById.get(articleDisplayId(a));
             if (a.source === 'pmc')
-                formatPmcArticle(a, lines, t);
+                formatPmcArticle(a, lines, t, result.truncation?.mode);
             else
                 formatUnpaywallArticle(a, lines, t);
         }
         return [{ type: 'text', text: lines.join('\n') }];
     },
 });
+/**
+ * Merge what a Europe PMC hit carried onto a candidate bound for Unpaywall. A
+ * DOI the candidate already holds wins — for `dois` input it is the caller's
+ * own identifier.
+ */
+function carryEpmcHit(candidate, hit) {
+    return {
+        ...candidate,
+        ...(hit.doi && !candidate.doi && { doi: hit.doi }),
+        ...(hit.title && { title: hit.title }),
+    };
+}
+/** Display-ready plain text, or `undefined` when nothing is left once markup is stripped. */
+function nonEmptyDisplayText(raw) {
+    return (raw && toDisplayText(raw)) || undefined;
+}
 /**
  * Run the Europe PMC step against everything that fell through PMC EFetch
  * plus any direct DOI input. Each candidate goes through search-by-best-id →
@@ -1983,24 +2131,28 @@ async function runEpmcStage(epmc, args) {
         }
         if (search.kind === 'miss')
             return { c, outcome: { kind: 'miss' } };
-        const doi = search.hit.doi ? { doi: search.hit.doi } : {};
+        const title = nonEmptyDisplayText(search.hit.title);
+        const hit = {
+            ...(search.hit.doi && { doi: search.hit.doi }),
+            ...(title && { title }),
+        };
         const fetched = await fetchEpmcArticle(epmc, search.hit, args, contextPmid);
         if (fetched.kind === 'error') {
-            return { c, ...doi, outcome: { kind: 'service-error', detail: fetched.detail } };
+            return { c, ...hit, outcome: { kind: 'service-error', detail: fetched.detail } };
         }
         if (fetched.kind === 'no-fulltext') {
             return {
                 c,
-                ...doi,
+                ...hit,
                 outcome: { kind: 'no-fulltext', ...(fetched.detail && { detail: fetched.detail }) },
             };
         }
         if (fetched.kind === 'no-body') {
-            return { c, ...doi, outcome: { kind: 'no-body', detail: fetched.detail } };
+            return { c, ...hit, outcome: { kind: 'no-body', detail: fetched.detail } };
         }
         return {
             c,
-            ...doi,
+            ...hit,
             outcome: { kind: 'hit' },
             article: fetched.article,
             sectionFilterMiss: fetched.sectionFilterMiss,
@@ -2052,25 +2204,25 @@ async function runEpmcStage(epmc, args) {
         pmidOutcomes.set(run.c.pmid, run.outcome);
         if (run.article)
             collectHit(run.c.pmid, { ...run, article: run.article });
-        // A DOI the EPMC hit carried is evidence the next stage needs, whatever the
-        // fetch outcome was — merge it in like the pmcid branch below, so Unpaywall
-        // gets it without a redundant PubMed metadata round-trip. (#119)
+        // What the EPMC hit carried is evidence the next stage needs, whatever the
+        // fetch outcome was: its DOI spares Unpaywall a PubMed metadata round-trip
+        // (#119), and its title backs up Unpaywall's own record (#144).
         else
-            remainingPmid.push(run.doi && !run.c.doi ? { ...run.c, doi: run.doi } : run.c);
+            remainingPmid.push(carryEpmcHit(run.c, run));
     }
     for (const run of pmcidResults) {
         pmcidOutcomes.set(run.c.normalized, run.outcome);
         if (run.article)
             collectHit(run.c.normalized, { ...run, article: run.article });
         else
-            remainingPmcid.push(run.doi && !run.c.c.doi ? { ...run.c.c, doi: run.doi } : run.c.c);
+            remainingPmcid.push(carryEpmcHit(run.c.c, run));
     }
     for (const run of doiResults) {
         doiOutcomes.set(run.c.doi, run.outcome);
         if (run.article)
             collectHit(run.c.doi, { ...run, article: run.article });
         else
-            remainingDoi.push(run.c);
+            remainingDoi.push(carryEpmcHit(run.c, run));
     }
     return {
         articles,
@@ -2220,9 +2372,15 @@ async function fetchPubmedDois(pmids, signal) {
  * Resolve a DOI to an open-access article via Unpaywall. `pmcId` and `pmid`,
  * when set, are stamped onto the resulting article so the branch that requested
  * it carries its identifier through — Unpaywall itself only knows the DOI.
+ *
+ * The article's title is the first one found in Unpaywall's own record, then
+ * `epmcTitle` — the Europe PMC record the chain searched for this id — then,
+ * for HTML content only, the title the extractor detects on the page. None is
+ * ever invented: with no source carrying one, the article has no title. The
+ * journal name and year come from Unpaywall's record alone. (#144)
  */
 async function resolveUnpaywall(args, service, ctx) {
-    const { pmcId, pmid, doi, budget } = args;
+    const { pmcId, pmid, doi, epmcTitle, budget } = args;
     const requestedIds = { ...(pmcId && { pmcId }), ...(pmid && { pmid }) };
     /** Budget the extracted body, then pair the article with its accounting. */
     const budgeted = (build, content) => {
@@ -2260,6 +2418,15 @@ async function resolveUnpaywall(args, service, ctx) {
         ctx.log.warning('Unpaywall content fetch failed', { doi, error: detail });
         return { unavailable: { reason: 'fetch-failed', detail } };
     }
+    const recordTitle = nonEmptyDisplayText(resolution.title) ?? epmcTitle;
+    const record = {
+        ...requestedIds,
+        doi,
+        sourceUrl: content.fetchedUrl,
+        location: resolution.location,
+        journalName: nonEmptyDisplayText(resolution.journalName),
+        year: resolution.year,
+    };
     try {
         if (content.kind === 'html') {
             const extracted = await htmlExtractor.extract(content.body, {
@@ -2276,13 +2443,10 @@ async function resolveUnpaywall(args, service, ctx) {
                 };
             }
             return budgeted((text) => buildUnpaywallArticle({
-                ...requestedIds,
-                doi,
-                sourceUrl: content.fetchedUrl,
-                location: resolution.location,
+                ...record,
                 contentFormat: 'html-markdown',
                 content: text,
-                title: extracted.title,
+                title: recordTitle ?? extracted.title,
                 wordCount: extracted.wordCount,
             }), body);
         }
@@ -2294,12 +2458,10 @@ async function resolveUnpaywall(args, service, ctx) {
             };
         }
         return budgeted((body) => buildUnpaywallArticle({
-            ...requestedIds,
-            doi,
-            sourceUrl: content.fetchedUrl,
-            location: resolution.location,
+            ...record,
             contentFormat: 'pdf-text',
             content: body,
+            title: recordTitle,
             totalPages: extracted.totalPages,
         }), text);
     }
@@ -2324,6 +2486,8 @@ function buildUnpaywallArticle(args) {
         sourceUrl: args.sourceUrl,
         content: args.content,
         ...(args.title && { title: args.title }),
+        ...(args.journalName && { journalName: args.journalName }),
+        ...(args.year !== undefined && { year: args.year }),
         ...(args.wordCount !== undefined && { wordCount: args.wordCount }),
         ...(args.totalPages !== undefined && { totalPages: args.totalPages }),
         ...(location.license && { license: location.license }),
@@ -2481,16 +2645,39 @@ function formatTruncation(t, lines) {
             ? ''
             : `, ${a.omittedAssets} asset(s) dropped whole: ${(a.omittedAssetNames ?? []).join(', ')}`;
         lines.push(`- ${a.id} (${a.source}): ${a.returnedCharacters} of ${a.originalCharacters} characters${tablesDropped}${assetsDropped}`);
-        for (const s of a.sections ?? []) {
-            lines.push(`  - ${s.title ?? 'untitled section'} — ${s.returnedCharacters} of ${s.originalCharacters} characters (truncated: ${s.truncated})`);
-        }
+        for (const s of a.sections ?? [])
+            formatLedgerEntry(s, lines, t.mode, 1);
     }
 }
+/**
+ * One section's ledger line, then its subsections' one level deeper. The line
+ * names the section by {@link sectionHeading}, so it reads exactly as the
+ * section's heading does in the body. An entry the budget emptied says what
+ * became of it — dropped in `truncate` mode, kept as a bare heading in
+ * `outline` mode. (#143, #148)
+ */
+function formatLedgerEntry(entry, lines, mode, depth) {
+    const fate = isBudgetEmptied(entry)
+        ? mode === 'truncate'
+            ? ' — dropped'
+            : ' — heading only'
+        : '';
+    lines.push(`${'  '.repeat(depth)}- ${sectionHeading(entry)} — ${entry.returnedCharacters} of ${entry.originalCharacters} characters (truncated: ${entry.truncated})${fate}`);
+    for (const sub of entry.subsections ?? [])
+        formatLedgerEntry(sub, lines, mode, depth + 1);
+}
 /** Per-article inline marker so a reader of one article's body knows it is partial. */
 function truncationNote(t) {
     return `\n> Body shortened to fit the requested character budget — ${t.returnedCharacters} of ${t.originalCharacters} characters returned. See \`truncation\` for per-section counts.`;
 }
-function formatPmcArticle(a, lines, truncation) {
+/**
+ * The marker an `outline`-mode heading carries when the budget left it no text,
+ * so it reads as withheld rather than as a heading over nothing. (#143)
+ */
+function emptiedSectionNote(originalCharacters) {
+    return `> Text omitted to fit the requested character budget — 0 of ${originalCharacters} characters returned.`;
+}
+function formatPmcArticle(a, lines, truncation, mode) {
     // Render-time only — `structuredContent.articles[].title` keeps the
     // plain-text value the JATS parser produced. (#102)
     lines.push(`### ${escapeMarkdownInline(a.title ?? articleDisplayId(a))}`);
@@ -2549,8 +2736,13 @@ function formatPmcArticle(a, lines, truncation) {
         lines.push(truncationNote(truncation));
     if (a.abstract)
         lines.push(`\n#### Abstract\n${a.abstract}`);
-    for (const sec of a.sections)
-        formatSection(sec, lines, 4);
+    // `outline` mode keeps every section and subsection, so each one lines up
+    // with its ledger entry by position. `truncate` mode drops the emptied ones —
+    // positions no longer line up, and nothing left needs a marker.
+    const ledger = mode === 'outline' ? truncation?.sections : undefined;
+    a.sections.forEach((sec, i) => {
+        formatSection(sec, lines, 4, ledger?.[i]);
+    });
     if (a.tables?.length)
         formatTables(a.tables, lines);
     if (a.assets?.length)
@@ -2677,6 +2869,10 @@ function formatUnpaywallArticle(a, lines, truncation) {
         : 'Unpaywall (PDF → plain text)';
     lines.push(`### ${escapeMarkdownInline(heading)}`);
     lines.push(`**Source:** ${formatLabel}`);
+    if (a.journalName)
+        lines.push(`**Journal:** ${escapeMarkdownInline(a.journalName)}`);
+    if (a.year !== undefined)
+        lines.push(`**Year:** ${a.year}`);
     if (a.pmcId)
         lines.push(`**PMCID:** ${a.pmcId}`);
     if (a.pmid)
@@ -2712,20 +2908,43 @@ function formatPmcAuthor(au) {
 function formatHeading(label, title) {
     return label ? `${label} ${title}` : title;
 }
+/** How a section with no title and no label is named — in its body heading and its ledger line. */
+const UNTITLED_SECTION_LABEL = 'untitled section';
+/**
+ * The name a section goes by in `content[]`: its label and title, else its
+ * label alone, else {@link UNTITLED_SECTION_LABEL}. The body heading and the
+ * truncation ledger line both take it from here, so the two always read the
+ * same. Render-time escaped like every other upstream string interpolated into
+ * a line, so a title's `*`, `_`, `` ` `` or `[` cannot restyle the heading;
+ * `structuredContent` keeps the plain title. (#148, #169)
+ */
+function sectionHeading(section) {
+    if (section.title)
+        return escapeMarkdownInline(formatHeading(section.label, section.title));
+    return section.label ? escapeMarkdownInline(section.label) : UNTITLED_SECTION_LABEL;
+}
 /**
  * Render one body section and everything nested under it, one markdown heading
  * level per nesting level. Walks the full depth the output schema carries, so
  * `content[]` shows every section `structuredContent` does. Headings stop
  * deepening at `######`, the deepest markdown supports. (#112)
+ *
+ * Every section gets a heading — an untitled one included, under the name the
+ * truncation ledger gives it — so its text never runs on from the block before
+ * it. `ledger` is the section's `outline`-mode accounting, when there is one: a
+ * section it shows the budget emptied carries a marker under its heading.
+ * (#143, #148)
  */
-function formatSection(section, lines, depth) {
-    if (section.title) {
-        lines.push(`\n${'#'.repeat(Math.min(depth, 6))} ${formatHeading(section.label, section.title)}`);
-    }
+function formatSection(section, lines, depth, ledger) {
+    lines.push(`\n${'#'.repeat(Math.min(depth, 6))} ${sectionHeading(section)}`);
     if (section.text)
         lines.push(section.text);
-    for (const sub of section.subsections ?? [])
-        formatSection(sub, lines, depth + 1);
+    else if (ledger && isBudgetEmptied(ledger)) {
+        lines.push(emptiedSectionNote(ledger.originalCharacters));
+    }
+    section.subsections?.forEach((sub, i) => {
+        formatSection(sub, lines, depth + 1, ledger?.subsections?.[i]);
+    });
 }
 /**
  * Strip absolute URLs from chain detail strings. Upstream errors (e.g.