USCardForum MCP Server

Instructions

Implementation Reference

• src/uscardforum/server_tools/topics.py:49-79 (handler)

  The @mcp.tool()-decorated function implementing the core logic of the get_new_topics MCP tool. It delegates to the DiscourseClient's get_new_topics method.
  @mcp.tool() def get_new_topics( page: Annotated[ int | None, Field(default=None, description="Page number for pagination (0-indexed, default: 0)"), ] = None, ) -> list[TopicSummary]: """ Fetch the latest/newest topics from USCardForum. Returns recently created topics sorted by creation time (newest first). These may have fewer replies but contain fresh information. Use this to: - Find newly posted deals or offers - See fresh questions from the community - Discover emerging discussions before they get popular Args: page: Page number for pagination (0-indexed). Use page=1 to get more topics. Returns a list of TopicSummary objects with: - id: Topic ID - title: Topic title - posts_count: Number of posts - created_at: When the topic was created - category_id: Which forum section it's in Tip: New topics with high view counts may indicate important news. """ return get_client().get_new_topics(page=page)
• src/uscardforum/models/topics.py:10-25 (schema)

  Pydantic BaseModel defining the structure of TopicSummary objects returned by get_new_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-25 (registration)

  Import statement that exposes get_new_topics as part of the server_tools package, enabling its registration in the MCP server.
  from .topics import get_hot_topics, get_new_topics, get_top_topics
• src/uscardforum/api/topics.py:45-64 (helper)

  The TopicsAPI method that fetches new topics by making an HTTP GET request to /latest.json and parsing the response into TopicSummary objects.
  def get_new_topics(self, *, page: int | None = None) -> list[TopicSummary]: """Fetch latest new topics. Args: page: Page number for pagination (0-indexed, default: 0) Returns: List of new topic summaries """ params: dict[str, Any] = {} if page is not None: params["page"] = int(page) payload = self._get( "/latest.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:173-183 (helper)

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