PubMed MCP Server

Instructions

Implementation Reference

• src/tool_handler.py:179-218 (handler)

  MCP tool handler _handle_get_article_details: validates input arguments, calls PubMedClient.get_article_details, formats articles using _format_article_details, and constructs MCPResponse.

  async def _handle_get_article_details(self, arguments: Dict[str, Any]) -> MCPResponse:
      """Handle getting detailed article information."""
      try:
          pmids = arguments.get("pmids", [])
          if not pmids:
              return MCPResponse(
                  content=[{"type": "text", "text": "PMIDs parameter is required"}], is_error=True
              )
  
          include_abstracts = arguments.get("include_abstracts", True)
          include_citations = arguments.get("include_citations", False)
  
          articles = await self.pubmed_client.get_article_details(
              pmids=pmids,
              include_abstracts=include_abstracts,
              include_citations=include_citations,
              cache=self.cache,
          )
  
          content = []
          content.append(
              {"type": "text", "text": f"**Article Details for {len(articles)} Articles**\n"}
          )
  
          if articles:
              for i, article in enumerate(articles, 1):
                  article_text = self._format_article_details(article, i)
                  content.append({"type": "text", "text": article_text})
          else:
              content.append(
                  {"type": "text", "text": "No articles found for the provided PMIDs."}
              )
  
          return MCPResponse(content=content)
  
      except Exception as e:
          logger.error(f"Error in get_article_details: {e}")
          return MCPResponse(
              content=[{"type": "text", "text": f"Error: {str(e)}"}], is_error=True
          )

• src/tools.py:95-119 (schema)

  Tool schema definition specifying input parameters: required pmids array, optional include_abstracts and include_citations booleans.

  {
      "name": "get_article_details",
      "description": ("Get detailed information for specific articles by PMID"),
      "inputSchema": {
          "type": "object",
          "properties": {
              "pmids": {
                  "type": "array",
                  "items": {"type": "string"},
                  "description": "List of PubMed IDs",
              },
              "include_abstracts": {
                  "type": "boolean",
                  "default": True,
                  "description": "Include abstracts in response",
              },
              "include_citations": {
                  "type": "boolean",
                  "default": False,
                  "description": "Include citation count and metrics",
              },
          },
          "required": ["pmids"],
      },
  },

• src/tool_handler.py:65-78 (registration)

  Registration of get_article_details tool in the handler_map dictionary, mapping to the _handle_get_article_details method.

  handler_map = {
      "search_pubmed": self._handle_search_pubmed,
      "get_article_details": self._handle_get_article_details,
      "search_by_author": self._handle_search_by_author,
      "find_related_articles": self._handle_find_related_articles,
      "export_citations": self._handle_export_citations,
      "search_mesh_terms": self._handle_search_mesh_terms,
      "search_by_journal": self._handle_search_by_journal,
      "get_trending_topics": self._handle_get_trending_topics,
      "analyze_research_trends": self._handle_analyze_research_trends,
      "compare_articles": self._handle_compare_articles,
      "get_journal_metrics": self._handle_get_journal_metrics,
      "advanced_search": self._handle_advanced_search,
  }

• src/pubmed_client.py:207-257 (helper)

  PubMedClient.get_article_details: validates PMIDs, checks/sets cache, fetches details via EFetch API using _fetch_article_details and parses into Article objects.

  async def get_article_details(
      self,
      pmids: List[str],
      include_abstracts: bool = True,
      include_citations: bool = False,
      cache: Optional[CacheManager] = None,
  ) -> List[Article]:
      """
      Get detailed article information for specific PMIDs.
  
      Args:
          pmids: List of PubMed IDs
          include_abstracts: Include abstracts
          include_citations: Include citation metrics
          cache: Cache manager instance
  
      Returns:
          List of Article objects
      """
      # Validate PMIDs
      valid_pmids = [pmid for pmid in pmids if validate_pmid(pmid)]
      if len(valid_pmids) != len(pmids):
          logger.warning(f"Some invalid PMIDs provided: {set(pmids) - set(valid_pmids)}")
  
      if not valid_pmids:
          return []
  
      # Check cache
      if cache:
          cache_key = cache.generate_key(
              "article_details",
              pmids=valid_pmids,
              include_abstracts=include_abstracts,
              include_citations=include_citations,
          )
          cached_result = cache.get(cache_key)
          if cached_result:
              return [Article(**article) for article in cached_result]
  
      articles = await self._fetch_article_details(
          valid_pmids,
          include_full_details=True,
          include_citations=include_citations,
      )
  
      # Cache the result
      if cache:
          cache.set(cache_key, [article.model_dump() for article in articles])
  
      return articles

• src/tool_handler.py:896-947 (helper)

  _format_article_details helper: formats detailed Article object into rich text string for MCP response, including authors, journal, abstract, keywords, MeSH, links.

      def _format_article_details(self, article, index: int) -> str:
          """Format detailed article information."""
          # Authors with affiliations
          authors_text = ""
          for i, author in enumerate(article.authors[:5], 1):
              authors_text += f"{i}. {author.first_name or author.initials or ''} {author.last_name}"
              if author.affiliation:
                  authors_text += (
                      f" ({author.affiliation[:50]}...)"
                      if len(author.affiliation) > 50
                      else f" ({author.affiliation})"
                  )
              authors_text += "\n"
  
          if len(article.authors) > 5:
              authors_text += f"... and {len(article.authors) - 5} more authors\n"
  
          # Keywords
          keywords_str = ", ".join(article.keywords[:10]) if article.keywords else "No keywords"
  
          # DOI and links
          links_text = ""
          if article.doi:
              links_text += f"DOI: https://doi.org/{article.doi}\n"
          if article.pmc_id:
              links_text += f"PMC: https://www.ncbi.nlm.nih.gov/pmc/articles/{article.pmc_id}\n"
          links_text += f"PubMed: https://pubmed.ncbi.nlm.nih.gov/{article.pmid}\n"
  
          article_text = f"""
  **{index}. {article.title}**
  
  **Authors:**
  {authors_text}
  
  **Journal:** {article.journal.title}
  **Publication Date:** {format_date(article.pub_date)}
  **Volume/Issue:** {article.journal.volume or 'N/A'}/{article.journal.issue or 'N/A'}
  
  **Abstract:**
  {article.abstract or 'No abstract available'}
  
  **Keywords:** {keywords_str}
  
  **MeSH Terms:** {format_mesh_terms(article.mesh_terms)}
  
  **Article Types:** {', '.join(article.article_types) if article.article_types else 'Not specified'}
  
  **Links:**
  {links_text}
  """
          return article_text