mcp-pubmed

Instructions

Implementation Reference

• src/tools.ts:104-130 (handler)

  The getRelated handler function implements the core logic: uses NCBI's elink API with 'pubmed_pubmed' link type to find related articles for a given PMID, skips the query article itself, fetches article details via efetch, and returns JSON-formatted results with related article metadata.

  export async function getRelated(args: z.infer<typeof getRelatedSchema>): Promise<string> {
    const result = await client.elink([args.pmid], "pubmed_pubmed") as {
      linksets?: Array<{ linksetdbs?: Array<{ links?: string[] }> }>;
    };
  
    const links = result.linksets?.[0]?.linksetdbs?.[0]?.links || [];
  
    if (links.length === 0) {
      return JSON.stringify({ pmid: args.pmid, related_count: 0, related_articles: [] }, null, 2);
    }
  
    // Skip first (it's usually the query article itself)
    const fetchIds = links.filter((id: string) => id !== args.pmid).slice(0, args.max_results);
    if (fetchIds.length === 0) {
      return JSON.stringify({ pmid: args.pmid, related_count: 0, related_articles: [] }, null, 2);
    }
  
    const xml = await client.efetch(fetchIds);
    const articles = parseArticles(xml);
  
    return JSON.stringify({
      pmid: args.pmid,
      related_count: links.length - 1,
      showing: articles.length,
      related_articles: articles.map(formatArticleSummary),
    }, null, 2);
  }

• src/tools.ts:25-28 (schema)

  The getRelatedSchema defines the input validation for the tool, requiring a pmid (PubMed ID) string and an optional max_results number between 1-100 with a default of 10.

  export const getRelatedSchema = z.object({
    pmid: z.string().describe("PubMed ID to find related articles for"),
    max_results: z.number().min(1).max(100).default(10).describe("Maximum results"),
  });

• src/index.ts:52-59 (registration)

  The get_related tool is registered with the MCP server, binding the schema to the handler function with a description explaining it finds related articles ranked by relevance using NCBI's algorithm.

  server.tool(
    "get_related",
    "Get related articles for a given PubMed article (PMID), ranked by relevance using NCBI's algorithm.",
    getRelatedSchema.shape,
    async (args) => ({
      content: [{ type: "text", text: await getRelated(getRelatedSchema.parse(args)) }],
    })
  );