mcp-simple-pubmed

Instructions

Implementation Reference

• mcp_simple_pubmed/server.py:126-167 (handler)

  The main async handler function implementing the get_paper_fulltext tool logic. It checks PMC availability, fetches full text if possible, or returns helpful alternatives using DOI/PubMed links.
  async def get_paper_fulltext(pmid: str) -> str: """Get full text of a PubMed article using its ID. This tool attempts to retrieve the complete text of the paper if available through PubMed Central. If the paper is not available in PMC, it will return a message explaining why and provide information about where the text might be available (e.g., through DOI). Example usage: get_paper_fulltext(pmid="39661433") Returns: - If successful: The complete text of the paper - If not available: A clear message explaining why (e.g., "not in PMC", "requires journal access") """ try: logger.info(f"Attempting to get full text for PMID: {pmid}") # First check PMC availability available, pmc_id = await fulltext_client.check_full_text_availability(pmid) if available: full_text = await fulltext_client.get_full_text(pmid) if full_text: logger.info(f"Successfully retrieved full text from PMC for PMID {pmid}") return full_text # Get article details to provide alternative locations article = await pubmed_client.get_article_details(pmid) message = "Full text is not available in PubMed Central.\n\n" message += "The article may be available at these locations:\n" message += f"- PubMed page: https://pubmed.ncbi.nlm.nih.gov/{pmid}/\n" if article and "doi" in article: message += f"- Publisher's site (via DOI): https://doi.org/{article['doi']}\n" logger.info(f"Full text not available in PMC for PMID {pmid}, provided alternative locations") return message except Exception as e: logger.exception(f"Error in get_paper_fulltext") raise ValueError(f"Error retrieving full text: {str(e)}")
• mcp_simple_pubmed/server.py:119-125 (registration)

  MCP tool registration decorator that registers the get_paper_fulltext handler with metadata annotations including title and API hints.
  @app.tool( annotations={ "title": "Get a paper's full text", "readOnlyHint": True, "openWorldHint": True # Calls external PubMed API } )
• mcp_simple_pubmed/server.py:126-139 (schema)

  Function signature (pmid: str -> str) and docstring defining input/output schema, description, and usage examples.
  async def get_paper_fulltext(pmid: str) -> str: """Get full text of a PubMed article using its ID. This tool attempts to retrieve the complete text of the paper if available through PubMed Central. If the paper is not available in PMC, it will return a message explaining why and provide information about where the text might be available (e.g., through DOI). Example usage: get_paper_fulltext(pmid="39661433") Returns: - If successful: The complete text of the paper - If not available: A clear message explaining why (e.g., "not in PMC", "requires journal access") """
• mcp_simple_pubmed/fulltext_client.py:77-132 (helper)

  Key helper method in FullTextClient that performs the actual full text retrieval from PubMed Central (PMC) using Entrez EFetch API, handling large/truncated responses.
  async def get_full_text(self, pmid: str) -> Optional[str]: """Get full text of the article if available through PMC. Handles truncated responses by making additional requests. Args: pmid: PubMed ID of the article Returns: Full text content if available, None otherwise """ try: # First check availability and get PMC ID available, pmc_id = await self.check_full_text_availability(pmid) if not available or pmc_id is None: logger.info(f"Full text not available in PMC for PMID {pmid}") return None logger.info(f"Fetching full text for PMC ID {pmc_id}") content = "" retstart = 0 while True: full_text_handle = Entrez.efetch( db="pmc", id=pmc_id, rettype="xml", retstart=retstart ) if not full_text_handle: break chunk = full_text_handle.read() full_text_handle.close() if isinstance(chunk, bytes): chunk = chunk.decode('utf-8') content += chunk # Check if there might be more content if "[truncated]" not in chunk and "Result too long" not in chunk: break # Increment retstart for next chunk retstart += len(chunk) # Add small delay to respect API rate limits time.sleep(0.5) return content except Exception as e: logger.exception(f"Error getting full text for PMID {pmid}: {str(e)}") return None
• mcp_simple_pubmed/fulltext_client.py:37-75 (helper)

  Helper method to check if full text is available in PMC and retrieve the PMC ID using Entrez ELink API.
  async def check_full_text_availability(self, pmid: str) -> Tuple[bool, Optional[str]]: """Check if full text is available in PMC and get PMC ID if it exists. Args: pmid: PubMed ID of the article Returns: Tuple of (availability boolean, PMC ID if available) """ try: logger.info(f"Checking PMC availability for PMID {pmid}") handle = Entrez.elink(dbfrom="pubmed", db="pmc", id=pmid) if not handle: logger.info(f"No PMC link found for PMID {pmid}") return False, None xml_content = handle.read() handle.close() # Parse XML to get PMC ID root = ET.fromstring(xml_content) linksetdb = root.find(".//LinkSetDb") if linksetdb is None: logger.info(f"No PMC ID found for PMID {pmid}") return False, None id_elem = linksetdb.find(".//Id") if id_elem is None: logger.info(f"No PMC ID element found for PMID {pmid}") return False, None pmc_id = id_elem.text logger.info(f"Found PMC ID {pmc_id} for PMID {pmid}") return True, pmc_id except Exception as e: logger.exception(f"Error checking PMC availability for PMID {pmid}: {str(e)}") return False, None