USCardForum MCP Server

Instructions

Implementation Reference

• src/uscardforum/server_tools/topics.py:201-256 (handler)

  MCP tool handler implementation for get_all_topic_posts, including input schema via Pydantic Annotated Fields and delegation to client API.
  @mcp.tool() def get_all_topic_posts( topic_id: Annotated[ int, Field(description="The numeric topic ID"), ], include_raw: Annotated[ bool, Field(default=False, description="Include markdown source (default: False)"), ] = False, start_post_number: Annotated[ int, Field(default=1, description="First post to fetch (default: 1)"), ] = 1, end_post_number: Annotated[ int | None, Field(default=None, description="Last post to fetch (optional, fetches to end if not set)"), ] = None, max_posts: Annotated[ int | None, Field(default=None, description="Maximum number of posts to return (optional safety limit)"), ] = None, ) -> list[Post]: """ Fetch all posts from a topic with automatic pagination. Args: topic_id: The numeric topic ID include_raw: Include markdown source (default: False) start_post_number: First post to fetch (default: 1) end_post_number: Last post to fetch (optional, fetches to end if not set) max_posts: Maximum number of posts to return (optional safety limit) This automatically handles pagination to fetch multiple batches. IMPORTANT: For topics with many posts (>100), use max_posts to limit the response size. You can always fetch more with start_post_number. Use cases: - Fetch entire small topic: get_all_topic_posts(topic_id=123) - Fetch first 50 posts: get_all_topic_posts(topic_id=123, max_posts=50) - Fetch posts 51-100: get_all_topic_posts(topic_id=123, start_post_number=51, max_posts=50) - Fetch specific range: get_all_topic_posts(topic_id=123, start=10, end=30) Returns the same Post structure as get_topic_posts but for all matching posts. Pro tip: Use get_topic_info first to check post_count before deciding whether to fetch all or paginate manually. """ return get_client().get_all_topic_posts( topic_id, include_raw=include_raw, start_post_number=start_post_number, end_post_number=end_post_number, max_posts=max_posts, )
• src/uscardforum/server_tools/topics.py:201-256 (schema)

  Input schema defined by Annotated parameters with Field descriptions for the get_all_topic_posts tool.
  @mcp.tool() def get_all_topic_posts( topic_id: Annotated[ int, Field(description="The numeric topic ID"), ], include_raw: Annotated[ bool, Field(default=False, description="Include markdown source (default: False)"), ] = False, start_post_number: Annotated[ int, Field(default=1, description="First post to fetch (default: 1)"), ] = 1, end_post_number: Annotated[ int | None, Field(default=None, description="Last post to fetch (optional, fetches to end if not set)"), ] = None, max_posts: Annotated[ int | None, Field(default=None, description="Maximum number of posts to return (optional safety limit)"), ] = None, ) -> list[Post]: """ Fetch all posts from a topic with automatic pagination. Args: topic_id: The numeric topic ID include_raw: Include markdown source (default: False) start_post_number: First post to fetch (default: 1) end_post_number: Last post to fetch (optional, fetches to end if not set) max_posts: Maximum number of posts to return (optional safety limit) This automatically handles pagination to fetch multiple batches. IMPORTANT: For topics with many posts (>100), use max_posts to limit the response size. You can always fetch more with start_post_number. Use cases: - Fetch entire small topic: get_all_topic_posts(topic_id=123) - Fetch first 50 posts: get_all_topic_posts(topic_id=123, max_posts=50) - Fetch posts 51-100: get_all_topic_posts(topic_id=123, start_post_number=51, max_posts=50) - Fetch specific range: get_all_topic_posts(topic_id=123, start=10, end=30) Returns the same Post structure as get_topic_posts but for all matching posts. Pro tip: Use get_topic_info first to check post_count before deciding whether to fetch all or paginate manually. """ return get_client().get_all_topic_posts( topic_id, include_raw=include_raw, start_post_number=start_post_number, end_post_number=end_post_number, max_posts=max_posts, )
• src/uscardforum/server_tools/__init__.py:32-32 (registration)

  Registration via import in server_tools __init__.py, making the tool available for higher-level imports.
  from .topics import get_topic_info, get_topic_posts, get_all_topic_posts
• src/uscardforum/server.py:20-20 (registration)

  Tool imported in main server.py entrypoint for MCP server registration.
  get_all_topic_posts,
• src/uscardforum/api/topics.py:165-221 (helper)

  Supporting utility in API layer implementing the pagination logic for fetching all topic posts.
  def get_all_topic_posts( self, topic_id: int, *, include_raw: bool = False, start_post_number: int = 1, end_post_number: int | None = None, max_posts: int | None = None, ) -> list[Post]: """Fetch all posts in a topic with automatic pagination. Args: topic_id: Topic ID include_raw: Include raw markdown (default: False) start_post_number: Starting post number (default: 1) end_post_number: Optional ending post number max_posts: Optional maximum posts to fetch Returns: List of all matching posts """ current = max(1, int(start_post_number)) collected: list[Post] = [] seen_numbers: set[int] = set() while True: if max_posts is not None and len(collected) >= int(max_posts): break batch = self.get_topic_posts( topic_id, post_number=current, include_raw=include_raw ) if not batch: break last_in_batch: int | None = None for post in batch: pn = post.post_number if pn not in seen_numbers: if end_post_number is not None and pn > int(end_post_number): last_in_batch = last_in_batch or pn continue seen_numbers.add(pn) collected.append(post) last_in_batch = pn if max_posts is not None and len(collected) >= int(max_posts): break if last_in_batch is None: break current = last_in_batch + 1 if end_post_number is not None and current > int(end_post_number): break collected.sort(key=lambda p: p.post_number) return collected