@cyanheads/pubmed-mcp-server 2.10.9 → 2.10.11

package/AGENTS.md

@@ -1,7 +1,7 @@
 # Agent Protocol
 
 **Server:** @cyanheads/pubmed-mcp-server
-**Version:** 2.10.9
+**Version:** 2.10.11
 **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.12.8`
 **Engines:** Bun ≥1.3.0, Node ≥24.0.0
 

package/CLAUDE.md

@@ -1,7 +1,7 @@
 # Agent Protocol
 
 **Server:** @cyanheads/pubmed-mcp-server
-**Version:** 2.10.9
+**Version:** 2.10.11
 **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.12.8`
 **Engines:** Bun ≥1.3.0, Node ≥24.0.0
 

package/README.md

@@ -9,7 +9,7 @@
 
 
 
-[![Version](https://img.shields.io/badge/Version-2.10.9-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.11-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>
 
@@ -59,6 +59,7 @@ Search PubMed with full NCBI query syntax and filters.
 - Sort by relevance, publication date, author, or journal
 - Pagination via offset for paging through large result sets
 - Optional brief summaries for top N results via ESummary
+- NCBI Bookshelf results carry their own venue — `bookTitle`, `publisherName`, and `docType` (`chapter`, `book`, or `citation`) — because PubMed leaves `source` empty on them; the book's editors are reported in `editors`, apart from the chapter's own authors
 - Returns the original query plus the fully applied PubMed query and normalized filter metadata
 
 ---
@@ -72,6 +73,8 @@ 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)
+- NCBI Bookshelf chapters and whole books are returned as first-class records, not reported unavailable: `recordType` (`journal-article`, `book-chapter`, `book`) tells them apart, and a `book` object carries the book title, publisher, place, dates, medium, edition, series, ISBNs, book DOI, editors, and Bookshelf accession. `journalInfo` is absent on those records — a book title is never reported as a journal
+- Journals that assign article numbers instead of page ranges often carry no pagination at all; the number is reported as `journalInfo.elocationId` with its `journalInfo.elocationIdType` (`pii`), never merged into `journalInfo.pages` and never confused with the DOI
 - 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
 
 ---
@@ -80,17 +83,18 @@ Fetch full article metadata by PubMed IDs.
 
 Fetch full-text articles via a three-stage chain: NCBI PMC EFetch → Europe PMC `fullTextXML` → Unpaywall.
 
-- Accepts exactly one of `pmcids` (direct PMC IDs), `pmids` (PubMed IDs, auto-resolved), or `dois` (auto-resolved to PMC via the ID Converter; preprints and EPMC-only OA fall through to Europe PMC / Unpaywall)
+- Accepts exactly one of `pmcids` (direct PMC IDs), `pmids` (PubMed IDs, auto-resolved), or `dois` (auto-resolved to PMC via the ID Converter; preprints and EPMC-only OA fall through to Europe PMC / Unpaywall). One identifier per element in every branch — a DOI carrying a comma or whitespace is rejected at the schema
 - NCBI PMC and Europe PMC both return structured JATS; output records origin via `viaSource: "pmc" | "europepmc" | "unpaywall"`
 - 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-body`, `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`, `doi-lookup-failed`, `no-oa`, `fetch-failed`, `parse-failed`, `service-error`) so callers can retry or explain to users without parsing text. `no-doi` and `doi-lookup-failed` are the settled and unsettled halves of the same gap: the first means the DOI lookup ran and the record has none, the second that the lookup itself errored, so a DOI may well exist and the request is worth retrying
 - 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 substring match at any nesting depth, e.g. `["methods", "results"]`) and configurable max sections apply to PMC output. A section that matches directly is returned whole; one kept only because a nested subsection matched keeps its heading as a breadcrumb with its own text cleared
 - Tables are returned as structured cells (`tables[]` on each PMC article — rows, caption, label, footnotes, and the enclosing section, named for back-matter and appendix tables as well as body ones), covering `<floats-group>`, `<back>` and appendix deposits alongside body tables. `colspan` and `rowspan` are expanded to one entry per grid column, so a value stays under the header it belongs to on both output surfaces; a cell spanning several columns or rows repeats across the cells it covers. A deposit with no readable markup comes back labelled with an `unextractableReason` rather than silently missing. Turn them off with `includeTables: false`
-- Character budgets keep context size predictable: `maxCharacters` caps body text per article (PMC sections, subsections and table content — cell, caption, label and footnote text, not the Markdown grid rendered around it — 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). Sections are served first and tables spend what is left, in document order until one does not fit; that table and the rest are dropped whole rather than cut mid-row, and named in `truncation.articles[].omittedTableNames`. Budgets run after the semantic filters, and a `truncation` object reports per-article and per-section character counts whenever anything was shortened
+- Figures and supplementary material come back as structured entries (`assets[]` on each PMC article — `assetType`, label, caption, the enclosing section, and the `<graphic>`/`<media>` pointer exactly as deposited, which is a name inside the PMC deposit rather than a fetchable URL), covering `<floats-group>`, `<back>` and appendix placements alongside body ones. Each one lifted out of the body leaves a `[Figure: <label>]` / `[Supplementary: <label>]` marker at its position, so reading order survives the lift. Turn them off with `includeAssets: false`, which removes the markers with them. Prose-shaped blocks — lists, definition lists, block quotes, boxed text, preformatted blocks, displayed formulae — render into the section text at their document position instead, and no block is ever concatenated into a neighbouring sentence
+- Character budgets keep context size predictable: `maxCharacters` caps body text per article (PMC sections and subsections, inline blocks included, plus table content — cell, caption, label and footnote text, not the Markdown grid rendered around it — and asset label, caption and pointer text; 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). Sections are served first, then tables, then assets, each spending what is left in document order until one does not fit; that entry and the rest are dropped whole rather than cut mid-row or returned with a shortened caption, and named in `truncation.articles[].omittedTableNames` / `omittedAssetNames`. 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
 
@@ -126,6 +130,8 @@ Fetch complete Europe PMC records by `source` + `epmcId`, the detail counterpart
 Generate formatted citations for articles.
 
 - Five citation styles: APA 7th, MLA 9th, BibTeX, RIS, Vancouver (ICMJE/NLM)
+- NCBI Bookshelf chapters and whole books cite in their own form in every style — Vancouver's `In: … editors` contribution pattern, APA's chapter-in-edited-book, MLA's `edited by`, BibTeX `@incollection` / `@book`, RIS `CHAP` / `BOOK` — carrying the book title, editors, publisher, place, ISBNs and Bookshelf URL
+- An article with no page range cites by its electronic article locator in each style's own convention — Vancouver's trailing `pii:` note, APA's `Article <n>`, MLA's `art. <n>`, biblatex `eid`, RIS `C7` — rather than dropping it or writing it into a page field
 - Request multiple styles per article in a single call
 - Hand-rolled formatters — zero external dependencies, fully Workers-compatible
 - Up to 50 articles per request
@@ -138,7 +144,7 @@ Generate formatted citations for articles.
 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 enriched with title, authors, publication date, and source via ESummary — or, for an NCBI Bookshelf record, its book title, publisher, and doc type in place of the empty source
 - 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
 
@@ -169,6 +175,7 @@ Resolve partial bibliographic references to PubMed IDs via NCBI ECitMatch.
 
 - Match citations by journal, year, volume, first page, and/or author name
 - More fields = better match accuracy; at least one field required
+- Bibliographic fields cannot contain a pipe (`|`) or a line break — ECitMatch's wire format is pipe-delimited, so those characters are rejected at the schema; the free-form `key` label is exempt
 - Batch up to 25 citations per request
 - Deterministic matching — more reliable than free-text search for known references
 - Returns explicit `matched`, `not_found`, and `ambiguous` statuses with recovery detail
@@ -181,6 +188,7 @@ Convert between article identifiers (DOI, PMID, PMCID) using the PMC ID Converte
 
 - Batch up to 50 IDs per request
 - Accepts DOIs, PMIDs, or PMCIDs (all IDs must be the same type)
+- One identifier per array element, checked against `idType` before the request — a packed value like `"23193287,37952131"` is rejected rather than expanded into extra records, since a comma is the converter's list delimiter in any encoding
 - Only resolves articles indexed in PubMed Central
 - Per-ID success/error reporting — partial batches return resolved mappings alongside structured errors for unresolvable IDs, not a batch-level failure
 

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

@@ -11,4 +11,20 @@ import { z } from '@cyanheads/mcp-ts-core';
  * stray prefixes like "PMID:").
  */
 export declare const pmidStringSchema: z.ZodString;
+/**
+ * Zod string schema for a single PMC ID. Digits, with the "PMC" prefix optional
+ * and case-insensitive — both forms are accepted upstream.
+ */
+export declare const pmcidStringSchema: z.ZodString;
+/**
+ * Zod string schema for a single DOI: the "10." directory indicator, a
+ * registrant prefix, "/", and a suffix.
+ *
+ * Every DOI character is allowed except whitespace and the comma, so the
+ * suffix punctuation a real DOI carries — parens, colons, angle brackets,
+ * semicolons, further slashes — passes through. The comma is excluded because
+ * it is the PMC ID Converter's list delimiter in any encoding, so an element
+ * carrying one is read upstream as two identifiers rather than one DOI.
+ */
+export declare const doiStringSchema: z.ZodString;
 //# 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;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAE3C;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,aAK1B,CAAC"}
+{"version":3,"file":"_schemas.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/_schemas.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAE3C;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,aAK1B,CAAC;AAEJ;;;GAGG;AACH,eAAO,MAAM,iBAAiB,aAK3B,CAAC;AAEJ;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,aAKzB,CAAC"}

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

@@ -13,4 +13,24 @@ import { z } from '@cyanheads/mcp-ts-core';
 export const pmidStringSchema = z
     .string()
     .regex(/^\d+$/, 'PMID must be a numeric identifier (e.g. "13054692"). Remove any whitespace, commas, or non-digit characters — provide each PMID separately.');
+/**
+ * Zod string schema for a single PMC ID. Digits, with the "PMC" prefix optional
+ * and case-insensitive — both forms are accepted upstream.
+ */
+export const pmcidStringSchema = z
+    .string()
+    .regex(/^(?:PMC)?\d+$/i, 'PMC ID must be digits, optionally prefixed with "PMC" (e.g. "PMC9575052" or "9575052"). Remove any whitespace or commas — provide each PMC ID separately.');
+/**
+ * Zod string schema for a single DOI: the "10." directory indicator, a
+ * registrant prefix, "/", and a suffix.
+ *
+ * Every DOI character is allowed except whitespace and the comma, so the
+ * suffix punctuation a real DOI carries — parens, colons, angle brackets,
+ * semicolons, further slashes — passes through. The comma is excluded because
+ * it is the PMC ID Converter's list delimiter in any encoding, so an element
+ * carrying one is read upstream as two identifiers rather than one DOI.
+ */
+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.');
 //# 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;;;GAGG;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"}
+{"version":3,"file":"_schemas.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/_schemas.ts"],"names":[],"mappings":"AAAA;;;GAGG;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;;;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"}

package/dist/mcp-server/tools/definitions/convert-ids.tool.d.ts

@@ -51,5 +51,11 @@ export declare const convertIdsTool: import("@cyanheads/mcp-ts-core").ToolDefini
     readonly when: 'NCBI returned a structured "not found" error for the requested ID(s).';
     readonly recovery: 'Verify the ID exists in PubMed; the resource was not found in NCBI and retrying will not help.';
     readonly retryable: false;
+}, {
+    readonly reason: 'malformed_id';
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
+    readonly when: 'An `ids` element does not match the declared `idType` — most often several identifiers packed into one element, which the comma-delimited upstream batch would split into extra records.';
+    readonly recovery: 'Submit one identifier per `ids` element, in the declared idType format; the same packed value will be rejected again.';
+    readonly retryable: false;
 }], undefined>;
 //# sourceMappingURL=convert-ids.tool.d.ts.map

package/dist/mcp-server/tools/definitions/convert-ids.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"convert-ids.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/convert-ids.tool.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAcjD,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA6GzB,CAAC"}
+{"version":3,"file":"convert-ids.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/convert-ids.tool.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAiCjD,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAyHzB,CAAC"}

package/dist/mcp-server/tools/definitions/convert-ids.tool.js

@@ -4,9 +4,10 @@
  * @module src/mcp-server/tools/definitions/convert-ids.tool
  */
 import { tool, z } from '@cyanheads/mcp-ts-core';
-import { NCBI_SERVICE_ERRORS } from '../../../services/error-contracts.js';
+import { NCBI_ID_INPUT_ERRORS, NCBI_SERVICE_ERRORS } from '../../../services/error-contracts.js';
 import { getNcbiService } from '../../../services/ncbi/ncbi-service.js';
 import { conceptMeta, EDAM_ACCESSION, EDAM_ID_MAPPING } from './_concepts.js';
+import { doiStringSchema, pmcidStringSchema, pmidStringSchema } from './_schemas.js';
 /**
  * NCBI's PMC ID Converter returns this exact wording for any non-PMC ID — even
  * articles that exist in PubMed and have a recoverable DOI. Rewrite to point
@@ -14,18 +15,34 @@ import { conceptMeta, EDAM_ACCESSION, EDAM_ID_MAPPING } from './_concepts.js';
  */
 const PMC_NOT_FOUND_RE = /^identifier not found in pmc$/i;
 const PMC_NOT_FOUND_REWRITE = 'Not in PMC ID Converter. Article may still exist in PubMed — try pubmed_fetch_articles (PMID → DOI) or pubmed_search_articles.';
+/**
+ * Per-`idType` element format, checked in the handler rather than the schema:
+ * a Zod `.regex()` on `ids` cannot branch on the sibling `idType` field.
+ *
+ * Every one of these rejects an element carrying a comma, which is what closes
+ * #120 — the converter reads a comma as its list delimiter, so a packed element
+ * comes back as several records and breaks the one-record-per-submitted-ID
+ * contract the counts are computed from.
+ */
+const ID_ELEMENT_SCHEMAS = {
+    doi: doiStringSchema,
+    pmcid: pmcidStringSchema,
+    pmid: pmidStringSchema,
+};
+/** Cap the offending value echoed back so an oversized element can't bloat the error. */
+const MAX_ECHOED_ID_LENGTH = 120;
 export const convertIdsTool = tool('pubmed_convert_ids', {
     description: `Convert between article identifiers (DOI, PMID, PMCID). Accepts up to 50 IDs of a single type per request. Only resolves articles indexed in PubMed Central — for articles not in PMC, use pubmed_search_articles instead.`,
     annotations: { readOnlyHint: true, openWorldHint: true },
     _meta: conceptMeta([EDAM_ID_MAPPING, EDAM_ACCESSION]),
     sourceUrl: 'https://github.com/cyanheads/pubmed-mcp-server/blob/main/src/mcp-server/tools/definitions/convert-ids.tool.ts',
-    errors: [...NCBI_SERVICE_ERRORS],
+    errors: [...NCBI_SERVICE_ERRORS, ...NCBI_ID_INPUT_ERRORS],
     input: z.object({
         ids: z
             .array(z.string().min(1))
             .min(1)
             .max(50)
-            .describe('Article identifiers to convert. All IDs must be the same type. DOIs: "10.1093/nar/gks1195", PMIDs: "23193287", PMCIDs: "PMC3531190" (the "PMC" prefix is optional — bare digits like "3531190" are also accepted).'),
+            .describe('Article identifiers to convert — one identifier per element, all of the same type. Each element is checked against `idType` before the request: `doi` starts with "10." and carries a "/" ("10.1093/nar/gks1195"); `pmid` is digits ("23193287"); `pmcid` is digits with an optional "PMC" prefix ("PMC3531190" or "3531190"). No element may contain a comma or whitespace — a packed value like "23193287,37952131" is rejected, so split it across elements.'),
         idType: z
             .enum(['pmcid', 'pmid', 'doi'])
             .describe('The type of IDs being submitted. Required so the API can unambiguously resolve them.'),
@@ -59,6 +76,14 @@ export const convertIdsTool = tool('pubmed_convert_ids', {
             count: input.ids.length,
             idType: input.idType,
         });
+        const elementSchema = ID_ELEMENT_SCHEMAS[input.idType];
+        for (const id of input.ids) {
+            const parsed = elementSchema.safeParse(id);
+            if (parsed.success)
+                continue;
+            const shown = id.length > MAX_ECHOED_ID_LENGTH ? `${id.slice(0, MAX_ECHOED_ID_LENGTH)}…` : id;
+            throw ctx.fail('malformed_id', `Invalid ${input.idType} element "${shown}". ${parsed.error.issues[0]?.message}`, { ...ctx.recoveryFor('malformed_id') });
+        }
         const raw = await getNcbiService().idConvert(input.ids, input.idType, { signal: ctx.signal });
         // NCBI returns pmid as a number in JSON — coerce all ID fields to strings
         const records = raw.map((r) => {

package/dist/mcp-server/tools/definitions/convert-ids.tool.js.map

@@ -1 +1 @@
-{"version":3,"file":"convert-ids.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/convert-ids.tool.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"convert-ids.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/convert-ids.tool.ts"],"names":[],"mappings":"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"}

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

@@ -12,6 +12,11 @@ export declare const fetchArticlesTool: import("@cyanheads/mcp-ts-core").ToolDef
     maxResponseCharacters: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>, z.ZodObject<{
     articles: z.ZodArray<z.ZodObject<{
+        recordType: z.ZodEnum<{
+            book: "book";
+            "book-chapter": "book-chapter";
+            "journal-article": "journal-article";
+        }>;
         pmid: z.ZodOptional<z.ZodString>;
         title: z.ZodOptional<z.ZodString>;
         abstractText: z.ZodOptional<z.ZodString>;
@@ -32,6 +37,8 @@ export declare const fetchArticlesTool: import("@cyanheads/mcp-ts-core").ToolDef
             volume: z.ZodOptional<z.ZodString>;
             issue: z.ZodOptional<z.ZodString>;
             pages: z.ZodOptional<z.ZodString>;
+            elocationId: z.ZodOptional<z.ZodString>;
+            elocationIdType: z.ZodOptional<z.ZodString>;
             publicationDate: z.ZodOptional<z.ZodObject<{
                 year: z.ZodOptional<z.ZodString>;
                 month: z.ZodOptional<z.ZodString>;
@@ -39,6 +46,26 @@ export declare const fetchArticlesTool: import("@cyanheads/mcp-ts-core").ToolDef
                 medlineDate: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>>;
         }, z.core.$strip>>;
+        book: z.ZodOptional<z.ZodObject<{
+            title: z.ZodOptional<z.ZodString>;
+            publisher: z.ZodOptional<z.ZodString>;
+            publisherLocation: z.ZodOptional<z.ZodString>;
+            pubDate: z.ZodOptional<z.ZodString>;
+            beginningDate: z.ZodOptional<z.ZodString>;
+            endingDate: z.ZodOptional<z.ZodString>;
+            medium: z.ZodOptional<z.ZodString>;
+            edition: z.ZodOptional<z.ZodString>;
+            collectionTitle: z.ZodOptional<z.ZodString>;
+            isbns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            doi: z.ZodOptional<z.ZodString>;
+            editors: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                lastName: z.ZodOptional<z.ZodString>;
+                firstName: z.ZodOptional<z.ZodString>;
+                initials: z.ZodOptional<z.ZodString>;
+                collectiveName: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>>;
+            accession: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
         doi: z.ZodOptional<z.ZodString>;
         pmcId: z.ZodOptional<z.ZodString>;
         pubmedUrl: 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;;;;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"}
+{"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;AAwRjE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAWhB,yBAAyB;;mBAE3B,sEAAsE;uBAE1E,qFAAqF;;;;EAkR3F,CAAC"}

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

@@ -7,8 +7,7 @@ import { tool, z } from '@cyanheads/mcp-ts-core';
 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 { parseFullArticle } from '../../../services/ncbi/parsing/article-parser.js';
-import { ensureArray } from '../../../services/ncbi/parsing/xml-helpers.js';
+import { parseArticleSet } from '../../../services/ncbi/parsing/article-parser.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';
@@ -43,9 +42,93 @@ const JournalInfoSchema = z
     volume: z.string().optional().describe('Volume number'),
     issue: z.string().optional().describe('Issue number'),
     pages: z.string().optional().describe('Page range (e.g. "48-55")'),
+    elocationId: z
+        .string()
+        .optional()
+        .describe('Electronic article locator from NCBI `ELocationID` — the publisher-assigned article number (e.g. "2400512"). Journals that assign article numbers instead of pages often omit pagination entirely, leaving this the only locator. Never a substitute for `pages`, and never the DOI: a DOI-typed `ELocationID` is reported in `doi` instead. Absent when the only locator NCBI supplies is marked invalid.'),
+    elocationIdType: z
+        .string()
+        .optional()
+        .describe('Type of `elocationId`, from NCBI\'s `EIdType` attribute — "pii" in practice. Free-form: NCBI does not close the set, so treat an unfamiliar value as opaque.'),
     publicationDate: JournalPublicationDateSchema.optional(),
 })
-    .describe('Journal information');
+    .describe('Journal information. Present on `journal-article` records only — absent on `book-chapter` and `book` records, because a Bookshelf record has no journal and its book title is never reported as one; read `book` for those. (#114)');
+const BookEditorSchema = z
+    .object({
+    lastName: z
+        .string()
+        .optional()
+        .describe('Editor surname, from the book\'s `Book/AuthorList Type="editors"` entry. Absent on a group editor, which carries `collectiveName` instead.'),
+    firstName: z
+        .string()
+        .optional()
+        .describe('Editor given name as NCBI supplies it (`ForeName`, often "Margaret P"). Absent when NCBI carries initials only, or on a group editor.'),
+    initials: z
+        .string()
+        .optional()
+        .describe('Editor initials with no separators (e.g. "MP"). Absent when NCBI supplies none, or on a group editor.'),
+    collectiveName: z
+        .string()
+        .optional()
+        .describe('Group or committee credited as editor, when the entry names an organization rather than a person. Mutually exclusive with the name-part fields.'),
+})
+    .describe('One editor of the containing book. Name parts only — editors are a citation credit, not a contributor record, so no affiliations or ORCID are reported for them.');
+const BookInfoSchema = z
+    .object({
+    title: z
+        .string()
+        .optional()
+        .describe('Title of the containing book, from `Book/BookTitle` (e.g. "GeneReviews®"). On a `book` record this is the same value as the record\'s own `title`.'),
+    publisher: z
+        .string()
+        .optional()
+        .describe('Publisher of the book, from `Book/Publisher/PublisherName`.'),
+    publisherLocation: z
+        .string()
+        .optional()
+        .describe('Place of publication, from `Book/Publisher/PublisherLocation` (e.g. "Seattle (WA)"). Absent when NCBI supplies no place.'),
+    pubDate: z
+        .string()
+        .optional()
+        .describe("Publication year from `Book/PubDate`. Year only — NCBI's month and day are not reported, since no citation style uses them for a book."),
+    beginningDate: z
+        .string()
+        .optional()
+        .describe('First year of a continuously-updated book, from `Book/BeginningDate` (GeneReviews runs from 1993). Absent on a book published once.'),
+    endingDate: z
+        .string()
+        .optional()
+        .describe('Last year of a closed date range, from `Book/EndingDate`. Absent while a book is still being updated, which leaves the range open-ended.'),
+    medium: z
+        .string()
+        .optional()
+        .describe('Medium the book is published in, from `Book/Medium` — "Internet" wherever NCBI supplies it. Absent when NCBI supplies none; it is never defaulted.'),
+    edition: z
+        .string()
+        .optional()
+        .describe('Edition statement from `Book/Edition`. Rare on Bookshelf titles — absent unless NCBI supplies one.'),
+    collectionTitle: z
+        .string()
+        .optional()
+        .describe('Series the book belongs to, from `Book/CollectionTitle` (e.g. "ADA Clinical Compendia Series"). Absent for a book outside a series.'),
+    isbns: z
+        .array(z.string().describe('One ISBN, verbatim as NCBI reports it — leading zeros intact'))
+        .optional()
+        .describe('Every `Book/Isbn` on the record. A book commonly carries a print and an electronic ISBN, so this is a list. Absent for a Bookshelf title with no ISBN, which is most of them.'),
+    doi: z
+        .string()
+        .optional()
+        .describe('The book\'s own DOI, from `Book/ELocationID` with `EIdType="doi"`. Distinct from the record-level `doi`, which is the chapter\'s: a chapter does not inherit this one.'),
+    editors: z
+        .array(BookEditorSchema)
+        .optional()
+        .describe('Editors of the containing book, from `Book/AuthorList` marked `Type="editors"`. Kept out of `authors`, which carries the chapter\'s own writers. Absent when the book credits no editors.'),
+    accession: z
+        .string()
+        .optional()
+        .describe('NCBI Bookshelf accession from `ArticleIdList` (`bookaccession`), e.g. "NBK1247". The record is readable at `https://www.ncbi.nlm.nih.gov/books/<accession>/`.'),
+})
+    .describe('The containing book of a `book-chapter`, or the book itself on a `book` record. Present only on those two record types, and never a stand-in for `journalInfo`.');
 const MeshQualifierSchema = z
     .object({
     qualifierName: z.string().describe('Qualifier/subheading name'),
@@ -79,12 +162,22 @@ const ArticleDateSchema = z
     .describe('Dated article event');
 const FetchedArticleSchema = z
     .object({
+    recordType: z
+        .enum(['journal-article', 'book-chapter', 'book'])
+        .describe('Which kind of PubMed record this is, set from the XML element it arrived in: `journal-article` for an ordinary article, `book-chapter` for an NCBI Bookshelf chapter, `book` for a whole Bookshelf book. Read this to tell the three apart — `publicationTypes` cannot, because PubMed labels a Bookshelf record "Review" or "Study Guide". `journalInfo` is present only on `journal-article`; `book` only on the other two.'),
     pmid: z.string().optional().describe('PubMed ID'),
-    title: z.string().optional().describe('Article title'),
+    title: z
+        .string()
+        .optional()
+        .describe('Article title — the chapter title on a `book-chapter`, and the book title on a `book` record, where it repeats `book.title`.'),
     abstractText: z.string().optional().describe('Abstract text'),
     affiliations: z.array(z.string()).optional().describe('Deduplicated author affiliations'),
-    authors: z.array(AuthorSchema).optional().describe('Author list'),
+    authors: z
+        .array(AuthorSchema)
+        .optional()
+        .describe("Author list. On a `book-chapter` these are the chapter's own authors, never the book's editors, which are in `book.editors`. Empty on a Bookshelf record that credits neither."),
     journalInfo: JournalInfoSchema.optional(),
+    book: BookInfoSchema.optional(),
     doi: z
         .string()
         .optional()
@@ -152,7 +245,7 @@ export const fetchArticlesTool = tool('pubmed_fetch_articles', {
         unavailablePmids: z
             .array(z.string())
             .optional()
-            .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.'),
+            .describe('PMIDs PubMed returned no record for. That is all this reports: PubMed omits an unknown PMID silently, with no error and no reason, so the absence says nothing about whether the PMID exists. Reported in full regardless of where a `maxResponseCharacters` cutoff lands — these are misses, not deferrals. Use `pubmed_search_articles` to find PMIDs that do resolve.'),
         deferred: DeferredSchema.optional(),
     }),
     // Recovery guidance for two cases — no articles returned at all, and articles
@@ -174,23 +267,19 @@ export const fetchArticlesTool = tool('pubmed_fetch_articles', {
         if (!xmlData || !('PubmedArticleSet' in xmlData)) {
             throw ctx.fail('invalid_efetch_response', 'Invalid EFetch response from NCBI: missing PubmedArticleSet', { requestedPmids: input.pmids.length, ...ctx.recoveryFor('invalid_efetch_response') });
         }
-        const rawArticles = xmlData.PubmedArticleSet?.PubmedArticle;
-        const xmlArticles = rawArticles ? ensureArray(rawArticles) : [];
-        const articles = xmlArticles
-            .filter((a) => a?.MedlineCitation)
-            .map((a) => {
-            const parsed = parseFullArticle(a, {
-                includeMesh: input.includeMesh,
-                includeGrants: input.includeGrants,
-            });
-            return {
-                ...parsed,
-                pubmedUrl: `https://pubmed.ncbi.nlm.nih.gov/${parsed.pmid}/`,
-                ...(parsed.pmcId && {
-                    pmcUrl: `https://www.ncbi.nlm.nih.gov/pmc/articles/${parsed.pmcId}/`,
-                }),
-            };
-        });
+        // Reads both members of the set. Taking `PubmedArticleSet.PubmedArticle`
+        // alone discards every NCBI Bookshelf record, whose PMIDs then surface as
+        // unavailable even though PubMed returned them. (#114)
+        const articles = parseArticleSet(xmlData.PubmedArticleSet, {
+            includeMesh: input.includeMesh,
+            includeGrants: input.includeGrants,
+        }).map((parsed) => ({
+            ...parsed,
+            pubmedUrl: `https://pubmed.ncbi.nlm.nih.gov/${parsed.pmid}/`,
+            ...(parsed.pmcId && {
+                pmcUrl: `https://www.ncbi.nlm.nih.gov/pmc/articles/${parsed.pmcId}/`,
+            }),
+        }));
         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
@@ -222,7 +311,7 @@ export const fetchArticlesTool = tool('pubmed_fetch_articles', {
         // 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.');
+            ctx.enrich.notice('No articles were returned: PubMed matched no record to any of these PMIDs. It omits a PMID it does not recognize silently, without an error or a reason, so nothing more than that is known here. Try pubmed_search_articles to discover PMIDs that resolve.');
         }
         if (deferred) {
             ctx.enrich({ truncated: true });
@@ -275,6 +364,9 @@ export const fetchArticlesTool = tool('pubmed_fetch_articles', {
                     parts.push(`**${ji.volume}**${ji.issue ? `(${ji.issue})` : ''}`);
                 if (ji.pages)
                     parts.push(ji.pages);
+                if (ji.elocationId) {
+                    parts.push(ji.elocationIdType ? `${ji.elocationIdType}: ${ji.elocationId}` : ji.elocationId);
+                }
                 if (ji.issn)
                     parts.push(`ISSN ${ji.issn}`);
                 if (ji.eIssn)
@@ -282,6 +374,56 @@ export const fetchArticlesTool = tool('pubmed_fetch_articles', {
                 if (parts.length)
                     lines.push(`\n**Journal:** ${parts.join(', ')}`);
             }
+            // Venue block for a Bookshelf record. `journalInfo` is never set on one,
+            // so a book would otherwise render as a bare title with no publisher,
+            // date or permalink — the fields a citation actually needs. (#114)
+            const bk = a.book;
+            if (bk) {
+                const bookLines = [];
+                // On a whole-book record the heading above already is the book title;
+                // the medium marker then stands alone rather than repeating it.
+                if (a.recordType !== 'book' && bk.title) {
+                    bookLines.push(`**Book:** ${bk.medium ? `${bk.title} [${bk.medium}]` : bk.title}`);
+                }
+                else if (bk.medium) {
+                    bookLines.push(`**Medium:** ${bk.medium}`);
+                }
+                if (bk.editors?.length) {
+                    bookLines.push('', `**Editors (${bk.editors.length}):**`);
+                    for (const ed of bk.editors) {
+                        bookLines.push(`- ${formatAuthor(ed)}`);
+                    }
+                }
+                if (bk.publisher)
+                    bookLines.push(`**Publisher:** ${bk.publisher}`);
+                if (bk.publisherLocation)
+                    bookLines.push(`**Publisher Location:** ${bk.publisherLocation}`);
+                // A book published over several years carries a closed range
+                // (GeneReviews 1993–2026); otherwise the single publication year. A
+                // publication year that differs from the range's start is kept beside it.
+                const range = bk.beginningDate && bk.endingDate && bk.beginningDate !== bk.endingDate
+                    ? `${bk.beginningDate}–${bk.endingDate}`
+                    : undefined;
+                const bookDate = range && bk.pubDate && bk.pubDate !== bk.beginningDate
+                    ? `${bk.pubDate} (${range})`
+                    : (range ?? bk.pubDate ?? bk.beginningDate ?? bk.endingDate);
+                if (bookDate)
+                    bookLines.push(`**Published:** ${bookDate}`);
+                if (bk.edition)
+                    bookLines.push(`**Edition:** ${bk.edition}`);
+                if (bk.collectionTitle)
+                    bookLines.push(`**Collection:** ${bk.collectionTitle}`);
+                if (bk.isbns?.length)
+                    bookLines.push(`**ISBN:** ${bk.isbns.join(', ')}`);
+                if (bk.doi)
+                    bookLines.push(`**Book DOI:** ${bk.doi}`);
+                if (bk.accession) {
+                    bookLines.push(`**Bookshelf:** https://www.ncbi.nlm.nih.gov/books/${bk.accession}/`);
+                }
+                if (bookLines.length > 0)
+                    lines.push('', ...bookLines);
+            }
+            lines.push(`**Record Type:** ${a.recordType}`);
             if (a.publicationTypes?.length)
                 lines.push(`**Type:** ${a.publicationTypes.join(', ')}`);
             if (a.pmid)