mcp-pubmed

Instructions

Implementation Reference

• src/tools.ts:41-69 (handler)

  The main implementation of searchArticles function that executes the PubMed search logic. It uses NCBI client to perform esearch and efetch operations, then parses and formats the results as JSON.

  export async function searchArticles(args: z.infer<typeof searchArticlesSchema>): Promise<string> {
    // Step 1: search
    const searchResult = await client.esearch(args.query, {
      retmax: args.max_results,
      sort: args.sort,
      mindate: args.min_date,
      maxdate: args.max_date,
      datetype: args.min_date || args.max_date ? "pdat" : undefined,
    }) as { esearchresult: { idlist: string[]; count: string; querytranslation: string } };
  
    const ids = searchResult.esearchresult.idlist;
    const totalCount = searchResult.esearchresult.count;
    const queryTranslation = searchResult.esearchresult.querytranslation;
  
    if (ids.length === 0) {
      return JSON.stringify({ total_count: 0, query_translation: queryTranslation, articles: [] }, null, 2);
    }
  
    // Step 2: fetch article details
    const xml = await client.efetch(ids);
    const articles = parseArticles(xml);
  
    return JSON.stringify({
      total_count: parseInt(totalCount),
      query_translation: queryTranslation,
      showing: articles.length,
      articles: articles.map(formatArticleSummary),
    }, null, 2);
  }

• src/tools.ts:9-15 (schema)

  The Zod schema defining the input validation for search_articles tool. It specifies query (required), max_results (1-100, default 10), sort (enum), and optional min_date/max_date parameters.

  export const searchArticlesSchema = z.object({
    query: z.string().describe("PubMed search query (supports full PubMed syntax including [Title], [Author], [MeSH], date ranges, boolean operators)"),
    max_results: z.number().min(1).max(100).default(10).describe("Maximum results to return (1-100)"),
    sort: z.enum(["relevance", "pub_date", "Author", "JournalName"]).default("relevance").describe("Sort order"),
    min_date: z.string().optional().describe("Minimum publication date (YYYY or YYYY/MM or YYYY/MM/DD)"),
    max_date: z.string().optional().describe("Maximum publication date (YYYY or YYYY/MM or YYYY/MM/DD)"),
  });

• src/index.ts:25-32 (registration)

  The MCP server tool registration for search_articles. This registers the tool with its name, description, schema shape, and the handler that executes when the tool is called.

  server.tool(
    "search_articles",
    "Search PubMed for biomedical articles. Supports full PubMed query syntax including field tags ([Title], [Author], [MeSH]), boolean operators (AND, OR, NOT), and date ranges.",
    searchArticlesSchema.shape,
    async (args) => ({
      content: [{ type: "text", text: await searchArticles(searchArticlesSchema.parse(args)) }],
    })
  );

• src/tools.ts:223-233 (helper)

  Helper function used by searchArticles to format article metadata into a summary format, limiting author lists and truncating abstracts to 500 characters.

  function formatArticleSummary(a: ArticleMetadata) {
    return {
      pmid: a.pmid,
      title: a.title,
      authors: a.authors.slice(0, 5).join(", ") + (a.authors.length > 5 ? " et al." : ""),
      journal: a.journal,
      pub_date: a.pubDate,
      doi: a.doi || undefined,
      abstract: a.abstract.length > 500 ? a.abstract.slice(0, 500) + "..." : a.abstract,
    };
  }