USCardForum MCP Server

Instructions

Implementation Reference

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

  The MCP tool handler for 'get_categories', decorated with @mcp.tool(). Retrieves and returns the forum category ID to name mapping using the client API.
  @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, which holds a dictionary of category ID to name mappings with utility methods.
  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/api/categories.py:58-74 (helper)

  Helper method in CategoriesAPI that fetches categories, builds the ID-to-name mapping, caches it, and returns a CategoryMap instance. Called 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)
• src/uscardforum/server_tools/__init__.py:25-30 (registration)

  Imports the get_categories tool handler into the server_tools package namespace for exposure to the MCP server.
  from .topics import get_hot_topics, get_new_topics, get_top_topics from .search import search_forum from .categories import get_categories # ============================================================================= # 📖 Reading — Access topic content