get_topic_info
Retrieve topic metadata to check post count, title, and timestamps before fetching content, enabling efficient pagination planning for forum 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 posts
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| topic_id | Yes | The numeric topic ID (from URLs like /t/slug/12345) |
Implementation Reference
- MCP tool handler for 'get_topic_info'. Decorated with @mcp.tool(), defines input schema via Annotated Field, calls client.get_topic_info(topic_id), returns TopicInfo.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) for 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/api/topics.py:98-115 (helper)TopicsAPI.get_topic_info: Fetches topic metadata from Discourse /t/{id}.json endpoint and parses into TopicInfo.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:200-210 (helper)DiscourseClient.get_topic_info: Wrapper that delegates to underlying TopicsAPI implementation.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)
- src/uscardforum/server_tools/__init__.py:32-32 (registration)Imports the get_topic_info tool from topics.py for exposure in the server_tools package.from .topics import get_topic_info, get_topic_posts, get_all_topic_posts