get_topic_info
Retrieve topic metadata to plan pagination before reading posts, including title, post count, and timestamps from USCardForum discussions.
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 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) - 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, ) - 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)