USCardForum MCP Server

Instructions

Implementation Reference

• src/uscardforum/server_tools/topics.py:12-47 (handler)

  MCP tool handler function for 'get_hot_topics' decorated with @mcp.tool(), delegates to DiscourseClient.get_hot_topics()
  @mcp.tool() def get_hot_topics( page: Annotated[ int | None, Field(default=None, description="Page number for pagination (0-indexed, default: 0)"), ] = None, ) -> list[TopicSummary]: """ Fetch currently trending/hot topics from USCardForum. This returns the most actively discussed topics right now, ranked by engagement metrics like recent replies, views, and likes. Use this to: - See what the community is currently discussing - Find breaking news or time-sensitive opportunities - Discover popular ongoing discussions Args: page: Page number for pagination (0-indexed). Use page=1 to get more topics. Returns a list of TopicSummary objects with fields: - id: Topic ID (use with get_topic_posts) - title: Topic title - posts_count: Total replies - views: View count - like_count: Total likes - created_at: Creation timestamp - last_posted_at: Last activity timestamp Example response interpretation: A topic with high views but low posts may be informational. A topic with many recent posts is actively being discussed. """ return get_client().get_hot_topics(page=page)
• src/uscardforum/models/topics.py:10-25 (schema)

  Pydantic model defining the output schema for get_hot_topics (list[TopicSummary])
  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 get_hot_topics in the main server entrypoint, which triggers registration via @mcp.tool() decorator
  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:24-44 (helper)

  Core API implementation that performs the HTTP request to /hot.json and parses into TopicSummary objects
  def get_hot_topics(self, *, page: int | None = None) -> list[TopicSummary]: """Fetch currently trending topics. Args: page: Page number for pagination (0-indexed, default: 0) Returns: List of hot topic summaries """ params: dict[str, Any] = {} if page is not None: params["page"] = int(page) payload = self._get( "/hot.json", params=params or None, headers={"Accept": "application/json, text/plain, */*"}, ) topics = payload.get("topic_list", {}).get("topics", []) return [TopicSummary(**t) for t in topics]
• src/uscardforum/client.py:161-172 (helper)

  Client wrapper that delegates to TopicsAPI and enriches with category names
  def get_hot_topics(self, *, page: int | None = None) -> list[TopicSummary]: """Fetch currently hot/trending topics. Args: page: Page number for pagination (0-indexed, default: 0) Returns: List of hot topic summaries """ topics = self._topics.get_hot_topics(page=page) return self._enrich_with_categories(topics)