@cyanheads/pubmed-mcp-server 2.6.12 → 2.7.0

package/dist/services/europe-pmc/api-client.js

@@ -0,0 +1,123 @@
+/**
+ * @fileoverview Low-level HTTP client for Europe PMC's REST API. Builds URLs,
+ * injects the optional contact email, and exposes single-attempt search and
+ * fullTextXML calls. Retry logic lives in `EuropePmcService`.
+ * @module src/services/europe-pmc/api-client
+ */
+import { McpError, serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
+import { fetchWithTimeout, httpErrorFromResponse, logger, requestContextService, } from '@cyanheads/mcp-ts-core/utils';
+import { recoveryFor } from '../../services/error-contracts.js';
+import { EUROPEPMC_API_BASE } from './types.js';
+const USER_AGENT = 'pubmed-mcp-server (+https://github.com/cyanheads/pubmed-mcp-server)';
+/** Low-level HTTP client for Europe PMC. Single-attempt — retries upstream. */
+export class EuropePmcApiClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Execute a search. Returns the raw JSON response body as a string so
+     * `EuropePmcService` can parse and surface SerializationError consistently
+     * when the body is malformed.
+     */
+    async search(params) {
+        const url = this.buildSearchUrl(params);
+        const ctx = requestContextService.createRequestContext({
+            operation: 'EuropePmcSearch',
+            query: params.query,
+        });
+        let response;
+        try {
+            response = await fetchWithTimeout(url, this.config.timeoutMs, ctx, {
+                headers: { Accept: 'application/json', 'User-Agent': USER_AGENT },
+                ...(params.signal && { signal: params.signal }),
+            });
+        }
+        catch (error) {
+            if (error instanceof McpError)
+                throw error;
+            const msg = error instanceof Error ? error.message : String(error);
+            throw serviceUnavailable(`Europe PMC search request failed: ${msg}`, { reason: 'europepmc_unreachable', ...recoveryFor('europepmc_unreachable') }, { cause: error });
+        }
+        if (!response.ok) {
+            throw await httpErrorFromResponse(response, {
+                service: 'Europe PMC',
+                data: { url, reason: 'europepmc_unreachable', ...recoveryFor('europepmc_unreachable') },
+            });
+        }
+        return response.text();
+    }
+    /**
+     * Fetch the JATS full-text XML for an EPMC record by its internal id.
+     * Returns `{ kind: 'not-available' }` for 404 — EPMC has the record but
+     * doesn't publish a full-text XML for it (very common for preprints).
+     */
+    async fullTextXml(epmcId, signal) {
+        const url = `${EUROPEPMC_API_BASE}/${encodeURIComponent(epmcId)}/fullTextXML`;
+        const ctx = requestContextService.createRequestContext({
+            operation: 'EuropePmcFullTextXml',
+            epmcId,
+        });
+        let response;
+        try {
+            response = await fetchWithTimeout(url, this.config.timeoutMs, ctx, {
+                headers: {
+                    Accept: 'application/xml, text/xml, */*;q=0.5',
+                    'User-Agent': USER_AGENT,
+                },
+                ...(signal && { signal }),
+            });
+        }
+        catch (error) {
+            if (error instanceof McpError)
+                throw error;
+            const msg = error instanceof Error ? error.message : String(error);
+            throw serviceUnavailable(`Europe PMC fullTextXML request failed: ${msg}`, { reason: 'europepmc_unreachable', epmcId, ...recoveryFor('europepmc_unreachable') }, { cause: error });
+        }
+        if (response.status === 404) {
+            return { kind: 'not-available', reason: 'EPMC has no fullTextXML for this record' };
+        }
+        if (!response.ok) {
+            throw await httpErrorFromResponse(response, {
+                service: 'Europe PMC fullTextXML',
+                data: { epmcId, reason: 'europepmc_unreachable', ...recoveryFor('europepmc_unreachable') },
+            });
+        }
+        const xml = await response.text();
+        if (!xml.trim()) {
+            logger.debug('Europe PMC returned an empty fullTextXML body.', requestContextService.createRequestContext({
+                operation: 'EuropePmcFullTextXmlEmpty',
+                epmcId,
+            }));
+            return { kind: 'not-available', reason: 'EPMC returned an empty fullTextXML body' };
+        }
+        return { kind: 'found', xml };
+    }
+    buildSearchUrl(params) {
+        const finalParams = {
+            query: this.buildQueryString(params),
+            format: 'json',
+            resultType: params.resultType ?? 'core',
+            pageSize: String(params.pageSize ?? 25),
+            cursorMark: params.cursorMark ?? '*',
+        };
+        if (params.sort)
+            finalParams.sort = params.sort;
+        if (this.config.email)
+            finalParams.email = this.config.email;
+        return `${EUROPEPMC_API_BASE}/search?${new URLSearchParams(finalParams).toString()}`;
+    }
+    /**
+     * Combine the caller's query with an optional source filter. EPMC's query
+     * syntax supports `SRC:"X"` field tokens — we OR-join the requested sources
+     * into a parenthesized clause and AND it with the user's query.
+     */
+    buildQueryString(params) {
+        const base = params.query.trim();
+        if (!params.sources || params.sources.length === 0)
+            return base;
+        const sourceClause = params.sources.map((s) => `SRC:"${s}"`).join(' OR ');
+        return `(${base}) AND (${sourceClause})`;
+    }
+}
+//# sourceMappingURL=api-client.js.map

