USCardForum MCP Server

Instructions

Fetch top-performing topics for a specific time period.

Args:
    period: Time window for ranking. Must be one of:
        - "daily": Top topics from today
        - "weekly": Top topics this week
        - "monthly": Top topics this month (default)
        - "quarterly": Top topics this quarter
        - "yearly": Top topics this year
    page: Page number for pagination (0-indexed). Use page=1 to get more topics.

Use this to:
- Find the most valuable discussions in a time range
- Research historically important threads
- Identify evergreen popular content

Returns TopicSummary objects sorted by engagement score.

Example: Use "yearly" to find the most impactful discussions,
or "daily" to see what's trending today.

Implementation Reference

• src/uscardforum/server_tools/topics.py:82-118 (handler)

  The primary MCP tool handler for 'get_top_topics', decorated with @mcp.tool(). Defines the input schema using Pydantic's Annotated and Field for parameters 'period' and 'page'. Includes comprehensive docstring. Delegates execution to the underlying DiscourseClient instance via get_client().

  @mcp.tool()
  def get_top_topics(
      period: Annotated[
          str,
          Field(
              default="monthly",
              description="Time window for ranking: 'daily', 'weekly', 'monthly' (default), 'quarterly', or 'yearly'",
          ),
      ] = "monthly",
      page: Annotated[
          int | None,
          Field(default=None, description="Page number for pagination (0-indexed, default: 0)"),
      ] = None,
  ) -> list[TopicSummary]:
      """
      Fetch top-performing topics for a specific time period.
  
      Args:
          period: Time window for ranking. Must be one of:
              - "daily": Top topics from today
              - "weekly": Top topics this week
              - "monthly": Top topics this month (default)
              - "quarterly": Top topics this quarter
              - "yearly": Top topics this year
          page: Page number for pagination (0-indexed). Use page=1 to get more topics.
  
      Use this to:
      - Find the most valuable discussions in a time range
      - Research historically important threads
      - Identify evergreen popular content
  
      Returns TopicSummary objects sorted by engagement score.
  
      Example: Use "yearly" to find the most impactful discussions,
      or "daily" to see what's trending today.
      """
      return get_client().get_top_topics(period=period, page=page)

• src/uscardforum/client.py:185-198 (helper)

  DiscourseClient wrapper method for get_top_topics. Calls the TopicsAPI implementation and enriches the TopicSummary objects with category names using _enrich_with_categories.

  def get_top_topics(
      self, period: str = "monthly", *, page: int | None = None
  ) -> list[TopicSummary]:
      """Fetch top topics for a time period.
  
      Args:
          period: One of 'daily', 'weekly', 'monthly', 'quarterly', 'yearly'
          page: Page number for pagination (0-indexed, default: 0)
  
      Returns:
          List of top topic summaries
      """
      topics = self._topics.get_top_topics(period=period, page=page)
      return self._enrich_with_categories(topics)

• src/uscardforum/api/topics.py:66-92 (helper)

  Low-level TopicsAPI.get_top_topics implementation. Performs HTTP GET to '/top.json' with 'period' and 'page' parameters, validates period, parses JSON response from Discourse API, and constructs list of TopicSummary Pydantic models.

  def get_top_topics(
      self, period: str = "monthly", *, page: int | None = None
  ) -> list[TopicSummary]:
      """Fetch top topics for a time period.
  
      Args:
          period: One of 'daily', 'weekly', 'monthly', 'quarterly', 'yearly'
          page: Page number for pagination (0-indexed, default: 0)
  
      Returns:
          List of top topic summaries
      """
      allowed = {"daily", "weekly", "monthly", "quarterly", "yearly"}
      if period not in allowed:
          raise ValueError(f"period must be one of {sorted(list(allowed))}")
  
      params: dict[str, Any] = {"period": period}
      if page is not None:
          params["page"] = int(page)
  
      payload = self._get(
          "/top.json",
          params=params,
          headers={"Accept": "application/json, text/plain, */*"},
      )
      topics = payload.get("topic_list", {}).get("topics", [])
      return [TopicSummary(**t) for t in topics]

• src/uscardforum/server_tools/__init__.py:25-71 (registration)

  Import of get_top_topics from .topics module in server_tools __init__.py, making it available for import from the package.

  from .topics import get_hot_topics, get_new_topics, get_top_topics
  from .search import search_forum
  from .categories import get_categories
  
  # =============================================================================
  # 📖 Reading — Access topic content
  # =============================================================================
  from .topics import get_topic_info, get_topic_posts, get_all_topic_posts
  
  # =============================================================================
  # 👤 Users — Profile & activity research
  # =============================================================================
  from .users import (
      get_user_summary,
      get_user_topics,
      get_user_replies,
      get_user_actions,
      get_user_badges,
      get_user_following,
      get_user_followers,
      get_user_reactions,
      list_users_with_badge,
  )
  
  # =============================================================================
  # 🔐 Auth — Authenticated actions (requires login)
  # =============================================================================
  from .auth import (
      login,
      get_current_session,
      get_notifications,
      bookmark_post,
      subscribe_topic,
  )
  
  # =============================================================================
  # Prompts & Resources
  # =============================================================================
  from .prompts import analyze_user, compare_cards, find_data_points, research_topic
  from .resources import resource_categories, resource_hot_topics, resource_new_topics
  
  
  __all__ = [
      # 📰 Discovery
      "get_hot_topics",
      "get_new_topics",
      "get_top_topics",

• src/uscardforum/server.py:26-26 (registration)

  Import of get_top_topics in server.py entrypoint, exposing the tool for MCP server startup.

  get_top_topics,