mcp-simple-pubmed

Instructions

Implementation Reference

• mcp_simple_pubmed/server.py:45-118 (handler)

  The primary handler function for the 'search_pubmed' tool. It validates parameters, performs the search via PubMedClient, enriches results with URIs and URLs, and returns formatted JSON.
  async def search_pubmed(query: str, max_results: int = 10) -> str: """Search PubMed for medical and life sciences research articles. You can use these search features: - Simple keyword search: "covid vaccine" - Field-specific search: - Title search: [Title] - Author search: [Author] - MeSH terms: [MeSH Terms] - Journal: [Journal] - Date ranges: Add year or date range like "2020:2024[Date - Publication]" - Combine terms with AND, OR, NOT - Use quotation marks for exact phrases Examples: - "covid vaccine" - basic search - "breast cancer"[Title] AND "2023"[Date - Publication] - "Smith J"[Author] AND "diabetes" - "RNA"[MeSH Terms] AND "therapy" The search will return: - Paper titles - Authors - Publication details - Abstract preview (when available) - Links to full text (when available) - DOI when available - Keywords and MeSH terms Note: Use quotes around multi-word terms for best results. """ try: # Validate and constrain max_results max_results = min(max(1, max_results), 50) logger.info(f"Processing search with query: {query}, max_results: {max_results}") # Perform the search results = await pubmed_client.search_articles( query=query, max_results=max_results ) # Create resource URIs for articles articles_with_resources = [] for article in results: pmid = article["pmid"] # Add original URIs article["abstract_uri"] = f"pubmed://{pmid}/abstract" article["full_text_uri"] = f"pubmed://{pmid}/full_text" # Add DOI URL if DOI exists if "doi" in article: article["doi_url"] = f"https://doi.org/{article['doi']}" # Add PubMed URLs article["pubmed_url"] = f"https://pubmed.ncbi.nlm.nih.gov/{pmid}/" # Add PMC URL only if PMCID is available if "pmcid" in article: article["pmc_url"] = f"https://www.ncbi.nlm.nih.gov/pmc/articles/{article['pmcid']}/" articles_with_resources.append(article) # Format the response formatted_results = json.dumps(articles_with_resources, indent=2) logger.info(f"Search completed successfully, found {len(results)} results") return formatted_results except Exception as e: logger.exception(f"Error in search_pubmed") raise ValueError(f"Error processing search request: {str(e)}")
