get_topic_info
Retrieve topic metadata to plan pagination and content fetching for USCardForum discussions. Check post count, title, and timestamps before reading full content.
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 postsInput Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| topic_id | Yes | The numeric topic ID (from URLs like /t/slug/12345) |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Topic title | |
| topic_id | Yes | Topic identifier | |
| post_count | No | Total number of posts | |
| last_posted_at | No | Last activity time | |
| highest_post_number | No | Highest post number |
Implementation Reference
- 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) - 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"), )