search_forum
Search USCardForum for credit card and points discussions using advanced query operators to filter by title, author, category, tag, date, or sort results.
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.Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query string. Supports operators: 'in:title', '@username', 'category:name', '#tag', 'after:date', 'before:date' | |
| page | No | Page number for pagination (starts at 1) | |
| order | No | Sort order: 'relevance' (default), 'latest', 'views', 'likes', 'activity', or 'posts' |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| posts | No | Matching posts | |
| users | No | Matching users | |
| topics | No | Matching topics | |
| grouped_search_result | No | Result metadata |
Implementation Reference
- The primary handler for the 'search_forum' tool. Uses @mcp.tool() decorator for registration. Input schema defined inline with Pydantic Field descriptions. Logic delegates search to the DiscourseClient instance.
@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) - Pydantic model defining the structured output schema for search results, including nested models for posts, topics, users, and grouped results. Provides from_api_response factory for parsing raw API data.
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.py:15-45 (registration)Imports all MCP tools including 'search_forum' from server_tools package. Importing triggers the automatic registration via decorators when the server module is loaded.
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, )