• mcp_simple_pubmed/server.py:38-44 (registration)

  Registers the 'search_pubmed' tool with the FastMCP app, including metadata annotations for title and API hints.
  @app.tool( annotations={ "title": "Search articles about medical and life sciences research available on PubMed.", "readOnlyHint": True, "openWorldHint": True # Calls external PubMed API } )
• mcp_simple_pubmed/server.py:45-75 (schema)

  Function signature defines input schema (query: str, max_results: int=10) and output str. Docstring provides detailed usage instructions serving as schema documentation.
  async def search_pubmed(query: str, max_results: int = 10) -> str: """Search PubMed for medical and life sciences research articles. You can use these search features: - Simple keyword search: "covid vaccine" - Field-specific search: - Title search: [Title] - Author search: [Author] - MeSH terms: [MeSH Terms] - Journal: [Journal] - Date ranges: Add year or date range like "2020:2024[Date - Publication]" - Combine terms with AND, OR, NOT - Use quotation marks for exact phrases Examples: - "covid vaccine" - basic search - "breast cancer"[Title] AND "2023"[Date - Publication] - "Smith J"[Author] AND "diabetes" - "RNA"[MeSH Terms] AND "therapy" The search will return: - Paper titles - Authors - Publication details - Abstract preview (when available) - Links to full text (when available) - DOI when available - Keywords and MeSH terms Note: Use quotes around multi-word terms for best results. """
• mcp_simple_pubmed/pubmed_client.py:37-83 (helper)

  Core helper method in PubMedClient that executes Entrez.esearch for PMIDs and fetches details using get_article_details.
  async def search_articles(self, query: str, max_results: int = 10) -> List[Dict[str, Any]]: """Search for articles matching the query. Args: query: Search query string max_results: Maximum number of results to return Returns: List of article metadata dictionaries """ try: logger.info(f"Searching PubMed with query: {query}") results = [] # Step 1: Search for article IDs handle = Entrez.esearch(db="pubmed", term=query, retmax=str(max_results)) if not handle: logger.error("Got None handle from esearch") return [] if isinstance(handle, http.client.HTTPResponse): logger.info("Got valid HTTP response from esearch") xml_content = handle.read() handle.close() # Parse XML to get IDs root = ET.fromstring(xml_content) id_list = root.findall('.//Id') if not id_list: logger.info("No results found") return [] pmids = [id_elem.text for id_elem in id_list] logger.info(f"Found {len(pmids)} articles") # Step 2: Get details for each article for pmid in pmids: article = await self.get_article_details(pmid) if article: results.append(article) return results except Exception as e: logger.exception(f"Error in search_articles: {str(e)}") raise
• mcp_simple_pubmed/pubmed_client.py:85-188 (helper)

  Helper method that parses PubMed efetch XML response to extract structured article metadata including title, abstract, authors, publication details, identifiers, and MeSH terms.
  async def get_article_details(self, pmid: str) -> Optional[Dict[str, Any]]: """Get details for a specific article by PMID. Args: pmid: PubMed ID of the article Returns: Dictionary with article metadata or None if not found """ try: logger.info(f"Fetching details for PMID {pmid}") detail_handle = Entrez.efetch(db="pubmed", id=pmid, rettype="xml") if detail_handle and isinstance(detail_handle, http.client.HTTPResponse): article_xml = detail_handle.read() detail_handle.close() # Parse article details article_root = ET.fromstring(article_xml) # Get basic article data article = { "pmid": pmid, "title": self._get_xml_text(article_root, './/ArticleTitle') or "No title", "abstract": self._get_full_abstract(article_root) or "No abstract available", "journal": self._get_xml_text(article_root, './/Journal/Title') or "", "authors": [], "keywords": [], "mesh_terms": [] } # Get authors author_list = article_root.findall('.//Author') for author in author_list: last_name = self._get_xml_text(author, 'LastName') or "" fore_name = self._get_xml_text(author, 'ForeName') or "" if last_name or fore_name: article["authors"].append(f"{last_name} {fore_name}".strip()) # Get publication date pub_date = article_root.find('.//PubDate') if pub_date is not None: year = self._get_xml_text(pub_date, 'Year') month = self._get_xml_text(pub_date, 'Month') day = self._get_xml_text(pub_date, 'Day') article["publication_date"] = { "year": year, "month": month, "day": day } # Get DOI and PMCID if available # Important: Only get ArticleIds from the main ArticleIdList, not from references pubmed_data = article_root.find('.//PubmedData') if pubmed_data is not None: # Use direct child path to avoid getting IDs from ReferenceList article_id_list_elem = pubmed_data.find('ArticleIdList') if article_id_list_elem is not None: for article_id in article_id_list_elem: id_type = article_id.get('IdType') if id_type == 'doi': article["doi"] = article_id.text elif id_type == 'pmc': article["pmcid"] = article_id.text # Get Keywords keyword_list = article_root.findall('.//Keyword') for keyword in keyword_list: if keyword.text: # Clean up keyword text (remove trailing periods, etc.) clean_keyword = keyword.text.strip().rstrip('.') if clean_keyword: article["keywords"].append(clean_keyword) # Get MeSH terms mesh_heading_list = article_root.findall('.//MeshHeading') for mesh_heading in mesh_heading_list: descriptor = mesh_heading.find('DescriptorName') if descriptor is not None and descriptor.text: mesh_term = { "descriptor": descriptor.text, "ui": descriptor.get('UI', ''), "qualifiers": [] } # Get qualifiers if present qualifiers = mesh_heading.findall('QualifierName') for qualifier in qualifiers: if qualifier.text: mesh_term["qualifiers"].append({ "name": qualifier.text, "ui": qualifier.get('UI', '') }) article["mesh_terms"].append(mesh_term) return article return None except Exception as e: logger.exception(f"Error getting article details for PMID {pmid}: {str(e)}") return None