PubMed MCP Server

Instructions

Implementation Reference

• src/tool_handler.py:503-585 (handler)

  Main handler function that performs yearly PubMed searches for the given topic over the specified number of years, calculates publication counts, growth rates, and formats a trend analysis response including recent notable articles.

  async def _handle_analyze_research_trends(self, arguments: Dict[str, Any]) -> MCPResponse:
      """Handle research trend analysis."""
      try:
          topic = arguments.get("topic", "")
          if not topic:
              return MCPResponse(
                  content=[{"type": "text", "text": "Topic is required"}], is_error=True
              )
  
          years_back = arguments.get("years_back", 5)
          # include_subtopics parameter is available but not currently used
          # include_subtopics = arguments.get("include_subtopics", False)
  
          # Analyze trends year by year
          current_year = datetime.now().year
          yearly_data = []
  
          for year in range(current_year - years_back, current_year + 1):
              search_result = await self.pubmed_client.search_articles(
                  query=topic,
                  max_results=200,  # Get more results for trend analysis
                  date_from=f"{year}/01/01",
                  date_to=f"{year}/12/31",
                  cache=self.cache,
              )
              yearly_data.append(
                  {
                      "year": year,
                      "count": search_result.total_results,
                      "articles": search_result.articles[:5],  # Top 5 articles
                  }
              )
  
          content = []
          content.append(
              {
                  "type": "text",
                  "text": f"**Research Trends for: {topic}**\n\n"
                  f"Analysis Period: {current_year - years_back} - {current_year}\n",
              }
          )
  
          # Show yearly trends
          trend_text = "**Publication Counts by Year:**\n"
          for data in yearly_data:
              trend_text += f"{data['year']}: {data['count']:,} articles\n"
  
          content.append({"type": "text", "text": trend_text})
  
          # Calculate growth
          if len(yearly_data) >= 2:
              recent_avg = sum([d["count"] for d in yearly_data[-2:]]) / 2
              early_avg = sum([d["count"] for d in yearly_data[:2]]) / 2
              growth_rate = ((recent_avg - early_avg) / early_avg * 100) if early_avg > 0 else 0
  
              content.append(
                  {
                      "type": "text",
                      "text": f"\n**Growth Analysis:**\n"
                      f"Recent average: {recent_avg:.0f} articles/year\n"
                      f"Early average: {early_avg:.0f} articles/year\n"
                      f"Growth rate: {growth_rate:+.1f}%\n",
                  }
              )
  
          # Show recent notable articles
          recent_articles = yearly_data[-1]["articles"] if yearly_data else []
          if recent_articles:
              content.append(
                  {"type": "text", "text": f"\n**Recent Notable Articles ({current_year}):**\n"}
              )
  
              for i, article_data in enumerate(recent_articles[:3], 1):
                  article_text = self._format_article_summary(article_data, i)
                  content.append({"type": "text", "text": article_text})
  
          return MCPResponse(content=content)
  
      except Exception as e:
          logger.error(f"Error in analyze_research_trends: {e}")
          return MCPResponse(
              content=[{"type": "text", "text": f"Error: {str(e)}"}], is_error=True
          )

• src/tools.py:247-269 (schema)

  JSON schema defining the input parameters for the analyze_research_trends tool, including required 'topic' and optional 'years_back' and 'include_subtopics'.

  {
      "name": "analyze_research_trends",
      "description": ("Analyze publication trends for a research topic over time"),
      "inputSchema": {
          "type": "object",
          "properties": {
              "topic": {"type": "string", "description": "Research topic to analyze"},
              "years_back": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 20,
                  "default": 5,
                  "description": "Number of years to analyze",
              },
              "include_subtopics": {
                  "type": "boolean",
                  "default": False,
                  "description": "Include analysis of related subtopics",
              },
          },
          "required": ["topic"],
      },
  },

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

  Tool registration mapping in handle_tool_call method, associating the 'analyze_research_trends' tool name with its handler _handle_analyze_research_trends.

  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,
  }