@cyanheads/pubmed-mcp-server 2.10.17 → 2.10.19

package/README.md

@@ -7,9 +7,7 @@
 
 <div align="center">
 
-
-
-[![Version](https://img.shields.io/badge/Version-2.10.17-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.19-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.1.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.2-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
 </div>
 
@@ -31,23 +29,23 @@
 
 ## Overview
 
-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.
+Biomedical literature from PubMed, 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 |
 |:---|:---|
-| `pubmed_search_articles` | Search PubMed with full query syntax, field-specific filters, date ranges, pagination, and optional brief summaries |
-| `pubmed_europepmc_search` | Search Europe PMC for preprints, patents, Agricola, and EPMC-only OA records that don't surface in PubMed. Cursor-based pagination. |
-| `pubmed_europepmc_fetch` | Fetch complete Europe PMC records — including the untruncated abstract — by `source` + `epmcId`, the only identifier many preprint, patent, and Agricola records carry |
-| `pubmed_fetch_articles` | Fetch full article metadata by PMIDs — abstract, authors, journal, MeSH terms, grants |
-| `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 a PubMed query via NCBI ESpell — every misspelled token corrected in one call; the recovery step after a zero-hit or thin search |
-| `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 — one citation or a batch of up to 25 — to PubMed IDs via ECitMatch |
-| `pubmed_convert_ids` | Convert between DOI, PMID, and PMCID using the PMC ID Converter API |
+| `pubmed_search_articles` | Search PubMed with full query syntax, structured filters, date ranges, and optional summaries |
+| `pubmed_fetch_articles` | Fetch article metadata by PMID: abstract, authors, journal, MeSH terms, grants, linked retraction and correction notices |
+| `pubmed_fetch_fulltext` | Fetch full text by PMID, PMCID, or DOI, falling back from PMC to Europe PMC to Unpaywall |
+| `pubmed_europepmc_search` | Search Europe PMC for preprints, patents, Agricola, and open-access records PubMed doesn't carry |
+| `pubmed_europepmc_fetch` | Fetch complete Europe PMC records, including the untruncated abstract, by `source` + `epmcId` |
+| `pubmed_format_citations` | Format citations in APA 7th, MLA 9th, BibTeX, RIS, or Vancouver (ICMJE/NLM) |
+| `pubmed_find_related` | Find similar articles, citing articles, or references for a PMID |
+| `pubmed_spell_check` | Correct a misspelled PubMed query via NCBI ESpell |
+| `pubmed_lookup_mesh` | Look up MeSH headings with tree numbers, scope notes, and entry terms |
+| `pubmed_lookup_citation` | Resolve partial references, up to 25 at a time, to PMIDs via ECitMatch |
+| `pubmed_convert_ids` | Convert between DOI, PMID, and PMCID via the PMC ID Converter |
 
 ### Resources
 
@@ -59,131 +57,103 @@ The biomedical literature via NCBI's E-utilities, PubMed Central, and Europe PMC
 
 | Prompt | Description |
 |:---|:---|
-| `research_plan` | Generate a structured 4-phase biomedical research plan outline |
+| `research_plan` | Generate a structured four-phase biomedical research plan |
 
 ## Capability reference
 
 ### `pubmed_search_articles` <sub>tool</sub>
 
-- 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`; the rendered summary shows the doc type only for these, not for ordinary journal articles (`citation`)
-- Reports `totalCount`, stated in the header beside the page (`Returned: 3 of 2924`); echoes the original query, the fully applied PubMed query, and normalized filter metadata
-- A query with no search term — blank, markup only, a bare field tag like `[pdat]`, or empty `()` — is rejected as `blank_query` rather than sent upstream
-- `limit` is accepted for `maxResults`
+- Full PubMed query syntax plus filters (author, journal, MeSH, publication type, language, species, abstract, free full text) and publication/modification/Entrez date ranges
+- Up to 1,000 results per page and offsets up to 9,998; `summaryCount` adds briefs for up to 50 hits
+- Reports `totalCount`, the `effectiveQuery` PubMed ran, and the `appliedFilters`
+- Rejects blank filter values, impossible dates, and reversed date ranges before PubMed is called
 
 ---
 
 ### `pubmed_fetch_articles` <sub>tool</sub>
 
-- Up to 200 PMIDs per call (POST for batches of 100 or more); `ids` is accepted for `pmids`
-- A zero-padded PMID (`00000001`) resolves as the PMID it spells; `unavailablePmids` lists misses as you sent them
-- 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
+- Up to 200 PMIDs per call; misses are listed in `unavailablePmids`
+- Abstract, authors, journal, DOI, publication types, linked retraction/erratum/comment notices, and links; MeSH terms on by default, grants via `includeGrants`
+- `recordType` separates journal articles from Bookshelf chapters and books; opt-in `maxResponseCharacters` defers overflow to `deferred.ids`
 
 ---
 
 ### `pubmed_fetch_fulltext` <sub>tool</sub>
 
-- Exactly one of `pmcids`, `pmids`, or `dois` (one id per element), up to 10 per request; a zero-padded PMID or PMC ID resolves as the ID it spells, DOIs match case-insensitively, and PMC IDs match with or without the `PMC` prefix in any case. Each record is fetched once however many spellings name it; `unavailable[].id` keeps your PMID or DOI spelling, and reports a PMC ID as `PMC<digits>`
-- 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, and the file pointer read through `<alternatives>` when a figure offers several formats); `source: "unpaywall"` returns a best-effort body with `contentFormat` (`html-markdown` / `pdf-text`), a `title` from Unpaywall's record (else the Europe PMC record, else the HTML page), and `journalName` / `year` when Unpaywall has them
-- A titled list, definition list, or boxed text that sits in the body outside any section, or is the only content of an untitled section, such as an abbreviations list, becomes a section under its own title, and a figure or table inside it names that section; a section with no title is headed `untitled section`, the same name the `truncation` ledger gives it, and section titles in headings and ledger lines are Markdown-escaped
-- 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, per section and subsection
-- A budget cut ends at a word boundary; `truncate` drops every section and subsection past the cut, while `outline` keeps each heading and marks one the budget left empty
+- One of `pmcids`, `pmids`, or `dois`, up to 10 per call, tried against PMC, then Europe PMC, then Unpaywall (needs `UNPAYWALL_EMAIL`); `viaSource` names the tier that answered
+- `source: "pmc"` returns sections, tables, and figures; `source: "unpaywall"` returns a best-effort HTML or PDF text body
+- Misses carry a typed `reason` and `triedTiers`; `sections`, `maxCharacters`, `overflowMode`, and `maxResponseCharacters` bound the response, and `truncation` reports what was cut
 
 ---
 
 ### `pubmed_europepmc_search` <sub>tool</sub>
 
-- 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`; `pageSize` up to 100, with `max_results` and `limit` accepted for it
-- Hits carry `source` plus `pmid` / `pmcId` / `doi` when known; `abstractSnippet` is capped at 400 characters, with `abstractTruncated` flagging the cut
-- `totalCount` reports the full hit count, stated in the header beside the page; `searchUrl` opens the same source-filtered query on europepmc.org
+- Adds preprints (`PPR`), patents (`PAT`), and Agricola (`AGR`) to `MED` and `PMC`; defaults to `MED`, `PMC`, `PPR`
+- Cursor pagination via `cursorMark` / `nextCursorMark`, up to 100 per page; abstracts arrive as 400-character snippets
 - Not registered when `EUROPEPMC_ENABLED=false`
 
 ---
 
 ### `pubmed_europepmc_fetch` <sub>tool</sub>
 
-- 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
+- Up to 25 records per call, addressed by a search hit's `source` + `epmcId`, with the full abstract; unresolved ids land in `notFound`
 - Not registered when `EUROPEPMC_ENABLED=false`
 
 ---
 
 ### `pubmed_format_citations` <sub>tool</sub>
 
-- 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; `ids` is accepted for `pmids`, and a zero-padded PMID resolves as the PMID it spells
+- Up to 50 PMIDs per call, in any mix of `apa`, `mla`, `bibtex`, `ris`, and `vancouver`
+- Bookshelf records cite as edited books; PMIDs that can't be fetched are reported as unavailable
 
 ---
 
 ### `pubmed_find_related` <sub>tool</sub>
 
-- `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
-- `maxResults` up to 50 (`limit` also accepted) with offset pagination; `totalCount` reports the full match count, stated in the header beside the page
-- A zero-padded source PMID resolves as the PMID it spells and is never listed among its own related articles
+- `similar`, `cited_by`, or `references`, up to 50 per page with offset pagination
+- Falls back to Europe PMC, then OpenAlex, and names the provider that answered; fails as `all_providers_failed` if none can
 
 ---
 
 ### `pubmed_spell_check` <sub>tool</sub>
 
-- Runs a PubMed query through NCBI ESpell and returns `original`, `corrected`, and `hasSuggestion`; every misspelled token is corrected in one call (`alzhiemer diseese treatmnt outcomse` → `alzheimer disease treatment outcomes`)
-- Reach for it after a zero-hit or thin `pubmed_search_articles` result, or when a drug, gene, disease, or author name may be misspelled, then re-run the search with `corrected`
-- A blank or whitespace-only query is rejected rather than sent upstream
+- Returns `original`, `corrected`, and `hasSuggestion`, fixing every misspelled token in one call
+- Run it after a zero-hit or thin search, then retry `pubmed_search_articles` with `corrected`
 
 ---
 
 ### `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 (`limit` also accepted) with offset pagination via `nextOffset`; `totalCount` reports the upstream match count
+- Descriptors by name or free-text term, with an exact heading match pinned first; up to 50 per page, continued via `nextOffset`
+- Records carry `meshId`; `includeDetails` (default on) adds tree numbers, scope notes, and entry terms
 
 ---
 
 ### `pubmed_lookup_citation` <sub>tool</sub>
 
-- Match on journal, year, volume, first page, and/or author — journal or year required, more fields for better precision
-- `citations` takes an array of up to 25 or a single citation object; `citation` is accepted for it
-- 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
+- Up to 25 partial citations per call; journal or year is required, and volume, first page, and author sharpen the match
+- Each comes back `matched`, `not_found`, or `ambiguous`, 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
-- One success/error row per submitted element, in order, with `requestedId` exactly as sent — repeats, a bare-digit PMCID, and a DOI's casing included; a partial batch never fails as a whole
-- A zero-padded PMID resolves as the PMID it spells
+- Up to 50 ids per call, all of one declared `idType` (`doi`, `pmid`, `pmcid`); only PMC-indexed articles resolve
+- One success or error row per id, in order, so a partial batch never fails
 
 ---
 
 ### `pubmed://database/info` <sub>resource</sub>
 
 - 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
+- `count`, `lastUpdate`, and `fields[]`, whose names are the search tags `pubmed_search_articles` accepts
 
 ---
 
 ### `research_plan` <sub>prompt</sub>
 
-- 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`
+- Arguments: `title`, `goal`, and `keywords` required; `organism` and `includeAgentPrompts` optional
+- Returns a four-phase research plan; `includeAgentPrompts: "true"` adds an agent-guidance block under each of its nine sub-steps, two of which point at tools: the literature review names `pubmed_search_articles` and `pubmed_lookup_mesh`, and the interpretation step names `pubmed_search_articles`
 
 ## Features
 
@@ -191,16 +161,17 @@ Built on [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core): s
 
 PubMed-specific:
 
-- Complete NCBI E-utilities integration (ESearch, EFetch, ESummary, ELink, ESpell, EInfo, ECitMatch) plus PMC ID Converter
-- Shared NCBI request queue — paced request starts, capped concurrency, a cooldown that holds every caller after an NCBI 429, and one deadline covering queue wait and retries
-- NCBI-specific XML parser with `isArray` hints for PubMed's inconsistent XML structure
-- Hand-rolled citation formatters (APA, MLA, BibTeX, RIS, Vancouver) — zero deps, Workers-compatible
+- NCBI E-utilities (ESearch, EFetch, ESummary, ELink, ESpell, EInfo, ECitMatch) and the PMC ID Converter, with Europe PMC, OpenAlex, and Unpaywall filling the gaps
+- Shared NCBI request queue: paced request starts, capped concurrency, a cooldown that holds every caller after an NCBI 429, and one deadline covering queue wait and retries
+- XML parsing built for PubMed's inconsistent records: structured abstracts, missing fields, varying date formats
+- Forgiving identifiers: a zero-padded PMID resolves as the PMID it spells in every tool that takes one; `pubmed_fetch_fulltext` also matches DOIs case-insensitively and PMC IDs with or without the `PMC` prefix
+- Hand-rolled citation formatters (APA, MLA, BibTeX, RIS, Vancouver) with no dependencies
 
 Agent-friendly output:
 
-- Provenance on every response — source labels, license fields, best-effort warnings on Unpaywall results, and effective-query echo on searches so agents can reason about trust
-- Graceful partial failure — batch tools return per-item success/error rows instead of failing the request, with structured status codes and actionable next-step text
-- Discriminated output contracts — `source: "pmc" | "unpaywall"`, typed `unavailable` reasons, `viaSource` and `triedTiers` fields — callers branch on data, not string parsing
+- Provenance on every response: source labels, license fields, best-effort warnings on Unpaywall results, and effective-query echo on searches, so agents can judge what to trust
+- Graceful partial failure: batch tools return per-item success/error rows instead of failing the request, with structured status codes and actionable next-step text
+- Discriminated output contracts: `source: "pmc" | "unpaywall"`, typed `unavailable` reasons, `viaSource` and `triedTiers` fields, so callers branch on data, not string parsing
 
 ## Getting started
 
@@ -282,8 +253,8 @@ MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
 
 ### Prerequisites
 
-- [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).
+- [Bun v1.4.0](https://bun.sh/) or higher (or Node.js v24+).
+- Optional: an [NCBI API key](https://www.ncbi.nlm.nih.gov/account/settings/) raises the rate limit from 3 to 10 requests per second.
 
 ### Installation
 
@@ -305,37 +276,41 @@ cd pubmed-mcp-server
 bun install
 ```
 
-## Configuration
+4. **Configure environment:**
 
-Key environment variables:
+```sh
+cp .env.example .env
+# edit .env and set NCBI_API_KEY, NCBI_ADMIN_EMAIL, and UNPAYWALL_EMAIL as needed
+```
+
+## Configuration
 
 | Variable | Description | Default |
 |:---|:---|:---|
-| `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http` | `stdio` |
-| `MCP_HTTP_PORT` | HTTP server port | `3010` |
-| `MCP_HTTP_ENDPOINT_PATH` | HTTP endpoint path where the MCP server is mounted | `/mcp` |
-| `MCP_SESSION_MODE` | HTTP session mode: `stateless`, `stateful`, or `auto` (resolves to `stateful`). This server ships `stateless` — it has no `ctx.requestInput` call sites. | `stateless` |
-| `MCP_PUBLIC_URL` | Public origin override for TLS-terminating reverse-proxy deployments (landing page, Server Card, RFC 9728 metadata). | none |
-| `MCP_AUTH_MODE` | Authentication: `none`, `jwt`, or `oauth` | `none` |
-| `MCP_LOG_LEVEL` | Log level (`debug`, `info`, `warning`, `error`, etc.) | `info` |
-| `MCP_GC_PRESSURE_INTERVAL_MS` | Opt-in Bun-only forced-GC pressure loop (ms). Drains the per-request `McpServer`/`McpSessionTransport` cycle under sustained low-traffic HTTP. Recommended starting point if heap growth is observed: `60000`. | `0` (disabled) |
-| `LOGS_DIR` | Directory for log files (Node.js only). Relative paths resolve against the application root. | `<app-root>/logs` |
-| `STORAGE_PROVIDER_TYPE` | Storage backend: `in-memory`, `filesystem`, `supabase`, `cloudflare-kv/r2/d1` | `in-memory` |
-| `NCBI_API_KEY` | NCBI API key for higher rate limits (10 req/s vs 3 req/s) | none |
-| `NCBI_ADMIN_EMAIL` | Contact email sent with NCBI requests (recommended by NCBI) | none |
-| `NCBI_REQUEST_DELAY_MS` | Minimum gap between NCBI request starts in ms | 334 (100 with key) |
-| `NCBI_MAX_CONCURRENT` | Max concurrent in-flight NCBI requests | `8` |
-| `NCBI_MAX_RETRIES` | Retry attempts for failed NCBI requests | 6 |
-| `NCBI_TIMEOUT_MS` | Per-request HTTP timeout in ms | `30000` |
-| `NCBI_TOTAL_DEADLINE_MS` | Total deadline for one NCBI call — queue wait, retry attempts, and backoff — in ms. A call the queue cannot start before it is rejected at once | `60000` |
-| `UNPAYWALL_EMAIL` | Contact email for Unpaywall. When set, `pubmed_fetch_fulltext` falls back to Unpaywall open-access copies for non-PMC DOIs | none |
-| `UNPAYWALL_TIMEOUT_MS` | Per-request HTTP timeout for Unpaywall lookups and content fetches, in ms | `20000` |
-| `EUROPEPMC_ENABLED` | Enable Europe PMC search tool and the `pubmed_fetch_fulltext` JATS fallback chain. Set `false` to disable all EPMC calls and skip tool registration. | `true` |
-| `EUROPEPMC_EMAIL` | Optional contact email sent with Europe PMC requests (EBI courtesy). | none |
-| `EUROPEPMC_REQUEST_DELAY_MS` | Minimum gap between Europe PMC request starts in ms | `200` |
-| `EUROPEPMC_MAX_RETRIES` | Retry attempts for failed Europe PMC requests | `3` |
-| `EUROPEPMC_TIMEOUT_MS` | Per-request HTTP timeout for Europe PMC calls, in ms | `20000` |
-| `OTEL_ENABLED` | Enable OpenTelemetry | `false` |
+| `NCBI_API_KEY` | NCBI API key; raises the rate limit from 3 to 10 req/s. | none |
+| `NCBI_ADMIN_EMAIL` | Contact email sent with NCBI requests, as NCBI recommends. | none |
+| `NCBI_REQUEST_DELAY_MS` | Minimum gap between NCBI request starts, in ms. | `400` (`100` with a key) |
+| `NCBI_MAX_CONCURRENT` | Max concurrent in-flight NCBI requests. | `8` |
+| `NCBI_MAX_RETRIES` | Retry attempts for failed NCBI requests. | `6` |
+| `NCBI_TIMEOUT_MS` | Per-request HTTP timeout, in ms. | `30000` |
+| `NCBI_TOTAL_DEADLINE_MS` | Deadline for one NCBI call across queue wait, retries, and backoff, in ms. A call that can't start in time is rejected at once. | `60000` |
+| `UNPAYWALL_EMAIL` | Contact email for Unpaywall. Setting it enables the Unpaywall tier of `pubmed_fetch_fulltext` for non-PMC DOIs. | none |
+| `UNPAYWALL_TIMEOUT_MS` | Per-request timeout for Unpaywall lookups and content fetches, in ms. | `20000` |
+| `EUROPEPMC_ENABLED` | Set `false` to disable every Europe PMC call: both Europe PMC tools go unregistered, `pubmed_fetch_fulltext` skips that tier, and `pubmed_find_related` skips that fallback. | `true` |
+| `EUROPEPMC_EMAIL` | Optional contact email sent with Europe PMC requests. | none |
+| `EUROPEPMC_REQUEST_DELAY_MS` | Minimum gap between Europe PMC request starts, in ms. | `200` |
+| `EUROPEPMC_MAX_RETRIES` | Retry attempts for failed Europe PMC requests. | `3` |
+| `EUROPEPMC_TIMEOUT_MS` | Per-request timeout for Europe PMC calls, in ms. | `20000` |
+| `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |
+| `MCP_HTTP_PORT` | HTTP server port. | `3010` |
+| `MCP_SESSION_MODE` | HTTP session mode: `stateless`, `stateful`, or `auto`. | `stateless` |
+| `MCP_AUTH_MODE` | Authentication: `none`, `jwt`, or `oauth`. | `none` |
+| `MCP_LOG_LEVEL` | Log level (`debug`, `info`, `warning`, `error`, etc.). | `info` |
+| `LOGS_DIR` | Directory for log files (Node.js only). | `<app-root>/logs` |
+| `STORAGE_PROVIDER_TYPE` | Storage backend: `in-memory`, `filesystem`, `supabase`, `cloudflare-kv/r2/d1`. | `in-memory` |
+| `OTEL_ENABLED` | Enable [OpenTelemetry](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry). | `false` |
+
+See [`.env.example`](./.env.example) for every server setting and the common framework overrides.
 
 ## Running the server
 
@@ -369,6 +344,7 @@ Key environment variables:
 | `src/services/ncbi` | NCBI E-utilities service layer — API client, queue, parser, formatter. |
 | `src/services/europe-pmc` | Europe PMC service — search + `fullTextXML` JATS retrieval. Reuses the NCBI JATS parser. |
 | `src/services/unpaywall` | Unpaywall service — DOI → OA location resolution and content fetch (HTML/PDF). |
+| `src/services/openalex` | OpenAlex service — last-resort provider for `pubmed_find_related`. |
 | `src/config` | Server-specific environment variable parsing and validation with Zod. |
 | `tests/` | Unit and integration tests, mirroring the `src/` structure. |
 
@@ -378,7 +354,8 @@ See [`CLAUDE.md`](./CLAUDE.md) for development guidelines and architectural rule
 
 - Handlers throw, framework catches — no `try/catch` in tool logic
 - Use `ctx.log` for logging, `ctx.state` for storage
-- Register new tools and resources in the `createApp()` arrays
+- Register new tools and resources in the `createApp()` arrays in `src/index.ts`
+- Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields
 
 ## Contributing
 

package/changelog/2.10.x/2.10.17.md

@@ -4,7 +4,7 @@ breaking: false
 security: false
 ---
 
-# 2.10.17 — 2026-09-23
+# 2.10.17 — 2026-09-22
 
 ## Fixed
 

package/changelog/2.10.x/2.10.18.md

@@ -0,0 +1,14 @@
+---
+summary: "Moves Europe PMC's request queue onto the framework pacer with retries outside it, so a backoff no longer holds a concurrency slot and an upstream Retry-After is honored; also widens the unkeyed NCBI request delay to 400ms and limits openalex_unreachable to exhausted ServiceUnavailable errors."
+breaking: false
+security: false
+---
+
+# 2.10.18 — 2026-09-22
+
+## Fixed
+
+- **Europe PMC's request queue moves onto the framework pacer, with retries outside it.** A backoff no longer holds one of the four concurrency slots, and every attempt waits out the start gap from the last request any caller started. An upstream `Retry-After` now sets the retry wait; one over the 30 s backoff cap fails without another attempt, `retryAfter` included. [#163](https://github.com/cyanheads/pubmed-mcp-server/issues/163)
+- **The unkeyed `NCBI_REQUEST_DELAY_MS` default rises from 334ms to 400ms.** 334ms sat exactly at NCBI's 3 req/s ceiling, so small bursts drew 429s that closed the request queue's cooldown gate. The keyed 100ms default and an explicit override still apply. [#162](https://github.com/cyanheads/pubmed-mcp-server/issues/162)
+- **OpenAlex stamps `openalex_unreachable` only on an exhausted `ServiceUnavailable`.** An exhausted `Timeout` or `RateLimited` keeps its own code with no reason, and every exhausted error keeps its upstream `retryAfter`. [#160](https://github.com/cyanheads/pubmed-mcp-server/issues/160)
+- **`pubmed_find_related` names a provider failure that carries no reason by its code** — `rate_limited` or `timed_out`, not `unclassified_error` — in the coverage summary and the all-providers-failed `data.attempted`. The coverage summary takes such a failure's retryability from its own `retryable` flag. [#160](https://github.com/cyanheads/pubmed-mcp-server/issues/160)

package/changelog/2.10.x/2.10.19.md

@@ -0,0 +1,42 @@
+---
+summary: "pubmed_fetch_articles returns the retraction, erratum, and comment notices NCBI links to a record, and the search tools reject blank queries, filters, and cursors and impossible or reversed date ranges instead of returning unfiltered or falsely empty results."
+breaking: false
+security: false
+---
+
+# 2.10.19 — 2026-09-27
+
+## Added
+
+- **`commentsCorrections[]` on `pubmed_fetch_articles`** ([#178](https://github.com/cyanheads/pubmed-mcp-server/issues/178)) — the notices NCBI links from `CommentsCorrectionsList` (`refType`, `refSource`, optional `pmid` and `note`), `Cites` entries excluded, in NCBI's order. `content[]` lists them under `#### Comments and Corrections (N)` ahead of the abstract; the field is absent when a record links nothing else.
+- **`ncbi_rate_limited`** (`RateLimited`, retryable) in the NCBI error contract, which `pubmed://database/info` now declares too — an NCBI 429 the call stops on carries it with NCBI's `retryAfter`, and its hint names `NCBI_API_KEY` as an operator setting.
+
+## Changed
+
+- **`pubmed_lookup_citation` advertises `citations` as `type: "array"` (1–25) again** ([#173](https://github.com/cyanheads/pubmed-mcp-server/issues/173)) — a lone citation object, or one sent as `citation`, is wrapped into a one-element array before validation, so a field error names its element (`citations.0.journal`).
+- **An NCBI JSON `error` field arrives as `data.ncbiErrors: [message]`**, as an XML `<ERROR>` does, in place of `data.ncbiError`.
+- **Cancelling `pubmed_fetch_fulltext` or `pubmed_find_related` ends the call** instead of falling through to the next full-text tier or related-articles provider.
+- **Error envelopes carry `data.requestId`, and a tool error's `content[]` ends with `request <id>`** (mcp-ts-core 0.13.10). Error `data` no longer carries server stack traces or request-context fields such as `operation` (mcp-ts-core 0.13.7, 0.13.8).
+- **An integer sent for a string field, or a JSON-stringified object, is repaired before validation**, and a rejection names the alias rewrite it applied (`Validated limit as maxResults.`) (mcp-ts-core 0.13.9).
+- **Streamable HTTP refusals** (MCP SDK 2.1.0, via mcp-ts-core 0.13.9) — a 2026-07-28 POST without `MCP-Protocol-Version` is refused `400` / `-32020`, and a JSON-RPC batch of more than 100 messages `400` / `-32600`.
+- **Docker image** — production dependencies install in a `$BUILDPLATFORM` deps stage through `scripts/install-otel.ts`; the image gains a `HEALTHCHECK` on `/healthz` and an `org.opencontainers.image.version` label from `APP_VERSION`, and drops `MCP_FORCE_CONSOLE_LOGGING`.
+- **Docs:** the README's tool table and capability reference are condensed to what each tool does and its limits; `.env.example` documents the Europe PMC settings and `NCBI_TOOL_IDENTIFIER`; `framework-skills/` synced to mcp-ts-core 0.13.10.
+
+## Fixed
+
+- **An NCBI call that stops short of its deadline reports its last attempt** ([#174](https://github.com/cyanheads/pubmed-mcp-server/issues/174)) — `ncbi_unreachable` with NCBI's message, `ncbiErrors`, and `attempts` when the next backoff would not fit. A real expiry stays `ncbi_deadline_exceeded` and now keeps `ncbiErrors`; its hint leads with a retry and names batch size only for a large batch.
+- **A one-source `pubmed_europepmc_search` filter keeps `EXT_ID` matches** ([#175](https://github.com/cyanheads/pubmed-mcp-server/issues/175)) — a single source is sent as `SRC:"X" OR SRC:"X"`, so a quoted or unquoted `EXT_ID` lookup matches.
+- **An unreadable `cursorMark` is reported as bad input, not an outage** ([#180](https://github.com/cyanheads/pubmed-mcp-server/issues/180)) — a second HTTP 503 on a caller's cursor, while the first page of the same query is served, fails as non-retryable `europepmc_invalid_input` naming `cursorMark`.
+- **Newly rejected inputs** — each used to reach the upstream and return unfiltered results, a false empty result, or an outage ([#176](https://github.com/cyanheads/pubmed-mcp-server/issues/176), [#177](https://github.com/cyanheads/pubmed-mcp-server/issues/177)):
+  - `pubmed_search_articles` `blank_filter`: an `author`, `journal`, or `language` value, or a `publicationTypes` / `meshTerms` element, of only whitespace, invisible characters, markup, `()`, `[]`, or `""`. `data.fields` names each (`meshTerms.1`); an exactly-empty string still sets no filter.
+  - `pubmed_search_articles` `invalid_date_range`: a `dateRange` bound that is no real calendar date (`2023/02/29`, month `13`, day `00`), or a `minDate` after `maxDate` once PubMed expands each partial date.
+  - `pubmed_search_articles`, `pubmed_spell_check`, `pubmed_lookup_mesh` `blank_query`: a `query` of only invisible characters, such as a zero-width space.
+  - `pubmed_europepmc_search` `blank_query`: a `query` with no term (`"   "`, `()`, `<b></b>`, `&nbsp;`). `blank_cursor`: a `cursorMark` of only whitespace or invisible characters.
+- **Minor:** an exhausted retry after one attempt reads `(failed after 1 attempt)`; `europepmc_invalid_input` errors carry `retryable: false`; the `openalex_invalid_response` contract declares `ServiceUnavailable`, the code it is thrown with.
+
+## Dependencies
+
+- `@cyanheads/mcp-ts-core` ^0.13.6 → ^0.13.10
+- `@socketsecurity/bun-security-scanner` ^1.1.2 → ^1.1.3 (dev)
+- `ignore` ^7.0.9 → ^7.0.10 (dev)
+- `packageManager` bun@1.4.0 → bun@1.4.2, with the Docker base images

package/dist/config/server-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server-config.d.ts","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAG3C,QAAA,MAAM,kBAAkB;;;;;;;;;;;;;;;;iBA8DtB,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAI9D,wBAAgB,eAAe,IAAI,YAAY,CA+B9C"}
+{"version":3,"file":"server-config.d.ts","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAG3C,QAAA,MAAM,kBAAkB;;;;;;;;;;;;;;;;iBA8DtB,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAI9D,wBAAgB,eAAe,IAAI,YAAY,CAmC9C"}

package/dist/config/server-config.js

@@ -10,7 +10,7 @@ const ServerConfigSchema = z.object({
     apiKey: z.string().optional().describe('NCBI API key'),
     toolIdentifier: z.string().default('pubmed-mcp-server').describe('NCBI tool identifier'),
     adminEmail: z.email().optional().describe('Admin contact email'),
-    requestDelayMs: z.coerce.number().min(50).max(5000).default(334).describe('Request delay in ms'),
+    requestDelayMs: z.coerce.number().min(50).max(5000).default(400).describe('Request delay in ms'),
     maxConcurrent: z.coerce
         .number()
         .min(1)
@@ -89,9 +89,13 @@ export function getServerConfig() {
         });
         /**
          * An API key raises NCBI's rate ceiling from ~3 req/s to ~10 req/s. If the
-         * operator hasn't explicitly overridden the delay, tighten from the 334ms
-         * safe default to 100ms when a key is present. A set-but-blank delay counts
+         * operator hasn't explicitly overridden the delay, tighten from the 400ms
+         * keyless default to 100ms when a key is present. A set-but-blank delay counts
          * as not overridden, matching how `parseEnvConfig` reads it.
+         *
+         * The keyless default sits above the 334ms that 3 req/s works out to, leaving
+         * margin for arrival jitter: spaced at exactly the ceiling, a small burst of
+         * concurrent calls draws 429s.
          */
         _config =
             parsed.apiKey && !process.env.NCBI_REQUEST_DELAY_MS?.trim()

package/dist/config/server-config.js.map

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

package/dist/mcp-server/resources/definitions/database-info.resource.d.ts

@@ -14,5 +14,47 @@ export declare const databaseInfoResource: import("@cyanheads/mcp-ts-core").Reso
         fullName: z.ZodOptional<z.ZodString>;
         description: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
-}, z.core.$strip>, undefined>;
+}, z.core.$strip>, readonly [{
+    readonly reason: 'queue_full';
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.RateLimited;
+    readonly when: 'The local NCBI request queue shed the call — the queue is full, or the call cannot start before its total deadline (for example behind the cooldown that follows an NCBI 429).';
+    readonly recovery: 'Wait the number of seconds in `retryAfter`, then retry; the NCBI request queue is saturated or cooling down after a rate limit.';
+    readonly retryable: true;
+    readonly thrownBy: 'service';
+}, {
+    readonly reason: 'ncbi_unreachable';
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
+    readonly when: 'NCBI E-utilities failed on every attempt the retry budget allowed — retries ran out, or the next backoff would overrun the total deadline.';
+    readonly recovery: 'Retry after a brief delay; NCBI failed on every attempt this call made.';
+    readonly retryable: true;
+    readonly thrownBy: 'service';
+}, {
+    readonly reason: 'ncbi_rate_limited';
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.RateLimited;
+    readonly when: 'NCBI answered HTTP 429 (too many requests) and the call stopped on it — retries ran out, the next backoff would overrun the total deadline, or the Retry-After NCBI named outlasts the time left or the 30-second backoff cap.';
+    readonly recovery: "Wait as long as `retryAfter` says when present (a number of seconds or an HTTP date), otherwise a few seconds, then retry; NCBI is throttling this server's requests. If the server runs without NCBI_API_KEY, setting it raises the E-utilities ceiling from about 3 to about 10 requests per second and shortens the default gap between requests — an operator setting in the server's environment, not a tool input.";
+    readonly retryable: true;
+    readonly thrownBy: 'service';
+}, {
+    readonly reason: 'ncbi_deadline_exceeded';
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.Timeout;
+    readonly when: 'The total NCBI request deadline expired before NCBI answered successfully — mid-request, while queued, or during a retry backoff.';
+    readonly recovery: 'Retry after a brief delay; NCBI may be under temporary load. For a large batch, split it into smaller calls.';
+    readonly retryable: true;
+    readonly thrownBy: 'service';
+}, {
+    readonly reason: 'ncbi_invalid_response';
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.SerializationError;
+    readonly when: 'NCBI returned a body that could not be parsed (invalid XML/JSON).';
+    readonly recovery: 'Retry the request; NCBI returned a malformed response that could not be parsed.';
+    readonly retryable: true;
+    readonly thrownBy: 'service';
+}, {
+    readonly reason: 'ncbi_resource_not_found';
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
+    readonly when: 'NCBI returned a structured "not found" error for the requested ID(s).';
+    readonly recovery: 'Verify the ID exists in PubMed; the resource was not found in NCBI and retrying will not help.';
+    readonly retryable: false;
+    readonly thrownBy: 'service';
+}]>;
 //# sourceMappingURL=database-info.resource.d.ts.map

package/dist/mcp-server/resources/definitions/database-info.resource.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"database-info.resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/database-info.resource.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAY,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAoBrD,eAAO,MAAM,oBAAoB;;;;;;;;;;6BA+C/B,CAAC"}
+{"version":3,"file":"database-info.resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/database-info.resource.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAY,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAqBrD,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgD/B,CAAC"}

package/dist/mcp-server/resources/definitions/database-info.resource.js

@@ -4,6 +4,7 @@
  * @module src/mcp-server/resources/definitions/database-info.resource
  */
 import { resource, z } from '@cyanheads/mcp-ts-core';
+import { NCBI_SERVICE_ERRORS } from '../../../services/error-contracts.js';
 import { getNcbiService } from '../../../services/ncbi/ncbi-service.js';
 import { ensureArray, getOptionalText, getText } from '../../../services/ncbi/parsing/xml-helpers.js';
 const FieldSchema = z
@@ -27,6 +28,7 @@ export const databaseInfoResource = resource('pubmed://database/info', {
     mimeType: 'application/json',
     params: z.object({}),
     output: OutputSchema,
+    errors: [...NCBI_SERVICE_ERRORS],
     async handler(_params, ctx) {
         ctx.log.info('Fetching PubMed database info');
         const raw = (await getNcbiService().eInfo({ db: 'pubmed' }, { signal: ctx.signal }));

package/dist/mcp-server/resources/definitions/database-info.resource.js.map

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

package/dist/mcp-server/tools/definitions/_visible-text.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @fileoverview The one test every blank-input rejection shares: does a value
+ * hold any character a reader could see? `String.prototype.trim` is not enough —
+ * it keeps U+0085 (NEL), control characters such as U+0001 and U+007F (`\p{Cc}`),
+ * every format character (`\p{Cf}`: zero-width space, word joiner, soft
+ * hyphen, …), and the other default-ignorable code points (Hangul fillers such
+ * as U+3164, variation selectors, the combining grapheme joiner), so a value
+ * made only of those reads as nonblank and reaches the upstream as an invisible
+ * term. (#176)
+ * @module src/mcp-server/tools/definitions/_visible-text
+ */
+/**
+ * True when `value` has at least one character outside `\p{White_Space}`,
+ * `\p{Cc}`, `\p{Cf}`, and `\p{Default_Ignorable_Code_Point}`. Pure: it strips no
+ * markup and decodes no entities, so a caller that sanitizes input runs this on
+ * the sanitized copy.
+ */
+export declare function hasVisibleText(value: string): boolean;
+//# sourceMappingURL=_visible-text.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"_visible-text.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/_visible-text.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAErD"}