USCardForum MCP Server

Instructions

Search USCardForum for topics and posts matching a query.

Args:
    query: Search query string. Supports Discourse operators:
        - Basic: "chase sapphire bonus"
        - In title only: "chase sapphire in:title"
        - By author: "@username chase"
        - In category: "category:credit-cards chase"
        - With tag: "#amex bonus"
        - Exact phrase: '"sign up bonus"'
        - Exclude: "chase -sapphire"
        - Time: "after:2024-01-01" or "before:2024-06-01"

    page: Page number for pagination (starts at 1)

    order: Sort order for results. Options:
        - "relevance": Best match (default)
        - "latest": Most recent first
        - "views": Most viewed
        - "likes": Most liked
        - "activity": Recent activity
        - "posts": Most replies

Returns a SearchResult object with:
- posts: List of matching SearchPost objects with excerpts
- topics: List of matching SearchTopic objects
- users: List of matching SearchUser objects
- grouped_search_result: Metadata about result counts

Example queries:
- "Chase Sapphire Reserve order:latest" - Recent CSR discussions
- "AMEX popup in:title" - Topics about AMEX popup in title
- "data point category:credit-cards" - Data points in CC category
- "@expert_user order:likes" - Most liked posts by a user

Pagination: If more results exist, increment page parameter.

Implementation Reference

• src/uscardforum/server_tools/search.py:12-70 (handler)

  Core handler function for the 'search_forum' MCP tool. Decorated with @mcp.tool(), defines input parameters with Pydantic Field descriptions, and delegates to the client's search method returning SearchResult.

  @mcp.tool()
  def search_forum(
      query: Annotated[
          str,
          Field(
              description="Search query string. Supports operators: 'in:title', '@username', 'category:name', '#tag', 'after:date', 'before:date'"
          ),
      ],
      page: Annotated[
          int | None,
          Field(default=None, description="Page number for pagination (starts at 1)"),
      ] = None,
      order: Annotated[
          str | None,
          Field(
              default=None,
              description="Sort order: 'relevance' (default), 'latest', 'views', 'likes', 'activity', or 'posts'",
          ),
      ] = None,
  ) -> SearchResult:
      """
      Search USCardForum for topics and posts matching a query.
  
      Args:
          query: Search query string. Supports Discourse operators:
              - Basic: "chase sapphire bonus"
              - In title only: "chase sapphire in:title"
              - By author: "@username chase"
              - In category: "category:credit-cards chase"
              - With tag: "#amex bonus"
              - Exact phrase: '"sign up bonus"'
              - Exclude: "chase -sapphire"
              - Time: "after:2024-01-01" or "before:2024-06-01"
  
          page: Page number for pagination (starts at 1)
  
          order: Sort order for results. Options:
              - "relevance": Best match (default)
              - "latest": Most recent first
              - "views": Most viewed
              - "likes": Most liked
              - "activity": Recent activity
              - "posts": Most replies
  
      Returns a SearchResult object with:
      - posts: List of matching SearchPost objects with excerpts
      - topics: List of matching SearchTopic objects
      - users: List of matching SearchUser objects
      - grouped_search_result: Metadata about result counts
  
      Example queries:
      - "Chase Sapphire Reserve order:latest" - Recent CSR discussions
      - "AMEX popup in:title" - Topics about AMEX popup in title
      - "data point category:credit-cards" - Data points in CC category
      - "@expert_user order:likes" - Most liked posts by a user
  
      Pagination: If more results exist, increment page parameter.
      """
      return get_client().search(query, page=page, order=order)

• src/uscardforum/models/search.py:1-100 (schema)

  Pydantic BaseModel definitions for the SearchResult output type returned by search_forum, including supporting models SearchPost, SearchTopic, SearchUser, and GroupedSearchResult. Includes a factory method to parse from API responses.

  """Domain models for search results."""
  
  from __future__ import annotations
  
  from datetime import datetime
  from typing import Any
  
  from pydantic import BaseModel, Field
  
  
  class SearchPost(BaseModel):
      """A post in search results."""
  
      id: int = Field(..., description="Post ID")
      topic_id: int = Field(..., description="Parent topic ID")
      post_number: int = Field(..., description="Position in topic")
      username: str | None = Field(None, description="Author username")
      blurb: str | None = Field(None, description="Content excerpt with highlights")
      created_at: datetime | None = Field(None, description="When posted")
      like_count: int = Field(0, description="Number of likes")
  
      class Config:
          extra = "ignore"
  
  
  class SearchTopic(BaseModel):
      """A topic in search results."""
  
      id: int = Field(..., description="Topic ID")
      title: str = Field(..., description="Topic title")
      posts_count: int = Field(0, description="Number of posts")
      views: int = Field(0, description="View count")
      like_count: int = Field(0, description="Total likes")
      category_id: int | None = Field(None, description="Category ID")
      category_name: str | None = Field(None, description="Category name")
      created_at: datetime | None = Field(None, description="Creation time")
  
      class Config:
          extra = "ignore"
  
  
  class SearchUser(BaseModel):
      """A user in search results."""
  
      id: int = Field(..., description="User ID")
      username: str = Field(..., description="Username")
      name: str | None = Field(None, description="Display name")
      avatar_template: str | None = Field(None, description="Avatar URL")
  
      class Config:
          extra = "ignore"
  
  
  class GroupedSearchResult(BaseModel):
      """Metadata about search result counts."""
  
      post_ids: list[int] = Field(default_factory=list, description="Matching post IDs")
      topic_ids: list[int] = Field(default_factory=list, description="Matching topic IDs")
      user_ids: list[int] = Field(default_factory=list, description="Matching user IDs")
      more_posts: bool | None = Field(None, description="More posts available")
      more_topics: bool | None = Field(None, description="More topics available")
  
      class Config:
          extra = "ignore"
  
  
  class SearchResult(BaseModel):
      """Complete search results."""
  
      posts: list[SearchPost] = Field(default_factory=list, description="Matching posts")
      topics: list[SearchTopic] = Field(
          default_factory=list, description="Matching topics"
      )
      users: list[SearchUser] = Field(default_factory=list, description="Matching users")
      grouped_search_result: GroupedSearchResult | None = Field(
          None, description="Result metadata"
      )
  
      class Config:
          extra = "ignore"
  
      @classmethod
      def from_api_response(cls, data: dict[str, Any]) -> SearchResult:
          """Parse from raw API response."""
          posts = [SearchPost(**p) for p in data.get("posts", [])]
          topics = [SearchTopic(**t) for t in data.get("topics", [])]
          users = [SearchUser(**u) for u in data.get("users", [])]
  
          grouped = None
          if "grouped_search_result" in data:
              grouped = GroupedSearchResult(**data["grouped_search_result"])
  
          return cls(
              posts=posts,
              topics=topics,
              users=users,
              grouped_search_result=grouped,
          )

• src/uscardforum/server_tools/__init__.py:48-48 (registration)

  Import of the search_forum tool function into the server_tools package __init__, enabling automatic @mcp.tool() registration when the package is imported.

  from .search import search_forum

• src/uscardforum/server.py:82-82 (registration)

  Explicit inclusion of search_forum in the __all__ export list of the main server module, ensuring it's available for MCP server setup.

  "search_forum",

• src/uscardforum/server_tools/__init__.py:85-85 (registration)

  Listing of search_forum in the server_tools __all__ list, exporting the tool for use in the MCP server.

  "search_forum",