@cyanheads/pubmed-mcp-server 2.8.0 → 2.9.0

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

@@ -0,0 +1,174 @@
+/**
+ * @fileoverview Low-level HTTP client for the OpenAlex API. Builds URLs,
+ * injects the optional polite-pool email, and exposes single-attempt fetch
+ * calls. Retry logic lives in `OpenAlexService`.
+ * @module src/services/openalex/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 { OPENALEX_API_BASE } 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. */
+export class OpenAlexApiClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Fetch a single work by PMID. Returns the work record (with related_works
+     * and referenced_works populated) or null when the PMID is unknown.
+     */
+    async getWorkByPmid(pmid, signal) {
+        const params = new URLSearchParams({
+            select: 'id,related_works,referenced_works',
+        });
+        if (this.config.email)
+            params.set('mailto', this.config.email);
+        const url = `${OPENALEX_API_BASE}/works/pmid:${encodeURIComponent(pmid)}?${params.toString()}`;
+        const ctx = requestContextService.createRequestContext({
+            operation: 'OpenAlexGetWorkByPmid',
+            pmid,
+        });
+        let response;
+        try {
+            response = await fetchWithTimeout(url, this.config.timeoutMs, ctx, {
+                headers: { Accept: 'application/json', '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(`OpenAlex request failed: ${msg}`, { reason: 'openalex_unreachable', ...recoveryFor('openalex_unreachable') }, { cause: error });
+        }
+        if (response.status === 404)
+            return null;
+        if (!response.ok) {
+            throw await httpErrorFromResponse(response, {
+                service: 'OpenAlex',
+                data: { url, reason: 'openalex_unreachable', ...recoveryFor('openalex_unreachable') },
+            });
+        }
+        const text = await response.text();
+        try {
+            return JSON.parse(text);
+        }
+        catch (error) {
+            throw serviceUnavailable('OpenAlex returned a non-JSON body.', { reason: 'openalex_invalid_response', ...recoveryFor('openalex_invalid_response') }, { cause: error });
+        }
+    }
+    /**
+     * 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.
+     */
+    resolveOaIdsToPmids(oaIds, signal) {
+        if (oaIds.length === 0)
+            return Promise.resolve([]);
+        // Strip https://openalex.org/ prefix if present — filter expects bare IDs
+        const bareIds = oaIds.map((id) => id.startsWith('https://openalex.org/') ? id.slice('https://openalex.org/'.length) : id);
+        const params = new URLSearchParams({
+            filter: `openalex:${bareIds.join('|')}`,
+            select: 'id,ids',
+            per_page: String(Math.min(oaIds.length, 200)),
+        });
+        if (this.config.email)
+            params.set('mailto', this.config.email);
+        const url = `${OPENALEX_API_BASE}/works?${params.toString()}`;
+        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.
+     */
+    async getCitedBy(oaId, perPage, signal) {
+        // Strip full URL prefix if needed
+        const bareId = oaId.startsWith('https://openalex.org/')
+            ? oaId.slice('https://openalex.org/'.length)
+            : oaId;
+        const params = new URLSearchParams({
+            filter: `cites:${bareId}`,
+            select: 'id,ids',
+            per_page: String(Math.min(perPage, 200)),
+        });
+        if (this.config.email)
+            params.set('mailto', this.config.email);
+        const url = `${OPENALEX_API_BASE}/works?${params.toString()}`;
+        const ctx = requestContextService.createRequestContext({
+            operation: 'OpenAlexGetCitedBy',
+            oaId: bareId,
+        });
+        let response;
+        try {
+            response = await fetchWithTimeout(url, this.config.timeoutMs, ctx, {
+                headers: { Accept: 'application/json', '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(`OpenAlex request failed: ${msg}`, { reason: 'openalex_unreachable', ...recoveryFor('openalex_unreachable') }, { cause: error });
+        }
+        if (!response.ok) {
+            throw await httpErrorFromResponse(response, {
+                service: 'OpenAlex',
+                data: { url, reason: 'openalex_unreachable', ...recoveryFor('openalex_unreachable') },
+            });
+        }
+        const text = await response.text();
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch (error) {
+            throw serviceUnavailable('OpenAlex returned a non-JSON body.', { reason: 'openalex_invalid_response', ...recoveryFor('openalex_invalid_response') }, { cause: error });
+        }
+        logger.debug('OpenAlex cited_by response', requestContextService.createRequestContext({
+            operation: 'OpenAlexGetCitedByDone',
+            oaId: bareId,
+            totalCount: parsed.meta?.count,
+            resultCount: parsed.results?.length,
+        }));
+        return {
+            works: parsed.results ?? [],
+            totalCount: parsed.meta?.count ?? 0,
+        };
+    }
+    /** Helper: fetch a /works?... URL and return parsed results. */
+    async fetchWorksList(url, operation, signal) {
+        const ctx = requestContextService.createRequestContext({ operation });
+        let response;
+        try {
+            response = await fetchWithTimeout(url, this.config.timeoutMs, ctx, {
+                headers: { Accept: 'application/json', '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(`OpenAlex request failed: ${msg}`, { reason: 'openalex_unreachable', ...recoveryFor('openalex_unreachable') }, { cause: error });
+        }
+        if (!response.ok) {
+            throw await httpErrorFromResponse(response, {
+                service: 'OpenAlex',
+                data: { url, reason: 'openalex_unreachable', ...recoveryFor('openalex_unreachable') },
+            });
+        }
+        const text = await response.text();
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch (error) {
+            throw serviceUnavailable('OpenAlex returned a non-JSON body.', { reason: 'openalex_invalid_response', ...recoveryFor('openalex_invalid_response') }, { cause: error });
+        }
+        return parsed.results ?? [];
+    }
+}
+//# sourceMappingURL=api-client.js.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,59 @@
+/**
+ * @fileoverview OpenAlex service for related-article fallback in `pubmed_find_related`.
+ * Provides three capabilities that mirror the NCBI eLink relationships:
+ *   - `similar(pmid, n)`: related_works → PMIDs (mirrors pubmed_pubmed)
+ *   - `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.
+ * 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';
+/** Service facade over the OpenAlex API for the find-related provider chain. */
+export declare class OpenAlexService {
+    private readonly client;
+    private readonly maxRetries;
+    constructor(client: OpenAlexApiClient, maxRetries: number);
+    /**
+     * 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).
+     */
+    similar(pmid: string, n: number, signal?: AbortSignal): Promise<{
+        pmids: string[];
+        totalCount: number;
+    }>;
+    /**
+     * Find works that cite the given PMID via OpenAlex `cites:W<id>` filter.
+     * Returns PMIDs only; drops any record with no PMID.
+     */
+    citedBy(pmid: string, n: number, signal?: AbortSignal): Promise<{
+        pmids: string[];
+        totalCount: number;
+    }>;
+    /**
+     * 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;
+    }>;
+    /**
+     * Extract unique numeric PMIDs from a list of works, excluding the source PMID.
+     * Any work with no PMID is silently dropped (never minted).
+     */
+    private extractPmids;
+    /** Retry wrapper for transient errors, mirroring the EPMC service pattern. */
+    private withRetry;
+}
+/** Initialize the OpenAlex service. Call from `setup()` in createApp. */
+export declare function initOpenAlexService(): void;
+/** Get the initialized OpenAlex service. Throws if not initialized. */
+export declare function getOpenAlexService(): OpenAlexService;
+/** Returns the service if initialized, undefined otherwise (for optional use). */
+export declare function getOpenAlexServiceOptional(): OpenAlexService | undefined;
+//# sourceMappingURL=openalex-service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"openalex-service.d.ts","sourceRoot":"","sources":["../../../src/services/openalex/openalex-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAOH,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAyCpD,gFAAgF;AAChF,qBAAa,eAAe;IAExB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU;gBADV,MAAM,EAAE,iBAAiB,EACzB,UAAU,EAAE,MAAM;IAGrC;;;;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;IAqBnD;;;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;IAkBnD;;;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;IAqBnD;;;OAGG;IACH,OAAO,CAAC,YAAY;IAYpB,8EAA8E;YAChE,SAAS;CAqDxB;AAMD,yEAAyE;AACzE,wBAAgB,mBAAmB,IAAI,IAAI,CAiB1C;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

@@ -0,0 +1,195 @@
+/**
+ * @fileoverview OpenAlex service for related-article fallback in `pubmed_find_related`.
+ * Provides three capabilities that mirror the NCBI eLink relationships:
+ *   - `similar(pmid, n)`: related_works → PMIDs (mirrors pubmed_pubmed)
+ *   - `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.
+ * 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 { internalError, JsonRpcErrorCode, McpError } from '@cyanheads/mcp-ts-core/errors';
+import { logger, requestContextService } from '@cyanheads/mcp-ts-core/utils';
+import { getServerConfig } from '../../config/server-config.js';
+import { recoveryFor } from '../../services/error-contracts.js';
+import { OpenAlexApiClient } from './api-client.js';
+/** Transient codes eligible for retry. */
+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 });
+    });
+}
+/**
+ * Extract a PMID string from an OpenAlex Work record's `ids.pmid` field.
+ * OpenAlex encodes PMIDs as full URLs: "https://pubmed.ncbi.nlm.nih.gov/31295471"
+ * This normalizes to the bare numeric string. Returns null when absent.
+ */
+function extractPmid(work) {
+    const raw = work.ids?.pmid;
+    if (!raw)
+        return null;
+    // Strip URL prefix if present (e.g. "https://pubmed.ncbi.nlm.nih.gov/31295471")
+    const match = /(\d+)\s*$/.exec(raw);
+    return match?.[1] ?? null;
+}
+/** Service facade over the OpenAlex API for the find-related provider chain. */
+export class OpenAlexService {
+    client;
+    maxRetries;
+    constructor(client, maxRetries) {
+        this.client = client;
+        this.maxRetries = maxRetries;
+    }
+    /**
+     * 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).
+     */
+    async similar(pmid, n, signal) {
+        const work = await this.withRetry(() => this.client.getWorkByPmid(pmid, signal), `getWorkByPmid(${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 };
+    }
+    /**
+     * Find works that cite the given PMID via OpenAlex `cites:W<id>` filter.
+     * Returns PMIDs only; drops any record with no PMID.
+     */
+    async citedBy(pmid, n, signal) {
+        const work = await this.withRetry(() => this.client.getWorkByPmid(pmid, signal), `getWorkByPmid(${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 };
+    }
+    /**
+     * 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);
+        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 };
+    }
+    /**
+     * Extract unique numeric PMIDs from a list of works, excluding the source PMID.
+     * Any work with no PMID is silently dropped (never minted).
+     */
+    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);
+        }
+        return result;
+    }
+    /** Retry wrapper for transient errors, mirroring the EPMC service pattern. */
+    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(`OpenAlex ${label} failed. Retrying (${attempt + 1}/${this.maxRetries}) in ${retryDelay}ms.`, requestContextService.createRequestContext({
+                        operation: 'OpenAlexRetry',
+                        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: 'openalex_unreachable',
+                    label,
+                    attempts,
+                    ...recoveryFor('openalex_unreachable'),
+                }, { cause: error });
+            }
+        }
+        throw internalError('OpenAlex request failed after all retries.', {
+            reason: 'openalex_unreachable',
+            ...recoveryFor('openalex_unreachable'),
+        });
+    }
+}
+// ─── Init / Accessor ────────────────────────────────────────────────────────
+let _service;
+/** Initialize the OpenAlex service. Call from `setup()` in createApp. */
+export function initOpenAlexService() {
+    const config = getServerConfig();
+    const client = new OpenAlexApiClient({
+        timeoutMs: config.europepmcTimeoutMs, // reuse EPMC timeout — same order of magnitude
+        ...(config.adminEmail && { email: config.adminEmail }),
+    });
+    // Reuse EPMC retry config — same upstream reliability tier
+    _service = new OpenAlexService(client, config.europepmcMaxRetries);
+    logger.info('OpenAlex service initialized.', requestContextService.createRequestContext({
+        operation: 'OpenAlexInit',
+        hasEmail: !!config.adminEmail,
+        maxRetries: config.europepmcMaxRetries,
+        timeoutMs: config.europepmcTimeoutMs,
+    }));
+}
+/** Get the initialized OpenAlex service. Throws if not initialized. */
+export function getOpenAlexService() {
+    if (!_service)
+        throw new Error('OpenAlex service not initialized. Call initOpenAlexService() first.');
+    return _service;
+}
+/** Returns the service if initialized, undefined otherwise (for optional use). */
+export function getOpenAlexServiceOptional() {
+    return _service;
+}
+//# sourceMappingURL=openalex-service.js.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,56 @@
+/**
+ * @fileoverview Types for the OpenAlex API. Covers the work lookup (PMID resolve),
+ * related/referenced works resolution, and cited-by filter endpoints.
+ *
+ * See https://docs.openalex.org/api-entities/works for the full API.
+ * We use three endpoints:
+ *   - GET /works/pmid:{pmid}?select=id,related_works,referenced_works
+ *   - GET /works?filter=openalex:{id}|{id}&select=id,ids  (batch PMID resolve)
+ *   - GET /works?filter=cites:{id}&select=id,ids  (cited_by)
+ *
+ * @module src/services/openalex/types
+ */
+/** Base URL for the OpenAlex public API. */
+export declare const OPENALEX_API_BASE = "https://api.openalex.org";
+/**
+ * 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 —
+ * any record without one is dropped.
+ */
+export interface OpenAlexWorkIds {
+    doi?: string;
+    mag?: string;
+    openalex?: string;
+    pmid?: string;
+    [key: string]: string | undefined;
+}
+/**
+ * Minimal Work record — only fields the service actually uses. We use
+ * `select=id,ids` on batch calls to keep responses small.
+ */
+export interface OpenAlexWork {
+    /** OpenAlex canonical ID, e.g. "https://openalex.org/W2960163646". */
+    id: string;
+    ids?: OpenAlexWorkIds;
+    /** IDs of referenced works (this work's reference list). Only present when requested. */
+    referenced_works?: string[];
+    /** IDs of related works (content-based similarity). Only present when requested. */
+    related_works?: string[];
+}
+/** Top-level response shape from the /works collection endpoint. */
+export interface OpenAlexWorksResponse {
+    meta?: {
+        count?: number;
+        page?: number;
+        per_page?: number;
+        next_cursor?: string;
+    };
+    results?: OpenAlexWork[];
+    [key: string]: unknown;
+}
+/** Resolved PMID list returned by service methods. */
+export interface OpenAlexRelatedResult {
+    pmids: string[];
+    totalCount: number;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +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"}

package/dist/services/openalex/types.js

@@ -0,0 +1,15 @@
+/**
+ * @fileoverview Types for the OpenAlex API. Covers the work lookup (PMID resolve),
+ * related/referenced works resolution, and cited-by filter endpoints.
+ *
+ * See https://docs.openalex.org/api-entities/works for the full API.
+ * We use three endpoints:
+ *   - GET /works/pmid:{pmid}?select=id,related_works,referenced_works
+ *   - GET /works?filter=openalex:{id}|{id}&select=id,ids  (batch PMID resolve)
+ *   - GET /works?filter=cites:{id}&select=id,ids  (cited_by)
+ *
+ * @module src/services/openalex/types
+ */
+/** Base URL for the OpenAlex public API. */
+export const OPENALEX_API_BASE = 'https://api.openalex.org';
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/pubmed-mcp-server",
-  "version": "2.8.0",
+  "version": "2.9.0",
   "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.8.0",
+  "version": "2.9.0",
   "remotes": [
     {
       "type": "streamable-http",
@@ -19,7 +19,7 @@
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@cyanheads/pubmed-mcp-server",
       "runtimeHint": "bun",
-      "version": "2.8.0",
+      "version": "2.9.0",
       "packageArguments": [
         {
           "type": "positional",
@@ -66,7 +66,7 @@
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@cyanheads/pubmed-mcp-server",
       "runtimeHint": "bun",
-      "version": "2.8.0",
+      "version": "2.9.0",
       "packageArguments": [
         {
           "type": "positional",