@djmima/pubmed-mcp 0.0.0-stage → 1.0.0

package/dist/tools/getFullTextArticle.js

@@ -0,0 +1,89 @@
+/**
+ * Tool: get_full_text_article
+ *
+ * Retrieve the full text of articles from PubMed Central (PMC).
+ * Full text is available for PMC articles whose publisher allows full-text
+ * download (the same test get_copyright_status uses for has_full_text).
+ * Articles not in PMC will return an error entry.
+ */
+import { z } from 'zod';
+import { IMPORTANT_LEGAL_NOTICE } from '../pubmed/types.js';
+import { parsePmcEfetchXml } from '../utils/xml.js';
+/** PMCIDs per request; the CLI splits longer lists into batches of this size. */
+export const MAX_FULL_TEXT_IDS = 20;
+export const getFullTextArticleSchema = {
+    pmc_ids: z
+        .array(z.string().min(1))
+        .min(1)
+        .max(MAX_FULL_TEXT_IDS)
+        .describe('Array of PubMed Central IDs (PMCIDs) to retrieve full text for. ' +
+        'PMCIDs must include the "PMC" prefix (e.g., ["PMC9583675", "PMC7984072"]). ' +
+        'Articles without downloadable full text are excluded from articles ' +
+        'and reported in errors.'),
+};
+/** Strip the PMC prefix to get the numeric portion NCBI expects. */
+function stripPmcPrefix(id) {
+    const trimmed = id.trim();
+    return trimmed.toUpperCase().startsWith('PMC') ? trimmed.slice(3) : trimmed;
+}
+function normalizePmcId(id) {
+    return `PMC${stripPmcPrefix(id)}`.toUpperCase();
+}
+export async function getFullTextArticle(params, client) {
+    // NCBI efetch for PMC expects numeric IDs (without "PMC" prefix)
+    const numericIds = params.pmc_ids.map(stripPmcPrefix);
+    const xml = await client.efetch({
+        db: 'pmc',
+        id: numericIds,
+        retmode: 'xml',
+    });
+    let parsedArticles;
+    try {
+        parsedArticles = parsePmcEfetchXml(xml);
+    }
+    catch (err) {
+        process.stderr.write(`PMC XML parse error: ${String(err)}\n`);
+        return {
+            important_legal_notice: IMPORTANT_LEGAL_NOTICE,
+            articles: [],
+            errors: params.pmc_ids.map((pmcid) => ({
+                pmcid: normalizePmcId(pmcid),
+                error: 'Failed to parse the PMC EFetch response.',
+            })),
+            count: 0,
+        };
+    }
+    const articles = [];
+    const errors = [];
+    const returnedIds = new Set();
+    for (const [index, article] of parsedArticles.entries()) {
+        const pmcid = article.identifiers.pmcid
+            ? normalizePmcId(article.identifiers.pmcid)
+            : normalizePmcId(params.pmc_ids[index] ?? '');
+        returnedIds.add(pmcid);
+        if (article.full_text.trim()) {
+            articles.push(article);
+        }
+        else {
+            errors.push({
+                pmcid,
+                error: 'Full text is not available from PMC EFetch for this article.',
+            });
+        }
+    }
+    for (const pmcid of new Set(params.pmc_ids.map(normalizePmcId))) {
+        if (!returnedIds.has(pmcid)) {
+            errors.push({
+                pmcid,
+                error: 'PMC EFetch did not return this article.',
+            });
+        }
+    }
+    return {
+        important_legal_notice: IMPORTANT_LEGAL_NOTICE,
+        articles,
+        errors,
+        count: articles.length,
+    };
+}
+//# sourceMappingURL=getFullTextArticle.js.map

package/dist/tools/getFullTextArticle.js.map

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