package/dist/services/europe-pmc/api-client.js.map

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

package/dist/services/europe-pmc/europe-pmc-service.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @fileoverview Europe PMC service. Wraps the EPMC REST API with rate-limiting,
+ * retries, and JATS XML parsing. Two methods: `search()` for keyword discovery
+ * across the EPMC corpus (MED/PMC/PPR/PAT/AGR) and `fullTextXml()` for fetching
+ * a record's full-text JATS. The XML parser matches NCBI's ordered config so
+ * `parsePmcArticle` consumes the result without modification.
+ *
+ * Optional service: only constructed when `EUROPEPMC_ENABLED=true` (the
+ * default). `getEuropePmcService()` returns `undefined` when disabled so
+ * callers can skip the chain step gracefully.
+ *
+ * @module src/services/europe-pmc/europe-pmc-service
+ */
+import type { JatsNode } from '../../services/ncbi/parsing/pmc-xml-helpers.js';
+import { EuropePmcApiClient } from './api-client.js';
+import { EuropePmcRequestQueue } from './request-queue.js';
+import type { EuropePmcFullTextResult, EuropePmcSearchParams, EuropePmcSearchResult, EuropePmcSource } from './types.js';
+/**
+ * Facade over the Europe PMC REST API. Two methods:
+ *   - `search()` — keyword search across MED/PMC/PPR/PAT/AGR.
+ *   - `fullTextXml()` — JATS full text for an EPMC record.
+ *
+ * Both honor `ctx.signal` for cancellation and retry transient failures with
+ * capped exponential backoff plus jitter.
+ */
+export declare class EuropePmcService {
+    private readonly client;
+    private readonly queue;
+    private readonly maxRetries;
+    private readonly orderedXmlParser;
+    constructor(client: EuropePmcApiClient, queue: EuropePmcRequestQueue, maxRetries: number);
+    /**
+     * Search Europe PMC. Cursor-based pagination — pass `cursorMark: '*'` (or
+     * omit) for the first page; pass the returned `nextCursorMark` for the next.
+     */
+    search(params: EuropePmcSearchParams): Promise<EuropePmcSearchResult>;
+    /**
+     * Fetch the JATS full text for an EPMC record. Returns:
+     *   - `{ kind: 'found', xml, epmcId, source }` — JATS XML string usable
+     *     directly by tool callers that hold their own parser, or via
+     *     `parseFullTextXml()` for the parsed tree.
+     *   - `{ kind: 'not-available', reason }` — EPMC has the record but
+     *     publishes no fullTextXML (404 or empty body).
+     */
+    fullTextXml(epmcId: string, source: EuropePmcSource, signal?: AbortSignal): Promise<EuropePmcFullTextResult>;
+    /**
+     * Parse a JATS XML string into the ordered node tree consumed by
+     * `parsePmcArticle`. Returns the `<article>` JatsNode, or `undefined` when
+     * the body doesn't contain an article element (malformed / empty).
+     *
+     * Throws `SerializationError` only for fundamentally invalid XML; an
+     * article-free but well-formed body returns `undefined` so callers can
+     * surface a `no-epmc-fulltext` outcome without a hard failure.
+     */
+    parseFullTextXml(xml: string): JatsNode | undefined;
+    /**
+     * Retry wrapper for transient errors. Mirrors NCBI's `withRetry` minus the
+     * service-level deadline — EPMC requests are cheaper individually and the
+     * caller (typically `ctx.signal`) bounds the total chain.
+     */
+    private withRetry;
+}
+/**
+ * Initialize the Europe PMC service when enabled. Safe to call regardless of
+ * config — `EUROPEPMC_ENABLED=false` leaves the service unset so callers see
+ * `undefined` and skip the chain step.
+ */
+export declare function initEuropePmcService(): void;
+/** Returns the initialized service, or `undefined` when EPMC is disabled. */
+export declare function getEuropePmcService(): EuropePmcService | undefined;
+//# sourceMappingURL=europe-pmc-service.d.ts.map

