get_topic_info
Retrieve topic metadata to plan efficient content retrieval. Check post count, title, and timestamps before fetching posts 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 posts
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| topic_id | Yes | The numeric topic ID (from URLs like /t/slug/12345) |
Implementation Reference
- Primary MCP tool handler for get_topic_info, including @mcp.tool() registration decorator, input schema definition, comprehensive docstring, and delegation to client implementation.@mcp.tool() 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 BaseModel defining the structured output schema 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/api/topics.py:98-115 (helper)Underlying API logic in TopicsAPI that performs the HTTP request to Discourse API endpoint /t/{topic_id}.json and parses response into TopicInfo model.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 wrapper method that delegates get_topic_info call to the internal TopicsAPI instance.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.py:15-85 (registration)Imports the get_topic_info tool function (with @mcp.tool decorator) into the main server entrypoint, triggering FastMCP registration when the module is imported/executed.from uscardforum.server_tools import ( analyze_user, bookmark_post, compare_cards, find_data_points, get_all_topic_posts, get_categories, get_current_session, get_hot_topics, get_new_topics, get_notifications, get_top_topics, get_topic_info, get_topic_posts, get_user_actions, get_user_badges, get_user_followers, get_user_following, get_user_reactions, get_user_replies, get_user_summary, get_user_topics, list_users_with_badge, login, research_topic, resource_categories, resource_hot_topics, resource_new_topics, search_forum, subscribe_topic, ) __all__ = [ "MCP_HOST", "MCP_PORT", "MCP_TRANSPORT", "NITAN_TOKEN", "SERVER_INSTRUCTIONS", "get_client", "main", "mcp", "analyze_user", "bookmark_post", "compare_cards", "find_data_points", "get_all_topic_posts", "get_categories", "get_current_session", "get_hot_topics", "get_new_topics", "get_notifications", "get_top_topics", "get_topic_info", "get_topic_posts", "get_user_actions", "get_user_badges", "get_user_followers", "get_user_following", "get_user_reactions", "get_user_replies", "get_user_summary", "get_user_topics", "list_users_with_badge", "login", "resource_categories", "resource_hot_topics", "resource_new_topics", "search_forum", "subscribe_topic", "research_topic", ]