USCardForum MCP Server

Instructions

Get metadata about a specific topic without fetching all posts.

Args:
    topic_id: The numeric topic ID (from URLs like /t/slug/12345)

Use this FIRST before reading a topic to:
- Check how many posts it contains (for pagination planning)
- Get the topic title and timestamps
- Decide whether to fetch all posts or paginate

Returns a TopicInfo object with:
- topic_id: The topic ID
- title: Full topic title
- post_count: Total number of posts
- highest_post_number: Last post number (may differ from count if posts deleted)
- last_posted_at: When the last reply was made

Strategy for large topics:
- <50 posts: Safe to fetch all at once
- 50-200 posts: Consider using max_posts parameter
- >200 posts: Fetch in batches or summarize key posts

Implementation Reference

• src/uscardforum/server_tools/topics.py:122-152 (handler)

  The main MCP tool handler for 'get_topic_info'. Uses @mcp.tool() decorator to register the function, which delegates to the DiscourseClient via get_client().

  def get_topic_info(
      topic_id: Annotated[
          int,
          Field(description="The numeric topic ID (from URLs like /t/slug/12345)"),
      ],
  ) -> TopicInfo:
      """
      Get metadata about a specific topic without fetching all posts.
  
      Args:
          topic_id: The numeric topic ID (from URLs like /t/slug/12345)
  
      Use this FIRST before reading a topic to:
      - Check how many posts it contains (for pagination planning)
      - Get the topic title and timestamps
      - Decide whether to fetch all posts or paginate
  
      Returns a TopicInfo object with:
      - topic_id: The topic ID
      - title: Full topic title
      - post_count: Total number of posts
      - highest_post_number: Last post number (may differ from count if posts deleted)
      - last_posted_at: When the last reply was made
  
      Strategy for large topics:
      - <50 posts: Safe to fetch all at once
      - 50-200 posts: Consider using max_posts parameter
      - >200 posts: Fetch in batches or summarize key posts
      """
      return get_client().get_topic_info(topic_id)

• src/uscardforum/models/topics.py:27-38 (schema)

  Pydantic model defining the output schema for get_topic_info tool (TopicInfo). The input schema is defined inline via Annotated Field in the handler.

  class TopicInfo(BaseModel):
      """Detailed topic metadata."""
  
      topic_id: int = Field(..., description="Topic identifier")
      title: str | None = Field(None, description="Topic title")
      post_count: int = Field(0, description="Total number of posts")
      highest_post_number: int = Field(0, description="Highest post number")
      last_posted_at: datetime | None = Field(None, description="Last activity time")
  
      class Config:
          extra = "ignore"

• src/uscardforum/server_tools/__init__.py:56-63 (registration)

  Registration/export of the get_topic_info tool by importing from topics.py submodule. These are then re-exported in __all__ and imported into the main MCP server.py.

  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:104-121 (helper)

  Core API implementation that fetches topic metadata from Discourse JSON endpoint /t/{id}.json. Called by client wrapper and ultimately by the tool handler.

  def get_topic_info(self, topic_id: int) -> TopicInfo:
      """Fetch topic metadata.
  
      Args:
          topic_id: Topic ID
  
      Returns:
          Topic info with post count, title, timestamps
      """
      payload = self._get(f"/t/{int(topic_id)}.json")
      return TopicInfo(
          topic_id=topic_id,
          title=payload.get("title"),
          post_count=payload.get("posts_count", 0),
          highest_post_number=payload.get("highest_post_number", 0),
          last_posted_at=payload.get("last_posted_at"),
      )

• src/uscardforum/client.py:216-225 (helper)

  Client wrapper method that delegates to TopicsAPI.get_topic_info. Invoked by server_tools get_client().

  def get_topic_info(self, topic_id: int) -> TopicInfo:
      """Fetch topic metadata.
  
      Args:
          topic_id: Topic ID
  
      Returns:
          Topic info with post count, title, timestamps
      """
      return self._topics.get_topic_info(topic_id)