Jupiter Broadcasting Podcast Data MCP Server

Instructions

Implementation Reference

• podcast_mcp/server.py:35-86 (handler)

  MCP tool handler for 'search_episodes'. Registered via @mcp.tool() decorator. Validates inputs, delegates search to rss_parser, adds pagination, and handles errors. Function signature and docstring define the tool schema.

  @mcp.tool()
  def search_episodes(
      show_name: str,
      since_date: Optional[str] = None,
      before_date: Optional[str] = None,
      hosts: Optional[List[str]] = None,
      text_search: Optional[str] = None,
      page: int = 1,
      per_page: int = 5,
  ) -> Dict[str, Any]:
      """Search for episodes based on various criteria. At least one search parameter must be provided.
      
      Args:
          show_name: Name of the specific show to search in (required)
          since_date: Only return episodes published on or after this date (YYYY-MM-DD or ISO format)
          before_date: Only return episodes published before this date (YYYY-MM-DD or ISO format)
          hosts: List of host names to filter by
          text_search: Search text to match against episode titles and descriptions
          page: Page number (1-indexed, default: 1)
          per_page: Number of results per page (default: 5)
      
      Returns:
          Dictionary containing episodes, pagination info (total, page, per_page, total_pages).
      """
      try:
          results = rss_parser.search_episodes(
              show_name=show_name,
              since_date=since_date,
              before_date=before_date,
              hosts=hosts,
              text_search=text_search,
          )
          
          total = len(results)
          total_pages = (total + per_page - 1) // per_page if per_page > 0 else 0
          start_idx = (page - 1) * per_page
          end_idx = start_idx + per_page
          
          return {
              "episodes": results[start_idx:end_idx],
              "pagination": {
                  "total": total,
                  "page": page,
                  "per_page": per_page,
                  "total_pages": total_pages,
              }
          }
      except ValueError as e:
          return {"error": str(e)}
      except Exception as e:
          return {"error": f"Search failed: {str(e)}"}

• podcast_mcp/rss_parser.py:114-175 (helper)

  Helper method in PodcastRSSParser class implementing the core search logic: fetches RSS feeds, parses episodes, applies date/host/text filters, and collects matching episodes.

  def search_episodes(
      self,
      show_name: Optional[str] = None,
      since_date: Optional[str] = None,
      before_date: Optional[str] = None,
      hosts: Optional[List[str]] = None,
      text_search: Optional[str] = None,
  ) -> List[Dict[str, Any]]:
      """Search episodes based on provided criteria."""
      if not any([show_name, since_date, before_date, hosts, text_search]):
          raise ValueError("At least one search parameter must be provided")
      
      results = []
      
      # Determine which shows to search
      shows_to_search = [show_name] if show_name else self.get_shows()
      
      # Parse date filters
      since_dt = None
      before_dt = None
      if since_date:
          since_dt = self._parse_date(since_date)
      if before_date:
          before_dt = self._parse_date(before_date)
      
      for show in shows_to_search:
          feed_root = self._get_feed(show)
          if feed_root is None:
              continue
              
          # Find all item elements (episodes)
          items = feed_root.xpath('//item')
          for item in items:
              episode_data = self._parse_episode(show, item)
              
              # Apply filters
              if since_dt and episode_data.get("published_date"):
                  episode_dt = self._parse_date(episode_data["published_date"])
                  if episode_dt and episode_dt < since_dt:
                      continue
              
              if before_dt and episode_data.get("published_date"):
                  episode_dt = self._parse_date(episode_data["published_date"])
                  if episode_dt and episode_dt > before_dt:
                      continue
              
              if hosts:
                  episode_hosts = episode_data.get("hosts", [])
                  if not any(host.lower() in [h.lower() for h in episode_hosts] for host in hosts):
                      continue
              
              if text_search:
                  search_text = text_search.lower()
                  title = episode_data.get("title", "").lower()
                  description = episode_data.get("description", "").lower()
                  if search_text not in title and search_text not in description:
                      continue
              
              results.append(episode_data)
      
      return results