@cyanheads/pubmed-mcp-server 2.8.0 → 2.9.0

package/AGENTS.md

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

package/CLAUDE.md

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

package/README.md

@@ -9,7 +9,7 @@
 
 
 
-[![Version](https://img.shields.io/badge/Version-2.8.0-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-^1.29.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-^6.0.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.2-blueviolet.svg?style=flat-square)](https://bun.sh/)
+[![Version](https://img.shields.io/badge/Version-2.9.0-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-^1.29.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-^6.0.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.2-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
 </div>
 

package/dist/index.js

@@ -19,6 +19,7 @@ import { searchArticlesTool } from './mcp-server/tools/definitions/search-articl
 import { spellCheckTool } from './mcp-server/tools/definitions/spell-check.tool.js';
 import { initEuropePmcService } from './services/europe-pmc/europe-pmc-service.js';
 import { initNcbiService } from './services/ncbi/ncbi-service.js';
+import { initOpenAlexService } from './services/openalex/openalex-service.js';
 import { initUnpaywallService } from './services/unpaywall/unpaywall-service.js';
 const config = getServerConfig();
 const tools = [
@@ -66,6 +67,7 @@ await createApp({
         initNcbiService();
         initUnpaywallService();
         initEuropePmcService();
+        initOpenAlexService();
     },
 });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,0DAA0D,CAAC;AAC9F,OAAO,EAAE,oBAAoB,EAAE,MAAM,8DAA8D,CAAC;AACpG,OAAO,EAAE,cAAc,EAAE,MAAM,oDAAoD,CAAC;AACpF,OAAO,EAAE,iBAAiB,EAAE,MAAM,uDAAuD,CAAC;AAC1F,OAAO,EAAE,iBAAiB,EAAE,MAAM,uDAAuD,CAAC;AAC1F,OAAO,EAAE,eAAe,EAAE,MAAM,qDAAqD,CAAC;AACtF,OAAO,EAAE,mBAAmB,EAAE,MAAM,yDAAyD,CAAC;AAC9F,OAAO,EAAE,kBAAkB,EAAE,MAAM,wDAAwD,CAAC;AAC5F,OAAO,EAAE,cAAc,EAAE,MAAM,oDAAoD,CAAC;AACpF,OAAO,EAAE,yBAAyB,EAAE,MAAM,gEAAgE,CAAC;AAC3G,OAAO,EAAE,kBAAkB,EAAE,MAAM,wDAAwD,CAAC;AAC5F,OAAO,EAAE,cAAc,EAAE,MAAM,oDAAoD,CAAC;AACpF,OAAO,EAAE,oBAAoB,EAAE,MAAM,6CAA6C,CAAC;AACnF,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAEjF,MAAM,MAAM,GAAG,eAAe,EAAE,CAAC;AACjC,MAAM,KAAK,GAAG;IACZ,kBAAkB;IAClB,iBAAiB;IACjB,iBAAiB;IACjB,mBAAmB;IACnB,eAAe;IACf,cAAc;IACd,cAAc;IACd,kBAAkB;IAClB,cAAc;IACd,GAAG,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,yBAAyB,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;CAChE,CAAC;AAEF,MAAM,SAAS,CAAC;IACd,KAAK;IACL,SAAS,EAAE,CAAC,oBAAoB,CAAC;IACjC,OAAO,EAAE,CAAC,kBAAkB,CAAC;IAC7B,YAAY,EACV,iqBAAiqB;IACnqB,OAAO,EAAE;QACP,WAAW,EAAE,KAAK;QAClB,OAAO,EACL,uGAAuG;QACzG,QAAQ,EAAE,gDAAgD;QAC1D,KAAK,EAAE;YACL,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,kCAAkC,EAAE,QAAQ,EAAE,IAAI,EAAE;YAC7E;gBACE,KAAK,EAAE,kBAAkB;gBACzB,IAAI,EAAE,8CAA8C;gBACpD,QAAQ,EAAE,IAAI;aACf;YACD;gBACE,KAAK,EAAE,qBAAqB;gBAC5B,IAAI,EAAE,gDAAgD;gBACtD,QAAQ,EAAE,IAAI;aACf;YACD,EAAE,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,4BAA4B,EAAE,QAAQ,EAAE,IAAI,EAAE;SAC9E;QACD,UAAU,EAAE;YACV,YAAY,EAAE,mBAAmB;YACjC,gBAAgB,EAAE,iBAAiB;YACnC,eAAe,EAAE,iBAAiB;SACnC;KACF;IACD,KAAK;QACH,eAAe,EAAE,CAAC;QAClB,oBAAoB,EAAE,CAAC;QACvB,oBAAoB,EAAE,CAAC;IACzB,CAAC;CACF,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,0DAA0D,CAAC;AAC9F,OAAO,EAAE,oBAAoB,EAAE,MAAM,8DAA8D,CAAC;AACpG,OAAO,EAAE,cAAc,EAAE,MAAM,oDAAoD,CAAC;AACpF,OAAO,EAAE,iBAAiB,EAAE,MAAM,uDAAuD,CAAC;AAC1F,OAAO,EAAE,iBAAiB,EAAE,MAAM,uDAAuD,CAAC;AAC1F,OAAO,EAAE,eAAe,EAAE,MAAM,qDAAqD,CAAC;AACtF,OAAO,EAAE,mBAAmB,EAAE,MAAM,yDAAyD,CAAC;AAC9F,OAAO,EAAE,kBAAkB,EAAE,MAAM,wDAAwD,CAAC;AAC5F,OAAO,EAAE,cAAc,EAAE,MAAM,oDAAoD,CAAC;AACpF,OAAO,EAAE,yBAAyB,EAAE,MAAM,gEAAgE,CAAC;AAC3G,OAAO,EAAE,kBAAkB,EAAE,MAAM,wDAAwD,CAAC;AAC5F,OAAO,EAAE,cAAc,EAAE,MAAM,oDAAoD,CAAC;AACpF,OAAO,EAAE,oBAAoB,EAAE,MAAM,6CAA6C,CAAC;AACnF,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,OAAO,EAAE,mBAAmB,EAAE,MAAM,yCAAyC,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAEjF,MAAM,MAAM,GAAG,eAAe,EAAE,CAAC;AACjC,MAAM,KAAK,GAAG;IACZ,kBAAkB;IAClB,iBAAiB;IACjB,iBAAiB;IACjB,mBAAmB;IACnB,eAAe;IACf,cAAc;IACd,cAAc;IACd,kBAAkB;IAClB,cAAc;IACd,GAAG,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,yBAAyB,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;CAChE,CAAC;AAEF,MAAM,SAAS,CAAC;IACd,KAAK;IACL,SAAS,EAAE,CAAC,oBAAoB,CAAC;IACjC,OAAO,EAAE,CAAC,kBAAkB,CAAC;IAC7B,YAAY,EACV,iqBAAiqB;IACnqB,OAAO,EAAE;QACP,WAAW,EAAE,KAAK;QAClB,OAAO,EACL,uGAAuG;QACzG,QAAQ,EAAE,gDAAgD;QAC1D,KAAK,EAAE;YACL,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,kCAAkC,EAAE,QAAQ,EAAE,IAAI,EAAE;YAC7E;gBACE,KAAK,EAAE,kBAAkB;gBACzB,IAAI,EAAE,8CAA8C;gBACpD,QAAQ,EAAE,IAAI;aACf;YACD;gBACE,KAAK,EAAE,qBAAqB;gBAC5B,IAAI,EAAE,gDAAgD;gBACtD,QAAQ,EAAE,IAAI;aACf;YACD,EAAE,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,4BAA4B,EAAE,QAAQ,EAAE,IAAI,EAAE;SAC9E;QACD,UAAU,EAAE;YACV,YAAY,EAAE,mBAAmB;YACjC,gBAAgB,EAAE,iBAAiB;YACnC,eAAe,EAAE,iBAAiB;SACnC;KACF;IACD,KAAK;QACH,eAAe,EAAE,CAAC;QAClB,oBAAoB,EAAE,CAAC;QACvB,oBAAoB,EAAE,CAAC;QACvB,mBAAmB,EAAE,CAAC;IACxB,CAAC;CACF,CAAC,CAAC"}

package/dist/mcp-server/tools/definitions/find-related.tool.d.ts

@@ -1,6 +1,8 @@
 /**
  * @fileoverview PubMed related articles tool — finds articles related to a
- * source article via NCBI ELink and enriches results with ESummary data.
+ * source article via a provider chain: NCBI ELink (primary) → Europe PMC →
+ * OpenAlex. First success wins; results are never merged across sources.
+ * Supports offset pagination on the returned window.
  * @module src/mcp-server/tools/definitions/find-related.tool
  */
 import { z } from '@cyanheads/mcp-ts-core';
@@ -12,6 +14,7 @@ export declare const findRelatedTool: import("@cyanheads/mcp-ts-core").ToolDefin
         cited_by: "cited_by";
     }>>;
     maxResults: z.ZodDefault<z.ZodNumber>;
+    offset: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>, z.ZodObject<{
     sourcePmid: z.ZodString;
     relationship: z.ZodEnum<{
@@ -19,6 +22,7 @@ export declare const findRelatedTool: import("@cyanheads/mcp-ts-core").ToolDefin
         similar: "similar";
         cited_by: "cited_by";
     }>;
+    offset: z.ZodNumber;
     articles: z.ZodArray<z.ZodObject<{
         pmid: z.ZodString;
         title: z.ZodOptional<z.ZodString>;
@@ -56,8 +60,43 @@ export declare const findRelatedTool: import("@cyanheads/mcp-ts-core").ToolDefin
     readonly when: "NCBI returned a structured \"not found\" error for the requested ID(s).";
     readonly recovery: "Verify the ID exists in PubMed; the resource was not found in NCBI and retrying will not help.";
     readonly retryable: false;
+}, {
+    readonly reason: "europepmc_unreachable";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
+    readonly when: "Europe PMC was unreachable after all retry attempts.";
+    readonly recovery: "Retry after a brief delay; Europe PMC was unreachable. NCBI PMC and Unpaywall remain available.";
+    readonly retryable: true;
+}, {
+    readonly reason: "europepmc_invalid_response";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.SerializationError;
+    readonly when: "Europe PMC returned a body that could not be parsed (invalid JSON or XML).";
+    readonly recovery: "Retry the request; Europe PMC returned a malformed response that could not be parsed.";
+    readonly retryable: true;
+}, {
+    readonly reason: "europepmc_invalid_input";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
+    readonly when: "Europe PMC rejected the request input (empty query, unknown sort field, malformed parameter).";
+    readonly recovery: "Adjust the input — usually the query or sort field — before retrying; the same input will be rejected again.";
+    readonly retryable: false;
+}, {
+    readonly reason: "openalex_unreachable";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
+    readonly when: "OpenAlex was unreachable after all retry attempts.";
+    readonly recovery: "Retry after a brief delay; OpenAlex was unreachable. NCBI and Europe PMC remain available.";
+    readonly retryable: true;
+}, {
+    readonly reason: "openalex_invalid_response";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.SerializationError;
+    readonly when: "OpenAlex returned a body that could not be parsed (invalid JSON).";
+    readonly recovery: "Retry the request; OpenAlex returned a malformed response that could not be parsed.";
+    readonly retryable: true;
 }], {
     readonly totalFound: z.ZodNumber;
+    readonly source: z.ZodEnum<{
+        europepmc: "europepmc";
+        openalex: "openalex";
+        ncbi: "ncbi";
+    }>;
     readonly notice: z.ZodOptional<z.ZodString>;
 }>;
 //# sourceMappingURL=find-related.tool.d.ts.map

package/dist/mcp-server/tools/definitions/find-related.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"find-related.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/find-related.tool.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAqCjD,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAsM1B,CAAC"}
+{"version":3,"file":"find-related.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/find-related.tool.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AA6KjD,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA8W1B,CAAC"}

package/dist/mcp-server/tools/definitions/find-related.tool.js

@@ -1,14 +1,18 @@
 /**
  * @fileoverview PubMed related articles tool — finds articles related to a
- * source article via NCBI ELink and enriches results with ESummary data.
+ * source article via a provider chain: NCBI ELink (primary) → Europe PMC →
+ * OpenAlex. First success wins; results are never merged across sources.
+ * Supports offset pagination on the returned window.
  * @module src/mcp-server/tools/definitions/find-related.tool
  */
 import { tool, z } from '@cyanheads/mcp-ts-core';
 import { McpError } from '@cyanheads/mcp-ts-core/errors';
-import { NCBI_SERVICE_ERRORS } from '../../../services/error-contracts.js';
+import { EUROPEPMC_SERVICE_ERRORS, NCBI_SERVICE_ERRORS, OPENALEX_SERVICE_ERRORS, } from '../../../services/error-contracts.js';
+import { getEuropePmcService } from '../../../services/europe-pmc/europe-pmc-service.js';
 import { getNcbiService } from '../../../services/ncbi/ncbi-service.js';
 import { extractBriefSummaries } from '../../../services/ncbi/parsing/esummary-parser.js';
 import { ensureArray } from '../../../services/ncbi/parsing/xml-helpers.js';
+import { getOpenAlexServiceOptional } from '../../../services/openalex/openalex-service.js';
 import { conceptMeta, EDAM_DATA_RETRIEVAL, SCHEMA_SCHOLARLY_ARTICLE } from './_concepts.js';
 import { pmidStringSchema } from './_schemas.js';
 function extractValue(field) {
@@ -18,13 +22,99 @@ function extractValue(field) {
         return field['#text'] !== undefined ? String(field['#text']) : '';
     return String(field);
 }
+// ─── NCBI provider ────────────────────────────────────────────────────────────
+async function ncbiProvider(pmid, relationship, signal) {
+    const ncbi = getNcbiService();
+    const linkName = relationship === 'cited_by'
+        ? 'pubmed_pubmed_citedin'
+        : relationship === 'references'
+            ? 'pubmed_pubmed_refs'
+            : 'pubmed_pubmed';
+    const eLinkResult = (await ncbi.eLink({
+        dbfrom: 'pubmed',
+        db: 'pubmed',
+        id: pmid,
+        cmd: 'neighbor',
+        linkname: linkName,
+        retmode: 'xml',
+    }, { signal }));
+    const eLinkResultsArray = ensureArray(eLinkResult?.eLinkResult);
+    const firstResult = eLinkResultsArray[0];
+    const linkSet = firstResult?.LinkSet;
+    let foundPmids = [];
+    if (linkSet?.LinkSetDb) {
+        const linkSetDbArray = ensureArray(linkSet.LinkSetDb);
+        const targetDb = linkSetDbArray.find((db) => db.LinkName === linkName) ?? linkSetDbArray[0];
+        if (targetDb?.Link) {
+            foundPmids = ensureArray(targetDb.Link)
+                .map((link) => extractValue(link.Id))
+                .filter((p) => p && p !== pmid && p !== '0');
+        }
+    }
+    return { allPmids: foundPmids, totalCount: foundPmids.length, source: 'ncbi' };
+}
+// ─── Europe PMC provider ──────────────────────────────────────────────────────
+/**
+ * Europe PMC supports citations and references for MED-source records.
+ * It has no `similar` equivalent, so we skip it for that relationship.
+ */
+function epmcSupports(relationship) {
+    return relationship === 'cited_by' || relationship === 'references';
+}
+/**
+ * Fetch enough pages to cover [offset, offset+maxResults) from EPMC.
+ * EPMC uses 1-based page numbers and its endpoint supports pageSize up to 1000.
+ * We fetch one page containing the window we need.
+ */
+async function epmcProvider(pmid, relationship, offset, maxResults, signal) {
+    const epmc = getEuropePmcService();
+    if (!epmc)
+        throw new Error('Europe PMC service not available');
+    // EPMC is 1-based; we need the page covering [offset, offset+maxResults).
+    // Simplest approach: fetch one page starting at the right position.
+    // pageSize = maxResults, page = floor(offset/maxResults) + 1 won't align
+    // cleanly. Instead, use a large pageSize and slice client-side, capped at 100.
+    const pageSize = Math.min(offset + maxResults, 100);
+    const page = 1;
+    const result = relationship === 'cited_by'
+        ? await epmc.citations(pmid, pageSize, page, signal)
+        : await epmc.references(pmid, pageSize, page, signal);
+    return { allPmids: result.pmids, totalCount: result.totalCount, source: 'europepmc' };
+}
+// ─── OpenAlex provider ────────────────────────────────────────────────────────
+async function openAlexProvider(pmid, relationship, maxNeeded, signal) {
+    const oa = getOpenAlexServiceOptional();
+    if (!oa)
+        throw new Error('OpenAlex service not available');
+    let result;
+    switch (relationship) {
+        case 'similar':
+            result = await oa.similar(pmid, maxNeeded, signal);
+            break;
+        case 'cited_by':
+            result = await oa.citedBy(pmid, maxNeeded, signal);
+            break;
+        case 'references':
+            result = await oa.references(pmid, maxNeeded, signal);
+            break;
+    }
+    return { allPmids: result.pmids, totalCount: result.totalCount, source: 'openalex' };
+}
+/** Compact, log-safe description of an unknown thrown value. */
+function describeError(err) {
+    return err instanceof Error ? err.message : String(err);
+}
 // ─── Tool Definition ─────────────────────────────────────────────────────────
 export const findRelatedTool = tool('pubmed_find_related', {
-    description: 'Find articles related to a source article — similar content (similar), articles citing this one (cited_by), or articles this one cites (references).',
+    description: 'Find articles related to a source article — similar content (similar), articles citing this one (cited_by), or articles this one cites (references). Uses NCBI ELink as the primary source; falls back to Europe PMC then OpenAlex when NCBI is unavailable.',
     annotations: { readOnlyHint: true, openWorldHint: true },
     _meta: conceptMeta([SCHEMA_SCHOLARLY_ARTICLE, EDAM_DATA_RETRIEVAL]),
     sourceUrl: 'https://github.com/cyanheads/pubmed-mcp-server/blob/main/src/mcp-server/tools/definitions/find-related.tool.ts',
-    errors: [...NCBI_SERVICE_ERRORS],
+    errors: [
+        ...NCBI_SERVICE_ERRORS,
+        ...EUROPEPMC_SERVICE_ERRORS,
+        ...OPENALEX_SERVICE_ERRORS,
+    ],
     input: z.object({
         pmid: pmidStringSchema.describe('Source PubMed ID'),
         relationship: z
@@ -32,10 +122,17 @@ export const findRelatedTool = tool('pubmed_find_related', {
             .default('similar')
             .describe('Relationship type: similar (content-based), cited_by (articles citing this one), references (articles this one cites)'),
         maxResults: z.number().int().min(1).max(50).default(10).describe('Maximum related articles'),
+        offset: z
+            .number()
+            .int()
+            .min(0)
+            .default(0)
+            .describe('Result offset for pagination (0-based); page through results by incrementing by maxResults'),
     }),
     output: z.object({
         sourcePmid: z.string().describe('Source PubMed ID'),
         relationship: z.enum(['similar', 'cited_by', 'references']).describe('Relationship type used'),
+        offset: z.number().describe('Result offset used'),
         articles: z
             .array(z
             .object({
@@ -48,129 +145,267 @@ export const findRelatedTool = tool('pubmed_find_related', {
             .describe('Related article with enriched summary'))
             .describe('Related articles'),
     }),
-    // Result-set context the agent reasons with — the pre-truncation match count and
-    // recovery guidance (invalid source PMID, or references for a non-PMC source).
-    // Surfaced via ctx.enrich(...) to structuredContent and content[]; out of the return.
+    // Result-set context the agent reasons with — pre-truncation match count,
+    // the answering provider, and recovery guidance. Surfaced via ctx.enrich(...)
+    // to structuredContent and content[]; kept out of the domain return.
     enrichment: {
-        totalFound: z.number().describe('Total related articles found before truncation'),
+        totalFound: z.number().describe('Total related articles found before windowing'),
+        source: z
+            .enum(['ncbi', 'europepmc', 'openalex'])
+            .describe('Provider that answered this request'),
         notice: z
             .string()
             .optional()
-            .describe('Optional guidance when results are empty — e.g. invalid source PMID, or references requested for a non-PMC source. Absent on successful result pages.'),
+            .describe('Guidance when results are empty, a fallback provider answered, or offset overshot. Absent on a clean NCBI result page.'),
     },
-    // content[] trailer presentation for the enrichment block. totalFound is scalar —
-    // a label restores the human-readable key; notice renders as a blockquote kind-tag.
     enrichmentTrailer: {
         totalFound: { label: 'Total Found' },
+        source: { label: 'Source' },
     },
     async handler(input, ctx) {
         const ncbi = getNcbiService();
         ctx.log.debug('Finding related articles', {
             pmid: input.pmid,
             relationship: input.relationship,
+            offset: input.offset,
         });
-        // `cmd=neighbor_score` is unstable on NCBI's side — it intermittently fails
-        // with a TXCLIENT::readAll EOF for high-traffic PMIDs. `cmd=neighbor` returns
-        // the `pubmed_pubmed` list in relevance order anyway, so we keep the ranking
-        // without the (arbitrary-scale) numeric score.
-        const linkName = input.relationship === 'cited_by'
-            ? 'pubmed_pubmed_citedin'
-            : input.relationship === 'references'
-                ? 'pubmed_pubmed_refs'
-                : 'pubmed_pubmed';
-        const eLinkResult = (await ncbi.eLink({
-            dbfrom: 'pubmed',
-            db: 'pubmed',
-            id: input.pmid,
-            cmd: 'neighbor',
-            linkname: linkName,
-            retmode: 'xml',
-        }, { signal: ctx.signal }));
-        const eLinkResultsArray = ensureArray(eLinkResult?.eLinkResult);
-        const firstResult = eLinkResultsArray[0];
-        const linkSet = firstResult?.LinkSet;
-        let foundPmids = [];
-        if (linkSet?.LinkSetDb) {
-            const linkSetDbArray = ensureArray(linkSet.LinkSetDb);
-            const targetDb = linkSetDbArray.find((db) => db.LinkName === linkName) ?? linkSetDbArray[0];
-            if (targetDb?.Link) {
-                foundPmids = ensureArray(targetDb.Link)
-                    .map((link) => extractValue(link.Id))
-                    .filter((pmid) => pmid && pmid !== input.pmid && pmid !== '0');
+        // ── Provider chain ──────────────────────────────────────────────────────
+        // Try NCBI first; on failure fall back to Europe PMC then OpenAlex (first
+        // success wins, never merged). A non-PMC `references` source returns an empty
+        // NCBI set rather than throwing — that structural fallback is handled below.
+        let providerResult = null;
+        let providerError;
+        // Records WHY a non-primary provider answered, so the provenance notice can
+        // distinguish an NCBI outage from references coverage for a non-PMC source.
+        let fallbackKind;
+        // 1. NCBI (primary)
+        try {
+            providerResult = await ncbiProvider(input.pmid, input.relationship, ctx.signal);
+        }
+        catch (err) {
+            ctx.log.warning('NCBI eLink failed, trying fallback providers', {
+                pmid: input.pmid,
+                err: describeError(err),
+            });
+            providerError = err;
+        }
+        // 2. Europe PMC (fallback for cited_by / references only). An empty EPMC
+        //    result is not "served" — fall through to OpenAlex rather than return 0.
+        if (providerResult === null && epmcSupports(input.relationship)) {
+            try {
+                const epmcResult = await epmcProvider(input.pmid, input.relationship, input.offset, input.maxResults, ctx.signal);
+                if (epmcResult.allPmids.length > 0) {
+                    providerResult = epmcResult;
+                    fallbackKind = 'outage';
+                }
+                providerError = undefined;
+            }
+            catch (err) {
+                ctx.log.warning('Europe PMC fallback failed, trying OpenAlex', {
+                    pmid: input.pmid,
+                    err: describeError(err),
+                });
+                providerError = err;
             }
         }
-        const totalFound = foundPmids.length;
-        ctx.enrich({ totalFound });
-        if (foundPmids.length === 0) {
-            // ELink returns an empty LinkSet for both invalid source PMIDs and valid
-            // PMIDs that simply have no related articles, so a single ESummary on the
-            // source disambiguates the two cases for every relationship type. NCBI's
-            // pubmed_pubmed_refs ELink also only resolves references for PMC-indexed
-            // sources, so the same lookup yields the PMCID for the references hint.
+        // 3. OpenAlex (last resort for all relationships)
+        if (providerResult === null) {
+            const oa = getOpenAlexServiceOptional();
+            if (oa) {
+                try {
+                    providerResult = await openAlexProvider(input.pmid, input.relationship, input.offset + input.maxResults, ctx.signal);
+                    fallbackKind = 'outage';
+                    providerError = undefined;
+                }
+                catch (err) {
+                    ctx.log.warning('OpenAlex fallback failed', {
+                        pmid: input.pmid,
+                        err: describeError(err),
+                    });
+                    providerError = err;
+                }
+            }
+        }
+        // ── Every provider failed ─────────────────────────────────────────────────
+        if (providerResult === null) {
+            ctx.enrich({ totalFound: 0, source: 'ncbi' });
+            ctx.enrich.notice(`All providers failed to retrieve related articles (NCBI, Europe PMC, OpenAlex). Last error: ${describeError(providerError ?? 'unknown')}. Retry after a brief delay.`);
+            return {
+                sourcePmid: input.pmid,
+                relationship: input.relationship,
+                offset: input.offset,
+                articles: [],
+            };
+        }
+        // ── NCBI returned an empty set ──────────────────────────────────────────────
+        // ELink returns an empty LinkSet for both invalid source PMIDs and valid PMIDs
+        // with no neighbors; a single ESummary disambiguates and yields the PMCID. For
+        // `references`, a valid non-PMC source has no NCBI reference list — Europe PMC
+        // and OpenAlex serve references for any source, so try them before giving up.
+        if (providerResult.source === 'ncbi' && providerResult.allPmids.length === 0) {
             let sourceSummary;
             let sourceConfirmedMissing = false;
             try {
                 const summaryResult = await ncbi.eSummary({ db: 'pubmed', id: input.pmid }, { signal: ctx.signal });
                 const summaries = await extractBriefSummaries(summaryResult);
                 sourceSummary = summaries[0];
-                // ESummary succeeded but returned nothing parseable — PMID is unknown.
                 if (!sourceSummary?.title)
                     sourceConfirmedMissing = true;
             }
             catch (err) {
                 ctx.log.debug('Source PMID ESummary failed', { err });
-                // Key off the contract reason rather than the JSON-RPC code: the service
-                // layer stamps `ncbi_resource_not_found` for "unknown UID" responses,
-                // while transient transport failures keep their ServiceUnavailable code
-                // with no such reason.
                 const reason = err instanceof McpError
                     ? err.data?.reason
                     : undefined;
-                if (reason === 'ncbi_resource_not_found') {
+                if (reason === 'ncbi_resource_not_found')
                     sourceConfirmedMissing = true;
-                }
             }
-            let notice;
             if (sourceConfirmedMissing) {
-                notice = `Source PMID ${input.pmid} not found in PubMed. Verify the ID with \`pubmed_fetch_articles\` or \`pubmed_search_articles\`.`;
+                ctx.enrich({ totalFound: 0, source: 'ncbi' });
+                ctx.enrich.notice(`Source PMID ${input.pmid} not found in PubMed. Verify the ID with \`pubmed_fetch_articles\` or \`pubmed_search_articles\`.`);
+                return {
+                    sourcePmid: input.pmid,
+                    relationship: input.relationship,
+                    offset: input.offset,
+                    articles: [],
+                };
             }
-            else if (sourceSummary?.title && input.relationship === 'references') {
-                const sourcePmcId = sourceSummary.pmcId;
-                notice = sourcePmcId
-                    ? `No reference list found in PMC for PMID ${input.pmid} (PMCID ${sourcePmcId}).`
-                    : `Reference lists require the source article to be indexed in PMC. PMID ${input.pmid} has no PMCID — references unavailable. Use pubmed_fetch_articles to inspect the article record, or try relationship: "similar" / "cited_by".`;
+            // References coverage fallback — only for a confirmed-valid source. NCBI
+            // resolves references only for PMC-indexed sources, so a valid non-PMC
+            // source returns empty; Europe PMC then OpenAlex serve them. An unconfirmed
+            // source (ESummary itself failed) stays silent — the empty set is most
+            // likely a transient NCBI issue, not a real "no references".
+            if (input.relationship === 'references' && sourceSummary?.title) {
+                let refFallback = null;
+                const refAttempts = [
+                    () => epmcProvider(input.pmid, 'references', input.offset, input.maxResults, ctx.signal),
+                    () => openAlexProvider(input.pmid, 'references', input.offset + input.maxResults, ctx.signal),
+                ];
+                for (const attempt of refAttempts) {
+                    try {
+                        const result = await attempt();
+                        if (result.allPmids.length > 0) {
+                            refFallback = result;
+                            break;
+                        }
+                    }
+                    catch (err) {
+                        ctx.log.warning('References fallback provider failed', { err: describeError(err) });
+                    }
+                }
+                if (refFallback) {
+                    providerResult = refFallback;
+                    fallbackKind = 'references_coverage';
+                }
+                else {
+                    ctx.enrich({ totalFound: 0, source: 'ncbi' });
+                    const sourcePmcId = sourceSummary.pmcId;
+                    ctx.enrich.notice(sourcePmcId
+                        ? `No reference list found for PMID ${input.pmid} (PMCID ${sourcePmcId}) via NCBI, Europe PMC, or OpenAlex.`
+                        : `No reference list available for PMID ${input.pmid} via NCBI, Europe PMC, or OpenAlex. Use pubmed_fetch_articles to inspect the article record, or try relationship: "similar" / "cited_by".`);
+                    return {
+                        sourcePmid: input.pmid,
+                        relationship: input.relationship,
+                        offset: input.offset,
+                        articles: [],
+                    };
+                }
+            }
+            else {
+                // similar / cited_by empty for a valid source, or references with an
+                // unconfirmed source — return the honest empty without a notice.
+                ctx.enrich({ totalFound: 0, source: 'ncbi' });
+                return {
+                    sourcePmid: input.pmid,
+                    relationship: input.relationship,
+                    offset: input.offset,
+                    articles: [],
+                };
             }
-            if (notice)
-                ctx.enrich.notice(notice);
+        }
+        // ── Window the result set + enrich ──────────────────────────────────────────
+        const { allPmids, totalCount, source } = providerResult;
+        ctx.enrich({ totalFound: totalCount, source });
+        // For NCBI the full neighbor set is in memory; for EPMC/OpenAlex the provider
+        // pre-fetched enough to cover the window. Slice the requested page either way.
+        const window = allPmids.slice(input.offset, input.offset + input.maxResults);
+        // Only the LAST ctx.enrich.notice survives, so collect the applicable
+        // fragments (overshoot, provenance, enrichment-degraded) and emit them once.
+        const notices = [];
+        if (input.offset > 0 && input.offset >= totalCount) {
+            notices.push(`Offset ${input.offset} exceeds totalFound (${totalCount}). Reset offset to 0 or reduce it below ${totalCount} to page through results.`);
+        }
+        if (source !== 'ncbi') {
+            const providerName = source === 'europepmc' ? 'Europe PMC' : 'OpenAlex';
+            const detail = source === 'openalex'
+                ? input.relationship === 'similar'
+                    ? 'related_works — OpenAlex similarity, not PubMed’s neighbor algorithm'
+                    : input.relationship === 'cited_by'
+                        ? 'cites: filter'
+                        : 'referenced_works'
+                : `${input.relationship === 'cited_by' ? 'citations' : 'references'} index`;
+            notices.push(fallbackKind === 'references_coverage'
+                ? `NCBI has no PMC-indexed reference list for PMID ${input.pmid} — references served by ${providerName} (${detail}).`
+                : `NCBI eLink unavailable — related articles served by ${providerName} (${detail}).`);
+        }
+        if (window.length === 0) {
+            if (notices.length > 0)
+                ctx.enrich.notice(notices.join(' '));
             return {
                 sourcePmid: input.pmid,
                 relationship: input.relationship,
+                offset: input.offset,
                 articles: [],
             };
         }
-        const pmidsToEnrich = foundPmids.slice(0, input.maxResults);
-        const summaryResult = await ncbi.eSummary({
-            db: 'pubmed',
-            id: pmidsToEnrich.join(','),
-        }, { signal: ctx.signal });
-        const briefSummaries = await extractBriefSummaries(summaryResult);
-        const summaryMap = new Map(briefSummaries.map((bs) => [bs.pmid, bs]));
-        const articles = pmidsToEnrich.map((pmid) => {
-            const details = summaryMap.get(pmid);
+        // Enrich the window with ESummary. When a fallback answered because NCBI is
+        // down, eSummary hits the same host and may also fail — degrade to bare PMIDs
+        // (the article metadata fields are all optional) rather than failing the whole
+        // request, so the chain's resilience survives the enrichment step.
+        try {
+            const summaryResult = await ncbi.eSummary({ db: 'pubmed', id: window.join(',') }, { signal: ctx.signal });
+            const briefSummaries = await extractBriefSummaries(summaryResult);
+            const summaryMap = new Map(briefSummaries.map((bs) => [bs.pmid, bs]));
+            const articles = window.map((pmid) => {
+                const details = summaryMap.get(pmid);
+                return {
+                    pmid,
+                    title: details?.title,
+                    authors: details?.authors,
+                    source: details?.source,
+                    pubDate: details?.pubDate,
+                };
+            });
+            if (notices.length > 0)
+                ctx.enrich.notice(notices.join(' '));
             return {
-                pmid,
-                title: details?.title,
-                authors: details?.authors,
-                source: details?.source,
-                pubDate: details?.pubDate,
+                sourcePmid: input.pmid,
+                relationship: input.relationship,
+                offset: input.offset,
+                articles,
             };
-        });
-        return { sourcePmid: input.pmid, relationship: input.relationship, articles };
+        }
+        catch (err) {
+            if (ctx.signal.aborted)
+                throw err;
+            ctx.log.warning('ESummary enrichment failed; returning related PMIDs without metadata', {
+                err: describeError(err),
+            });
+            notices.push('Article metadata is temporarily unavailable (NCBI eSummary did not respond); returning related PMIDs only. Retry for full metadata, or use pubmed_fetch_articles.');
+            ctx.enrich.notice(notices.join(' '));
+            return {
+                sourcePmid: input.pmid,
+                relationship: input.relationship,
+                offset: input.offset,
+                articles: window.map((pmid) => ({ pmid })),
+            };
+        }
     },
     format: (result) => {
         const lines = [
             `# Related Articles for PMID ${result.sourcePmid}`,
             `**Relationship:** ${result.relationship}`,
+            `**Returned:** ${result.articles.length} | **Offset:** ${result.offset}`,
         ];
         if (result.articles.length === 0) {
             lines.push('No related articles found.');