package/dist/services/europe-pmc/europe-pmc-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"europe-pmc-service.d.ts","sourceRoot":"","sources":["../../../src/services/europe-pmc/europe-pmc-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAaH,OAAO,KAAK,EAAE,QAAQ,EAAgB,MAAM,4CAA4C,CAAC;AAEzF,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EACV,uBAAuB,EAEvB,qBAAqB,EAErB,qBAAqB,EACrB,eAAe,EAChB,MAAM,YAAY,CAAC;AA2BpB;;;;;;;GAOG;AACH,qBAAa,gBAAgB;IAIzB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAL7B,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAY;gBAG1B,MAAM,EAAE,kBAAkB,EAC1B,KAAK,EAAE,qBAAqB,EAC5B,UAAU,EAAE,MAAM;IAmBrC;;;OAGG;IACG,MAAM,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IA0C3E;;;;;;;OAOG;IACG,WAAW,CACf,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,eAAe,EACvB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,uBAAuB,CAAC;IAkBnC;;;;;;;;OAQG;IACH,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS;IAgCnD;;;;OAIG;YACW,SAAS;CAsDxB;AAMD;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAuB3C;AAED,6EAA6E;AAC7E,wBAAgB,mBAAmB,IAAI,gBAAgB,GAAG,SAAS,CAElE"}

package/dist/services/europe-pmc/europe-pmc-service.js

