get_categories

Instructions

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.

Implementation Reference

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

  The MCP tool handler for 'get_categories'. Decorated with @mcp.tool(), it fetches the CategoryMap from the DiscourseClient and returns it as the tool output.

  @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 BaseModel defining the output schema of the get_categories tool: a dictionary mapping category IDs to names.

  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:15-45 (registration)

  Multi-line import statement from server_tools that includes get_categories, registering it as an MCP tool in the FastMCP server entrypoint.

  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/api/categories.py:58-74 (helper)

  Helper function in CategoriesAPI that builds the CategoryMap from API response, called indirectly via client.get_category_map() from 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)

• src/uscardforum/client.py:298-304 (helper)

  Client wrapper method get_category_map() that delegates to CategoriesAPI, called by get_client().get_category_map() in the tool handler.

  def get_category_map(self) -> CategoryMap:
      """Get mapping of category IDs to names.
  
      Returns:
          CategoryMap with ID to name mapping
      """
      return self._categories.get_category_map()