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 primary MCP tool handler for 'get_topic_info'. Defined with @mcp.tool() decorator, includes input schema via Annotated[int, Field()], detailed docstring, and delegates to client API.

  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 (TopicInfo) returned by the get_topic_info tool.

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

  Import of get_topic_info from topics.py into server_tools package, making it available for export to server.py.

  from .topics import get_topic_info, get_topic_posts, get_all_topic_posts

• src/uscardforum/server.py:27-27 (registration)

  Import of get_topic_info into the main server.py entrypoint, where all MCP tools are collected and exposed.

  get_topic_info,

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

  Underlying API helper method in TopicsAPI that implements the core logic: HTTP GET to /t/{topic_id}.json and constructs TopicInfo from response.

  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"),
      )