package/dist/tools/lookupArticleByCitation.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Tool: lookup_article_by_citation
+ *
+ * Look up PubMed IDs for articles given structured citation metadata
+ * (journal, year, volume, first page, author). Uses NCBI's ECitmatch endpoint.
+ */
+import { z } from 'zod';
+import type { NcbiClient } from '../pubmed/client.js';
+import type { LookupArticleByCitationResponse } from '../pubmed/types.js';
+/** Citations per request; the CLI splits longer lists into batches of this size. */
+export declare const MAX_CITATIONS = 100;
+export declare const lookupArticleByCitationSchema: {
+    citations: z.ZodArray<z.ZodObject<{
+        journal: z.ZodString;
+        year: z.ZodNumber;
+        volume: z.ZodOptional<z.ZodDefault<z.ZodString>>;
+        first_page: z.ZodOptional<z.ZodDefault<z.ZodString>>;
+        author: z.ZodOptional<z.ZodDefault<z.ZodString>>;
+        key: z.ZodString;
+    }, z.core.$strip>>;
+};
+export type LookupArticleByCitationParams = {
+    citations: Array<{
+        journal: string;
+        year: number;
+        volume?: string;
+        first_page?: string;
+        author?: string;
+        key: string;
+    }>;
+};
+export declare function lookupArticleByCitation(params: LookupArticleByCitationParams, client: NcbiClient): Promise<LookupArticleByCitationResponse>;
+//# sourceMappingURL=lookupArticleByCitation.d.ts.map

package/dist/tools/lookupArticleByCitation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lookupArticleByCitation.d.ts","sourceRoot":"","sources":["../../src/tools/lookupArticleByCitation.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAE,+BAA+B,EAAkB,MAAM,oBAAoB,CAAC;AAE1F,oFAAoF;AACpF,eAAO,MAAM,aAAa,MAAM,CAAC;AAEjC,eAAO,MAAM,6BAA6B;;;;;;;;;CAmDzC,CAAC;AAEF,MAAM,MAAM,6BAA6B,GAAG;IAC1C,SAAS,EAAE,KAAK,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,GAAG,EAAE,MAAM,CAAC;KACb,CAAC,CAAC;CACJ,CAAC;AA2CF,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,6BAA6B,EACrC,MAAM,EAAE,UAAU,GACjB,OAAO,CAAC,+BAA+B,CAAC,CAc1C"}

package/dist/tools/lookupArticleByCitation.js

