USCardForum MCP Server

Instructions

Implementation Reference

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

  MCP tool handler for get_topic_posts. Defines input schema via Annotated Fields and calls client to fetch posts.
  @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/models/topics.py:40-58 (schema)

  Pydantic BaseModel for Post objects returned by get_topic_posts, defining output schema and validation.
  class Post(BaseModel): """A single post within a topic.""" id: int = Field(..., description="Unique post identifier") post_number: int = Field(..., description="Position in topic (1-indexed)") username: str = Field(..., description="Author's username") cooked: str | None = Field(None, description="HTML-rendered content") raw: str | None = Field(None, description="Raw markdown source") created_at: datetime | None = Field(None, description="When posted") updated_at: datetime | None = Field(None, description="Last edit time") like_count: int = Field(0, description="Number of likes") reply_count: int = Field(0, description="Number of direct replies") reply_to_post_number: int | None = Field( None, description="Post number this replies to" ) class Config: extra = "ignore"
• src/uscardforum/server.py:15-45 (registration)

  Imports get_topic_posts into server.py __all__, enabling FastMCP to discover and register the tool.
  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)

  DiscourseClient helper method implementing get_topic_posts by delegating to TopicsAPI.
  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 )