USCardForum MCP Server

Instructions

Implementation Reference

• src/uscardforum/server_tools/categories.py:8-30 (handler)

  The @mcp.tool() decorated function implementing the core logic of the get_categories MCP tool. It retrieves the CategoryMap from the client and returns it.
  @mcp.tool() def get_categories() -> CategoryMap: """ Get a mapping of all forum categories. Returns a CategoryMap object with category_id to category name mapping. Categories organize topics by subject area. Common USCardForum categories include sections for: - Credit card applications and approvals - Bank account bonuses - Travel and redemptions - Data points and experiences Use category IDs to: - Filter search results by category - Understand which section a topic belongs to - Navigate to specific areas of interest The mapping includes both main categories and subcategories. """ return get_client().get_category_map()
• src/uscardforum/models/categories.py:24-47 (schema)

  Pydantic model defining the output schema (CategoryMap) returned by the get_categories tool.
  class CategoryMap(BaseModel): """Mapping of category IDs to names.""" categories: dict[int, str] = Field( default_factory=dict, description="ID to name mapping" ) def get_name(self, category_id: int) -> str | None: """Get category name by ID.""" return self.categories.get(category_id) def __getitem__(self, category_id: int) -> str: """Get category name by ID.""" return self.categories[category_id] def __contains__(self, category_id: int) -> bool: """Check if category ID exists.""" return category_id in self.categories def items(self): """Iterate over category mappings.""" return self.categories.items()
• src/uscardforum/server.py:19-23 (registration)

  Import statement in the MCP server entrypoint that registers the get_categories tool by importing the decorated handler function.
  find_data_points, get_all_topic_posts, get_categories, get_current_session, get_hot_topics,
• src/uscardforum/api/categories.py:58-74 (helper)

  Helper method get_category_map() in CategoriesAPI that builds the CategoryMap from API data, called indirectly by the tool handler.
  def get_category_map(self, use_cache: bool = True) -> CategoryMap: """Get mapping of category IDs to names. Args: use_cache: Use cached map if available (default: True) Returns: CategoryMap with ID to name mapping """ if use_cache and self._category_cache is not None: return CategoryMap(categories=self._category_cache) categories = self.get_categories() mapping = {cat.id: cat.name for cat in categories} self._category_cache = mapping return CategoryMap(categories=mapping)