@cyanheads/pubmed-mcp-server 2.10.14 → 2.10.16

package/dist/services/error-contracts.js

@@ -12,22 +12,28 @@
  *
  * Tool definitions import the contract arrays directly and spread them into
  * their `errors: [...]` declarations to surface the failure modes to the LLM.
+ * Every service-array entry carries `thrownBy: 'service'` so the linter's
+ * `error-contract-unthrown` check skips it while still checking the handler's
+ * own reasons. Spread a service array only into a tool whose handler lets that
+ * service's errors propagate — a tool that catches them all never produces
+ * those reasons.
  *
  * @module src/services/error-contracts
  */
 import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
 /**
- * Failure modes the NCBI service layer can surface. Tools that consume
- * `getNcbiService()` should spread these into their own `errors[]` so the
- * declared contract matches what actually reaches the wire.
+ * Failure modes the NCBI service layer can surface. Tools whose handler lets
+ * `getNcbiService()` failures propagate spread these into their own `errors[]`
+ * so the declared contract matches what actually reaches the wire.
  */
 export const NCBI_SERVICE_ERRORS = [
     {
         reason: 'queue_full',
         code: JsonRpcErrorCode.RateLimited,
-        when: 'Local NCBI request queue is at capacity.',
-        recovery: 'Retry after 1-2 seconds; the request queue hit the NCBI rate limit.',
+        when: 'The local NCBI request queue shed the call — the queue is full, or the call cannot start before its total deadline (for example behind the cooldown that follows an NCBI 429).',
+        recovery: 'Wait the number of seconds in `retryAfter`, then retry; the NCBI request queue is saturated or cooling down after a rate limit.',
         retryable: true,
+        thrownBy: 'service',
     },
     {
         reason: 'ncbi_unreachable',
@@ -35,6 +41,7 @@ export const NCBI_SERVICE_ERRORS = [
         when: 'NCBI E-utilities is unreachable after all retry attempts.',
         recovery: 'Retry after a brief delay; NCBI was unreachable across all retry attempts.',
         retryable: true,
+        thrownBy: 'service',
     },
     {
         reason: 'ncbi_deadline_exceeded',
@@ -42,6 +49,7 @@ export const NCBI_SERVICE_ERRORS = [
         when: 'Total request deadline expired before NCBI returned a response.',
         recovery: 'Reduce batch size or retry; NCBI may be under temporary load.',
         retryable: true,
+        thrownBy: 'service',
     },
     {
         reason: 'ncbi_invalid_response',
@@ -49,6 +57,7 @@ export const NCBI_SERVICE_ERRORS = [
         when: 'NCBI returned a body that could not be parsed (invalid XML/JSON).',
         recovery: 'Retry the request; NCBI returned a malformed response that could not be parsed.',
         retryable: true,
+        thrownBy: 'service',
     },
     {
         reason: 'ncbi_resource_not_found',
@@ -56,6 +65,7 @@ export const NCBI_SERVICE_ERRORS = [
         when: 'NCBI returned a structured "not found" error for the requested ID(s).',
         recovery: 'Verify the ID exists in PubMed; the resource was not found in NCBI and retrying will not help.',
         retryable: false,
+        thrownBy: 'service',
     },
 ];
 /**
@@ -73,8 +83,8 @@ export const NCBI_QUERY_INPUT_ERRORS = [
     {
         reason: 'blank_query',
         code: JsonRpcErrorCode.ValidationError,
-        when: 'The query holds no search term once whitespace, and any markup the tool strips first, are removed — so NCBI would receive a blank term.',
-        recovery: 'Supply a nonblank search term; NCBI cannot search a blank term and retrying the same input will not help.',
+        when: 'The query holds no search term once whitespace, and anything the tool strips before searching, are removed — so NCBI would receive a blank term. pubmed_search_articles strips markup, bracketed field tags, and parentheses, so a bare field tag such as `[pdat]` or empty parentheses `()` count as blank there.',
+        recovery: 'Supply a nonblank search term — a bare field tag or empty parentheses carry none; NCBI cannot search a blank term and retrying the same input will not help.',
         retryable: false,
     },
 ];
@@ -109,12 +119,13 @@ export const UNPAYWALL_SERVICE_ERRORS = [
         when: 'Unpaywall was unreachable when resolving a DOI or fetching content.',
         recovery: 'Retry after a brief delay; Unpaywall was unreachable. The PMC source remains the primary path.',
         retryable: true,
+        thrownBy: 'service',
     },
 ];
 /**
- * Failure modes the OpenAlex service layer can surface. Tools that consume
- * `getOpenAlexService()` / `getOpenAlexServiceOptional()` should spread
- * these into their `errors[]`.
+ * Failure modes the OpenAlex service layer can surface. Tools whose handler
+ * lets `getOpenAlexService()` / `getOpenAlexServiceOptional()` failures
+ * propagate spread these into their `errors[]`.
  */
 export const OPENALEX_SERVICE_ERRORS = [
     {
@@ -123,6 +134,7 @@ export const OPENALEX_SERVICE_ERRORS = [
         when: 'OpenAlex was unreachable after all retry attempts.',
         recovery: 'Retry after a brief delay; OpenAlex was unreachable. NCBI and Europe PMC remain available.',
         retryable: true,
+        thrownBy: 'service',
     },
     {
         reason: 'openalex_invalid_response',
@@ -130,19 +142,22 @@ export const OPENALEX_SERVICE_ERRORS = [
         when: 'OpenAlex returned a body that could not be parsed (invalid JSON).',
         recovery: 'Retry the request; OpenAlex returned a malformed response that could not be parsed.',
         retryable: true,
+        thrownBy: 'service',
     },
 ];
 /**
- * Failure modes the Europe PMC service layer can surface. Tools that consume
- * `getEuropePmcService()` should spread these into their `errors[]`.
+ * Failure modes the Europe PMC service layer can surface. Tools whose handler
+ * lets `getEuropePmcService()` failures propagate spread these into their
+ * `errors[]`.
  */
 export const EUROPEPMC_SERVICE_ERRORS = [
     {
         reason: 'europepmc_unreachable',
         code: JsonRpcErrorCode.ServiceUnavailable,
-        when: 'Europe PMC was unreachable after all retry attempts.',
+        when: 'Europe PMC failed on every retry attempt — unreachable, an HTTP 404 or 5xx other than a 504 timeout from its search endpoint, or an empty response with no results.',
         recovery: 'Retry after a brief delay; Europe PMC was unreachable. NCBI PMC and Unpaywall remain available.',
         retryable: true,
+        thrownBy: 'service',
     },
     {
         reason: 'europepmc_invalid_response',
@@ -150,13 +165,15 @@ export const EUROPEPMC_SERVICE_ERRORS = [
         when: 'Europe PMC returned a body that could not be parsed (invalid JSON or XML).',
         recovery: 'Retry the request; Europe PMC returned a malformed response that could not be parsed.',
         retryable: true,
+        thrownBy: 'service',
     },
     {
         reason: 'europepmc_invalid_input',
         code: JsonRpcErrorCode.ValidationError,
-        when: 'Europe PMC rejected the request input (empty query, unknown sort field, malformed parameter).',
-        recovery: 'Adjust the input — usually the query or sort field — before retrying; the same input will be rejected again.',
+        when: 'Europe PMC rejected the request input — an error message such as an empty query, an empty response to a sort with an undocumented field or no asc/desc direction, or an empty response to a pagination cursor on every attempt.',
+        recovery: 'Adjust the input — the query, the sort, or the cursorMark — before retrying; the same input will be rejected again.',
         retryable: false,
+        thrownBy: 'service',
     },
 ];
 const REASON_TO_RECOVERY = new Map([

package/dist/services/error-contracts.js.map

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

package/dist/services/europe-pmc/api-client.d.ts

@@ -1,7 +1,11 @@
 /**
- * @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`.
+ * @fileoverview Low-level HTTP client for Europe PMC's REST API. Builds URLs and
+ * the source-filtered search query (`buildSearchQuery`, shared with the service
+ * so it can report the query it sent), injects the optional contact email, and
+ * exposes single-attempt search, fullTextXML, and citation-link calls.
+ * Classifies each endpoint's HTTP failures — a failed search as
+ * `europepmc_unreachable`, a missing fullTextXML as `not-available` — while
+ * retry logic lives in `EuropePmcService`.
  * @module src/services/europe-pmc/api-client
  */
 import { type EuropePmcSearchParams } from './types.js';
@@ -36,6 +40,16 @@ export declare class EuropePmcApiClient {
      * 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.
+     *
+     * A failed `/search` is an outage, never "no match" — a genuine zero-hit
+     * query is HTTP 200 with `hitCount: 0`. A 404 is reclassified from its
+     * status-mapped `NotFound` to `ServiceUnavailable` so the service retries it.
+     * A retryable 5xx keeps its code, so a 504 stays `Timeout`. Only a failure
+     * that ends up `ServiceUnavailable` carries `europepmc_unreachable` and its
+     * recovery hint, the one code that reason is declared for. An upstream
+     * `retryAfter` is kept. A 429 and every other 4xx pass through unchanged, as
+     * does a 501, whose `data.retryable: false` keeps it out of the retry loop.
+     * (#152)
      */
     search(params: EuropePmcSearchParams): Promise<string>;
     /**
@@ -64,11 +78,12 @@ export declare class EuropePmcApiClient {
     /** Helper: fetch a links (citations/references) JSON URL and return the body. */
     private fetchLinksJson;
     private buildSearchUrl;
-    /**
-     * 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.
-     */
-    private buildQueryString;
 }
+/**
+ * The query string a search sends: the caller's query combined with an
+ * optional source filter. EPMC's query syntax supports `SRC:"X"` field tokens —
+ * the requested sources are OR-joined into a parenthesized clause and ANDed
+ * with the caller's query.
+ */
+export declare function buildSearchQuery(params: Pick<EuropePmcSearchParams, 'query' | 'sources'>): string;
 //# sourceMappingURL=api-client.d.ts.map

package/dist/services/europe-pmc/api-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../../../src/services/europe-pmc/api-client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,EAAsB,KAAK,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAI5E,MAAM,WAAW,wBAAwB;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,MAAM,4BAA4B,GACpC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9C;;;;;;;;GAQG;AACH,qBAAa,kBAAkB;IACjB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAAnC,YAA6B,MAAM,EAAE,wBAAwB,EAAI;IAEjE;;;;OAIG;IACG,MAAM,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,MAAM,CAAC,CAwB3D;IAED;;;;;;;;;OASG;IACG,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,4BAA4B,CAAC,CA4C7F;IAED;;;;OAIG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAG7F;IAED;;;;OAIG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAG9F;IAED,iFAAiF;YACnE,cAAc;IA8B5B,OAAO,CAAC,cAAc;IActB;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;CAMzB"}
+{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../../../src/services/europe-pmc/api-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,OAAO,EAAsB,KAAK,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAI5E,MAAM,WAAW,wBAAwB;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,MAAM,4BAA4B,GACpC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9C;;;;;;;;GAQG;AACH,qBAAa,kBAAkB;IACjB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAAnC,YAA6B,MAAM,EAAE,wBAAwB,EAAI;IAEjE;;;;;;;;;;;;;;OAcG;IACG,MAAM,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,MAAM,CAAC,CA4C3D;IAED;;;;;;;;;OASG;IACG,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,4BAA4B,CAAC,CA4C7F;IAED;;;;OAIG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAG7F;IAED;;;;OAIG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAG9F;IAED,iFAAiF;YACnE,cAAc;IA8B5B,OAAO,CAAC,cAAc;CAavB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,IAAI,CAAC,qBAAqB,EAAE,OAAO,GAAG,SAAS,CAAC,GAAG,MAAM,CAKjG"}

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

@@ -1,7 +1,11 @@
 /**
- * @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`.
+ * @fileoverview Low-level HTTP client for Europe PMC's REST API. Builds URLs and
+ * the source-filtered search query (`buildSearchQuery`, shared with the service
+ * so it can report the query it sent), injects the optional contact email, and
+ * exposes single-attempt search, fullTextXML, and citation-link calls.
+ * Classifies each endpoint's HTTP failures — a failed search as
+ * `europepmc_unreachable`, a missing fullTextXML as `not-available` — while
+ * retry logic lives in `EuropePmcService`.
  * @module src/services/europe-pmc/api-client
  */
 import { JsonRpcErrorCode, McpError, serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
@@ -27,6 +31,16 @@ export class EuropePmcApiClient {
      * 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.
+     *
+     * A failed `/search` is an outage, never "no match" — a genuine zero-hit
+     * query is HTTP 200 with `hitCount: 0`. A 404 is reclassified from its
+     * status-mapped `NotFound` to `ServiceUnavailable` so the service retries it.
+     * A retryable 5xx keeps its code, so a 504 stays `Timeout`. Only a failure
+     * that ends up `ServiceUnavailable` carries `europepmc_unreachable` and its
+     * recovery hint, the one code that reason is declared for. An upstream
+     * `retryAfter` is kept. A 429 and every other 4xx pass through unchanged, as
+     * does a 501, whose `data.retryable: false` keeps it out of the retry loop.
+     * (#152)
      */
     async search(params) {
         const url = this.buildSearchUrl(params);
@@ -42,8 +56,22 @@ export class EuropePmcApiClient {
             });
         }
         catch (error) {
-            if (error instanceof McpError)
-                throw error;
+            if (error instanceof McpError) {
+                const status = error.data?.status;
+                const isOutage = status === 404 ||
+                    (typeof status === 'number' && status >= 500 && error.data?.retryable !== false);
+                if (!isOutage)
+                    throw error;
+                const code = status === 404 ? JsonRpcErrorCode.ServiceUnavailable : error.code;
+                throw new McpError(code, `Europe PMC search request failed: ${error.message}`, {
+                    ...(code === JsonRpcErrorCode.ServiceUnavailable && {
+                        reason: 'europepmc_unreachable',
+                        ...recoveryFor('europepmc_unreachable'),
+                    }),
+                    status,
+                    ...(error.data?.retryAfter !== undefined && { retryAfter: error.data.retryAfter }),
+                }, { cause: 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 });
         }
@@ -137,7 +165,7 @@ export class EuropePmcApiClient {
     }
     buildSearchUrl(params) {
         const finalParams = {
-            query: this.buildQueryString(params),
+            query: buildSearchQuery(params),
             format: 'json',
             resultType: params.resultType ?? 'core',
             pageSize: String(params.pageSize ?? 25),
@@ -149,17 +177,18 @@ export class EuropePmcApiClient {
             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})`;
-    }
+}
+/**
+ * The query string a search sends: the caller's query combined with an
+ * optional source filter. EPMC's query syntax supports `SRC:"X"` field tokens —
+ * the requested sources are OR-joined into a parenthesized clause and ANDed
+ * with the caller's query.
+ */
+export function buildSearchQuery(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

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

@@ -7,6 +7,12 @@
  * from the same `ORDERED_XML_PARSER_OPTIONS` NCBI's ordered parser uses, so
  * `parsePmcArticle` consumes the result without modification.
  *
+ * A search's retry boundary covers fetch and response classification, so
+ * Europe PMC's intermittent empty `{ version }` envelope is retried like an
+ * HTTP outage; only a sort or cursor that explains it is reported as bad input.
+ * A search reports the effective query Europe PMC echoes back, or — with no
+ * echo — the source-filtered query it sent.
+ *
  * Optional service: only constructed when `EUROPEPMC_ENABLED=true` (the
  * default). `getEuropePmcService()` returns `undefined` when disabled so
  * callers can skip the chain step gracefully.
@@ -36,8 +42,18 @@ export declare class EuropePmcService {
     /**
      * Search Europe PMC. Cursor-based pagination — pass `cursorMark: '*'` (or
      * omit) for the first page; pass the returned `nextCursorMark` for the next.
+     *
+     * The retry boundary covers the fetch and the response classification
+     * together, so an empty envelope retries like any other transient failure
+     * rather than surfacing after the loop has already returned. (#159)
      */
     search(params: EuropePmcSearchParams): Promise<EuropePmcSearchResult>;
+    /**
+     * One search attempt: fetch, parse, and classify the body. `isLastAttempt`
+     * lets an empty envelope that has persisted through the whole retry budget
+     * be attributed to a caller-supplied cursor.
+     */
+    private searchOnce;
     /**
      * Look up specific records by `source` + EPMC id. One search request covers
      * the whole batch: each ref becomes a `recordLookupQuery` clause, OR-joined
@@ -103,7 +119,12 @@ export declare class EuropePmcService {
     /**
      * 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.
+     * caller (typically `ctx.signal`) bounds the total chain. `execute` receives
+     * the zero-based attempt index. On exhaustion the last error keeps its code
+     * and an upstream `retryAfter`, so a 429 still tells the caller how long to
+     * wait. Only a `ServiceUnavailable` gains `europepmc_unreachable` and its hint;
+     * a `Timeout` or `RateLimited` keeps its code with no reason, as the NCBI
+     * service reports them.
      */
     private withRetry;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"europe-pmc-service.d.ts","sourceRoot":"","sources":["../../../src/services/europe-pmc/europe-pmc-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAeH,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,kBAAkB,EAElB,sBAAsB,EACtB,kBAAkB,EAClB,qBAAqB,EAErB,qBAAqB,EACrB,eAAe,EAChB,MAAM,YAAY,CAAC;AA2CpB;;;;;;;;;GASG;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;IAE7C,YACmB,MAAM,EAAE,kBAAkB,EAC1B,KAAK,EAAE,qBAAqB,EAC5B,UAAU,EAAE,MAAM,EAQpC;IAED;;;OAGG;IACG,MAAM,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CA6F1E;IAED;;;;;;;;;;OAUG;IACG,YAAY,CAChB,IAAI,EAAE,SAAS,kBAAkB,EAAE,EACnC,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAQ/B;IAED;;;;;;;OAOG;IACG,WAAW,CACf,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,eAAe,EACvB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,uBAAuB,CAAC,CAgBlC;IAED;;;;;;;;;;OAUG;IACH,SAAS,CACP,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,sBAAsB,CAAC,CAQjC;IAED;;;;;;;;;;OAUG;IACH,UAAU,CACR,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,sBAAsB,CAAC,CAQjC;IAED;;;;;OAKG;YACW,iBAAiB;IAsE/B;;;;;;;;OAQG;IACH,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CA8BlD;IAED;;;;OAIG;YACW,SAAS;CAoDxB;AAMD;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAyB3C;AAED,6EAA6E;AAC7E,wBAAgB,mBAAmB,IAAI,gBAAgB,GAAG,SAAS,CAElE"}
+{"version":3,"file":"europe-pmc-service.d.ts","sourceRoot":"","sources":["../../../src/services/europe-pmc/europe-pmc-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAiBH,OAAO,KAAK,EAAE,QAAQ,EAAgB,MAAM,4CAA4C,CAAC;AAEzF,OAAO,EAAoB,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACvE,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EACV,uBAAuB,EAEvB,kBAAkB,EAElB,sBAAsB,EACtB,kBAAkB,EAClB,qBAAqB,EAErB,qBAAqB,EACrB,eAAe,EAChB,MAAM,YAAY,CAAC;AAqEpB;;;;;;;;;GASG;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;IAE7C,YACmB,MAAM,EAAE,kBAAkB,EAC1B,KAAK,EAAE,qBAAqB,EAC5B,UAAU,EAAE,MAAM,EAQpC;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAWpE;IAED;;;;OAIG;YACW,UAAU;IAwHxB;;;;;;;;;;OAUG;IACG,YAAY,CAChB,IAAI,EAAE,SAAS,kBAAkB,EAAE,EACnC,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAQ/B;IAED;;;;;;;OAOG;IACG,WAAW,CACf,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,eAAe,EACvB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,uBAAuB,CAAC,CAgBlC;IAED;;;;;;;;;;OAUG;IACH,SAAS,CACP,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,sBAAsB,CAAC,CAQjC;IAED;;;;;;;;;;OAUG;IACH,UAAU,CACR,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,sBAAsB,CAAC,CAQjC;IAED;;;;;OAKG;YACW,iBAAiB;IAsE/B;;;;;;;;OAQG;IACH,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CA8BlD;IAED;;;;;;;;;OASG;YACW,SAAS;CAkDxB;AAMD;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAyB3C;AAED,6EAA6E;AAC7E,wBAAgB,mBAAmB,IAAI,gBAAgB,GAAG,SAAS,CAElE"}

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

@@ -7,13 +7,19 @@
  * from the same `ORDERED_XML_PARSER_OPTIONS` NCBI's ordered parser uses, so
  * `parsePmcArticle` consumes the result without modification.
  *
+ * A search's retry boundary covers fetch and response classification, so
+ * Europe PMC's intermittent empty `{ version }` envelope is retried like an
+ * HTTP outage; only a sort or cursor that explains it is reported as bad input.
+ * A search reports the effective query Europe PMC echoes back, or — with no
+ * echo — the source-filtered query it sent.
+ *
  * 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, McpError, serializationError, validationError, } from '@cyanheads/mcp-ts-core/errors';
+import { internalError, JsonRpcErrorCode, McpError, serializationError, serviceUnavailable, validationError, } from '@cyanheads/mcp-ts-core/errors';
 import { defaultIsTransient, logger, requestContextService } from '@cyanheads/mcp-ts-core/utils';
 // biome-ignore lint/suspicious/noDeprecatedImports: staying on in-tree XMLValidator — see ncbi/response-handler.ts
 import { XMLParser, XMLValidator } from 'fast-xml-parser';
@@ -21,7 +27,7 @@ import { getServerConfig } from '../../config/server-config.js';
 import { recoveryFor } from '../error-contracts.js';
 import { ORDERED_XML_PARSER_OPTIONS } from '../ncbi/parsing/ordered-xml-parser-options.js';
 import { ensureArray } from '../ncbi/parsing/xml-helpers.js';
-import { EuropePmcApiClient } from './api-client.js';
+import { buildSearchQuery, EuropePmcApiClient } from './api-client.js';
 import { EuropePmcRequestQueue } from './request-queue.js';
 const MAX_BACKOFF_MS = 30_000;
 function abortableSleep(ms, signal) {
@@ -63,6 +69,28 @@ function recordLookupQuery({ epmcId, source }) {
     const extIdClause = `(EXT_ID:${epmcId} AND SRC:${source})`;
     return source === 'PMC' ? `${extIdClause} OR (PMCID:${epmcId})` : extIdClause;
 }
+/** The sort fields Europe PMC documents. */
+const DOCUMENTED_SORT_FIELDS = new Set(['P_PDATE_D', 'CITED', 'AUTH_FIRST', 'PUB_YEAR']);
+/**
+ * Whether a sort is the likely cause of an empty `{ version }` envelope: one of
+ * its comma-separated keys has a field outside the documented set, or lacks an
+ * `asc`/`desc` direction. Europe PMC answers those shapes with the envelope on
+ * every request, and orders by every key of a valid list (`PUB_YEAR desc, CITED
+ * desc`). Field and direction compare case-insensitively and tolerate extra
+ * whitespace, matching Europe PMC's own parsing.
+ *
+ * Classification only, never a local allowlist: the request always goes out.
+ * Europe PMC honors some undocumented fields (`ID asc` reorders results) and
+ * silently ignores others (`SCORE desc`), so only the envelope itself decides.
+ */
+function sortExplainsEnvelope(sort) {
+    return sort.split(',').some((key) => {
+        const [field = '', direction = '', ...rest] = key.trim().split(/\s+/);
+        return (rest.length > 0 ||
+            !DOCUMENTED_SORT_FIELDS.has(field.toUpperCase()) ||
+            !/^(asc|desc)$/i.test(direction));
+    });
+}
 /**
  * Facade over the Europe PMC REST API:
  *   - `search()` — keyword search across MED/PMC/PPR/PAT/AGR.
@@ -92,9 +120,21 @@ export class EuropePmcService {
     /**
      * Search Europe PMC. Cursor-based pagination — pass `cursorMark: '*'` (or
      * omit) for the first page; pass the returned `nextCursorMark` for the next.
+     *
+     * The retry boundary covers the fetch and the response classification
+     * together, so an empty envelope retries like any other transient failure
+     * rather than surfacing after the loop has already returned. (#159)
      */
-    async search(params) {
-        const text = await this.queue.enqueue(() => this.withRetry(() => this.client.search(params), 'search', params.signal), 'search', params.signal);
+    search(params) {
+        return this.queue.enqueue(() => this.withRetry((attempt) => this.searchOnce(params, attempt === this.maxRetries), 'search', params.signal), 'search', params.signal);
+    }
+    /**
+     * One search attempt: fetch, parse, and classify the body. `isLastAttempt`
+     * lets an empty envelope that has persisted through the whole retry budget
+     * be attributed to a caller-supplied cursor.
+     */
+    async searchOnce(params, isLastAttempt) {
+        const text = await this.client.search(params);
         let parsed;
         try {
             parsed = JSON.parse(text);
@@ -121,40 +161,56 @@ export class EuropePmcService {
             });
         }
         /**
-         * EPMC silently returns a `{ version }`-only envelope (no `hitCount`, no
-         * `request` echo, no `resultList`) when it rejects a parameter — most
-         * commonly an undocumented `sort` field. Without this guard the response
-         * normalizes to a fake 0-hit success and the caller never learns the sort
-         * was rejected. Route to ValidationError (non-retryable) since retrying
-         * the same input will be rejected again.
+         * EPMC answers some requests with a `{ version }`-only envelope — no
+         * `hitCount`, no `request` echo, no `resultList`. Without this guard the
+         * response normalizes to a fake 0-hit success. Every cause produces the
+         * byte-identical body, so it is classified by its likely cause:
+         *
+         * - A sort that EPMC rejects every time (see `sortExplainsEnvelope`) fails
+         *   fast as non-retryable input — retrying only adds backoff.
+         * - A non-default cursor that draws it on every attempt is most likely
+         *   invalid or expired; EPMC rejects a malformed cursor every time.
+         * - Otherwise it is intermittent upstream noise — valid requests, with or
+         *   without a documented sort, draw it on a fraction of calls and succeed
+         *   when repeated — so it is thrown as a transient `europepmc_unreachable`
+         *   for the retry loop, and never names the caller's input. (#159)
+         *
+         * Each throw keeps the diagnosis (message) apart from the next step
+         * (recovery hint): the framework mirrors `data.recovery.hint` into
+         * `content[]`, and one string passed as both renders byte-identical
+         * Error:/Recovery: blocks. (#75)
          */
         if (parsed.hitCount === undefined &&
             parsed.request === undefined &&
             parsed.resultList === undefined) {
-            // Split the diagnosis (message) from the actionable next step (recovery
-            // hint). The framework mirrors data.recovery.hint into content[], so
-            // passing one string as both renders byte-identical Error:/Recovery:
-            // blocks — the same distinct message-vs-hint shape as the errMsg throw
-            // ~20 lines up. (#75)
-            const { message, hint } = params.sort
-                ? {
-                    message: `Europe PMC silently rejected the request — most likely the invalid sort field "${params.sort}".`,
-                    hint: 'Use a documented sort (`P_PDATE_D desc`, `CITED desc`, `AUTH_FIRST asc`, or `PUB_YEAR desc`), or omit `sort` for relevance ranking.',
-                }
-                : {
-                    message: 'Europe PMC silently rejected the request — empty envelope with no hitCount.',
-                    hint: 'Verify the query syntax, sort field, and cursorMark, then retry.',
-                };
-            throw validationError(message, {
-                reason: 'europepmc_invalid_input',
-                ...(params.sort && { sort: params.sort }),
-                ...(params.cursorMark && params.cursorMark !== '*' && { cursorMark: params.cursorMark }),
-                responseSnippet: text.substring(0, 200),
-                recovery: { hint },
-            });
+            const cursorMark = params.cursorMark && params.cursorMark !== '*' ? params.cursorMark : undefined;
+            if (params.sort && sortExplainsEnvelope(params.sort)) {
+                throw validationError(`Europe PMC silently rejected the request — most likely the sort "${params.sort}", which needs a documented field and an asc/desc direction.`, {
+                    reason: 'europepmc_invalid_input',
+                    sort: params.sort,
+                    ...(cursorMark && { cursorMark }),
+                    responseSnippet: text.substring(0, 200),
+                    recovery: {
+                        hint: 'Use a documented sort (`P_PDATE_D desc`, `CITED desc`, `AUTH_FIRST asc`, or `PUB_YEAR desc`), or omit `sort` for relevance ranking.',
+                    },
+                });
+            }
+            if (cursorMark && isLastAttempt) {
+                throw validationError(`Europe PMC answered every attempt for cursorMark "${cursorMark}" with an empty response — the cursor is most likely invalid or expired.`, {
+                    reason: 'europepmc_invalid_input',
+                    cursorMark,
+                    responseSnippet: text.substring(0, 200),
+                    recovery: {
+                        hint: 'Restart from the first page with `cursorMark: "*"`, or pass the exact `nextCursorMark` from the previous response.',
+                    },
+                });
+            }
+            throw serviceUnavailable('Europe PMC returned an empty response with no hit count or result list.', { reason: 'europepmc_unreachable', ...recoveryFor('europepmc_unreachable') });
         }
         const hits = ensureArray(parsed.resultList?.result);
-        const echoed = parsed.request?.queryString ?? params.query;
+        // Without an echo, report the query actually sent — source filter included —
+        // not the caller's bare query, which searches every source. (#150)
+        const echoed = parsed.request?.queryString ?? buildSearchQuery(params);
         // EPMC's `request.cursorMark` echo is URL-encoded (the wire form), while
         // `nextCursorMark` in the JSON body is raw. Use the caller's input as the
         // current cursor so the echo is consistent and the equality check below
@@ -331,14 +387,19 @@ export class EuropePmcService {
     /**
      * 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.
+     * caller (typically `ctx.signal`) bounds the total chain. `execute` receives
+     * the zero-based attempt index. On exhaustion the last error keeps its code
+     * and an upstream `retryAfter`, so a 429 still tells the caller how long to
+     * wait. Only a `ServiceUnavailable` gains `europepmc_unreachable` and its hint;
+     * a `Timeout` or `RateLimited` keeps its code with no reason, as the NCBI
+     * service reports them.
      */
     async withRetry(execute, label, signal) {
         for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
             if (signal?.aborted)
                 throw signal.reason;
             try {
-                return await execute();
+                return await execute(attempt);
             }
             catch (error) {
                 if (signal?.aborted)
@@ -359,20 +420,18 @@ export class EuropePmcService {
                     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',
+                throw new McpError(error.code, `${error.message} (failed after ${attempts} attempts)`, {
+                    ...(error.code === JsonRpcErrorCode.ServiceUnavailable && {
+                        reason: 'europepmc_unreachable',
+                        ...recoveryFor('europepmc_unreachable'),
+                    }),
                     label,
                     attempts,
-                    ...recoveryFor('europepmc_unreachable'),
+                    ...(error.data?.retryAfter !== undefined && { retryAfter: error.data.retryAfter }),
                 }, { cause: error });
             }
         }
-        throw internalError('Europe PMC request failed after all retries.', {
-            reason: 'europepmc_unreachable',
-            label,
-            ...recoveryFor('europepmc_unreachable'),
-        });
+        throw internalError('Europe PMC request failed after all retries.', { label });
     }
 }
 // ─── Init / Accessor ────────────────────────────────────────────────────────