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-119 (handler)

  Primary MCP tool handler for get_top_topics. Defines input parameters with validation and descriptions (schema). Executes by calling the shared DiscourseClient instance.

  @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/models/topics.py:10-25 (schema)

  Pydantic model defining the output schema for get_top_topics (list[TopicSummary]). Used for response serialization and validation.

  class TopicSummary(BaseModel):
      """Summary of a topic for list views (hot, new, top topics)."""
  
      id: int = Field(..., description="Unique topic identifier")
      title: str = Field(..., description="Topic title")
      posts_count: int = Field(0, description="Total number of posts")
      views: int = Field(0, description="Total view count")
      like_count: int = Field(0, description="Total likes on the topic")
      category_id: int | None = Field(None, description="Category identifier")
      category_name: str | None = Field(None, description="Category name")
      created_at: datetime | None = Field(None, description="When topic was created")
      last_posted_at: datetime | None = Field(None, description="Last activity time")
  
      class Config:
          extra = "ignore"

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

  Explicit import of all server tools including get_top_topics into the server entrypoint module. Triggers auto-registration of @mcp.tool() decorated functions when mcp.run() is called.

  from uscardforum.server_tools import (
      analyze_user,
      bookmark_post,
      compare_cards,
      find_data_points,
      get_all_topic_posts,
      get_categories,
      get_current_session,
      get_hot_topics,
      get_new_topics,
      get_notifications,
      get_top_topics,
      get_topic_info,
      get_topic_posts,
      get_user_actions,
      get_user_badges,
      get_user_followers,
      get_user_following,
      get_user_reactions,
      get_user_replies,
      get_user_summary,
      get_user_topics,
      list_users_with_badge,
      login,
      research_topic,
      resource_categories,
      resource_hot_topics,
      resource_new_topics,
      search_forum,
      subscribe_topic,
  )

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

  Core API helper that performs the HTTP GET request to /top.json endpoint, parses response, and constructs TopicSummary objects. Called by client.get_top_topics().

  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/client.py:185-198 (helper)

  Client wrapper method that calls TopicsAPI.get_top_topics() and enriches results with category names.

  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)