@cyanheads/pubmed-mcp-server 2.10.13 → 2.10.14

package/changelog/2.10.x/2.10.5.md

@@ -0,0 +1,31 @@
+---
+summary: "Adopts mcp-ts-core 0.12.5: no HTTP status classifies as InternalError anymore (500/501 join the rest of 5xx as ServiceUnavailable), and an SSRF DNS-guard bypass on Bun 1.4 Linux is closed. The NCBI, OpenAlex, and Europe PMC retry loops now honor the framework's retryable:false opt-out so a 501 fails on the first attempt instead of retrying."
+breaking: false
+security: true
+---
+
+# 2.10.5 — 2026-09-02
+
+## Changed
+
+- **`@cyanheads/mcp-ts-core` `^0.12.3` → `^0.12.5`** — no HTTP status classifies as `InternalError` anymore; 500 and 501 join the rest of the 5xx range as `ServiceUnavailable` (504 stays `Timeout`), and a caller disconnect now classifies as `RequestCancelled` (-32011) rather than `InternalError`.
+- **Shipped skills re-synced** — `add-tool` 2.21, `api-config` 1.15, `api-context` 2.2, `api-errors` 1.8, `api-linter` 1.13, `api-utils` 2.8, `design-mcp-server` 2.23, `maintenance` 2.6, `release-and-publish` 2.13, `setup` 1.10.
+
+## Fixed
+
+- **Retry loops stop retrying a non-retryable 501** — new `src/services/retry-policy.ts` adds `isTransient()`, honoring the framework's `data.retryable === false` opt-out ahead of code-based classification. Folding 501 into the transient `ServiceUnavailable` code otherwise made the NCBI, OpenAlex, and Europe PMC retry loops re-ask a method the upstream declared unimplemented. `NcbiApiClient`'s local 500→`ServiceUnavailable` `codeOverride` is removed — the framework now classifies it natively.
+- **`.env.example` / README now show `MCP_SESSION_MODE=stateless`** — matching the Dockerfile default this server has shipped with; the prior `auto` example resolved to `stateful`, a mode this server has no `ctx.requestInput` call sites to use.
+
+## Security
+
+- **SSRF DNS-guard bypass on Bun 1.4 Linux** (inherited from `@cyanheads/mcp-ts-core` 0.12.4) — `assertDnsNotPrivate` now queries both `node:dns` resolvers, closing a gap where a hostname only the system resolver could see (`/etc/hosts`, split DNS, an NSS module) passed the guard and connected.
+
+## Dependencies
+
+- `@cyanheads/mcp-ts-core` `^0.12.3` → `^0.12.5`
+- `defuddle` `^0.19.2` → `^0.19.3`
+- `fast-xml-parser` `^5.11.0` → `^5.11.1`
+- `zod` `^4.4.3` → `^4.5.4`
+- `@biomejs/biome` (dev) `^2.5.9` → `^2.5.11`
+- `@types/node` (dev) `^26.2.0` → `^26.4.0`
+- `ignore` (dev) `^7.0.6` → `^7.0.7`

package/changelog/2.10.x/2.10.6.md

