USCardForum MCP Server

Instructions

Implementation Reference

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

  MCP tool handler for get_top_topics: @mcp.tool()-decorated function that defines input schema via Annotated Fields and delegates execution to DiscourseClient.get_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 BaseModel TopicSummary defining the output schema (list[TopicSummary]) for the get_top_topics tool
  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:25-46 (registration)

  Imports the get_top_topics tool from server_tools (among other MCP tools), which registers it in the MCP server via the @mcp.tool decorator
  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)

  Low-level TopicsAPI.get_top_topics method that performs the HTTP GET /top.json request with period/page parameters and parses the 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)

  DiscourseClient.get_top_topics wrapper method that delegates to TopicsAPI.get_top_topics and enriches TopicSummary objects 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)