@cyanheads/pubmed-mcp-server
Version:
Search PubMed/Europe PMC, fetch articles and full text (PMC/EPMC/Unpaywall), citations, MeSH terms via MCP. STDIO or Streamable HTTP.
73 lines • 4.13 kB
TypeScript
/**
* @fileoverview High-level service for interacting with NCBI E-utilities.
* Orchestrates the API client, request queue, and response handler to provide
* typed methods for each E-utility endpoint. Uses init/accessor pattern.
* @module src/services/ncbi/ncbi-service
*/
import { NcbiApiClient } from './api-client.js';
import { NcbiRequestQueue } from './request-queue.js';
import { NcbiResponseHandler } from './response-handler.js';
import { type ECitMatchCitation, type ECitMatchResult, type ESearchResult, type ESpellResult, type ESummaryResult, type IdConvertRecord, type NcbiCallOptions, type NcbiRequestOptions, type NcbiRequestParams, type XmlPubmedArticleSet } from './types.js';
/**
* Facade over NCBI's E-utility suite. Each public method corresponds to a
* single E-utility endpoint.
*/
export declare class NcbiService {
private readonly apiClient;
private readonly queue;
private readonly responseHandler;
private readonly maxRetries;
private readonly totalDeadlineMs;
constructor(apiClient: NcbiApiClient, queue: NcbiRequestQueue, responseHandler: NcbiResponseHandler, maxRetries: number, totalDeadlineMs: number);
eSearch(params: NcbiRequestParams, options?: NcbiCallOptions): Promise<ESearchResult>;
eSummary(params: NcbiRequestParams, options?: NcbiCallOptions): Promise<ESummaryResult>;
eFetch<T = {
PubmedArticleSet?: XmlPubmedArticleSet;
}>(params: NcbiRequestParams, options?: NcbiRequestOptions): Promise<T>;
eLink<T = Record<string, unknown>>(params: NcbiRequestParams, options?: NcbiCallOptions): Promise<T>;
eSpell(params: NcbiRequestParams, options?: NcbiCallOptions): Promise<ESpellResult>;
eInfo(params: NcbiRequestParams, options?: NcbiCallOptions): Promise<unknown>;
/**
* Look up PMIDs from partial citation strings via NCBI ECitMatch.
* Each citation can include journal, year, volume, first page, and author name.
*/
eCitMatch(citations: ECitMatchCitation[], options?: NcbiCallOptions): Promise<ECitMatchResult[]>;
/**
* Convert between article identifiers (DOI, PMID, PMCID) using the PMC ID Converter API.
* Accepts up to 200 IDs in a single request. Only works for articles in PMC.
*/
idConvert(ids: string[], idtype?: string, options?: NcbiCallOptions): Promise<IdConvertRecord[]>;
/** Error codes that are transient and worth retrying with backoff. */
private static readonly RETRYABLE_CODES;
/** Maximum backoff delay per retry (prevents exponential explosion at high retry counts). */
private static readonly MAX_BACKOFF_MS;
/**
* Wraps a task with a service-level deadline. Returns a combined AbortSignal
* (internal deadline OR'd with the caller's `ctx.signal`, if any) that the
* task must forward to both the HTTP call and any backoff sleep so cancellation
* interrupts the full retry chain — not just the next attempt.
*/
private runWithDeadline;
/**
* Retry wrapper for transient NCBI errors (ServiceUnavailable, Timeout, RateLimited).
* Non-transient McpErrors and unexpected plain Errors fail immediately.
* Uses capped exponential backoff with jitter. Backoff sleep is abortable via
* `signal`, so deadline expiration or caller cancel short-circuits the chain.
*/
private withRetry;
/**
* Runs a request under a service-level deadline that bounds queue wait time
* + retry chain + HTTP execution. The deadline is constructed *outside* the
* queue so a backlog can't burn a request's budget before it even dispatches.
*
* The combined deadline+caller signal is threaded into the queue (cancels a
* still-waiting task), the retry chain (cancels pending backoff sleeps),
* and the HTTP fetch (cancels wedged requests).
*/
private performRequest;
}
/** Initialize the NCBI service. Call from `setup()` in createApp. */
export declare function initNcbiService(): void;
/** Get the initialized NCBI service. Throws if not initialized. */
export declare function getNcbiService(): NcbiService;
//# sourceMappingURL=ncbi-service.d.ts.map