@@ -0,0 +1,96 @@
+/**
+ * Tool: lookup_article_by_citation
+ *
+ * Look up PubMed IDs for articles given structured citation metadata
+ * (journal, year, volume, first page, author). Uses NCBI's ECitmatch endpoint.
+ */
+import { z } from 'zod';
+/** Citations per request; the CLI splits longer lists into batches of this size. */
+export const MAX_CITATIONS = 100;
+export const lookupArticleByCitationSchema = {
+    citations: z
+        .array(z.object({
+        journal: z
+            .string()
+            .describe('Journal name or abbreviation (e.g., "Nature", "J Immunol", ' +
+            '"N Engl J Med"). Spaces should be included as-is.'),
+        year: z
+            .number()
+            .int()
+            .min(1800)
+            .max(2100)
+            .describe('Publication year (e.g., 2023).'),
+        volume: z
+            .string()
+            .default('')
+            .optional()
+            .describe('Journal volume number (e.g., "204"). Leave empty if unknown.'),
+        first_page: z
+            .string()
+            .default('')
+            .optional()
+            .describe('First page number of the article (e.g., "1234"). ' +
+            'Leave empty if unknown.'),
+        author: z
+            .string()
+            .default('')
+            .optional()
+            .describe('First author last name (e.g., "Smith"). ' +
+            'Leave empty if unknown.'),
+        key: z
+            .string()
+            .describe('Your own identifier for this citation (e.g., "ref1", "paper_A"). ' +
+            'Echoed back in the response to correlate results.'),
+    }))
+        .min(1)
+        .max(MAX_CITATIONS)
+        .describe('Array of citation objects to look up. ' +
+        'Provide as much information as available for best match accuracy.'),
+};
+/**
+ * Parse the plain-text response from ecitmatch.cgi.
+ *
+ * Format: journal|year|volume|first_page|author|key|PMID_or_NOT_FOUND
+ * One line per citation (empty lines ignored).
+ */
+function parseEcitmatchResponse(text, originalCitations) {
+    if (/^\s*(?:<!doctype\s+html|<html\b)/i.test(text)) {
+        throw new Error('ECitMatch returned HTML instead of citation match text');
+    }
+    const lines = text
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .filter(Boolean);
+    return lines.map((line, idx) => {
+        const parts = line.split('|');
+        // Fields: [0]journal, [1]year, [2]volume, [3]first_page, [4]author, [5]key, [6]result
+        const result = parts.at(-1)?.trim() ?? '';
+        const isFound = result !== '' && result !== 'NOT_FOUND' && /^\d+$/.test(result);
+        // Use original citation data where available (ecitmatch may alter formatting)
+        const original = originalCitations[idx];
+        const echoedKey = parts.length >= 7 ? parts[5] : parts[0];
+        return {
+            journal: original?.journal ?? parts[0] ?? '',
+            year: String(original?.year ?? parts[1] ?? ''),
+            volume: original?.volume ?? parts[2] ?? '',
+            first_page: original?.first_page ?? parts[3] ?? '',
+            author: original?.author ?? parts[4] ?? '',
+            pmid: isFound ? result : '',
+            key: original?.key ?? echoedKey ?? '',
+        };
+    });
+}
+export async function lookupArticleByCitation(params, client) {
+    const citations = params.citations.map((c) => ({
+        journal: c.journal,
+        year: c.year,
+        volume: c.volume ?? '',
+        first_page: c.first_page ?? '',
+        author: c.author ?? '',
+        key: c.key,
+    }));
+    const rawText = await client.ecitmatch(citations);
+    const results = parseEcitmatchResponse(rawText, params.citations);
+    return { citations: results };
+}
+//# sourceMappingURL=lookupArticleByCitation.js.map

package/dist/tools/lookupArticleByCitation.js.map

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

package/dist/tools/searchArticles.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Tool: search_articles
+ *
+ * Search PubMed for biomedical articles using standard PubMed syntax or
+ * keywords. Returns a list of PMIDs plus metadata about the result set.
+ */
+import { z } from 'zod';
+import type { NcbiClient } from '../pubmed/client.js';
+import type { SearchArticlesResponse } from '../pubmed/types.js';
+declare const SEARCH_FIELDS: readonly ["title", "tiab", "mesh", "author", "journal", "affiliation"];
+export declare const searchArticlesSchema: {
+    query: z.ZodString;
+    max_results: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+    retstart: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+    sort: z.ZodOptional<z.ZodEnum<{
+        relevance: "relevance";
+        pub_date: "pub_date";
+        author: "author";
+        journal_name: "journal_name";
+    }>>;
+    field: z.ZodOptional<z.ZodEnum<{
+        author: "author";
+        title: "title";
+        tiab: "tiab";
+        mesh: "mesh";
+        journal: "journal";
+        affiliation: "affiliation";
+    }>>;
+    date_from: z.ZodOptional<z.ZodString>;
+    date_to: z.ZodOptional<z.ZodString>;
+    datetype: z.ZodDefault<z.ZodEnum<{
+        pdat: "pdat";
+        edat: "edat";
+        mdat: "mdat";
+    }>>;
+};
+export type SearchArticlesParams = {
+    query: string;
+    max_results?: number;
+    retstart?: number;
+    sort?: 'relevance' | 'pub_date' | 'author' | 'journal_name';
+    field?: (typeof SEARCH_FIELDS)[number];
+    date_from?: string;
+    date_to?: string;
+    datetype?: 'pdat' | 'edat' | 'mdat';
+};
+export declare function searchArticles(params: SearchArticlesParams, client: NcbiClient): Promise<SearchArticlesResponse>;
+export {};
+//# sourceMappingURL=searchArticles.d.ts.map