@@ -0,0 +1,243 @@
+/**
+ * @fileoverview Europe PMC service. Wraps the EPMC REST API with rate-limiting,
+ * retries, and JATS XML parsing. Two methods: `search()` for keyword discovery
+ * across the EPMC corpus (MED/PMC/PPR/PAT/AGR) and `fullTextXml()` for fetching
+ * a record's full-text JATS. The XML parser matches NCBI's ordered config so
+ * `parsePmcArticle` consumes the result without modification.
+ *
+ * Optional service: only constructed when `EUROPEPMC_ENABLED=true` (the
+ * default). `getEuropePmcService()` returns `undefined` when disabled so
+ * callers can skip the chain step gracefully.
+ *
+ * @module src/services/europe-pmc/europe-pmc-service
+ */
+import { internalError, JsonRpcErrorCode, McpError, serializationError, } from '@cyanheads/mcp-ts-core/errors';
+import { logger, requestContextService } from '@cyanheads/mcp-ts-core/utils';
+import { XMLParser, XMLValidator } from 'fast-xml-parser';
+import { getServerConfig } from '../../config/server-config.js';
+import { recoveryFor } from '../../services/error-contracts.js';
+import { ensureArray } from '../../services/ncbi/parsing/xml-helpers.js';
+import { EuropePmcApiClient } from './api-client.js';
+import { EuropePmcRequestQueue } from './request-queue.js';
+/** Retryable transient codes — same set NCBI uses. */
+const RETRYABLE_CODES = new Set([
+    JsonRpcErrorCode.ServiceUnavailable,
+    JsonRpcErrorCode.Timeout,
+    JsonRpcErrorCode.RateLimited,
+]);
+const MAX_BACKOFF_MS = 30_000;
+function abortableSleep(ms, signal) {
+    if (!signal)
+        return new Promise((r) => setTimeout(r, ms));
+    if (signal.aborted)
+        return Promise.reject(signal.reason);
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal.reason);
+        };
+        const timer = setTimeout(() => {
+            signal.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}
+/**
+ * Facade over the Europe PMC REST API. Two methods:
+ *   - `search()` — keyword search across MED/PMC/PPR/PAT/AGR.
+ *   - `fullTextXml()` — JATS full text for an EPMC record.
+ *
+ * Both honor `ctx.signal` for cancellation and retry transient failures with
+ * capped exponential backoff plus jitter.
+ */
+export class EuropePmcService {
+    client;
+    queue;
+    maxRetries;
+    orderedXmlParser;
+    constructor(client, queue, maxRetries) {
+        this.client = client;
+        this.queue = queue;
+        this.maxRetries = maxRetries;
+        /**
+         * EPMC's fullTextXML is JATS Z39.96 — same DTD PMC uses — so the parser
+         * config mirrors `NcbiResponseHandler.orderedXmlParser`. `preserveOrder`
+         * keeps inline mixed content readable; `trimValues: false` retains spaces
+         * between text and inline children.
+         */
+        this.orderedXmlParser = new XMLParser({
+            preserveOrder: true,
+            ignoreAttributes: false,
+            attributeNamePrefix: '@_',
+            parseTagValue: true,
+            trimValues: false,
+            processEntities: true,
+            htmlEntities: true,
+        });
+    }
+    /**
+     * Search Europe PMC. Cursor-based pagination — pass `cursorMark: '*'` (or
+     * omit) for the first page; pass the returned `nextCursorMark` for the next.
+     */
+    async search(params) {
+        const text = await this.queue.enqueue(() => this.withRetry(() => this.client.search(params), 'search', params.signal), 'search', params.signal);
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch (error) {
+            throw serializationError('Failed to parse Europe PMC search JSON response.', {
+                reason: 'europepmc_invalid_response',
+                responseSnippet: text.substring(0, 200),
+                ...recoveryFor('europepmc_invalid_response'),
+            }, { cause: error });
+        }
+        const hits = ensureArray(parsed.resultList?.result);
+        const echoed = parsed.request?.queryString ?? params.query;
+        // EPMC echoes back the input cursor mark on the final page, so absence of
+        // an explicit "next" or equality with the request's cursor marks the end.
+        const cursorMark = parsed.request?.cursorMark ?? params.cursorMark ?? '*';
+        const nextCursor = parsed.nextCursorMark && parsed.nextCursorMark !== cursorMark
+            ? parsed.nextCursorMark
+            : undefined;
+        return {
+            hits,
+            hitCount: parsed.hitCount ?? hits.length,
+            ...(nextCursor && { nextCursorMark: nextCursor }),
+            cursorMark,
+            query: echoed,
+        };
+    }
+    /**
+     * Fetch the JATS full text for an EPMC record. Returns:
+     *   - `{ kind: 'found', xml, epmcId, source }` — JATS XML string usable
+     *     directly by tool callers that hold their own parser, or via
+     *     `parseFullTextXml()` for the parsed tree.
+     *   - `{ kind: 'not-available', reason }` — EPMC has the record but
+     *     publishes no fullTextXML (404 or empty body).
+     */
+    async fullTextXml(epmcId, source, signal) {
+        const outcome = await this.queue.enqueue(() => this.withRetry(() => this.client.fullTextXml(epmcId, signal), `fullTextXml(${epmcId})`, signal), `fullTextXml(${epmcId})`, signal);
+        if (outcome.kind === 'not-available') {
+            return { kind: 'not-available', reason: outcome.reason };
+        }
+        return { kind: 'found', xml: outcome.xml, epmcId, source };
+    }
+    /**
+     * Parse a JATS XML string into the ordered node tree consumed by
+     * `parsePmcArticle`. Returns the `<article>` JatsNode, or `undefined` when
+     * the body doesn't contain an article element (malformed / empty).
+     *
+     * Throws `SerializationError` only for fundamentally invalid XML; an
+     * article-free but well-formed body returns `undefined` so callers can
+     * surface a `no-epmc-fulltext` outcome without a hard failure.
+     */
+    parseFullTextXml(xml) {
+        const validationResult = XMLValidator.validate(xml.replace(/<!DOCTYPE[^>]*>/gi, ''));
+        if (validationResult !== true) {
+            throw serializationError('Received invalid XML from Europe PMC.', {
+                reason: 'europepmc_invalid_response',
+                responseSnippet: xml.substring(0, 200),
+                ...recoveryFor('europepmc_invalid_response'),
+            });
+        }
+        let parsed;
+        try {
+            parsed = this.orderedXmlParser.parse(xml);
+        }
+        catch (error) {
+            const parserError = error instanceof Error ? error.message : String(error);
+            throw serializationError(`Failed to parse Europe PMC fullTextXML response: ${parserError}`, {
+                reason: 'europepmc_invalid_response',
+                parserError,
+                responseSnippet: xml.substring(0, 200),
+                ...recoveryFor('europepmc_invalid_response'),
+            }, { cause: error });
+        }
+        if (!Array.isArray(parsed))
+            return;
+        const nodes = parsed;
+        return nodes.find((n) => 'article' in n);
+    }
+    /**
+     * Retry wrapper for transient errors. Mirrors NCBI's `withRetry` minus the
+     * service-level deadline — EPMC requests are cheaper individually and the
+     * caller (typically `ctx.signal`) bounds the total chain.
+     */
+    async withRetry(execute, label, signal) {
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            if (signal?.aborted)
+                throw signal.reason;
+            try {
+                return await execute();
+            }
+            catch (error) {
+                if (signal?.aborted)
+                    throw signal.reason;
+                if (!(error instanceof McpError))
+                    throw error;
+                if (!RETRYABLE_CODES.has(error.code))
+                    throw error;
+                if (attempt < this.maxRetries) {
+                    const baseDelay = Math.min(1000 * 2 ** attempt, MAX_BACKOFF_MS);
+                    const jitter = baseDelay * (0.75 + 0.5 * Math.random());
+                    const retryDelay = Math.round(jitter);
+                    logger.warning(`Europe PMC ${label} failed. Retrying (${attempt + 1}/${this.maxRetries}) in ${retryDelay}ms.`, requestContextService.createRequestContext({
+                        operation: 'EuropePmcRetry',
+                        label,
+                        attempt: attempt + 1,
+                        retryDelay,
+                    }));
+                    await abortableSleep(retryDelay, signal);
+                    continue;
+                }
+                const attempts = this.maxRetries + 1;
+                const msg = error instanceof Error ? error.message : String(error);
+                throw new McpError(error.code, `${msg} (failed after ${attempts} attempts)`, {
+                    reason: 'europepmc_unreachable',
+                    label,
+                    attempts,
+                    ...recoveryFor('europepmc_unreachable'),
+                }, { cause: error });
+            }
+        }
+        throw internalError('Europe PMC request failed after all retries.', {
+            reason: 'europepmc_unreachable',
+            label,
+            ...recoveryFor('europepmc_unreachable'),
+        });
+    }
+}
+// ─── Init / Accessor ────────────────────────────────────────────────────────
+let _service;
+/**
+ * Initialize the Europe PMC service when enabled. Safe to call regardless of
+ * config — `EUROPEPMC_ENABLED=false` leaves the service unset so callers see
+ * `undefined` and skip the chain step.
+ */
+export function initEuropePmcService() {
+    const config = getServerConfig();
+    if (!config.europepmcEnabled) {
+        logger.info('Europe PMC service disabled (EUROPEPMC_ENABLED=false).');
+        return;
+    }
+    const client = new EuropePmcApiClient({
+        timeoutMs: config.europepmcTimeoutMs,
+        ...(config.europepmcEmail && { email: config.europepmcEmail }),
+    });
+    const queue = new EuropePmcRequestQueue(config.europepmcRequestDelayMs);
+    _service = new EuropePmcService(client, queue, config.europepmcMaxRetries);
+    logger.info('Europe PMC service initialized.', requestContextService.createRequestContext({
+        operation: 'EuropePmcInit',
+        requestDelayMs: config.europepmcRequestDelayMs,
+        maxRetries: config.europepmcMaxRetries,
+        timeoutMs: config.europepmcTimeoutMs,
+        hasEmail: !!config.europepmcEmail,
+    }));
+}
+/** Returns the initialized service, or `undefined` when EPMC is disabled. */
+export function getEuropePmcService() {
+    return _service;
+}
+//# sourceMappingURL=europe-pmc-service.js.map