@@ -0,0 +1,30 @@
+---
+summary: "Five bug fixes: pubmed_find_related no longer returns false-empty Europe PMC pages or a fake empty success when every provider fails, Europe PMC title/author/journal markup is stripped and Markdown-escaped, an all-numeric spell_check query round-trips as text, and Unpaywall HTML is no longer parsed as a PDF. Adopts mcp-ts-core 0.12.7."
+breaking: false
+security: false
+---
+
+# 2.10.6 — 2026-09-08
+
+## Changed
+
+- **`@cyanheads/mcp-ts-core` `^0.12.5` → `^0.12.7`** — an argument rejection now carries `structuredContent.error` classified as `InvalidParams` rather than `ValidationError`, on every transport; Node and workerd type checking run as separate programs, lifting the `@cloudflare/workers-types` hold. Packaging validation adopted here checks each present plugin manifest's `version` against `package.json`'s.
+- **Shipped skills re-synced** — `add-tool` 2.22, `api-errors` 1.9, `api-workers` 1.8, `design-mcp-server` 2.24, `field-test` 2.10, `git-wrapup` 1.12.
+
+## Fixed
+
+- **`pubmed_find_related`'s Europe PMC fallback no longer returns false-empty pages** (#101) — `epmcProvider()` pages Europe PMC (up to 1000 rows/page, up to 10 pages) until the requested window of PubMed-addressable rows is filled instead of fetching a single page capped at 100. `EuropePmcService.citations()`/`references()` now report `droppedNoPmid` (non-`MED` rows with no PubMed PMID) and `hitCount` separately from the addressable `totalCount`; the tool discloses excluded rows and a page-cap shortfall in its enrichment notice instead of silently returning an empty window.
+- **`pubmed_find_related` fails instead of faking an empty success when every provider fails** (#103) — a chain where NCBI, Europe PMC, and OpenAlex all fail now throws a typed `all_providers_failed` error carrying each attempted provider's reason (`data.attempted`), rather than returning `articles: []` with an invented `source: "ncbi"`. A provider disabled by server configuration (`EUROPEPMC_ENABLED=false`, no `OpenAlexService`) is now reported as `provider_disabled` and excluded from the retry hint; a provider that genuinely serves zero related records still succeeds unchanged.
+- **Europe PMC `title`/`authors`/`journal` markup no longer leaks into either output surface** (#102) — `pubmed_europepmc_fetch` and `pubmed_europepmc_search` now run all three through `toDisplayText()`, the same JATS/HTML-stripping, entity-decoding pass already applied to `abstractText`. A new `escapeMarkdownInline()` (`src/mcp-server/tools/definitions/_text.ts`) additionally neutralizes Markdown-significant characters at every title-as-heading interpolation in `content[]` — both Europe PMC tools plus `pubmed_fetch_articles`, `pubmed_fetch_fulltext`, `pubmed_search_articles`, and `pubmed_find_related` — so upstream text can no longer alter heading structure, toggle emphasis, or inject a link; `structuredContent` keeps the unescaped plain-text value.
+- **`pubmed_spell_check` no longer fails output validation on an all-numeric query** (#108) — `NcbiService.eSpell` now parses its response with a new verbatim (`parseTagValue: false`) XML parser, so a query like `33306283` round-trips as the string `"33306283"` instead of being coerced to a number, and `"007"` / `"1e5"` round-trip byte-identical instead of losing their leading zero or exponential form.
+- **`pubmed_fetch_fulltext` no longer parses an HTML paywall page as a PDF** (#104) — `UnpaywallService.fetchAs` classifies a fetched Unpaywall response by its bytes' `%PDF-` magic header instead of the requested kind, so a `url_for_pdf` response that is actually HTML (a publisher paywall/interstitial) falls through to the `location.url` landing page instead of failing with a misleading `Invalid PDF structure` error; a genuine PDF served under an unexpected `content-type` still parses.
+
+## Dependencies
+
+- `@cyanheads/mcp-ts-core` `^0.12.5` → `^0.12.7`
+- `@biomejs/biome` (dev) `^2.5.11` → `^2.5.12`
+- `@types/node` (dev) `^26.4.0` → `^26.4.1`
+- `@vitest/coverage-istanbul` (dev) `^4.1.11` → `^5.0.0`
+- `ignore` (dev) `^7.0.7` → `^7.0.8`
+- `tsc-alias` (dev) `^1.9.2` → `^1.9.4`
+- `vitest` (dev) `^4.1.11` → `^5.0.0`

package/changelog/2.10.x/2.10.7.md

@@ -0,0 +1,17 @@
+---
+summary: "pubmed_fetch_articles and pubmed_fetch_fulltext gain an opt-in maxResponseCharacters whole-response budget with deferred-article continuation; fetch_fulltext reports unqueriedTiers when a search skipped an unconfigured tier; format_citations names accepted format values on an invalid input."
+breaking: false
+security: false
+---
+
+# 2.10.7 — 2026-09-09
+
+## Added
+
+- **`maxResponseCharacters`** on `pubmed_fetch_articles` (#99) and `pubmed_fetch_fulltext` (#100) — an opt-in whole-response character ceiling, distinct from `fetch_fulltext`'s existing per-article `maxCharacters`. Articles are kept in response order until the next one would cross the ceiling; the rest are deferred whole (never partially populated) and listed in the new `deferred.ids`, keyed under the branch they were requested on (`pmids`/`pmcids`/`dois` for `fetch_fulltext`). Re-calling with `deferred.ids` resumes exactly where the response stopped. Omitting the field is byte-identical to prior output. Shared accounting lives in the new `src/mcp-server/tools/definitions/_budget.ts` (`fitWholeItems`, `serializedCharacters`).
+- **`unavailable[].unqueriedTiers`** on `pubmed_fetch_fulltext` (#110) — lists tiers (`europepmc`, `unpaywall`) the chain skipped because this deployment has not configured them and that could have served the id, so a caller can tell an incomplete search from a settled miss. A tier inapplicable to the id (no DOI for Unpaywall) is never listed.
+
+## Changed
+
+- **`pubmed_fetch_fulltext`'s `reason` no longer folds an unconfigured tier's absence into the reported signal** (#110) — `reason` now always reflects the most specific content signal a tier that actually answered reported; the incompleteness moved to `unqueriedTiers` instead of silently overriding `reason`. Two reason values shift as a result: a DOI-less record with Unpaywall unconfigured now reports `no-doi` (was `no-pmc-fallback-disabled`), and a PMCID/PMID no tier indexes now reports `not-found` even when Unpaywall's last chain entry is `no-doi`.
+- **`pubmed_format_citations`'s `format` union now names its accepted values on a top-level validation failure** — an invalid value (e.g. `"chicago"`) surfaces `Invalid option: expected one of "apa"|"mla"|"bibtex"|"ris"|"vancouver", or a non-empty array of those values` in `content[]` directly, instead of a generic `Invalid input` that buried the accepted values inside `structuredContent.error`.

package/changelog/2.10.x/2.10.8.md

@@ -0,0 +1,22 @@
+---
+summary: "ECitMatch reconciliation now keys on per-request wire tokens so duplicate caller keys no longer misassign results; pubmed_fetch_fulltext folds JATS sections nested three or more levels deep into the deepest surviving subsection's text; mixed-citation references separate zero-gap adjacent pub-ids and title/volume pairs."
+breaking: false
+security: false
+---
+
+# 2.10.8 — 2026-09-09
+
+## Changed
+
+- **`.env.example` Supabase keys** — `SUPABASE_SERVICE_ROLE_KEY` is what the `supabase` storage provider requires and `SUPABASE_ANON_KEY` is optional; each line now names its role.
+
+## Fixed
+
+- **`pubmed_lookup_citation` duplicate-key result misassignment** — `eCitMatch` reconciled response rows by the caller-supplied `key`, which may repeat; a duplicate (or a caller key colliding with an auto-assigned one) collapsed two citations onto one row and handed the second citation's PMID and validation context to the first. Reconciliation now runs on a per-request wire token unique within the call, restoring the caller's key on the way out. ([#113](https://github.com/cyanheads/pubmed-mcp-server/issues/113))
+- **`pubmed_fetch_fulltext` sections nested three or more levels deep** — the output schema declares two levels of JATS section nesting; deeper `<sec>` elements were silently stripped by output validation. They now fold into the deepest surviving subsection's `text`, each heading on its own line; the schema stays at two levels since `format-parity`'s 8-hop walker already spends its budget reaching `sections[].subsections[]`. The character-budget report's `originalCharacters` now counts those folded heading lines, since they're real characters in the returned text. ([#112](https://github.com/cyanheads/pubmed-mcp-server/issues/112))
+- **`pubmed_fetch_fulltext` reference citations with zero-gap adjacent elements** — JATS `mixed-citation` rendered via flat `textContent()`, which glues together elements with no separating text: adjacent typed `<pub-id>`s fused into one token, and an inline italic title running straight into a following bold volume fused the same way. `extractReferences` now renders `mixed-citation` child-by-child, labeling typed pub-ids and inserting a single space between zero-gap adjacent elements. ([#115](https://github.com/cyanheads/pubmed-mcp-server/issues/115), [#123](https://github.com/cyanheads/pubmed-mcp-server/issues/123))
+
+## Dependencies
+
+- `@cyanheads/mcp-ts-core` ^0.12.7 → ^0.12.8 — releases now run through a gated release PR: `git-wrapup` stops at a pushed `release/<version>` branch with an open PR, and `release-and-publish` fast-forwards `main` and tags its tip.
+- Skills synced from 0.12.8 — new `release-pr-review` 1.0; `api-config` 1.16, `api-services` 1.5, `api-telemetry` 1.8, `api-utils` 2.9, `code-simplifier` 1.4, `field-test` 2.12, `git-wrapup` 1.13, `orchestrations` 1.8, `release-and-publish` 2.14.

package/changelog/2.10.x/2.10.9.md

@@ -0,0 +1,15 @@
+---
+summary: "pubmed_fetch_fulltext now extracts JATS tables as structured cells, finds Europe PMC references nested under <body> at any depth, and matches a sections filter against subsection titles too; mixed-citation author names and Europe PMC's numeric-text coercion are also fixed."
+breaking: false
+security: false
+---
+
+# 2.10.9 — 2026-09-10
+
+## Fixed
+
+- **`pubmed_fetch_fulltext` JATS tables dropped or fused into prose** — a `<table-wrap>` beside a section's paragraphs was silently absent from the response, and one nested inside a `<p>` had its cells concatenated into the surrounding sentence with no delimiter. Tables are now extracted into a new `tables[]` field (article-level, covering body, `<floats-group>`, `<back>`, and appendix deposits) with `colspan`/`rowspan` expanded to one cell per grid column; a deposit with no readable markup (graphic-only, CALS `<tgroup>`) is returned labeled with `unextractableReason` instead of silently missing. New `includeTables` input (default `true`); table text now counts against `maxCharacters` and a table that doesn't fit is dropped whole rather than cut mid-row. ([#111](https://github.com/cyanheads/pubmed-mcp-server/issues/111))
+- **`pubmed_fetch_fulltext` Europe PMC references nested under `<body>` discarded** — `extractReferences` searched only a direct `<back>` child for `<ref-list>`, missing the majority Europe PMC placement (`body/sec/sec/ref-list`) entirely. It now finds `<ref-list>` at any depth under the article, deduplicating by `<ref>` id so a document exposing the same list under both `<back>` and `<body>` still yields each reference once. ([#116](https://github.com/cyanheads/pubmed-mcp-server/issues/116))
+- **`pubmed_fetch_fulltext` mixed-citation author names glued together** — a `<name>`/`<string-name>`/`<person-group>` with no text between `<surname>` and `<given-names>` rendered joined (`NybakkenJW`); `renderMixedCitation` now applies its zero-gap element spacing rule inside author-name wrappers, not just between a citation's direct children. ([#124](https://github.com/cyanheads/pubmed-mcp-server/issues/124))
+- **`pubmed_fetch_fulltext` `sections` filter matched only top-level titles** — a filter term naming a subsection heading (e.g. `"Demographics"` nested under `"Results"`) returned nothing, with no indication that subsections were unmatchable. Matching is now recursive across nesting depth; a section kept only because a descendant matched is returned as a breadcrumb, with its own text cleared and just the matching branch beneath it. ([#126](https://github.com/cyanheads/pubmed-mcp-server/issues/126))
+- **Europe PMC full-text parser coerced numeric-looking text** — `EuropePmcService`'s XML parser ran `parseTagValue: true` against a comment claiming parity with the PMC parser, so bibliographic tokens (page ranges, reference labels like `"1."`) were coerced through `Number` on the Europe PMC path but not the PMC EFetch path. Both parsers now build from one shared `ORDERED_XML_PARSER_OPTIONS` constant, keeping the two paths byte-identical in configuration — which also gives the Europe PMC path the `maxTotalExpansions` entity-expansion cap it had been running without. ([#127](https://github.com/cyanheads/pubmed-mcp-server/issues/127))

package/changelog/2.2.x/2.2.0.md

@@ -0,0 +1,67 @@
+---
+summary: "The server was migrated to use the `@cyanheads/mcp-ts-core` framework for MCP plumbing."
+breaking: false
+---
+
+# 2.2.0 — 2026-03-23
+
+## Framework Migration
+
+The server was migrated to use the `@cyanheads/mcp-ts-core` framework for MCP plumbing. This will simplify and streamline future development.
+
+## Tool Renames
+
+All tools were renamed for clarity. Schemas and capabilities are unchanged.
+
+| Previous (v2.1.x) | New (v2.2.0) |
+|:-------------------|:-------------|
+| `pubmed_search` | `pubmed_search_articles` |
+| `pubmed_fetch` | `pubmed_fetch_articles` |
+| `pubmed_pmc_fetch` | `pubmed_fetch_fulltext` |
+| `pubmed_related` | `pubmed_find_related` |
+| `pubmed_cite` | `pubmed_format_citations` |
+| `pubmed_mesh_lookup` | `pubmed_lookup_mesh` |
+| `pubmed_spell` | `pubmed_spell_check` |
+
+## Changed
+
+- **Framework migration**: Replaced inline framework code (~58k lines) with `@cyanheads/mcp-ts-core` package dependency. All tools, resources, and prompts now use the framework's declarative builders (`tool()`, `resource()`, `prompt()`)
+- **Tool definitions**: Rewritten from handler-factory pattern to single-file `tool()` builder definitions with Zod input/output schemas, `format` functions, and `annotations`
+- **Resource definition**: `database-info.resource.ts` migrated from custom `ResourceDefinition` type to framework's `resource()` builder with `handler(params, ctx)` pattern
+- **Prompt definition**: `research-plan.prompt.ts` migrated from custom `PromptDefinition` type to framework's `prompt()` builder
+- **Entry point**: `src/index.ts` simplified from DI container + server bootstrap to single `createApp()` call with tool/resource/prompt arrays
+- **NCBI service**: Flattened from `services/ncbi/core/` subdirectory to `services/ncbi/` top-level; uses framework's `logger` instead of custom logger
+- **Config**: Replaced monolithic `src/config/index.ts` with focused `src/config/server-config.ts` (NCBI-specific env vars only; framework handles transport, auth, storage)
+- **Build**: Switched from custom build scripts to framework-provided `tsconfig.base.json`, `biome.json`, and `vitest.config.ts` extensions
+- **Tool file renames**: Files renamed to match tool names (e.g., `pubmed-search.tool.ts` → `search-articles.tool.ts`, `pubmed-spell.tool.ts` → `spell-check.tool.ts`)
+- **CLAUDE.md**: Replaced generic placeholder patterns with actual server examples (spell-check tool, database-info resource, NCBI config), updated structure tree, removed unused context properties
+- **README.md**: Updated all tool names and descriptions to match renames, updated config section
+- **Dockerfile**: Fixed image title/description labels, added `source` label, corrected log directory name and default port
+- **Default HTTP port**: Reverted to `3010` across `.env.example`, `Dockerfile`, `README.md`, and `server.json` (was changed to `3017` in 2.0.1)
+- **server-config.ts**: Replaced `z.string().email()` with `z.email()` shorthand
+- **.env.example**: Added `NCBI_TIMEOUT_MS` entry
+
+## Added
+
+- **Test suite**: 178 tests across 17 files in `tests/` mirroring `src/` structure — covers config, NCBI service layer, XML/JSON parsers, citation formatters, all 7 tools, 1 resource, and 1 prompt using `createMockContext()` from `@cyanheads/mcp-ts-core/testing`
+- **Skills directory**: Framework skill files for development workflows (add-tool, add-resource, devcheck, field-test, etc.)
+- **MCP definition linter**: `bun run lint:mcp` validates tool/resource/prompt definitions against the MCP spec at build time
+- **devcheck.config.json**: Centralized devcheck configuration
+
+## Fixed
+
+- **fetch-articles**: Added `unavailablePmids` to output — surfaces which requested PMIDs returned no article data
+- **fetch-fulltext**: Added `unavailablePmcIds` to output — tracks which PMC IDs returned no data; fetch failures now return a graceful empty result instead of throwing
+- **research-plan prompt**: Corrected tool reference from `pubmed_mesh_lookup` to `pubmed_lookup_mesh`; clarified `includeAgentPrompts` description
+
+## Security
+
+- **package.json**: Added `overrides` to pin transitive dependencies `express-rate-limit` (>=8.2.2) and `hono` (>=4.12.7) to patched versions
+
+## Removed
+
+- **Inline framework code**: DI container, transport layer (stdio/HTTP/Workers), storage providers, auth strategies, error handler, logger, telemetry, utilities — all now provided by `@cyanheads/mcp-ts-core`
+- **Legacy tests**: Old test suite removed (covered framework internals, not server logic); replaced by new `tests/` suite
+- **Worker entry point**: `src/worker.ts` removed (framework handles Workers deployment via `createWorkerHandler()`)
+- **Cloudflare config**: `wrangler.toml`, `schemas/cloudflare-d1-schema.sql` removed
+- **Misc**: `.husky/pre-commit`, `smithery.yaml`, `repomix.config.json`, `typedoc.json`, `tsdoc.json`, various README docs in `src/`

package/changelog/2.2.x/2.2.1.md

@@ -0,0 +1,10 @@
+---
+summary: "Fix: adds missing `mcpName` field to `package.json` required by the MCP registry for publishing."
+breaking: false
+---
+
+# 2.2.1 — 2026-03-23
+
+## Fixed
+
+- **package.json**: Added `mcpName` field required by the MCP registry for publishing

package/changelog/2.2.x/2.2.2.md

@@ -0,0 +1,20 @@
+---
+summary: "Format improvements for `fetch-articles`, `fetch-fulltext`, and `find-related`; NCBI raw exception traces replaced with user-friendly messages; `@cyanheads/mcp-ts-core` 0.1.29."
+breaking: false
+---
+
+# 2.2.2 — 2026-03-24
+
+## Changed
+
+- **fetch-articles format**: Now displays authors (first 3 + "et al."), journal info (abbreviation, year, volume, issue, pages), publication types, and unavailable PMIDs
+- **fetch-fulltext format**: Renders subsections within body sections
+- **find-related**: Added `source` and `pubDate` fields to output schema and format display
+
+## Fixed
+
+- **NCBI error messages**: Raw C++ exception traces from NCBI are now replaced with concise, user-friendly messages
+
+## Updated
+
+- `@cyanheads/mcp-ts-core` to 0.1.29

package/changelog/2.2.x/2.2.3.md

@@ -0,0 +1,17 @@
+---
+summary: "Retry logic moved to `NcbiService.performRequest` to cover XML-level NCBI errors; backoff changed to 1s base; HTML rate-limit responses now throw `ServiceUnavailable`. 8 new retry integration tests."
+breaking: false
+---
+
+# 2.2.3 — 2026-03-24
+
+## Changed
+
+- **Retry logic**: Moved retry with exponential backoff from `NcbiApiClient` (HTTP-only) to `NcbiService.performRequest`, so retries now cover both HTTP-level failures and XML-level NCBI errors (e.g., 200 OK with C++ exception traces in the response body)
+- **Backoff timing**: Retry delays changed from 200ms base (200, 400, 800ms) to 1s base (1s, 2s, 4s) for more conservative backoff
+- **`api-client`**: Simplified to single-attempt; now checks `response.ok` and throws `ServiceUnavailable` for non-OK HTTP status codes
+
+## Added
+
+- **HTML response detection**: `NcbiResponseHandler` now detects HTML responses from NCBI (typically rate-limiting pages) and throws `ServiceUnavailable` instead of an opaque XML parse error
+- **Retry integration tests**: New colocated test file `src/services/ncbi/ncbi-service.test.ts` — 8 tests covering HTTP retry, XML-level retry, timeout retry, non-retryable error passthrough, exhaustion messaging, and backoff timing

package/changelog/2.2.x/2.2.4.md

@@ -0,0 +1,34 @@
+---
+summary: "Format output enriched — `pubmed_fetch_articles` gains affiliations, MeSH/grants; `pubmed_fetch_fulltext` gains authors, journal, references. Deps: `mcp-ts-core` →0.2.3, `biome` →2.4.9."
+breaking: false
+---
+
+# 2.2.4 — 2026-03-28
+
+## Added
+
+- **fetch-articles format**: Affiliations, keywords, MeSH terms (with major topic markers and qualifiers), and grant information now rendered in format output
+- **fetch-fulltext format**: Authors, affiliations, journal info, article type, publication date, PubMed URL, keywords, and reference list now rendered in format output; unavailable PMC IDs surfaced
+- **Skills**: `report-issue-framework` and `report-issue-local` for filing bugs/feature requests against the framework or this server
+
+## Changed
+
+- **polish-docs-meta skill**: Updated to v1.2 — added GitHub repo metadata sync step, description propagation rule (`package.json` → README header, `server.json`, Dockerfile), renumbered checklist steps
+
+## Refactored
+
+- Optional chaining cleanup in `article-parser.ts` and `fetch-articles.tool.ts` (replaced `x && x.y` with `x?.y`)
+
+## Updated
+
+- `@cyanheads/mcp-ts-core` to ^0.2.3
+- `@biomejs/biome` to ^2.4.9
+- `vitest` to ^4.1.2
+
+## Security
+
+- Added overrides for `brace-expansion` (>=2.0.3), `path-to-regexp` (>=8.4.0), `picomatch` (>=4.0.4), `yaml` (>=2.8.3)
+
+## Docs
+
+- Added `LOGS_DIR` env var to README and reference docs

package/changelog/2.2.x/2.2.5.md

@@ -0,0 +1,10 @@
+---
+summary: "Maintenance — `@cyanheads/mcp-ts-core` bumped to ^0.2.8. No runtime API changes."
+breaking: false
+---
+
+# 2.2.5 — 2026-03-28
+
+## Updated
+
+- `@cyanheads/mcp-ts-core` to ^0.2.8

package/changelog/2.2.x/2.2.6.md

@@ -0,0 +1,17 @@
+---
+summary: "Skill updates — `add-tool` v1.1 expands `format()` template and adds Tool Response Design section; `add-resource` and `design-mcp-server` gain coverage guidance and tools-first patterns. Bumps `mcp-ts-core` ^0.2.10, `biome` ^2.4.10."
+breaking: false
+---
+
+# 2.2.6 — 2026-03-30
+
+## Changed
+
+- **add-tool skill** (v1.1): Content-complete `format()` template; new Tool Response Design section covering batch input, partial success, empty results, error classification, operational metadata, and context budget
+- **add-resource skill** (v1.1): Added tool coverage guidance — verify data is reachable via the tool surface for tool-only clients
+- **design-mcp-server skill** (v2.1): Tools-first design philosophy, live API probing step, batch input design patterns, convenience shortcuts, error design table with classification, resilience and API efficiency planning, naming convention refinement
+
+## Updated
+
+- `@cyanheads/mcp-ts-core` to ^0.2.10
+- `@biomejs/biome` to ^2.4.10

package/changelog/2.3.x/2.3.0.md

@@ -0,0 +1,27 @@
+---
+summary: "Adds `pubmed_lookup_citation` (ECitMatch, batch 25) and `pubmed_convert_ids` (DOI/PMID/PMCID via PMC ID Converter, batch 50). Refactored retry logic and HTTP error classification in `NcbiApiClient`."
+breaking: false
+---
+
+# 2.3.0 — 2026-03-31
+
+## Added
+
+- **`pubmed_lookup_citation` tool**: Resolve partial bibliographic references (journal, year, volume, page, author) to PubMed IDs via NCBI ECitMatch. Batch up to 25 citations per request with deterministic matching.
+- **`pubmed_convert_ids` tool**: Convert between DOI, PMID, and PMCID using the PMC ID Converter API. Batch up to 50 IDs per request; returns all available identifier mappings.
+- **`NcbiService.eCitMatch()`**: ECitMatch service method — formats bdata pipe-delimited strings, parses multi-line responses, handles NOT_FOUND/AMBIGUOUS results.
+- **`NcbiService.idConvert()`**: PMC ID Converter service method — JSON-based external API call with error classification.
+- **`NcbiApiClient.makeExternalRequest()`**: HTTP client method for non-eutils NCBI endpoints (e.g., PMC ID Converter). Uses plain fetch with `AbortSignal.timeout` for response body access on error status codes.
+- **Test coverage**: Full test suites for both new tools and service methods (eCitMatch parsing, idConvert JSON handling, input validation, format output)
+
+## Changed
+
+- **Retry logic**: Extracted inline retry loop from `performRequest` into reusable `withRetry()` method, shared by both eutils and external API calls
+- **HTTP error classification**: `NcbiApiClient` now distinguishes 4xx (InvalidRequest) from 5xx (ServiceUnavailable) errors instead of treating all non-OK responses as ServiceUnavailable
+- **Endpoint suffix handling**: `api-client.ts` skips `.fcgi` suffix for endpoints that already contain a dot (e.g., `ecitmatch.cgi`)
+
+## Docs
+
+- Updated README tool count (7 → 9), added tool descriptions and detail sections for both new tools
+- Updated CLAUDE.md tool count (7 → 9)
+- Regenerated `docs/tree.md` with new files

package/changelog/2.3.x/2.3.1.md

@@ -0,0 +1,15 @@
+---
+summary: "Fix `pubmed_search_articles` ignoring empty `dateRange` strings — skips date clause instead of producing a malformed NCBI query (closes [#14](https://github.com/cyanheads/pubmed-mcp-server/issues/14))."
+breaking: false
+---
+
+# 2.3.1 — 2026-04-01
+
+## Fixed
+
+- **`pubmed_search_articles`**: Empty `dateRange` strings (e.g., `{ minDate: "", maxDate: "" }`) no longer produce a malformed NCBI query returning 0 results — the handler now skips the date clause when either date is empty ([#14](https://github.com/cyanheads/pubmed-mcp-server/issues/14))
+- **`pubmed_search_articles`**: Date field descriptions updated to reflect accepted NCBI formats (`YYYY/MM/DD`, `YYYY/MM`, or `YYYY`)
+
+## Added
+
+- **Test coverage**: 7 new tests for `dateRange` handling — empty strings, omitted dateRange, partial dates, valid dates, and dash-to-slash conversion

package/changelog/2.3.x/2.3.10.md

@@ -0,0 +1,20 @@
+---
+summary: "PMC full-text parser preserves document order via `preserveOrder: true` (closes [#19](https://github.com/cyanheads/pubmed-mcp-server/issues/19)); all-invalid-ID fetches now surface failures (closes #20)."
+breaking: false
+---
+
+# 2.3.10 — 2026-04-20
+
+## Fixed
+
+- **`pubmed_fetch_fulltext` — PMC parser lost document order on mixed-content markup** (`pmc-article-parser.ts`, `response-handler.ts`, `pmc-xml-helpers.ts`): `extractTextContent` consumed `fast-xml-parser` output in `preserveOrder: false` mode, which collapses `#text` fragments and reorders inline children by property-key order. Older Science/Nature PMC deposits (e.g. `PMC4089965`) came back with garbled abstracts — sentences interleaved, gene lists detached — and `sections: []` because the body's direct `<p>` children were skipped whenever a trailing supplementary `<sec>` was present. Added a second `FastXmlParser` instance with `preserveOrder: true, trimValues: false` dedicated to PMC, routed via a new `useOrderedParser` flag on `NcbiRequestOptions`. New `pmc-xml-helpers.ts` module provides typed helpers (`tagNameOf`, `childrenOf`, `attrOf`, `textContent`, `findOne`, `findAll`) over the ordered shape. Rewrote `pmc-article-parser.ts` around them; `extractBodySections` now walks body children in document order so mixed `<p>` + `<sec>` bodies preserve their main text. PubMed E-utilities parsing is unchanged — the ordered parser is opt-in.
+- **`pubmed_fetch_articles` / `pubmed_fetch_fulltext` — silent empty payload when all requested IDs are invalid** (`fetch-articles.tool.ts`, `fetch-fulltext.tool.ts`): Both tools short-circuited before computing `unavailablePmids` / `unavailablePmcIds`, so a caller passing a single bad ID received `{ articles: [], totalReturned: 0 }` with no signal about what failed. The mixed-input path (some valid, some invalid) worked correctly; only the all-invalid path regressed. Dropped the early returns; the existing post-parse set-difference logic now covers every case uniformly. Also narrowed the ordered-mode error tag regex in `response-handler.ts` to case-sensitive `<ERROR>` so PMC's lowercase per-ID `<error id="…">` element (returned for missing PMCIDs) falls through as data rather than triggering a retry-throw cascade.
+
+## Changed
+
+- **Removed obsolete `XmlJats*` types** (`types.ts`): The unordered JATS element types no longer describe the parser output for PMC responses. Replaced with a short note pointing readers at `pmc-xml-helpers.ts` for the `JatsNode` / `JatsNodeList` interface.
+
+## References
+
+- Closes [#19](https://github.com/cyanheads/pubmed-mcp-server/issues/19) — PMC full-text parser lost document order on complex inline markup.
+- Closes [#20](https://github.com/cyanheads/pubmed-mcp-server/issues/20) — `fetch_articles` / `fetch_fulltext` silently returned empty when all IDs were invalid.

package/changelog/2.3.x/2.3.11.md

@@ -0,0 +1,21 @@
+---
+summary: "`pubmed_fetch_articles` format() renders all schema fields in `content[]` (closes [#26](https://github.com/cyanheads/pubmed-mcp-server/issues/26)); actionable PMID validation errors (#27); parser omits empty arrays for absent fields (#28)."
+breaking: false
+---
+
+# 2.3.11 — 2026-04-20
+
+## Fixed
+
+- **`pubmed_fetch_articles` — `format()` silently dropped schema fields from `content[]`** (`fetch-articles.tool.ts`): The rendered markdown that most LLM clients forward to the model omitted `articleDates`, per-author `firstName` / `orcid` / `affiliationIndices`, journal `issn` / `eIssn` / full publication date (month, day, medlineDate), the raw `pmcId`, grant `acronym`, and collapsed authors beyond the third to `et al.` — even though every value was present in `structuredContent`. Rewrote the formatter: authors render as a bulleted list with `firstName lastName`, 1-based affiliation markers that point into a new numbered `Affiliations` section, and an inline ORCID suffix when present; the journal line now renders year/month/day (or `medlineDate`) and the preferred ISSN; a new `Article Dates` line surfaces electronic/received/revised dates; grants show the acronym alongside the ID; and empty-result responses include a one-line hint that points the caller at `pubmed_search_articles`. Field-tested end-to-end over HTTP with PMIDs 13054692, 17960126, 36813558 to confirm every field in the output schema now appears in `content[]`.
+
+## Changed
+
+- **PMID schema validation error message — actionable across all tools accepting PMIDs** (`fetch-articles.tool.ts`, `fetch-fulltext.tool.ts`, `find-related.tool.ts`, `format-citations.tool.ts`): The shared `z.string().regex(/^\d+$/)` guard previously produced the raw `Invalid string: must match pattern /^\d+$/` message for every failure mode — trailing whitespace, comma-joined IDs, and non-digit input all looked identical. Supplied an explicit regex message that names the domain concept, shows an example (`"13054692"`), and lists the common pitfalls (whitespace, commas, non-digit characters) so the caller can self-correct without inspecting the regex.
+- **Article parser omits empty arrays for absent optional fields** (`article-parser.ts`): `parseFullArticle` no longer returns `publicationTypes: []`, `keywords: []`, `articleDates: []`, `meshTerms: []` (when `includeMesh: true` but none present), or `grantList: []` (when `includeGrants: true` but none present). The schema already marked these `.optional()`; now the runtime matches the types. Reduces payload size on older papers (Watson & Crick 1953 no longer carries three empty arrays) and tightens the contract between parser output and the output schema.
+
+## References
+
+- Closes [#26](https://github.com/cyanheads/pubmed-mcp-server/issues/26) — `fetch_articles` format() dropped fields from `content[]` that were present in `structuredContent`.
+- Closes [#27](https://github.com/cyanheads/pubmed-mcp-server/issues/27) — PMID validation error was opaque; now surfaces actionable guidance.
+- Closes [#28](https://github.com/cyanheads/pubmed-mcp-server/issues/28) — Parser returned empty arrays for absent fields instead of omitting them.

package/changelog/2.3.x/2.3.2.md

@@ -0,0 +1,27 @@
+---
+summary: "ESummary date parsing fix (`parseNcbiDate`), `pubmed_fetch_fulltext` now propagates eFetch errors, `pubmed_search_articles` uses `effectiveQuery` for PubMed link, `pubmed_format_citations` adds POST mode for large batches."
+breaking: false
+---
+
+# 2.3.2 — 2026-04-04
+
+## Fixed
+
+- **ESummary date parsing**: Added dedicated `parseNcbiDate()` for NCBI's non-standard date formats (`YYYY Mon`, `YYYY Mon DD`, `YYYY Mon-Mon`, `YYYY`). chrono-node's `forwardDate` option was misinterpreting past months as future dates (e.g., "2018 Jun" resolved to a future June). The new parser handles all known NCBI formats as a fast path, falling back to chrono-node only for unrecognized strings.
+- **`pubmed_search_articles`**: Search URL now uses `effectiveQuery` (post-filter) instead of raw `input.query`, so the PubMed link matches the actual search executed
+- **`pubmed_fetch_fulltext`**: Removed try/catch that silently swallowed eFetch errors and returned empty results — errors now propagate per the "handlers throw" convention
+- **`pubmed_format_citations`**: Added explicit `retmode: 'xml'` and POST mode for batches >= 25 PMIDs
+
+## Changed
+
+- **`pubmed_fetch_articles`**: Lowered POST threshold from > 200 to >= 100 PMIDs for more reliable large batch requests
+
+## Added
+
+- **Test coverage**: Comprehensive `parseNcbiDate` unit tests covering all 12 months, year-only, month ranges (dash/slash separators), whitespace handling, and rejection of invalid formats. Integration tests through `standardizeESummaryDate` and `extractBriefSummaries`. Optional live NCBI API integration tests (`NCBI_INTEGRATION=1`).
+
+## Updated
+
+- `@cyanheads/mcp-ts-core` to ^0.2.12
+- `fast-xml-parser` to ^5.5.10
+- `@types/node` to ^25.5.2

package/changelog/2.3.x/2.3.3.md

@@ -0,0 +1,38 @@
+---
+summary: "Output enrichments — `pubmed_search_articles` adds `effectiveQuery` and `appliedFilters`, `pubmed_lookup_citation` adds per-citation `status`, `pubmed_format_citations` adds partial-result counters."
+breaking: false
+---
+
+# 2.3.3 — 2026-04-09
+
+## Added
+
+- **`pubmed_search_articles`**: Returned `effectiveQuery` and normalized `appliedFilters` metadata so clients can inspect the exact filters sent to PubMed
+- **`pubmed_lookup_citation`**: Returned per-citation `status` (`matched`, `not_found`, `ambiguous`) and ECitMatch detail for non-exact outcomes
+- **`pubmed_format_citations`**: Returned `totalSubmitted`, `totalFormatted`, and `unavailablePmids` for partial-result handling
+- **Skill**: Added the `code-simplifier` agent skill for cleanup/refinement passes after edits
+- **Test coverage**: Added `tests/index.test.ts` for `createApp()` registration/setup and expanded tool/service tests for search, citation lookup, citation formatting, related articles, and fulltext flows, including regression coverage for normalized `appliedFilters` output and summary clamping in `pubmed_search_articles`
+
+## Fixed
+
+- **`pubmed_search_articles`**: History-backed summary fetches now clamp to the returned PMID page, and `appliedFilters` now reports the normalized/sanitized values actually sent to PubMed
+
+## Changed
+
+- **`pubmed_search_articles`**: Format output now shows the effective query and a normalized Applied Filters section
+- **`pubmed_lookup_citation`**: Format output now gives next-step guidance for ambiguous and unmatched citations instead of a flat status table
+
+## Updated
+
+- `@cyanheads/mcp-ts-core` to ^0.3.4
+- `fast-xml-parser` to ^5.5.11
+- `vitest` to ^4.1.4
+- Added `@vitest/coverage-istanbul` for coverage support
+
+## Security
+
+- Added/raised overrides for `@hono/node-server` (>=1.19.13), `hono` (>=4.12.12), and `vite` (>=8.0.8)
+
+## Docs
+
+- Marked `docs/design.md` as historical and regenerated `docs/tree.md` for the current project layout

package/changelog/2.3.x/2.3.4.md

@@ -0,0 +1,21 @@
+---
+summary: "HTTP 429 now classified as `RateLimited` and retried; default `maxRetries` raised 3 → 6 with 30s backoff cap and ±25% jitter."
+breaking: false
+---
+
+# 2.3.4 — 2026-04-12
+
+## Fixed
+
+- **HTTP 429 classification**: NCBI rate-limit responses (HTTP 429) were misclassified as `InvalidRequest` and failed immediately without retrying. Now correctly classified as `RateLimited`.
+- **Retry resilience**: `RateLimited` errors are now included in the retryable error set alongside `ServiceUnavailable` and `Timeout`.
+
+## Changed
+
+- **Retry defaults**: Increased default `maxRetries` from 3 to 6, extending the retry window from ~7s to ~45-75s before giving up.
+- **Backoff strategy**: Added 30s cap on exponential backoff (prevents explosion at high retry counts) and ±25% jitter (prevents thundering herd on concurrent retries).
+
+## Updated
+
+- `@biomejs/biome` to ^2.4.11
+- `@types/node` to ^25.6.0

package/changelog/2.3.x/2.3.5.md

@@ -0,0 +1,24 @@
+---
+summary: "XML handling — raised entity expansion ceiling, preserved diacritics, wrapped parser failures as `SerializationError`. Retry tightened: only transient `McpError` retries. `fast-xml-parser` ^5.5.12."
+breaking: false
+---
+
+# 2.3.5 — 2026-04-13
+
+## Fixed
+
+- **XML response handling**: Raised the numeric entity expansion ceiling for trusted NCBI XML, preserved decoded punctuation/diacritics in parsed metadata, and wrapped parser failures as `SerializationError`.
+- **Retry behavior**: Stopped retrying unexpected plain errors in `NcbiService`; only transient `McpError` responses are retried now.
+
+## Added
+
+- **Regression coverage**: Added end-to-end and unit tests for Unicode metadata, en-dash page ranges, parser failure wrapping, and entity-heavy XML payloads.
+
+## Updated
+
+- `@cyanheads/mcp-ts-core` to ^0.3.5
+- `fast-xml-parser` to ^5.5.12
+
+## Docs
+
+- Updated the `design-mcp-server` and `add-test` skills for MCP Apps planning guidance and default test layout guidance.

package/changelog/2.3.x/2.3.6.md

@@ -0,0 +1,26 @@
+---
+summary: "Maintenance — five deps updated, `overrides` block removed (all nine pinned transitives patched upstream), tool description strings collapsed to single-paragraph convention."
+breaking: false
+---
+
+# 2.3.6 — 2026-04-19
+
+## Updated
+
+- `@cyanheads/mcp-ts-core` to ^0.3.7
+- `fast-xml-parser` to ^5.7.1
+- `sanitize-html` to ^2.17.3
+- `@biomejs/biome` to ^2.4.12
+- `typescript` to ^6.0.3
+
+## Removed
+
+- **Dependency overrides**: Removed the `overrides` block from `package.json`. All nine pinned transitive deps (`hono`, `@hono/node-server`, `brace-expansion`, `express-rate-limit`, `path-to-regexp`, `picomatch`, `vite`, `yaml`, `lodash`) have since shipped patched versions upstream, making the overrides dead weight. `bun audit` remains clean.
+
+## Changed
+
+- **Tool descriptions**: Collapsed multi-line `+` string concatenation in `pubmed_search_articles`, `pubmed_fetch_fulltext`, and `pubmed_convert_ids` to single strings, aligning with the project's description convention and the updated `add-tool` / `design-mcp-server` skill guidance (single cohesive paragraph, no structural noise).
+
+## Docs
+
+- Synced `add-tool` (v1.4) and `design-mcp-server` (v2.3) skills from the framework — both now emphasize single-paragraph tool descriptions over bullet lists or blank-line-separated sections.

package/changelog/2.3.x/2.3.7.md

@@ -0,0 +1,31 @@
+---
+summary: "Citation formatter fixes — APA collective-author period, RIS page expansion, BibTeX double-period; adds pub-type mapping, ISSN, PMC URL, MeSH keywords (closes [#15](https://github.com/cyanheads/pubmed-mcp-server/issues/15))."
+breaking: false
+---
+
+# 2.3.7 — 2026-04-20
+
+## Fixed
+
+- **APA — missing period before year with collective authors** (`citation-formatter.ts`): `formatApa` now coerces a trailing period on the author block. Individual author initials already end with `.`, but collective names (e.g., `ATLAS Collaboration`, `KEYNOTE-024 Investigators`, `ACTT-1 Study Group Members`) did not, producing `Name (Year).` instead of the APA 7 §9.8-compliant `Name. (Year).`. Fix mirrors the `endsWith('.')` idiom already used in `formatMla`.
+- **RIS — truncated-end page ranges emitted as absolute pages** (`splitPages`): `737-8` now expands to `SP 737 / EP 738`, `1639-41` to `SP 1639 / EP 1641`, etc. PubMed uses a truncated-end convention for page ranges; downstream RIS importers (Zotero, EndNote, Mendeley) treat `EP` as an absolute page number, so the unexpanded form rendered wrong page ranges in compiled bibliographies.
+- **BibTeX — trailing period retained inside `title = {...}`** (`formatBibtex`): titles ending with `.` are now stripped before emission. biblatex styles append their own terminal period, so the prior behavior produced `...Final Report..` (double period) in compiled bibliographies. Mirrors the existing APA/MLA title handling.
+
+## Changed
+
+- **MLA `p.` vs `pp.`** (`formatMla`): single-page citations now use `p.`, page ranges continue to use `pp.`, per MLA 9 §6.56.
+- **RIS abstract whitespace** (`formatRis`): structured-abstract newlines (`BACKGROUND:\n\nMETHODS:\n\n...`) are collapsed to single spaces before emission. Strict RIS parsers treat blank lines as record terminators, so the prior output could truncate records at the first `\n\n` boundary.
+- **`getYear` fallback** (`citation-formatter.ts`): falls back to `articleDates` (typically the electronic pub date) when `journalInfo.publicationDate.year` is absent, instead of emitting `n.d.` prematurely.
+
+## Added
+
+- **Publication type → entry/reference type mapping**: `publicationTypes` now drives BibTeX entry types (`@book`, `@inbook`, `@misc`) and RIS `TY` codes (`BOOK`, `CHAP`, `GEN`) for `Book`, `Book Chapter`, and `Preprint`. Unmapped types fall back to `@article` / `TY - JOUR`.
+- **RIS `SN` (ISSN) tag**: `journalInfo.issn` (with `eIssn` fallback) now emitted in RIS records.
+- **BibTeX `issn`, `pmcid` fields**: surfaced from parsed metadata when present.
+- **PMC URL in RIS**: second `UR` tag emitted when `pmcId` is present (`https://pmc.ncbi.nlm.nih.gov/articles/PMC.../`).
+- **Merged keywords + MeSH**: RIS `KW` tags and BibTeX `keywords` now include MeSH descriptor names alongside article keywords, deduplicated.
+- **Test coverage**: 11 new test cases covering the three bug fixes, MLA `p.`/`pp.` branching, abstract whitespace normalization, pub-type mapping, ISSN, PMC URL, MeSH merging, and `articleDates` year fallback.
+
+## References
+
+- Closes [#15](https://github.com/cyanheads/pubmed-mcp-server/issues/15) — field-testing report identifying the three APA/RIS/BibTeX correctness issues.

package/changelog/2.3.x/2.3.8.md

@@ -0,0 +1,19 @@
+---
+summary: "`pubmed_fetch_fulltext` PMID→PMCID resolution switched from eLink to PMC ID Converter (closes [#16](https://github.com/cyanheads/pubmed-mcp-server/issues/16)); `@cyanheads/mcp-ts-core` 0.3.7 → 0.4.1."
+breaking: false
+---
+
+# 2.3.8 — 2026-04-20
+
+## Fixed
+
+- **`pubmed_fetch_fulltext` — PMID→PMCID resolution via PMC ID Converter instead of eLink** (`fetch-fulltext.tool.ts`): `resolvePmidsToPmcIds` now calls `NcbiService.idConvert()` — the purpose-built DOI/PMID/PMCID mapping endpoint — rather than `eLink(cmd=neighbor, linkname=pubmed_pmc)`. Triggered by a sustained NCBI outage on 2026-04-20 where eLink's `exLinkSrv2` backend returned `Couldn't resolve #exLinkSrv2, the address table is empty.` for every request, breaking all fulltext calls; the ID Converter runs on a different backend and stayed up throughout. Equivalent coverage (both require the article be in PMC), batch-friendly (up to 200 IDs/request vs. the tool's 10 cap), and drops ~30 lines of ELink XML type shims.
+
+## Changed
+
+- **Dependency updates**: `@cyanheads/mcp-ts-core` 0.3.7 → 0.4.1, picking up OTel prompt telemetry (0.4.1), Vitest 4 `projects` testing helpers (0.4.0), and the duplicate `"Error:"` prefix fix (0.3.8). No handler-facing API changes.
+- **Skill sync**: `skills/api-utils` refreshed from the package — adds `withRetry` options reference and partial-success batch metric documentation.
+
+## References
+
+- Closes [#16](https://github.com/cyanheads/pubmed-mcp-server/issues/16) — feature request to swap the fulltext resolution path off eLink, filed after the 2026-04-20 outage.