PubMed MCP Server

Instructions

Implementation Reference

• src/index.ts:210-241 (registration)

  MCP tool registration for 'get_fulltext', including schema and execution handler that delegates to getFullTextHandler

  server.registerTool(
    'get_fulltext',
    {
      title: 'PubMed Full Text',
      description: 'Get full text content of PubMed articles using PMIDs.',
      inputSchema: {
        pmids: z.array(z.string()).describe('Array of PubMed IDs (PMIDs) to get full text for')
      }
    },
    async ({ pmids }) => {
      try {
        const results = await getFullTextHandler.getFullText(pmids);
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify(results, null, 2),
            },
          ],
        };
      } catch (error) {
        return {
          content: [
            {
              type: 'text',
              text: `Error fetching full text: ${error instanceof Error ? error.message : 'Unknown error'}`,
            },
          ],
        };
      }
    }
  );

• src/handlers/get-fulltext.ts:7-15 (handler)

  Factory function creating the getFullText handler that delegates execution to PubMedAPI

  export function createGetFullTextHandler(pubmedOptions: PubMedOptions): GetFullTextHandler {
    const pubmedApi = createPubMedAPI(pubmedOptions);
  
    return {
      async getFullText(pmids: string[]): Promise<FullTextResult[]> {
        return await pubmedApi.getFullText(pmids);
      }
    };
  }

• src/index.ts:216-217 (schema)

  Input schema for the 'get_fulltext' tool using Zod validation

    pmids: z.array(z.string()).describe('Array of PubMed IDs (PMIDs) to get full text for')
  }

