USCardForum MCP Server

Instructions

Implementation Reference

• src/uscardforum/server_tools/topics.py:154-199 (handler)

  The MCP tool handler function for 'get_topic_posts', decorated with @mcp.tool(). It defines the input schema using Annotated[Field] and delegates to the DiscourseClient.get_topic_posts method.
  @mcp.tool() def get_topic_posts( topic_id: Annotated[ int, Field(description="The numeric topic ID"), ], post_number: Annotated[ int, Field(default=1, description="Which post number to start from (default: 1 = first post)"), ] = 1, include_raw: Annotated[ bool, Field(default=False, description="Include raw markdown source (default: False, returns HTML)"), ] = False, ) -> list[Post]: """ Fetch a batch of posts from a topic starting at a specific position. Args: topic_id: The numeric topic ID post_number: Which post number to start from (default: 1 = first post) include_raw: Include raw markdown source (default: False, returns HTML) This fetches ~20 posts per call starting from post_number. Use for paginated reading of topics. Returns a list of Post objects with: - post_number: Position in topic (1, 2, 3...) - username: Author's username - cooked: HTML content of the post - raw: Markdown source (if include_raw=True) - created_at: When posted - updated_at: Last edit time - like_count: Number of likes - reply_count: Number of direct replies - reply_to_post_number: Which post this replies to (if any) Pagination example: 1. Call with post_number=1, get posts 1-20 2. Call with post_number=21, get posts 21-40 3. Continue until no posts returned """ return get_client().get_topic_posts( topic_id, post_number=post_number, include_raw=include_raw )
• src/uscardforum/server.py:15-45 (registration)

  Import statement in the main server entrypoint that brings in the get_topic_posts tool handler (line 28), making it available for automatic registration via the @mcp.tool() decorator when the module is imported and the server runs.
  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, )
• src/uscardforum/client.py:211-231 (helper)

  Helper method in DiscourseClient that wraps the TopicsAPI.get_topic_posts, called by the MCP tool handler via get_client().
  def get_topic_posts( self, topic_id: int, *, post_number: int = 1, include_raw: bool = False, ) -> list[Post]: """Fetch a batch of posts starting at a specific post number. Args: topic_id: Topic ID post_number: Starting post number (default: 1) include_raw: Include raw markdown (default: False) Returns: List of posts sorted by post_number """ return self._topics.get_topic_posts( topic_id, post_number=post_number, include_raw=include_raw )
• src/uscardforum/server_tools/topics.py:8-8 (schema)

  Import of Post model used as return type for get_topic_posts tool, defining the output schema.
  from uscardforum.models.topics import Post, TopicInfo, TopicSummary