package/dist/tools/searchArticles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"searchArticles.d.ts","sourceRoot":"","sources":["../../src/tools/searchArticles.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAUjE,QAAA,MAAM,aAAa,wEAOT,CAAC;AAEX,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;CAqEhC,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,WAAW,GAAG,UAAU,GAAG,QAAQ,GAAG,cAAc,CAAC;IAC5D,KAAK,CAAC,EAAE,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;CACrC,CAAC;AAEF,wBAAsB,cAAc,CAClC,MAAM,EAAE,oBAAoB,EAC5B,MAAM,EAAE,UAAU,GACjB,OAAO,CAAC,sBAAsB,CAAC,CAmCjC"}

package/dist/tools/searchArticles.js

@@ -0,0 +1,121 @@
+/**
+ * Tool: search_articles
+ *
+ * Search PubMed for biomedical articles using standard PubMed syntax or
+ * keywords. Returns a list of PMIDs plus metadata about the result set.
+ */
+import { z } from 'zod';
+// Sort parameter mapping: tool value → NCBI API value
+const SORT_MAP = {
+    relevance: 'relevance',
+    pub_date: 'pub_date',
+    author: 'Author',
+    journal_name: 'JournalName',
+};
+const SEARCH_FIELDS = [
+    'title',
+    'tiab',
+    'mesh',
+    'author',
+    'journal',
+    'affiliation',
+];
+export const searchArticlesSchema = {
+    query: z
+        .string()
+        .min(1)
+        .describe('PubMed search query using standard PubMed syntax or plain keywords. ' +
+        'Supports Boolean operators (AND, OR, NOT), field tags ([Title], [Author], ' +
+        '[MeSH Terms], etc.), and date ranges.'),
+    max_results: z
+        .number()
+        .int()
+        .min(1)
+        .max(10000)
+        .default(20)
+        .optional()
+        .describe('Maximum number of article IDs to return (default: 20, max: 10000).'),
+    retstart: z
+        .number()
+        .int()
+        .min(0)
+        .default(0)
+        .optional()
+        .describe('Zero-based offset of the first result to return. ' +
+        'Use with max_results for pagination.'),
+    sort: z
+        .enum(['relevance', 'pub_date', 'author', 'journal_name'])
+        .optional()
+        .describe('Sort order for results. ' +
+        'relevance: most relevant first; ' +
+        'pub_date: most recent first; ' +
+        'author: alphabetical by first author; ' +
+        'journal_name: alphabetical by journal.'),
+    field: z
+        .enum(SEARCH_FIELDS)
+        .optional()
+        .describe('Optional PubMed field applied to every untagged term in the query: ' +
+        'title, tiab (title/abstract), mesh, author, journal, or affiliation. ' +
+        'This prevents cross-field automatic term mapping for those terms. ' +
+        'An explicit field tag in the query takes precedence for the tagged term.'),
+    date_from: z
+        .string()
+        .optional()
+        .describe('Start of date range filter (YYYY/MM/DD, YYYY/MM, or YYYY). ' +
+        'Applied to the date type specified by datetype. May be given without date_to.'),
+    date_to: z
+        .string()
+        .optional()
+        .describe('End of date range filter (YYYY/MM/DD, YYYY/MM, or YYYY). ' +
+        'Applied to the date type specified by datetype. May be given without date_from.'),
+    datetype: z
+        .enum(['pdat', 'edat', 'mdat'])
+        .default('pdat')
+        .describe('Date type to filter on: ' +
+        'pdat = publication date (default); ' +
+        'edat = Entrez date (date added to PubMed); ' +
+        'mdat = modification date.'),
+};
+export async function searchArticles(params, client) {
+    const retmax = params.max_results ?? 20;
+    const retstart = params.retstart ?? 0;
+    const result = await client.esearch({
+        term: params.query,
+        retmax,
+        retstart,
+        sort: params.sort ? SORT_MAP[params.sort] : undefined,
+        ...(params.field ? { field: params.field } : {}),
+        datetype: params.datetype ?? 'pdat',
+        ...dateRange(params.date_from, params.date_to),
+    });
+    const total_count = parseInt(result.count, 10);
+    const returned_count = result.idlist.length;
+    const has_more = retstart + returned_count < total_count;
+    return {
+        pmids: result.idlist,
+        total_count,
+        returned_count,
+        query: params.query,
+        query_translation: result.querytranslation ?? '',
+        has_more,
+        warnings: {
+            phrases_ignored: result.warninglist?.phrasesignored ?? [],
+            quoted_phrases_not_found: result.warninglist?.quotedphrasesnotfound ?? [],
+            output_messages: result.warninglist?.outputmessages ?? [],
+        },
+        errors: {
+            phrases_not_found: result.errorlist?.phrasesnotfound ?? [],
+            fields_not_found: result.errorlist?.fieldsnotfound ?? [],
+        },
+    };
+}
+// NCBI ESearch silently ignores mindate or maxdate unless both are sent, so a
+// one-sided range is completed with an open bound on the other side.
+const OPEN_MIN_DATE = '1000';
+const OPEN_MAX_DATE = '3000';
+function dateRange(from, to) {
+    if (!from && !to)
+        return {};
+    return { mindate: from || OPEN_MIN_DATE, maxdate: to || OPEN_MAX_DATE };
+}
+//# sourceMappingURL=searchArticles.js.map