package/dist/services/europe-pmc/europe-pmc-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"europe-pmc-service.js","sourceRoot":"","sources":["../../../src/services/europe-pmc/europe-pmc-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,QAAQ,EACR,kBAAkB,GACnB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,MAAM,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAC7E,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE1D,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAE5D,OAAO,EAAE,WAAW,EAAE,MAAM,wCAAwC,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAU3D,sDAAsD;AACtD,MAAM,eAAe,GAAG,IAAI,GAAG,CAAmB;IAChD,gBAAgB,CAAC,kBAAkB;IACnC,gBAAgB,CAAC,OAAO;IACxB,gBAAgB,CAAC,WAAW;CAC7B,CAAC,CAAC;AAEH,MAAM,cAAc,GAAG,MAAM,CAAC;AAE9B,SAAS,cAAc,CAAC,EAAU,EAAE,MAAoB;IACtD,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;IAC1D,IAAI,MAAM,CAAC,OAAO;QAAE,OAAO,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACzD,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC3C,MAAM,OAAO,GAAG,GAAG,EAAE;YACnB,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACxB,CAAC,CAAC;QACF,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC5B,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAC7C,OAAO,EAAE,CAAC;QACZ,CAAC,EAAE,EAAE,CAAC,CAAC;QACP,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5D,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,gBAAgB;IAIR;IACA;IACA;IALF,gBAAgB,CAAY;IAE7C,YACmB,MAA0B,EAC1B,KAA4B,EAC5B,UAAkB;QAFlB,WAAM,GAAN,MAAM,CAAoB;QAC1B,UAAK,GAAL,KAAK,CAAuB;QAC5B,eAAU,GAAV,UAAU,CAAQ;QAEnC;;;;;WAKG;QACH,IAAI,CAAC,gBAAgB,GAAG,IAAI,SAAS,CAAC;YACpC,aAAa,EAAE,IAAI;YACnB,gBAAgB,EAAE,KAAK;YACvB,mBAAmB,EAAE,IAAI;YACzB,aAAa,EAAE,IAAI;YACnB,UAAU,EAAE,KAAK;YACjB,eAAe,EAAE,IAAI;YACrB,YAAY,EAAE,IAAI;SACnB,CAAC,CAAC;IACL,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,MAAM,CAAC,MAA6B;QACxC,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CACnC,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,EAC/E,QAAQ,EACR,MAAM,CAAC,MAAM,CACd,CAAC;QAEF,IAAI,MAA+B,CAAC;QACpC,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAA4B,CAAC;QACvD,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,MAAM,kBAAkB,CACtB,kDAAkD,EAClD;gBACE,MAAM,EAAE,4BAA4B;gBACpC,eAAe,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,GAAG,CAAC;gBACvC,GAAG,WAAW,CAAC,4BAA4B,CAAC;aAC7C,EACD,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAC;QACJ,CAAC;QAED,MAAM,IAAI,GAAG,WAAW,CAAqB,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;QACxE,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,EAAE,WAAW,IAAI,MAAM,CAAC,KAAK,CAAC;QAE3D,0EAA0E;QAC1E,0EAA0E;QAC1E,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,EAAE,UAAU,IAAI,MAAM,CAAC,UAAU,IAAI,GAAG,CAAC;QAC1E,MAAM,UAAU,GACd,MAAM,CAAC,cAAc,IAAI,MAAM,CAAC,cAAc,KAAK,UAAU;YAC3D,CAAC,CAAC,MAAM,CAAC,cAAc;YACvB,CAAC,CAAC,SAAS,CAAC;QAEhB,OAAO;YACL,IAAI;YACJ,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,IAAI,CAAC,MAAM;YACxC,GAAG,CAAC,UAAU,IAAI,EAAE,cAAc,EAAE,UAAU,EAAE,CAAC;YACjD,UAAU;YACV,KAAK,EAAE,MAAM;SACd,CAAC;IACJ,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,WAAW,CACf,MAAc,EACd,MAAuB,EACvB,MAAoB;QAEpB,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CACtC,GAAG,EAAE,CACH,IAAI,CAAC,SAAS,CACZ,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EAC7C,eAAe,MAAM,GAAG,EACxB,MAAM,CACP,EACH,eAAe,MAAM,GAAG,EACxB,MAAM,CACP,CAAC;QAEF,IAAI,OAAO,CAAC,IAAI,KAAK,eAAe,EAAE,CAAC;YACrC,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;QAC3D,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAC7D,CAAC;IAED;;;;;;;;OAQG;IACH,gBAAgB,CAAC,GAAW;QAC1B,MAAM,gBAAgB,GAAG,YAAY,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,mBAAmB,EAAE,EAAE,CAAC,CAAC,CAAC;QACrF,IAAI,gBAAgB,KAAK,IAAI,EAAE,CAAC;YAC9B,MAAM,kBAAkB,CAAC,uCAAuC,EAAE;gBAChE,MAAM,EAAE,4BAA4B;gBACpC,eAAe,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC,EAAE,GAAG,CAAC;gBACtC,GAAG,WAAW,CAAC,4BAA4B,CAAC;aAC7C,CAAC,CAAC;QACL,CAAC;QAED,IAAI,MAAe,CAAC;QACpB,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC5C,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,MAAM,WAAW,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAC3E,MAAM,kBAAkB,CACtB,oDAAoD,WAAW,EAAE,EACjE;gBACE,MAAM,EAAE,4BAA4B;gBACpC,WAAW;gBACX,eAAe,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC,EAAE,GAAG,CAAC;gBACtC,GAAG,WAAW,CAAC,4BAA4B,CAAC;aAC7C,EACD,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;YAAE,OAAO;QACnC,MAAM,KAAK,GAAG,MAAsB,CAAC;QACrC,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,IAAI,CAAC,CAAC,CAAC;IAC3C,CAAC;IAED;;;;OAIG;IACK,KAAK,CAAC,SAAS,CACrB,OAAyB,EACzB,KAAa,EACb,MAAoB;QAEpB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,IAAI,CAAC,UAAU,EAAE,OAAO,EAAE,EAAE,CAAC;YAC5D,IAAI,MAAM,EAAE,OAAO;gBAAE,MAAM,MAAM,CAAC,MAAM,CAAC;YAEzC,IAAI,CAAC;gBACH,OAAO,MAAM,OAAO,EAAE,CAAC;YACzB,CAAC;YAAC,OAAO,KAAc,EAAE,CAAC;gBACxB,IAAI,MAAM,EAAE,OAAO;oBAAE,MAAM,MAAM,CAAC,MAAM,CAAC;gBACzC,IAAI,CAAC,CAAC,KAAK,YAAY,QAAQ,CAAC;oBAAE,MAAM,KAAK,CAAC;gBAC9C,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC;oBAAE,MAAM,KAAK,CAAC;gBAElD,IAAI,OAAO,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;oBAC9B,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,IAAI,OAAO,EAAE,cAAc,CAAC,CAAC;oBAChE,MAAM,MAAM,GAAG,SAAS,GAAG,CAAC,IAAI,GAAG,GAAG,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;oBACxD,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;oBACtC,MAAM,CAAC,OAAO,CACZ,cAAc,KAAK,sBAAsB,OAAO,GAAG,CAAC,IAAI,IAAI,CAAC,UAAU,QAAQ,UAAU,KAAK,EAC9F,qBAAqB,CAAC,oBAAoB,CAAC;wBACzC,SAAS,EAAE,gBAAgB;wBAC3B,KAAK;wBACL,OAAO,EAAE,OAAO,GAAG,CAAC;wBACpB,UAAU;qBACX,CAAC,CACH,CAAC;oBACF,MAAM,cAAc,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;oBACzC,SAAS;gBACX,CAAC;gBAED,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,GAAG,CAAC,CAAC;gBACrC,MAAM,GAAG,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBACnE,MAAM,IAAI,QAAQ,CAChB,KAAK,CAAC,IAAI,EACV,GAAG,GAAG,kBAAkB,QAAQ,YAAY,EAC5C;oBACE,MAAM,EAAE,uBAAuB;oBAC/B,KAAK;oBACL,QAAQ;oBACR,GAAG,WAAW,CAAC,uBAAuB,CAAC;iBACxC,EACD,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAC;YACJ,CAAC;QACH,CAAC;QAED,MAAM,aAAa,CAAC,8CAA8C,EAAE;YAClE,MAAM,EAAE,uBAAuB;YAC/B,KAAK;YACL,GAAG,WAAW,CAAC,uBAAuB,CAAC;SACxC,CAAC,CAAC;IACL,CAAC;CACF;AAED,+EAA+E;AAE/E,IAAI,QAAsC,CAAC;AAE3C;;;;GAIG;AACH,MAAM,UAAU,oBAAoB;IAClC,MAAM,MAAM,GAAG,eAAe,EAAE,CAAC;IACjC,IAAI,CAAC,MAAM,CAAC,gBAAgB,EAAE,CAAC;QAC7B,MAAM,CAAC,IAAI,CAAC,wDAAwD,CAAC,CAAC;QACtE,OAAO;IACT,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,kBAAkB,CAAC;QACpC,SAAS,EAAE,MAAM,CAAC,kBAAkB;QACpC,GAAG,CAAC,MAAM,CAAC,cAAc,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,cAAc,EAAE,CAAC;KAC/D,CAAC,CAAC;IACH,MAAM,KAAK,GAAG,IAAI,qBAAqB,CAAC,MAAM,CAAC,uBAAuB,CAAC,CAAC;IACxE,QAAQ,GAAG,IAAI,gBAAgB,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,mBAAmB,CAAC,CAAC;IAC3E,MAAM,CAAC,IAAI,CACT,iCAAiC,EACjC,qBAAqB,CAAC,oBAAoB,CAAC;QACzC,SAAS,EAAE,eAAe;QAC1B,cAAc,EAAE,MAAM,CAAC,uBAAuB;QAC9C,UAAU,EAAE,MAAM,CAAC,mBAAmB;QACtC,SAAS,EAAE,MAAM,CAAC,kBAAkB;QACpC,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,cAAc;KAClC,CAAC,CACH,CAAC;AACJ,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,mBAAmB;IACjC,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/services/europe-pmc/request-queue.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @fileoverview Rate-limited request scheduler for Europe PMC calls. Caps
+ * concurrent in-flight requests and enforces a minimum start-gap between
+ * dispatches to stay polite with EBI's infrastructure. Independent rate
+ * domain from NCBI's queue — Europe PMC runs on a different host with its
+ * own limits.
+ * @module src/services/europe-pmc/request-queue
+ */
+/**
+ * Schedules Europe PMC requests against two independent ceilings:
+ *
+ *   - **Throughput** (`minStartGapMs`): minimum delay between two consecutive
+ *     dispatch times. Defaults to 200ms to be polite with EBI.
+ *   - **Concurrency** (`maxConcurrent`): maximum simultaneous in-flight
+ *     requests. Decouples concurrency from rate so slow upstream responses
+ *     don't block new dispatches.
+ *
+ * Enqueue accepts an optional `AbortSignal` so callers can bound their total
+ * time inside the scheduler — when the signal fires, a still-waiting task
+ * rejects immediately instead of sitting behind a saturated worker.
+ */
+export declare class EuropePmcRequestQueue {
+    private readonly waiters;
+    private readonly minStartGapMs;
+    private readonly maxConcurrent;
+    private inFlight;
+    private lastStartTime;
+    private nextDispatchTimer;
+    constructor(minStartGapMs: number, maxConcurrent?: number);
+    enqueue<T>(task: () => Promise<T>, label: string, signal?: AbortSignal): Promise<T>;
+    private tryDispatch;
+}
+//# sourceMappingURL=request-queue.d.ts.map

package/dist/services/europe-pmc/request-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-queue.d.ts","sourceRoot":"","sources":["../../../src/services/europe-pmc/request-queue.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAeH;;;;;;;;;;;;GAYG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IACxC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,iBAAiB,CAA4C;gBAEzD,aAAa,EAAE,MAAM,EAAE,aAAa,GAAE,MAA+B;IAKjF,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC;IA+BnF,OAAO,CAAC,WAAW;CAoDpB"}

package/dist/services/europe-pmc/request-queue.js

@@ -0,0 +1,107 @@
+/**
+ * @fileoverview Rate-limited request scheduler for Europe PMC calls. Caps
+ * concurrent in-flight requests and enforces a minimum start-gap between
+ * dispatches to stay polite with EBI's infrastructure. Independent rate
+ * domain from NCBI's queue — Europe PMC runs on a different host with its
+ * own limits.
+ * @module src/services/europe-pmc/request-queue
+ */
+import { logger, requestContextService } from '@cyanheads/mcp-ts-core/utils';
+const DEFAULT_MAX_CONCURRENT = 4;
+/**
+ * Schedules Europe PMC requests against two independent ceilings:
+ *
+ *   - **Throughput** (`minStartGapMs`): minimum delay between two consecutive
+ *     dispatch times. Defaults to 200ms to be polite with EBI.
+ *   - **Concurrency** (`maxConcurrent`): maximum simultaneous in-flight
+ *     requests. Decouples concurrency from rate so slow upstream responses
+ *     don't block new dispatches.
+ *
+ * Enqueue accepts an optional `AbortSignal` so callers can bound their total
+ * time inside the scheduler — when the signal fires, a still-waiting task
+ * rejects immediately instead of sitting behind a saturated worker.
+ */
+export class EuropePmcRequestQueue {
+    waiters = [];
+    minStartGapMs;
+    maxConcurrent;
+    inFlight = 0;
+    lastStartTime = 0;
+    nextDispatchTimer;
+    constructor(minStartGapMs, maxConcurrent = DEFAULT_MAX_CONCURRENT) {
+        this.minStartGapMs = minStartGapMs;
+        this.maxConcurrent = maxConcurrent;
+    }
+    enqueue(task, label, signal) {
+        return new Promise((resolve, reject) => {
+            if (signal?.aborted) {
+                reject(signal.reason);
+                return;
+            }
+            const waiter = {
+                resolve,
+                reject,
+                task,
+                label,
+                ...(signal && { signal }),
+            };
+            if (signal) {
+                const onAbort = () => {
+                    const idx = this.waiters.indexOf(waiter);
+                    if (idx === -1)
+                        return;
+                    this.waiters.splice(idx, 1);
+                    reject(signal.reason);
+                };
+                waiter.onAbort = onAbort;
+                signal.addEventListener('abort', onAbort, { once: true });
+            }
+            this.waiters.push(waiter);
+            this.tryDispatch();
+        });
+    }
+    tryDispatch() {
+        if (this.nextDispatchTimer !== undefined)
+            return;
+        while (this.inFlight < this.maxConcurrent && this.waiters.length > 0) {
+            const now = Date.now();
+            const gap = this.minStartGapMs - (now - this.lastStartTime);
+            if (gap > 0) {
+                this.nextDispatchTimer = setTimeout(() => {
+                    this.nextDispatchTimer = undefined;
+                    this.tryDispatch();
+                }, gap);
+                return;
+            }
+            const waiter = this.waiters.shift();
+            if (!waiter)
+                return;
+            if (waiter.signal && waiter.onAbort) {
+                waiter.signal.removeEventListener('abort', waiter.onAbort);
+            }
+            this.lastStartTime = Date.now();
+            this.inFlight += 1;
+            logger.debug(`Executing Europe PMC request via queue: ${waiter.label}`, requestContextService.createRequestContext({
+                operation: 'EuropePmcQueueDispatch',
+                label: waiter.label,
+                inFlight: this.inFlight,
+                queueDepth: this.waiters.length,
+            }));
+            Promise.resolve()
+                .then(() => waiter.task())
+                .then(waiter.resolve, (err) => {
+                logger.error('Error processing Europe PMC request from queue.', requestContextService.createRequestContext({
+                    operation: 'EuropePmcQueueProcess',
+                    label: waiter.label,
+                    errorMessage: err instanceof Error ? err.message : String(err),
+                }));
+                waiter.reject(err);
+            })
+                .finally(() => {
+                this.inFlight -= 1;
+                this.tryDispatch();
+            });
+        }
+    }
+}
+//# sourceMappingURL=request-queue.js.map

package/dist/services/europe-pmc/request-queue.js.map

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