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 MCP tool handler for 'get_top_topics', decorated with @mcp.tool(). Defines input parameters with Pydantic Field descriptions and calls the underlying client to fetch top topics.

  @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 structure of each TopicSummary object returned by the get_top_topics tool (output schema).

  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:56-63 (registration)

  Import statement that brings get_top_topics into the server_tools namespace, triggering the @mcp.tool() decorator registration when the package is imported.

  from .topics import (
      get_all_topic_posts,
      get_hot_topics,
      get_new_topics,
      get_top_topics,
      get_topic_info,
      get_topic_posts,
  )

• src/uscardforum/api/topics.py:72-98 (helper)

  Underlying API implementation in TopicsAPI that makes the HTTP request to /top.json and parses the 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(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:201-214 (helper)

  Client wrapper method that calls the API and enriches topics 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)