package/dist/tools/searchArticles.js.map

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

package/dist/utils/xml.d.ts

@@ -0,0 +1,37 @@
+/**
+ * XML parsing utilities for NCBI E-utilities responses.
+ *
+ * PubMed returns XML by default from efetch.fcgi.
+ * PMC full-text articles use the JATS XML format.
+ */
+import type { ArticleMetadata, FullTextArticle } from '../pubmed/types.js';
+/**
+ * Parse the XML returned by efetch.fcgi (db=pubmed) into ArticleMetadata objects.
+ */
+export declare function parsePubmedEfetchXml(xml: string): ArticleMetadata[];
+/**
+ * Parse the XML returned by efetch.fcgi (db=pmc) into FullTextArticle objects.
+ */
+export declare function parsePmcEfetchXml(xml: string): FullTextArticle[];
+export interface PmcAccessInfo {
+    pmcid: string;
+    /** PMC's own flag (custom-meta "pmc-prop-open-access"). */
+    isOpenAccess: boolean;
+    /** Same test get_full_text_article applies: EFetch returned body/back text. */
+    hasFullText: boolean;
+    /** Short license code from custom-meta "pmc-license-ref", e.g. "CC BY-NC-ND". */
+    license?: string;
+    copyrightStatement?: string;
+}
+/**
+ * Read access and license status from efetch.fcgi (db=pmc) XML.
+ * Replaces the PMC OA Web Service (oa.fcgi), which NCBI retired on 2026-08-25.
+ */
+export declare function parsePmcAccessXml(xml: string): PmcAccessInfo[];
+/**
+ * Recursively extract all plain text from a parsed XML node.
+ * Inline elements (italic, bold, sup, sub, etc.) are flattened to text.
+ */
+export declare function extractText(node: unknown): string;
+export declare function cleanPmcText(text: string): string;
+//# sourceMappingURL=xml.d.ts.map

package/dist/utils/xml.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xml.d.ts","sourceRoot":"","sources":["../../src/utils/xml.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAKV,eAAe,EAEf,eAAe,EAEhB,MAAM,oBAAoB,CAAC;AA2G5B;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,EAAE,CAOnE;AAyID;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,EAAE,CAOhE;AAqJD,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,YAAY,EAAE,OAAO,CAAC;IACtB,+EAA+E;IAC/E,WAAW,EAAE,OAAO,CAAC;IACrB,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,EAAE,CA+B9D;AAWD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CA4BjD;AA+CD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQjD"}