@cyanheads/pubmed-mcp-server 2.10.8 → 2.10.10

package/dist/services/openalex/api-client.js

@@ -7,7 +7,7 @@
 import { JsonRpcErrorCode, McpError, serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
 import { fetchWithTimeout, logger, requestContextService } from '@cyanheads/mcp-ts-core/utils';
 import { recoveryFor } from '../error-contracts.js';
-import { OPENALEX_API_BASE } from './types.js';
+import { OPENALEX_API_BASE, OPENALEX_MAX_PAGE_SIZE, } from './types.js';
 const USER_AGENT = 'pubmed-mcp-server (+https://github.com/cyanheads/pubmed-mcp-server)';
 /**
  * Low-level HTTP client for OpenAlex. Single-attempt — retries upstream.
@@ -72,7 +72,12 @@ export class OpenAlexApiClient {
     /**
      * Batch-resolve a list of OpenAlex work IDs to their PMIDs.
      * Uses the filter=openalex:W1|W2|... endpoint with select=id,ids.
-     * Returns only records that carry a `pmid` field.
+     *
+     * One call resolves one batch: the OR-filter accepts at most
+     * `OPENALEX_MAX_FILTER_VALUES` values and the endpoint serves at most
+     * `OPENALEX_MAX_PAGE_SIZE` rows, so splitting a longer list is the caller's
+     * job (`OpenAlexService`). Results arrive in OpenAlex's order, not the
+     * requested one.
      */
     resolveOaIdsToPmids(oaIds, signal) {
         if (oaIds.length === 0)
@@ -82,7 +87,7 @@ export class OpenAlexApiClient {
         const params = new URLSearchParams({
             filter: `openalex:${bareIds.join('|')}`,
             select: 'id,ids',
-            per_page: String(Math.min(oaIds.length, 200)),
+            per_page: String(Math.min(oaIds.length, OPENALEX_MAX_PAGE_SIZE)),
         });
         if (this.config.email)
             params.set('mailto', this.config.email);
@@ -90,10 +95,14 @@ export class OpenAlexApiClient {
         return this.fetchWorksList(url, 'OpenAlexResolveOaIds', signal);
     }
     /**
-     * Fetch works that cite a given OpenAlex work ID (the cited_by relationship).
-     * Returns up to `perPage` records with PMIDs.
+     * Fetch one page of works that cite a given OpenAlex work ID (the cited_by
+     * relationship). Returns up to `perPage` records plus OpenAlex's own total.
+     *
+     * `page` is 1-based. Basic paging is bounded by `page × per_page ≤ 10,000`;
+     * past that OpenAlex rejects the request and requires cursor paging, so the
+     * caller's page cap must keep the walk inside that ceiling.
      */
-    async getCitedBy(oaId, perPage, signal) {
+    async getCitedBy(oaId, perPage, page, signal) {
         // Strip full URL prefix if needed
         const bareId = oaId.startsWith('https://openalex.org/')
             ? oaId.slice('https://openalex.org/'.length)
@@ -101,14 +110,15 @@ export class OpenAlexApiClient {
         const params = new URLSearchParams({
             filter: `cites:${bareId}`,
             select: 'id,ids',
-            per_page: String(Math.min(perPage, 200)),
+            per_page: String(Math.min(perPage, OPENALEX_MAX_PAGE_SIZE)),
+            page: String(page),
         });
         if (this.config.email)
             params.set('mailto', this.config.email);
         const url = `${OPENALEX_API_BASE}/works?${params.toString()}`;
         const ctx = requestContextService.createRequestContext({
             operation: 'OpenAlexGetCitedBy',
-            additionalContext: { oaId: bareId },
+            additionalContext: { oaId: bareId, page },
         });
         let response;
         try {
@@ -135,6 +145,7 @@ export class OpenAlexApiClient {
             operation: 'OpenAlexGetCitedByDone',
             additionalContext: {
                 oaId: bareId,
+                page,
                 totalCount: parsed.meta?.count,
                 resultCount: parsed.results?.length,
             },

package/dist/services/openalex/api-client.js.map

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

package/dist/services/openalex/openalex-service.d.ts

@@ -5,13 +5,20 @@
  *   - `citedBy(pmid, n)`: cites:W<id> filter → PMIDs (mirrors pubmed_pubmed_citedin)
  *   - `references(pmid, n)`: referenced_works → PMIDs (mirrors pubmed_pubmed_refs)
  *
- * All three methods drop records with no PMID — never mints fake IDs.
+ * Each method returns at least `n` PubMed-addressable rows when OpenAlex has
+ * them: `citedBy` walks pages of the `cites:` filter, and the other two resolve
+ * the work's ID list in batches, both stopping once the window is covered,
+ * upstream runs out, or a cap is reached. Records with no PMID are dropped —
+ * never minted — and counted, so callers can disclose the shortfall instead of
+ * serving an unexplained empty window.
+ *
  * Uses the NCBI_ADMIN_EMAIL config (adminEmail) as the OpenAlex polite-pool
  * `mailto=` parameter when set; omits it when unset.
  *
  * @module src/services/openalex/openalex-service
  */
 import { OpenAlexApiClient } from './api-client.js';
+import { type OpenAlexRelatedResult } from './types.js';
 /** Service facade over the OpenAlex API for the find-related provider chain. */
 export declare class OpenAlexService {
     private readonly client;
@@ -20,33 +27,43 @@ export declare class OpenAlexService {
     /**
      * Find works with similar content to the given PMID via OpenAlex `related_works`.
      * Returns PMIDs only; drops any record with no PMID.
-     * `n` is the number of PMIDs to return (OpenAlex caps related_works at ~10).
+     * `n` is the size of the window the caller needs covered.
      */
-    similar(pmid: string, n: number, signal?: AbortSignal): Promise<{
-        pmids: string[];
-        totalCount: number;
-    }>;
+    similar(pmid: string, n: number, signal?: AbortSignal): Promise<OpenAlexRelatedResult>;
     /**
      * Find works that cite the given PMID via OpenAlex `cites:W<id>` filter.
      * Returns PMIDs only; drops any record with no PMID.
+     *
+     * Pages are all one size and are pulled until the filtered array covers `n`,
+     * upstream runs out, or `OPENALEX_MAX_UPSTREAM_REQUESTS` is hit — the rows OpenAlex
+     * serves count every citing work, but only those with a PubMed PMID are
+     * addressable, so a single page sized on the raw window can under-fill it.
      */
-    citedBy(pmid: string, n: number, signal?: AbortSignal): Promise<{
-        pmids: string[];
-        totalCount: number;
-    }>;
+    citedBy(pmid: string, n: number, signal?: AbortSignal): Promise<OpenAlexRelatedResult>;
     /**
      * Find works referenced by the given PMID via OpenAlex `referenced_works`.
      * Returns PMIDs only; drops any record with no PMID.
      */
-    references(pmid: string, n: number, signal?: AbortSignal): Promise<{
-        pmids: string[];
-        totalCount: number;
-    }>;
+    references(pmid: string, n: number, signal?: AbortSignal): Promise<OpenAlexRelatedResult>;
+    /** Look up the source work by PMID; `null` when OpenAlex doesn't index it. */
+    private fetchWork;
+    /**
+     * Resolve an OpenAlex ID list (a work's references or related works) to PMIDs,
+     * in batches, until the window is covered, the list is exhausted, or the
+     * request cap is reached. The work record carries the whole list, so this
+     * paginates resolution rather than an upstream query.
+     *
+     * Each batch's rows are re-ordered to the requested IDs, so the result follows
+     * the source list — a window at any offset stays stable across calls, whatever
+     * order OpenAlex answers a batch in.
+     */
+    private resolveIdsToPmids;
     /**
-     * Extract unique numeric PMIDs from a list of works, excluding the source PMID.
-     * Any work with no PMID is silently dropped (never minted).
+     * Shape a walk's outcome. Exhausting the fetchable set makes the addressable
+     * count exact; short of that only OpenAlex's own total is known, and a window
+     * the walk never reached is flagged rather than served as a silent empty.
      */
-    private extractPmids;
+    private finish;
     /** Retry wrapper for transient errors, mirroring the EPMC service pattern. */
     private withRetry;
 }

package/dist/services/openalex/openalex-service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openalex-service.d.ts","sourceRoot":"","sources":["../../../src/services/openalex/openalex-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAQH,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAyCpD,gFAAgF;AAChF,qBAAa,eAAe;IAExB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAF7B,YACmB,MAAM,EAAE,iBAAiB,EACzB,UAAU,EAAE,MAAM,EACjC;IAEJ;;;;OAIG;IACG,OAAO,CACX,IAAI,EAAE,MAAM,EACZ,CAAC,EAAE,MAAM,EACT,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAmBlD;IAED;;;OAGG;IACG,OAAO,CACX,IAAI,EAAE,MAAM,EACZ,CAAC,EAAE,MAAM,EACT,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAgBlD;IAED;;;OAGG;IACG,UAAU,CACd,IAAI,EAAE,MAAM,EACZ,CAAC,EAAE,MAAM,EACT,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAmBlD;IAED;;;OAGG;IACH,OAAO,CAAC,YAAY;IAYpB,8EAA8E;YAChE,SAAS;CAmDxB;AAMD,yEAAyE;AACzE,wBAAgB,mBAAmB,IAAI,IAAI,CAmB1C;AAED,uEAAuE;AACvE,wBAAgB,kBAAkB,IAAI,eAAe,CAIpD;AAED,kFAAkF;AAClF,wBAAgB,0BAA0B,IAAI,eAAe,GAAG,SAAS,CAExE"}
+{"version":3,"file":"openalex-service.d.ts","sourceRoot":"","sources":["../../../src/services/openalex/openalex-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAQH,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAIL,KAAK,qBAAqB,EAE3B,MAAM,YAAY,CAAC;AAmFpB,gFAAgF;AAChF,qBAAa,eAAe;IAExB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAF7B,YACmB,MAAM,EAAE,iBAAiB,EACzB,UAAU,EAAE,MAAM,EACjC;IAEJ;;;;OAIG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAW3F;IAED;;;;;;;;OAQG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,qBAAqB,CAAC,CA4B3F;IAED;;;OAGG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAW9F;IAED,8EAA8E;IAC9E,OAAO,CAAC,SAAS;IAQjB;;;;;;;;;OASG;YACW,iBAAiB;IAiC/B;;;;OAIG;IACH,OAAO,CAAC,MAAM;IAcd,8EAA8E;YAChE,SAAS;CAmDxB;AAMD,yEAAyE;AACzE,wBAAgB,mBAAmB,IAAI,IAAI,CAmB1C;AAED,uEAAuE;AACvE,wBAAgB,kBAAkB,IAAI,eAAe,CAIpD;AAED,kFAAkF;AAClF,wBAAgB,0BAA0B,IAAI,eAAe,GAAG,SAAS,CAExE"}

package/dist/services/openalex/openalex-service.js

@@ -5,7 +5,13 @@
  *   - `citedBy(pmid, n)`: cites:W<id> filter → PMIDs (mirrors pubmed_pubmed_citedin)
  *   - `references(pmid, n)`: referenced_works → PMIDs (mirrors pubmed_pubmed_refs)
  *
- * All three methods drop records with no PMID — never mints fake IDs.
+ * Each method returns at least `n` PubMed-addressable rows when OpenAlex has
+ * them: `citedBy` walks pages of the `cites:` filter, and the other two resolve
+ * the work's ID list in batches, both stopping once the window is covered,
+ * upstream runs out, or a cap is reached. Records with no PMID are dropped —
+ * never minted — and counted, so callers can disclose the shortfall instead of
+ * serving an unexplained empty window.
+ *
  * Uses the NCBI_ADMIN_EMAIL config (adminEmail) as the OpenAlex polite-pool
  * `mailto=` parameter when set; omits it when unset.
  *
@@ -17,6 +23,7 @@ import { getServerConfig } from '../../config/server-config.js';
 import { recoveryFor } from '../error-contracts.js';
 import { isTransient } from '../retry-policy.js';
 import { OpenAlexApiClient } from './api-client.js';
+import { OPENALEX_MAX_FILTER_VALUES, OPENALEX_MAX_PAGE_SIZE, OPENALEX_MAX_UPSTREAM_REQUESTS, } from './types.js';
 /** Transient codes eligible for retry. */
 const RETRYABLE_CODES = new Set([
     JsonRpcErrorCode.ServiceUnavailable,
@@ -24,6 +31,10 @@ const RETRYABLE_CODES = new Set([
     JsonRpcErrorCode.RateLimited,
 ]);
 const MAX_BACKOFF_MS = 30_000;
+/** Strip the `https://openalex.org/` prefix an OA ID may carry. */
+function bareOaId(id) {
+    return id.startsWith('https://openalex.org/') ? id.slice('https://openalex.org/'.length) : id;
+}
 function abortableSleep(ms, signal) {
     if (!signal)
         return new Promise((r) => setTimeout(r, ms));
@@ -54,6 +65,44 @@ function extractPmid(work) {
     const match = /(\d+)\s*$/.exec(raw);
     return match?.[1] ?? null;
 }
+/**
+ * Nothing to page through: no source work, or an empty ID list. Built per call
+ * rather than shared — the `pmids` array escapes to the caller by identity, and
+ * one module-level instance would hand every empty answer the same array.
+ */
+function emptyResult() {
+    return { pmids: [], totalCount: 0, droppedNoPmid: 0, reachCapped: false };
+}
+/**
+ * Accumulates PubMed-addressable rows across pages or batches: dedupes, drops
+ * the source work, and counts the rows that carry no PMID. Kept as one object
+ * so a multi-request walk cannot reset the `seen` set between requests and
+ * re-emit a PMID an earlier page already returned.
+ */
+class PmidCollector {
+    excludePmid;
+    pmids = [];
+    droppedNoPmid = 0;
+    seen = new Set();
+    constructor(excludePmid) {
+        this.excludePmid = excludePmid;
+    }
+    /**
+     * Add one candidate row. `undefined` means OpenAlex returned nothing for a
+     * requested ID — unaddressable in PubMed exactly like a row with no PMID.
+     */
+    add(work) {
+        const pmid = work ? extractPmid(work) : null;
+        if (!pmid) {
+            this.droppedNoPmid++;
+            return;
+        }
+        if (pmid === this.excludePmid || this.seen.has(pmid))
+            return;
+        this.seen.add(pmid);
+        this.pmids.push(pmid);
+    }
+}
 /** Service facade over the OpenAlex API for the find-related provider chain. */
 export class OpenAlexService {
     client;
@@ -65,61 +114,96 @@ export class OpenAlexService {
     /**
      * Find works with similar content to the given PMID via OpenAlex `related_works`.
      * Returns PMIDs only; drops any record with no PMID.
-     * `n` is the number of PMIDs to return (OpenAlex caps related_works at ~10).
+     * `n` is the size of the window the caller needs covered.
      */
     async similar(pmid, n, signal) {
-        const work = await this.withRetry(() => this.client.getWorkByPmid(pmid, signal), `getWorkByPmid(${pmid})`, signal);
+        const work = await this.fetchWork(pmid, signal);
         if (!work)
-            return { pmids: [], totalCount: 0 };
-        const relatedIds = (work.related_works ?? []).slice(0, Math.min(n * 3, 50));
-        if (relatedIds.length === 0)
-            return { pmids: [], totalCount: 0 };
-        const resolved = await this.withRetry(() => this.client.resolveOaIdsToPmids(relatedIds, signal), `resolveRelatedWorks(${pmid})`, signal);
-        const pmids = this.extractPmids(resolved, pmid).slice(0, n);
-        return { pmids, totalCount: work.related_works?.length ?? 0 };
+            return emptyResult();
+        return this.resolveIdsToPmids(pmid, work.related_works ?? [], n, `resolveRelatedWorks(${pmid})`, signal);
     }
     /**
      * Find works that cite the given PMID via OpenAlex `cites:W<id>` filter.
      * Returns PMIDs only; drops any record with no PMID.
+     *
+     * Pages are all one size and are pulled until the filtered array covers `n`,
+     * upstream runs out, or `OPENALEX_MAX_UPSTREAM_REQUESTS` is hit — the rows OpenAlex
+     * serves count every citing work, but only those with a PubMed PMID are
+     * addressable, so a single page sized on the raw window can under-fill it.
      */
     async citedBy(pmid, n, signal) {
-        const work = await this.withRetry(() => this.client.getWorkByPmid(pmid, signal), `getWorkByPmid(${pmid})`, signal);
+        const work = await this.fetchWork(pmid, signal);
         if (!work)
-            return { pmids: [], totalCount: 0 };
-        const { works, totalCount } = await this.withRetry(() => this.client.getCitedBy(work.id, n, signal), `getCitedBy(${work.id})`, signal);
-        const pmids = this.extractPmids(works, pmid);
-        return { pmids, totalCount };
+            return emptyResult();
+        const perPage = Math.min(n, OPENALEX_MAX_PAGE_SIZE);
+        const collector = new PmidCollector(pmid);
+        let upstreamCount = 0;
+        let exhausted = false;
+        for (let page = 1; page <= OPENALEX_MAX_UPSTREAM_REQUESTS && collector.pmids.length < n; page++) {
+            const { works, totalCount } = await this.withRetry(() => this.client.getCitedBy(work.id, perPage, page, signal), `getCitedBy(${work.id}, page ${page})`, signal);
+            upstreamCount = totalCount;
+            for (const w of works)
+                collector.add(w);
+            if (works.length < perPage || page * perPage >= totalCount) {
+                exhausted = true;
+                break;
+            }
+        }
+        return this.finish(collector, exhausted, upstreamCount, n);
     }
     /**
      * Find works referenced by the given PMID via OpenAlex `referenced_works`.
      * Returns PMIDs only; drops any record with no PMID.
      */
     async references(pmid, n, signal) {
-        const work = await this.withRetry(() => this.client.getWorkByPmid(pmid, signal), `getWorkByPmid(${pmid})`, signal);
+        const work = await this.fetchWork(pmid, signal);
         if (!work)
-            return { pmids: [], totalCount: 0 };
-        const refIds = (work.referenced_works ?? []).slice(0, Math.min(n * 3, 200));
-        if (refIds.length === 0)
-            return { pmids: [], totalCount: 0 };
-        const resolved = await this.withRetry(() => this.client.resolveOaIdsToPmids(refIds, signal), `resolveReferencedWorks(${pmid})`, signal);
-        const pmids = this.extractPmids(resolved, pmid).slice(0, n);
-        return { pmids, totalCount: work.referenced_works?.length ?? 0 };
+            return emptyResult();
+        return this.resolveIdsToPmids(pmid, work.referenced_works ?? [], n, `resolveReferencedWorks(${pmid})`, signal);
+    }
+    /** Look up the source work by PMID; `null` when OpenAlex doesn't index it. */
+    fetchWork(pmid, signal) {
+        return this.withRetry(() => this.client.getWorkByPmid(pmid, signal), `getWorkByPmid(${pmid})`, signal);
     }
     /**
-     * Extract unique numeric PMIDs from a list of works, excluding the source PMID.
-     * Any work with no PMID is silently dropped (never minted).
+     * Resolve an OpenAlex ID list (a work's references or related works) to PMIDs,
+     * in batches, until the window is covered, the list is exhausted, or the
+     * request cap is reached. The work record carries the whole list, so this
+     * paginates resolution rather than an upstream query.
+     *
+     * Each batch's rows are re-ordered to the requested IDs, so the result follows
+     * the source list — a window at any offset stays stable across calls, whatever
+     * order OpenAlex answers a batch in.
      */
-    extractPmids(works, excludePmid) {
-        const seen = new Set();
-        const result = [];
-        for (const w of works) {
-            const pmid = extractPmid(w);
-            if (!pmid || pmid === excludePmid || seen.has(pmid))
-                continue;
-            seen.add(pmid);
-            result.push(pmid);
+    async resolveIdsToPmids(pmid, oaIds, n, label, signal) {
+        if (oaIds.length === 0)
+            return emptyResult();
+        const collector = new PmidCollector(pmid);
+        let consumed = 0;
+        for (let batch = 0; batch < OPENALEX_MAX_UPSTREAM_REQUESTS &&
+            consumed < oaIds.length &&
+            collector.pmids.length < n; batch++) {
+            const ids = oaIds.slice(consumed, consumed + OPENALEX_MAX_FILTER_VALUES);
+            const resolved = await this.withRetry(() => this.client.resolveOaIdsToPmids(ids, signal), label, signal);
+            const byId = new Map(resolved.map((w) => [bareOaId(w.id), w]));
+            for (const id of ids)
+                collector.add(byId.get(bareOaId(id)));
+            consumed += ids.length;
         }
-        return result;
+        return this.finish(collector, consumed >= oaIds.length, oaIds.length, n);
+    }
+    /**
+     * Shape a walk's outcome. Exhausting the fetchable set makes the addressable
+     * count exact; short of that only OpenAlex's own total is known, and a window
+     * the walk never reached is flagged rather than served as a silent empty.
+     */
+    finish(collector, exhausted, upstreamCount, n) {
+        return {
+            pmids: collector.pmids,
+            totalCount: exhausted ? collector.pmids.length : upstreamCount,
+            droppedNoPmid: collector.droppedNoPmid,
+            reachCapped: !exhausted && collector.pmids.length < n,
+        };
     }
     /** Retry wrapper for transient errors, mirroring the EPMC service pattern. */
     async withRetry(execute, label, signal) {

package/dist/services/openalex/openalex-service.js.map

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

package/dist/services/openalex/types.d.ts

@@ -12,6 +12,26 @@
  */
 /** Base URL for the OpenAlex public API. */
 export declare const OPENALEX_API_BASE = "https://api.openalex.org";
+/**
+ * Rows OpenAlex serves per request. The documented `per_page` range is 1-100,
+ * and basic paging is additionally bounded by `page × per_page ≤ 10,000` —
+ * beyond that the API returns HTTP 400 and demands cursor paging.
+ */
+export declare const OPENALEX_MAX_PAGE_SIZE = 100;
+/**
+ * Values one `filter=openalex:W1|W2|…` OR-clause accepts. A 101st value is
+ * rejected with HTTP 400 ("Maximum number of values exceeded"), so a caller
+ * resolving a long ID list must split it into batches of this size.
+ */
+export declare const OPENALEX_MAX_FILTER_VALUES = 100;
+/**
+ * Upstream requests one service call may spend reaching the window — pages of
+ * the `cites:` filter, or ID-resolution batches. Ten pages of 100 reach 1,000
+ * upstream rows: past the 50-row `maxResults` ceiling at any realistic offset,
+ * inside the `page × per_page ≤ 10,000` basic-paging limit, and ~3s of
+ * sequential requests at the ~0.3s a page costs (~0.7s for a 100-ID batch).
+ */
+export declare const OPENALEX_MAX_UPSTREAM_REQUESTS = 10;
 /**
  * Identifier block on an OpenAlex Work. Only `openalex` (the OA ID) is always
  * present; `pmid` is absent for non-PubMed records. We only care about PMIDs —
@@ -48,9 +68,22 @@ export interface OpenAlexWorksResponse {
     results?: OpenAlexWork[];
     [key: string]: unknown;
 }
-/** Resolved PMID list returned by service methods. */
+/**
+ * Resolved PMID list returned by service methods. `pmids` is indexed in
+ * PubMed-addressable rows only — upstream records with no PMID are dropped and
+ * counted in `droppedNoPmid`, so a caller can disclose the gap between
+ * OpenAlex's own totals and what it can actually return.
+ */
 export interface OpenAlexRelatedResult {
+    /** Candidate rows fetched for this request that carry no PubMed PMID. */
+    droppedNoPmid: number;
     pmids: string[];
+    /** Paging/batching stopped at its cap before the requested window was covered. */
+    reachCapped: boolean;
+    /**
+     * Exact PubMed-addressable count once the fetchable set is exhausted;
+     * OpenAlex's own upstream count while rows remain unfetched.
+     */
     totalCount: number;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/services/openalex/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/services/openalex/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,4CAA4C;AAC5C,eAAO,MAAM,iBAAiB,6BAA6B,CAAC;AAE5D;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CACnC;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,sEAAsE;IACtE,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,CAAC,EAAE,eAAe,CAAC;IACtB,yFAAyF;IACzF,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,oFAAoF;IACpF,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,oEAAoE;AACpE,MAAM,WAAW,qBAAqB;IACpC,IAAI,CAAC,EAAE;QACL,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,OAAO,CAAC,EAAE,YAAY,EAAE,CAAC;IACzB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,sDAAsD;AACtD,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/services/openalex/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,4CAA4C;AAC5C,eAAO,MAAM,iBAAiB,6BAA6B,CAAC;AAE5D;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAE1C;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,MAAM,CAAC;AAE9C;;;;;;GAMG;AACH,eAAO,MAAM,8BAA8B,KAAK,CAAC;AAEjD;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CACnC;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,sEAAsE;IACtE,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,CAAC,EAAE,eAAe,CAAC;IACtB,yFAAyF;IACzF,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,oFAAoF;IACpF,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,oEAAoE;AACpE,MAAM,WAAW,qBAAqB;IACpC,IAAI,CAAC,EAAE;QACL,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,OAAO,CAAC,EAAE,YAAY,EAAE,CAAC;IACzB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,yEAAyE;IACzE,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,kFAAkF;IAClF,WAAW,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB"}

package/dist/services/openalex/types.js

@@ -12,4 +12,24 @@
  */
 /** Base URL for the OpenAlex public API. */
 export const OPENALEX_API_BASE = 'https://api.openalex.org';
+/**
+ * Rows OpenAlex serves per request. The documented `per_page` range is 1-100,
+ * and basic paging is additionally bounded by `page × per_page ≤ 10,000` —
+ * beyond that the API returns HTTP 400 and demands cursor paging.
+ */
+export const OPENALEX_MAX_PAGE_SIZE = 100;
+/**
+ * Values one `filter=openalex:W1|W2|…` OR-clause accepts. A 101st value is
+ * rejected with HTTP 400 ("Maximum number of values exceeded"), so a caller
+ * resolving a long ID list must split it into batches of this size.
+ */
+export const OPENALEX_MAX_FILTER_VALUES = 100;
+/**
+ * Upstream requests one service call may spend reaching the window — pages of
+ * the `cites:` filter, or ID-resolution batches. Ten pages of 100 reach 1,000
+ * upstream rows: past the 50-row `maxResults` ceiling at any realistic offset,
+ * inside the `page × per_page ≤ 10,000` basic-paging limit, and ~3s of
+ * sequential requests at the ~0.3s a page costs (~0.7s for a 100-ID batch).
+ */
+export const OPENALEX_MAX_UPSTREAM_REQUESTS = 10;
 //# sourceMappingURL=types.js.map

package/dist/services/openalex/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/services/openalex/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,4CAA4C;AAC5C,MAAM,CAAC,MAAM,iBAAiB,GAAG,0BAA0B,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/services/openalex/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,4CAA4C;AAC5C,MAAM,CAAC,MAAM,iBAAiB,GAAG,0BAA0B,CAAC;AAE5D;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAG,CAAC;AAE1C;;;;GAIG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,GAAG,CAAC;AAE9C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG,EAAE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/pubmed-mcp-server",
-  "version": "2.10.8",
+  "version": "2.10.10",
   "mcpName": "io.github.cyanheads/pubmed-mcp-server",
   "description": "Search PubMed/Europe PMC, fetch articles and full text (PMC/EPMC/Unpaywall), citations, MeSH terms via MCP. STDIO or Streamable HTTP.",
   "type": "module",

package/server.json

@@ -6,7 +6,7 @@
     "url": "https://github.com/cyanheads/pubmed-mcp-server",
     "source": "github"
   },
-  "version": "2.10.8",
+  "version": "2.10.10",
   "remotes": [
     {
       "type": "streamable-http",
@@ -19,7 +19,7 @@
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@cyanheads/pubmed-mcp-server",
       "runtimeHint": "bun",
-      "version": "2.10.8",
+      "version": "2.10.10",
       "packageArguments": [
         {
           "type": "positional",
@@ -66,7 +66,7 @@
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@cyanheads/pubmed-mcp-server",
       "runtimeHint": "bun",
-      "version": "2.10.8",
+      "version": "2.10.10",
       "packageArguments": [
         {
           "type": "positional",