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)

  MCP tool handler for 'get_top_topics'. Defines input schema with Pydantic Annotated Fields and comprehensive docstring. Executes core logic by delegating to the DiscourseClient implementation.

  @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 structure for each topic in the list returned by get_top_topics.

  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_tools/__init__.py:25-26 (registration)

  Explicit import of the get_top_topics tool from topics.py into the server_tools __init__, making it available for re-export and MCP server registration.

  from .topics import get_hot_topics, get_new_topics, get_top_topics
  from .search import search_forum

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

  Low-level API implementation in TopicsAPI that makes HTTP request to /top.json and parses JSON response into TopicSummary objects.

  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 that calls the API layer 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)