@cyanheads/pubmed-mcp-server 2.10.12 → 2.10.14

package/README.md

@@ -9,7 +9,7 @@
 
 
 
-[![Version](https://img.shields.io/badge/Version-2.10.12-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.14-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>
 
@@ -29,9 +29,11 @@
 
 ---
 
-## Tools
+## Overview
 
-11 tools for working with PubMed, PubMed Central, and Europe PMC data:
+The biomedical literature via NCBI's E-utilities, PubMed Central, and Europe PMC. Search it, fetch metadata and full text, resolve identifiers and partial citations, format references, and ground queries in MeSH vocabulary. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.
+
+### Tools
 
 | Tool | Description |
 |:---|:---|
@@ -42,173 +44,139 @@
 | `pubmed_fetch_fulltext` | Fetch full-text articles via a chain: NCBI PMC EFetch → Europe PMC `fullTextXML` → Unpaywall. Accepts PMIDs, PMCIDs, or DOIs. |
 | `pubmed_format_citations` | Generate formatted citations in APA 7th, MLA 9th, BibTeX, RIS, or Vancouver (ICMJE/NLM) |
 | `pubmed_find_related` | Find similar articles, citing articles, or references for a given PMID |
-| `pubmed_spell_check` | Spell-check biomedical queries using NCBI's ESpell service |
-| `pubmed_lookup_mesh` | Search and explore MeSH vocabulary — tree numbers, scope notes, entry terms |
+| `pubmed_spell_check` | Spell-check a biomedical query via NCBI ESpell — returns the corrected query and whether a suggestion was found |
+| `pubmed_lookup_mesh` | Search MeSH by heading — tree numbers, scope notes, entry terms — for building controlled-vocabulary queries |
 | `pubmed_lookup_citation` | Resolve partial bibliographic references to PubMed IDs via ECitMatch |
 | `pubmed_convert_ids` | Convert between DOI, PMID, and PMCID using the PMC ID Converter API |
 
-### `pubmed_search_articles`
+### Resources
 
-Search PubMed with full NCBI query syntax and filters.
+| Resource | Description |
+|:---|:---|
+| `pubmed://database/info` | PubMed database metadata via EInfo (field list, record count, last update) |
 
-- Free-text queries with PubMed's full boolean and field-tag syntax
-- Field-specific filters: author, journal, MeSH terms, language, species
-- Common filters: has abstract, free full text
-- Date range filtering by publication, modification, or Entrez date
-- Publication type filtering (Review, Clinical Trial, Meta-Analysis, etc.)
-- 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
+### Prompts
 
----
+| Prompt | Description |
+|:---|:---|
+| `research_plan` | Generate a structured 4-phase biomedical research plan outline |
 
-### `pubmed_fetch_articles`
+## Capability reference
 
-Fetch full article metadata by PubMed IDs.
+### `pubmed_search_articles` <sub>tool</sub>
 
-- Batch fetch up to 200 articles at once (auto-switches to POST for batches >= 100)
-- Returns structured data: title, abstract, authors with deduplicated affiliations, journal info, DOI
-- 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
+- Full PubMed boolean and field-tag syntax, plus structured filters: author, journal, MeSH terms, language, species, publication type, has-abstract, free-full-text
+- Date ranges by publication, modification, or Entrez date; sort by relevance, date, author, or journal; offset pagination
+- Optional brief summaries for the top N results via ESummary
+- NCBI Bookshelf hits carry `bookTitle`, `publisherName`, `docType`, and `editors` in place of the empty `source`
+- Echoes the original query, the fully applied PubMed query, and normalized filter metadata
 
 ---
 
-### `pubmed_fetch_fulltext`
-
-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). 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`, `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`
-- 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
+### `pubmed_fetch_articles` <sub>tool</sub>
 
----
+- Up to 200 PMIDs per call (POST for batches of 100 or more)
+- Title, abstract, authors with deduplicated affiliations, journal info, DOI, PubMed/PMC links; optional MeSH terms, grants, and publication types
+- Tolerant of PubMed's inconsistent XML — structured abstracts, missing fields, varying date formats
+- Bookshelf chapters and books are first-class: `recordType` (`journal-article` / `book-chapter` / `book`) plus a `book` object (title, publisher, editors, ISBNs, Bookshelf accession); `journalInfo` is absent on them
+- Article-number journals report `journalInfo.elocationId` + `elocationIdType` rather than a page range
+- Opt-in `maxResponseCharacters` keeps whole records in order until the ceiling, then defers the rest to `deferred.ids` for a follow-up call
 
-### `pubmed_europepmc_search`
+---
 
-Search Europe PMC (EBI/EMBL-EBI), a broader open-access biomedical corpus than PubMed alone.
+### `pubmed_fetch_fulltext` <sub>tool</sub>
 
-- Surfaces records PubMed search can't reach — preprints (`source: PPR`), patents (`source: PAT`), Agricola (`source: AGR`), plus everything in PubMed (`MED`) and PMC (`PMC`). On recent queries this can mean dozens of relevant hits with zero PubMed overlap.
-- Default sources `["MED", "PMC", "PPR"]`; pass `sources` to include `PAT` / `AGR`
-- Cursor-based pagination via `cursorMark` (unlike `pubmed_search_articles`, which uses offset) — `*` for the first page, return `nextCursorMark` for the next
-- Output discriminator on `source` plus optional `pmid` / `pmcId` / `doi` cross-walking
-- `abstractSnippet` is capped at 400 characters to keep a page bounded; `abstractTruncated` says whether it was cut, and `pubmed_europepmc_fetch` returns the whole abstract for the records worth reading in full
-- Disabled when `EUROPEPMC_ENABLED=false`; tool is not registered in that case
+- Exactly one of `pmcids`, `pmids`, or `dois` (one id per element), up to 10 per request
+- Three-tier chain: NCBI PMC EFetch → Europe PMC `fullTextXML` (`EUROPEPMC_ENABLED`, default on) → Unpaywall (needs `UNPAYWALL_EMAIL`); `viaSource` names which tier served each article
+- Preprints, patents, and Agricola records have metadata via `pubmed_europepmc_search` but no full text through this chain — Europe PMC's `fullTextXML` is PMC-keyed
+- `source: "pmc"` returns structured sections plus `tables[]` (cells, caption, label, footnotes) and `assets[]` (figures and supplementary material, with `[Figure: <label>]` markers left in the body); `source: "unpaywall"` returns a best-effort body with `contentFormat` (`html-markdown` / `pdf-text`)
+- Unavailable entries carry a typed `reason` (`not-found`, `no-doi`, `doi-lookup-failed`, `no-oa`, `service-error`, …), `idType`, `triedTiers` (per-tier outcome in execution order), and `unqueriedTiers` when an unconfigured tier could have served the id
+- Filters and budgets: `sections` (case-insensitive title match), `maxSections`, `includeTables`, `includeAssets`, `maxCharacters`, `maxCharactersPerSection`, `overflowMode` (`truncate` / `outline`), and `maxResponseCharacters`, which defers whole articles past the ceiling to `deferred.ids`; a `truncation` object reports what was shortened or omitted
 
 ---
 
-### `pubmed_europepmc_fetch`
-
-Fetch complete Europe PMC records by `source` + `epmcId`, the detail counterpart to `pubmed_europepmc_search`.
+### `pubmed_europepmc_search` <sub>tool</sub>
 
-- Returns the full, untruncated abstract as display-ready plain text — markup stripped, HTML entities decoded
-- Addressed by the `source` and `epmcId` of a search hit, the only identifier preprint (`PPR`), patent (`PAT`), and Agricola (`AGR`) records reliably carry — `pubmed_fetch_articles` needs a PMID and `pubmed_fetch_fulltext` needs a PMCID, PMID, or DOI
-- Up to 25 records per call, resolved in a single Europe PMC request
-- Pairs unresolved requests back to the caller in `notFound` instead of failing the batch
-- Disabled when `EUROPEPMC_ENABLED=false`; tool is not registered in that case
+- Reaches records PubMed can't: preprints (`PPR`), patents (`PAT`), Agricola (`AGR`), alongside `MED` and `PMC`; default `sources` is `["MED", "PMC", "PPR"]`
+- Cursor pagination via `cursorMark` — `*` for the first page, then `nextCursorMark`
+- Hits carry `source` plus `pmid` / `pmcId` / `doi` when known; `abstractSnippet` is capped at 400 characters, with `abstractTruncated` flagging the cut
+- Not registered when `EUROPEPMC_ENABLED=false`
 
 ---
 
-### `pubmed_format_citations`
-
-Generate formatted citations for articles.
+### `pubmed_europepmc_fetch` <sub>tool</sub>
 
-- 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
-- Reports formatted counts and unavailable PMIDs for partial-result handling
+- Full records with the untruncated plain-text abstract, addressed by `source` + `epmcId` — the only identifier preprint, patent, and Agricola records reliably carry
+- Up to 25 per call in one Europe PMC request; unresolved ids come back in `notFound` rather than failing the batch
+- Not registered when `EUROPEPMC_ENABLED=false`
 
 ---
 
-### `pubmed_find_related`
+### `pubmed_format_citations` <sub>tool</sub>
 
-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 — 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
+- APA 7th, MLA 9th, BibTeX, RIS, Vancouver (ICMJE/NLM); several styles per article in one call, up to 50 articles
+- Bookshelf chapters and books cite in each style's edited-book form; articles without a page range cite by electronic locator in each style's convention
+- Hand-rolled formatters — zero dependencies, Workers-compatible
+- Reports formatted counts and unavailable PMIDs
 
 ---
 
-### `pubmed_spell_check`
-
-Spell-check a biomedical query using NCBI's ESpell.
+### `pubmed_find_related` <sub>tool</sub>
 
-- Returns the original query, corrected query, and whether a suggestion was found
-- Useful for query refinement before searching
+- `similar`, `cited_by`, or `references` for a PMID, in NCBI relevance order, enriched with title, authors, date, and source (or Bookshelf book title and publisher)
+- Falls back to Europe PMC, then OpenAlex, when NCBI can't answer; the response names the provider. Fails with a typed `all_providers_failed` error rather than an empty result
 
 ---
 
-### `pubmed_lookup_mesh`
+### `pubmed_spell_check` <sub>tool</sub>
 
-Search and explore the MeSH (Medical Subject Headings) vocabulary.
+- Runs a query through NCBI ESpell and returns `original`, `corrected`, and `hasSuggestion`
+- A blank or whitespace-only query is rejected rather than sent upstream
 
-- Search MeSH terms by name with exact-heading matching
-- Detailed records with tree numbers, scope notes, and entry terms by default
-- Useful for building precise PubMed queries with controlled vocabulary
+---
+
+### `pubmed_lookup_mesh` <sub>tool</sub>
+
+- Looks up MeSH descriptors by name or free-text term, pinning the exact-heading match to the top of the first page
+- Records carry `meshId` (DescriptorUI), `entrezUid`, and, with `includeDetails` (default on), tree numbers, scope notes, and entry terms
+- `maxResults` up to 50 with offset pagination via `nextOffset`; `totalCount` reports the upstream match count
 
 ---
 
-### `pubmed_lookup_citation`
+### `pubmed_lookup_citation` <sub>tool</sub>
 
-Resolve partial bibliographic references to PubMed IDs via NCBI ECitMatch.
+- Match on journal, year, volume, first page, and/or author — at least one field, more fields for better precision; up to 25 per call
+- Pipes and line breaks are rejected at the schema (ECitMatch's wire format is pipe-delimited); the free-form `key` label is exempt
+- Explicit `matched`, `not_found`, and `ambiguous` statuses with recovery detail
+
+---
 
-- 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
+### `pubmed_convert_ids` <sub>tool</sub>
+
+- Up to 50 DOIs, PMIDs, or PMCIDs per call, all one type; only PMC-indexed articles resolve
+- One id per element — a packed `"23193287,37952131"` is rejected rather than expanded
+- Per-id success/error rows; a partial batch never fails as a whole
 
 ---
 
-### `pubmed_convert_ids`
+### `pubmed://database/info` <sub>resource</sub>
 
-Convert between article identifiers (DOI, PMID, PMCID) using the PMC ID Converter API.
+- Live EInfo call for the `pubmed` database, returned as `application/json`
+- `dbName`, `description`, `count`, `lastUpdate`, and `fields[]` — each field's short `name` (the tag usable in `pubmed_search_articles` queries), `fullName`, and `description`
+- No parameters
 
-- 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
+---
 
-## Resource and prompt
+### `research_plan` <sub>prompt</sub>
 
-| Type | Name | Description |
-|:---|:---|:---|
-| Resource | `pubmed://database/info` | PubMed database metadata via EInfo (field list, record count, last update) |
-| Prompt | `research_plan` | Generate a structured 4-phase biomedical research plan outline |
+- Arguments: `title`, `goal`, `keywords` (comma-separated) required; `organism` and `includeAgentPrompts` (`"true"` / `"false"`) optional
+- Returns two messages: an assistant framing message (biomedical research planning assistant, grounds recommendations in the PubMed tools when available) and a user message carrying the plan
+- The plan walks four phases — Conception & Planning, Data Collection & Processing, Analysis & Interpretation, Dissemination — with sub-steps under each
+- `includeAgentPrompts: "true"` adds an agent-guidance block under each sub-step, several of which point at `pubmed_search_articles` and `pubmed_lookup_mesh`
 
 ## Features
 
-Built on [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core):
-
-- Declarative tool definitions — single file per tool, framework handles registration and validation
-- Unified error handling across all tools
-- Pluggable auth (`none`, `jwt`, `oauth`)
-- Swappable storage backends: `in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`
-- Structured logging with optional OpenTelemetry tracing
-- Runs locally (stdio/HTTP) or on Cloudflare Workers from the same codebase
+Built on [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core): stdio and Streamable HTTP transports, pluggable auth (`none` / `jwt` / `oauth`), swappable storage (`in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`), structured logging with optional OpenTelemetry tracing.
 
 PubMed-specific:
 
@@ -303,7 +271,7 @@ MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
 
 ### Prerequisites
 
-- [Bun v1.3.2](https://bun.sh/) or higher.
+- [Bun v1.4.0](https://bun.sh/) or higher.
 - Optional: [NCBI API key](https://www.ncbi.nlm.nih.gov/account/settings/) for higher rate limits (10 req/s vs 3 req/s).
 
 ### Installation
@@ -328,7 +296,7 @@ bun install
 
 ## Configuration
 
-All configuration is validated at startup via Zod schemas in `src/config/server-config.ts`. Key environment variables:
+Key environment variables:
 
 | Variable | Description | Default |
 |:---|:---|:---|
@@ -403,7 +371,7 @@ See [`CLAUDE.md`](./CLAUDE.md) for development guidelines and architectural rule
 
 ## Contributing
 
-Issues and pull requests are welcome. Run checks and tests before submitting:
+Issues are welcome. Run checks and tests before submitting:
 
 ```sh
 bun run devcheck

package/changelog/2.0.x/2.0.0.md

@@ -0,0 +1,32 @@
+---
+summary: "Initial release — 7 PubMed tools, NCBI E-utilities service layer (eSearch/eSummary/eFetch/eLink/eSpell/eInfo with rate-limit + retry), `research_plan` prompt, and `pubmed://database/info` resource."
+breaking: false
+---
+
+# 2.0.0 — 2026-03-04
+
+## Added
+
+- **NCBI Service Layer**: Complete E-utilities integration (`eSearch`, `eSummary`, `eFetch`, `eLink`, `eSpell`, `eInfo`) with request queuing, rate limiting, retry with exponential backoff, and XML parsing.
+- **7 PubMed Tools**:
+  - `pubmed_search` — Search PubMed with filters, date ranges, and optional summaries
+  - `pubmed_fetch` — Fetch full article metadata by PMIDs (abstract, authors, journal, MeSH)
+  - `pubmed_cite` — Generate formatted citations (APA 7th, MLA 9th, BibTeX, RIS)
+  - `pubmed_related` — Find related/cited-by/references via ELink
+  - `pubmed_spell` — Spell-check biomedical queries via ESpell
+  - `pubmed_trending` — Date-filtered search for recent publications
+  - `pubmed_mesh_lookup` — MeSH vocabulary search and exploration
+- **Research Plan Prompt**: `research_plan` — structured 4-phase biomedical research plan generation
+- **Database Info Resource**: `pubmed://database/info` — PubMed database metadata via EInfo
+- **Citation Formatters**: Hand-rolled, zero-dependency, Workers-compatible formatters for APA, MLA, BibTeX, and RIS
+- **NCBI Configuration**: `NCBI_API_KEY`, `NCBI_ADMIN_EMAIL`, `NCBI_REQUEST_DELAY_MS`, `NCBI_MAX_RETRIES`, `NCBI_TIMEOUT_MS`
+
+## Changed
+
+- **Rebranded** from `mcp-ts-template` to `@cyanheads/pubmed-mcp-server` (package.json, server.json, smithery.yaml, wrangler.toml)
+- **Architecture**: Built on mcp-ts-template 3.0 with DI container, typed tokens, Zod-validated config, OpenTelemetry, and multi-transport support (stdio, HTTP, Cloudflare Workers)
+
+## Removed
+
+- All template example tools, resources, prompts, and services (graph, LLM, speech)
+- `openai`, `@modelcontextprotocol/ext-apps` dependencies

package/changelog/2.0.x/2.0.1.md

@@ -0,0 +1,32 @@
+---
+summary: "`pubmed_search` gains field filters, offset pagination, and PMC URLs; `pubmed_mesh_lookup` exact-heading sort; `pubmed_trending` removed; six tool and config defaults revised."
+breaking: false
+---
+
+# 2.0.1 — 2026-03-04
+
+## Added
+
+- **Search filters**: `pubmed_search` gained field-specific filters (`author`, `journal`, `meshTerms`, `language`, `hasAbstract`, `freeFullText`, `species`) and pagination via `offset`
+- **PMC links**: `pubmed_fetch` and `pubmed_search` summaries now include `pmcId`, `pubmedUrl`, and `pmcUrl` for direct article access
+- **Affiliation deduplication**: article parser collects affiliations into a single array with per-author index references, reducing payload size for multi-center papers
+- **Exact MeSH heading search**: `pubmed_mesh_lookup` runs a parallel `[MH]` exact-heading search and stable-sorts exact matches to the top
+
+## Changed
+
+- **`pubmed_search`**: renamed `includeSummaries` to `summaryCount`; date range format changed from `YYYY/MM/DD` to `YYYY-MM-DD` (auto-converted internally)
+- **`pubmed_cite`**: max PMIDs raised from 20 to 50
+- **`pubmed_related`**: simplified to use `cmd=neighbor` for all relationship types instead of `neighbor_history` + WebEnv for cited_by/references
+- **`pubmed_mesh_lookup`**: `includeDetails` now defaults to `true`; switched from eFetch to eSummary for detail retrieval (MeSH eFetch returns plain text, not XML)
+- **NCBI response handler**: demoted `eSearchResult.ErrorList` (PhraseNotFound, FieldNotFound) from errors to warnings — NCBI populates these on valid zero-result queries; enabled `processEntities` and `htmlEntities` in XML parser
+- **Config defaults**: HTTP port 3010 → 3017, transport default `http` → `stdio`, storage default `filesystem` → `in-memory`
+
+## Fixed
+
+- **Auth factory tests**: JWT strategy tests now provide `mcpAuthSecretKey` and restore it on teardown
+- **Response handler tests**: updated assertions to match ErrorList demotion (PhraseNotFound is a warning, not a thrown error)
+- **Conformance tests**: removed `pubmed_trending` from expected tools list
+
+## Removed
+
+- **`pubmed_trending` tool**: removed — its functionality is fully covered by `pubmed_search` with date range and `pub_date` sort

package/changelog/2.1.x/2.1.0.md

@@ -0,0 +1,17 @@
+---
+summary: "Adds `pubmed_pmc_fetch` tool — fetch full-text articles from PubMed Central via NCBI EFetch, with a JATS XML parser returning structured body sections, metadata, and references."
+breaking: false
+---
+
+# 2.1.0 — 2026-03-04
+
+## Added
+
+- **`pubmed_pmc_fetch` tool**: Fetch full-text articles from PubMed Central (PMC) via NCBI EFetch with `db=pmc`. Accepts PMC IDs directly or PubMed IDs (auto-resolved to PMCIDs via ELink). Returns structured body sections, subsections, metadata, and optional references parsed from JATS XML.
+- **PMC article parser**: JATS XML parser (`pmc-article-parser.ts`) extracts metadata (authors, affiliations, journal, keywords, publication date, abstract), recursive body sections, and back-matter references from PMC EFetch responses.
+- **PMC types**: JATS XML element types and parsed PMC result types (`XmlJatsArticle`, `ParsedPmcArticle`, etc.) in `src/services/ncbi/types.ts`.
+
+## Changed
+
+- **NCBI response handler**: Added PMC JATS-specific jpaths (`pmc-articleset.article`, `contrib-group.contrib`, `body.sec`, `ref-list.ref`, etc.) to the `isArray` set for consistent XML parsing.
+- **README**: Added `pubmed_pmc_fetch` tool documentation, updated server description to mention full-text fetch.

package/changelog/2.1.x/2.1.1.md

@@ -0,0 +1,29 @@
+---
+summary: "Bug fixes across response handler, PMC/article parsers, and citation formatter — plus comprehensive test coverage for NCBI service and parser edge cases."
+breaking: false
+---
+
+# 2.1.1 — 2026-03-04
+
+## Fixed
+
+- **Response handler**: `extractTextValues` now handles numeric and boolean primitives emitted by fast-xml-parser when `parseTagValue` is enabled
+- **Response handler**: Error detection uses shared `ERROR_PATHS` constant to stay in sync with error message extraction
+- **PMC article parser**: Empty PMCID no longer produces a bare "PMC" prefix — returns empty string instead
+- **Article parser**: Eliminated redundant `getText()` calls for month, day, and medlineDate in `extractJournalInfo`
+- **Citation formatter**: `formatAuthorApa` no longer produces "undefined." when firstName contains consecutive spaces
+- **Citation formatter**: Reordered `formatAuthorApa` logic so authors with only initials (no lastName) return formatted initials instead of empty string
+
+## Changed
+
+- **Citation formatter**: `escapeBibtex` refactored from chained `.replace()` calls to a single regex with switch — fixes ordering bug where backslash-then-brace sequences were double-escaped
+- **Citation formatter**: `splitPages` simplified with destructuring
+
+## Added
+
+- Comprehensive test coverage for NCBI service edge cases: eSearch non-numeric fields, eSpell fallbacks, eSummary retmode logic, eFetch POST behavior
+- Response handler tests: `CannotRetrievePMID` error path, numeric error values, DOCTYPE stripping, `returnRawXml` error passthrough
+- Citation formatter tests: BibTeX special character escaping, APA author formatting edge cases, author-count boundaries (1/3/20/21), page splitting with en-dash/em-dash, minimal article formatting
+- Article parser tests: PMC ID extraction from `ArticleIdList`, ORCID extraction, ISSN type classification, MedlineDate without year, empty AffiliationInfo handling
+- ESummary parser tests: nested Author objects, string authors, PMC ID from ArticleIds, FullJournalName fallback
+- PMC article parser tests: `pmc-uid` fallback, empty PMCID, affiliations, page ranges, pub-date priority (epub > ppub > pub)

package/changelog/2.1.x/2.1.2.md

@@ -0,0 +1,18 @@
+---
+summary: "`pmc_fetch` renamed to `pubmed_pmc_fetch`; log directory path resolution switched to `node:path` for cross-platform correctness ([#9](https://github.com/cyanheads/pubmed-mcp-server/pull/9))."
+breaking: false
+---
+
+# 2.1.2 — 2026-03-04
+
+## Changed
+
+- **Tool rename**: `pmc_fetch` renamed to `pubmed_pmc_fetch` for consistency with the `pubmed_*` naming convention across all tools
+
+## Fixed
+
+- **Config**: Path resolution for logs directory now uses `node:path` utilities (`dirname`, `join`, `isAbsolute`) instead of URL-based arithmetic for cross-platform correctness ([#9](https://github.com/cyanheads/pubmed-mcp-server/pull/9))
+
+## Updated
+
+- `@cloudflare/workers-types` to `4.20260305.1`

package/changelog/2.1.x/2.1.3.md

@@ -0,0 +1,10 @@
+---
+summary: "Fix: OpenTelemetry NodeSDK now initializes on Bun — `isBun` guard removed, manual spans, custom metrics, and OTLP export all work correctly."
+breaking: false
+---
+
+# 2.1.3 — 2026-03-04
+
+## Fixed
+
+- **Telemetry**: Enable OpenTelemetry NodeSDK on Bun — the `isBun` guard was unnecessarily blocking initialization when manual spans, custom metrics, and OTLP export all work correctly

package/changelog/2.1.x/2.1.4.md

@@ -0,0 +1,12 @@
+---
+summary: "`pubmed_fetch` gains `affiliations` and `articleDates` fields; public hosted endpoint added to README; new output-schema coverage tests prevent strict-client rejections."
+breaking: false
+---
+
+# 2.1.4 — 2026-03-04
+
+## Added
+
+- **pubmed_fetch**: `affiliations` (deduplicated author affiliations) and `articleDates` (electronic publication, received, accepted dates) now included in article output
+- **Public hosted instance**: Added public Streamable HTTP endpoint (`https://pubmed.caseyjhand.com/mcp`) to README — no installation required
+- **Output schema coverage tests**: New test suite validates that tool output schemas cover every field returned by parsers at runtime, preventing strict-client rejections from `additionalProperties: false`

package/changelog/2.1.x/2.1.5.md

@@ -0,0 +1,18 @@
+---
+summary: "NCBI config now logged at startup (API key status, delay, retries, timeout). Dep bumps: `@biomejs/biome` 2.4.6, `jose` 6.2.0, `@types/node` 25.3.5."
+breaking: false
+---
+
+# 2.1.5 — 2026-03-06
+
+## Added
+
+- **Startup logging**: NCBI configuration (API key status, email, request delay, max retries, timeout) now logged at initialization for easier debugging
+
+## Updated
+
+- `@biomejs/biome` to 2.4.6
+- `@cloudflare/workers-types` to 4.20260307.1
+- `@types/node` to 25.3.5
+- `@types/sanitize-html` to 2.16.1
+- `jose` to 6.2.0

package/changelog/2.1.x/2.1.6.md

@@ -0,0 +1,15 @@
+---
+summary: "Fix: `structuredContent` removed from error responses (valid for success only); `fast-check` → 4.6.0, `jose` → 6.2.1."
+breaking: false
+---
+
+# 2.1.6 — 2026-03-09
+
+## Fixed
+
+- **Error responses**: Removed `structuredContent` from error responses in tool handler factory — `structuredContent` is only valid for successful results, not error payloads
+
+## Updated
+
+- `fast-check` to 4.6.0
+- `jose` to 6.2.1

package/changelog/2.10.x/2.10.0.md

@@ -0,0 +1,17 @@
+---
+summary: "New pubmed_europepmc_fetch tool (11th tool) resolves full Europe PMC records by source + epmcId; pubmed_fetch_fulltext gains maxCharacters/maxCharactersPerSection/overflowMode budget controls; a shared surrogate-pair-safe slice helper backs both."
+breaking: false
+security: false
+---
+
+# 2.10.0 — 2026-07-26
+
+## Added
+
+- **`pubmed_europepmc_fetch` tool** — new 11th tool. Resolves specific Europe PMC records by `source` + `epmcId` and returns each one's complete, untruncated abstract, up to 25 records per call resolved in a single Europe PMC request; unresolved pairs come back in `notFound` instead of failing the batch. This is the retrieval path for preprint (`PPR`), patent (`PAT`), and Agricola (`AGR`) records, which frequently carry no PMID and no DOI. Backed by a new `EuropePmcService.fetchRecords()` method that OR-joins `(EXT_ID:<id> AND SRC:<source>)` clauses into one search query. ([#83](https://github.com/cyanheads/pubmed-mcp-server/issues/83))
+- **`pubmed_fetch_fulltext` character budgets** — new `maxCharacters`, `maxCharactersPerSection`, and `overflowMode` (`truncate` | `outline`) inputs cap body text per article. `truncate` fills sections in document order so early sections stay whole; `outline` spreads the budget evenly across sections so every heading survives with an excerpt. Applies to `source=pmc` section/subsection text and the `source=unpaywall` body; titles, abstracts, identifiers, and references are never counted or cut. A new `truncation` output object reports per-article and per-section character counts whenever a budget shortened the response, and a matching `ctx.enrich.notice()` names what was spent. ([#81](https://github.com/cyanheads/pubmed-mcp-server/issues/81))
+- **`pubmed_europepmc_search` `abstractTruncated`** — new boolean alongside `abstractSnippet` (capped at 400 characters) marking whether the snippet was cut; pass the hit's `source` and `epmcId` to `pubmed_europepmc_fetch` for the full text. ([#83](https://github.com/cyanheads/pubmed-mcp-server/issues/83))
+
+## Fixed
+
+- **Character cuts could split a UTF-16 surrogate pair** — `pubmed_fetch_fulltext`'s new budget cuts and `pubmed_europepmc_search`'s `abstractSnippet` cut now back off one code unit when the boundary lands mid-pair, via a new shared `sliceCodeUnits` helper (`src/mcp-server/tools/definitions/_text.ts`). Budgets remain a code-unit ceiling; reported character counts are measured off the text actually returned, never assumed from the requested allowance. ([#93](https://github.com/cyanheads/pubmed-mcp-server/issues/93))

package/changelog/2.10.x/2.10.1.md

@@ -0,0 +1,14 @@
+---
+summary: "eSearch upstream failures now throw instead of masking as zero-hit searches; pubmed_search_articles surfaces ignored field tags, unmatched phrases, and dropped partial dateRange filters via notice; the summaryCount cap message points at pubmed_fetch_articles when maxed; research_plan's includeAgentPrompts is now correctly advertised as optional."
+breaking: false
+security: false
+---
+
+# 2.10.1 — 2026-07-26
+
+## Fixed
+
+- **`eSearchResult.ERROR` was missing from `ERROR_PATHS`** — an upstream eSearch failure parsed as a zero-hit success instead of throwing. `pubmed_search_articles`'s `offset` is now bounded at 9998 (`OFFSET_MAX`), matching PubMed's `retstart` ceiling, and the ceiling is stated in its `.describe()`. `pubmed_lookup_mesh`'s `offset` is left unbounded — `db=mesh` has no equivalent `retstart` ceiling. ([#95](https://github.com/cyanheads/pubmed-mcp-server/issues/95))
+- **eSearch `ErrorList`/`WarningList` never reached the caller** — `pubmed_search_articles` now reads both off the eSearch result and surfaces them through the `notice` enrichment: an unrecognized field tag fires independently of hit count, and an unmatched phrase names the exact clause instead of the generic empty-result guidance. `NcbiService.eSearch` normalizes every list member to `string[]` — NCBI collapses a single-entry member to a scalar, which the declared type didn't account for. ([#96](https://github.com/cyanheads/pubmed-mcp-server/issues/96))
+- **Partial `dateRange` and the `summaryCount` cap were both undisclosed** — a `dateRange` with exactly one bound filled now fires a notice naming the supplied bound and a sentinel for an open-ended range, instead of silently dropping the filter. The `summaryCount` cap message now points at `pubmed_fetch_articles` with the remaining PMIDs when already at its maximum, instead of advising a raise that isn't possible. `buildNotice()` now collects every applicable signal and joins them, rather than returning the first of two mutually exclusive branches. ([#97](https://github.com/cyanheads/pubmed-mcp-server/issues/97))
+- **`research_plan`'s `includeAgentPrompts` was advertised as a required prompt argument** — the SDK derives `prompts/list`'s `required` flag from schema optionality, and a `ZodDefault` doesn't read as optional. Changed from `.default('false')` to `.optional()`; `buildPlan`'s `=== 'true'` check behaves identically for an omitted value. ([#98](https://github.com/cyanheads/pubmed-mcp-server/issues/98))

package/changelog/2.10.x/2.10.10.md

@@ -0,0 +1,22 @@
+---
+summary: "pubmed_fetch_fulltext renders JATS block content at its own position and returns figures and supplementary material as a structured assets[] field, pubmed_find_related's OpenAlex fallback pages to the full requested window, and the query tools reject a blank query instead of forwarding it to NCBI."
+breaking: false
+security: false
+---
+
+# 2.10.10 — 2026-09-10
+
+## Added
+
+- **`pubmed_fetch_fulltext` `assets[]`** — every `<fig>` and `<supplementary-material>` a PMC article carries, with `assetType`, `label`, `caption`, `id`, `sectionTitle`, and the deposit-relative `href` pointer; each lifted asset leaves a `[Figure: <label>]` / `[Supplementary: <label>]` marker at its position. New `includeAssets` input (default `true`) mirrors `includeTables`. ([#130](https://github.com/cyanheads/pubmed-mcp-server/issues/130))
+- **`pubmed_find_related` `coverageFailures`** — when the Europe PMC or OpenAlex reference-coverage fallback throws, an entry naming `provider`, `reason`, and `retryable` is added instead of folding the failure into a false "no references" answer. ([#118](https://github.com/cyanheads/pubmed-mcp-server/issues/118))
+
+## Fixed
+
+- **JATS block content (lists, definition lists, quotes, boxed text, preformatted text, formulae) dropped or fused into surrounding prose** — each now renders inline at its position instead of vanishing or gluing onto a paragraph's sentence, and an article whose entire body is one such block (e.g. a legacy OCR `<preformat>` deposit) is no longer reported as having no body. A caption's own title no longer runs into the sentence that follows it — on tables as well as on figures and supplementary material — and a caption or label hung directly on a `<media>`/`<graphic>` pointer is now read. ([#130](https://github.com/cyanheads/pubmed-mcp-server/issues/130))
+- **`pubmed_fetch_fulltext` returned the first serialized `<abstract>` regardless of `@abstract-type`** — the untyped abstract is now preferred over a typed one (e.g. `graphical`, `executive-summary`), and content within the selected abstract renders through the same block-aware walk as body text, so an embedded figure caption reaches `assets[]` instead of the prose. ([#134](https://github.com/cyanheads/pubmed-mcp-server/issues/134))
+- **`pubmed_find_related`'s OpenAlex fallback stalled after its first upstream page** — `cited_by`, `references`, and `similar` now page (or batch-resolve, for the latter two) until the requested window is filled, upstream is exhausted, or a 10-page/batch cap is reached, with `totalCount` reporting the exact PubMed-addressable count once exhausted. This also fixes an HTTP 400 the `references` path threw once `offset + maxResults` reached 34, from a candidate filter of up to 200 values against OpenAlex's 100-value OR-clause ceiling. ([#117](https://github.com/cyanheads/pubmed-mcp-server/issues/117))
+- **A failed Europe PMC/OpenAlex reference-coverage fallback was reported as a genuine empty answer** — a thrown fallback now surfaces via `coverageFailures` and a distinct notice instead of being folded into NCBI's "no reference list" wording, and a provider disabled by configuration is marked non-retryable with no retry guidance offered. ([#118](https://github.com/cyanheads/pubmed-mcp-server/issues/118))
+- **A failed DOI backfill lookup was misreported as `no-doi`** — a new `doi-lookup-failed` reason (added to `UnavailableReasonSchema` and `TierOutcomeSchema`) now distinguishes an errored lookup from a record that genuinely has none. A DOI Europe PMC already returned is also now carried forward to Unpaywall instead of being discarded, skipping a redundant PubMed round-trip. ([#119](https://github.com/cyanheads/pubmed-mcp-server/issues/119))
+- **`pubmed_search_articles` accepted a blank query and forwarded it to NCBI as a blank term** — a whitespace-only or sanitized-to-empty query was previously retried as a misclassified transient outage across seven attempts and roughly a minute of backoff; it now fails immediately with a declared `blank_query` reason (`ValidationError`, non-retryable). ([#122](https://github.com/cyanheads/pubmed-mcp-server/issues/122))
+- **`pubmed_spell_check` and `pubmed_lookup_mesh` accepted blank queries and returned a false empty success** — both now reject the same `blank_query` reason before calling NCBI, instead of reporting a checked-but-empty result for a query that was never searched. ([#133](https://github.com/cyanheads/pubmed-mcp-server/issues/133))