• src/pubmed-api.ts:702-871 (helper)

  Core implementation of getFullText in PubMedAPI: handles caching, full-text availability via PMC ID converter and elink, fetches XML from PMC efetch, extracts structured text content, decodes entities, and caches results

  const getFullText = async (pmids: string[]): Promise<FullTextResult[]> => {
    if (pmids.length === 0) return [];
  
    // Check cache for existing full texts if cache is enabled
    const cachedResults: FullTextResult[] = cache
      ? (await Promise.all(pmids.map(async (pmid) => {
        const cached = await cache.getCachedFullText(pmid);
        return cached ? { pmid, fullText: cached, cacheFilePath: cache.getFullTextFilePath(pmid) } : null;
      }))).filter((result) => result !== null)
      : [];
    const uncachedPmids: string[] = pmids.filter(
      pmid => !cachedResults.some(result => result.pmid === pmid)
    );
  
    // If all full texts are cached, return them
    if (uncachedPmids.length === 0) {
      return cachedResults;
    }
  
    // Batch check full text availability for uncached PMIDs
    const availabilityResultsArray = await checkFullTextAvailability(uncachedPmids);
  
    // Convert array to map for easier lookup
    const availabilityResults = Object.fromEntries(availabilityResultsArray);
  
    // Group PMIDs by their PMC IDs for batch fetching
    const pmcToPmidMap: { [pmcId: string]: string[] } = {};
    const resultsMap: { [pmid: string]: FullTextResult } = {};
  
    // Initialize results and group by PMC ID
    uncachedPmids.forEach(pmid => {
      const availability = availabilityResults[pmid];
      if (availability?.pmcId) {
        if (!pmcToPmidMap[availability.pmcId]) {
          pmcToPmidMap[availability.pmcId] = [];
        }
        pmcToPmidMap[availability.pmcId].push(pmid);
        // Store links for later assignment
        resultsMap[pmid] = { pmid, fullText: null, links: availability.links };
      } else {
        resultsMap[pmid] = { pmid, fullText: null, links: availability?.links || [] };
      }
    });
  
    // Batch fetch full texts for PMC IDs
    for (const [pmcId, relatedPmids] of Object.entries(pmcToPmidMap)) {
      try {
        // PMC efetch API expects PMC ID with 'PMC' prefix
        const pmcIdWithPrefix = pmcId.startsWith('PMC') ? pmcId : `PMC${pmcId}`;
        const params = {
          db: 'pmc',
          id: pmcIdWithPrefix,
          retmode: 'xml'
          // Note: PMC database only supports rettype: null (empty) per NCBI documentation
        };
  
        const url = buildUrl('efetch', params);
        const xmlResponse = await makeRequest(url);
        const parsedData = parser.parse(xmlResponse);
  
        const article = parsedData['pmc-articleset']?.article || parsedData.pmc_articleset?.article || parsedData.article;
  
        if (article) {
          const extractTextFromNode = (node: unknown): string => {
            if (node == null) return ''
  
            if (typeof node === 'string') {
              return decodeHtmlEntities(node)
            }
  
            if (Array.isArray(node)) {
              return node
                .map(extractTextFromNode)
                .filter(text => text.length > 0)
                .join('\n\n') // Use paragraph breaks for array elements
            }
  
            if (typeof node === 'object') {
              const obj = node as Record<string, unknown>
              const textValue = obj['#text']
              if (typeof textValue === 'string') {
                return decodeHtmlEntities(textValue)
              }
  
              let text = ''
              for (const value of Object.values(obj)) {
                text += extractTextFromNode(value) + ' '
              }
              return text.trim()
            }
  
            return ''
          }
  
          let fullText = '';
  
          if (article.front?.['article-meta']?.['title-group']?.['article-title']) {
            const title = extractTextFromNode(article.front['article-meta']['title-group']['article-title']);
            fullText += `# ${title}\n\n`;
          }
  
          if (article.front?.['article-meta']?.abstract) {
            const abstract = extractTextFromNode(article.front['article-meta'].abstract);
            fullText += `## Abstract\n\n${abstract}\n\n`;
          }
  
          if (article.body) {
            // Try to extract structured content first
            const structuredContent = extractStructuredContent(article.body, extractTextFromNode);
            if (structuredContent) {
              fullText += `## Content\n\n${structuredContent}`;
            } else {
              // Fallback to basic text extraction
              const content = extractTextFromNode(article.body);
              fullText += `## Content\n\n${content}\n\n`;
            }
          }
  
          // Clean up text formatting
          fullText = fullText
            .replace(/[ \t]+/g, ' ')                    // Multiple spaces/tabs to single space
            .trim();
  
          // Assign the same full text to all related PMIDs and cache it
          for (const pmid of relatedPmids) {
            const existingLinks = resultsMap[pmid]?.links;
            resultsMap[pmid] = {
              pmid,
              fullText: fullText || null,
              ...(existingLinks && existingLinks.length > 0 && { links: existingLinks })
            };
  
            // Cache the full text if cache is enabled and fullText is not null
            if (cache && fullText) {
              try {
                await cache.setCachedFullText(pmid, fullText);
                resultsMap[pmid].cacheFilePath = cache.getFullTextFilePath(pmid);
              } catch (err) {
                console.error('Error caching full text:', err);
              }
            }
          }
        } else {
          // No article found for this PMC ID
          relatedPmids.forEach(pmid => {
            const existingLinks = resultsMap[pmid]?.links;
            resultsMap[pmid] = {
              pmid,
              fullText: null,
              ...(existingLinks && existingLinks.length > 0 && { links: existingLinks })
            };
          });
        }
      } catch (error) {
        console.error(`Error fetching full text for PMC ID ${pmcId}:`, error);
        relatedPmids.forEach(pmid => {
          const existingLinks = resultsMap[pmid]?.links;
          resultsMap[pmid] = {
            pmid,
            fullText: null,
            ...(existingLinks && existingLinks.length > 0 && { links: existingLinks })
          };
        });
      }
    }
  
    // Combine cached and fetched results, maintaining the original order
    const allResults = [...cachedResults, ...Object.values(resultsMap)];
    return pmids.map(pmid => allResults.find(result => result.pmid === pmid)).filter(Boolean) as FullTextResult[];
  };