USCardForum MCP Server

Instructions

Fetch badges earned by a user.

Args:
    username: The user's handle
    grouped: Group badges by type (default: True)

Returns a UserBadges object with:
- badges: List of Badge objects with name, description, granted_at
- badge_types: Badge type information

Badges indicate:
- Participation milestones (first post, anniversaries)
- Community recognition (editor, leader)
- Special achievements

Use to assess user experience and trustworthiness.

Implementation Reference

• src/uscardforum/server_tools/users.py:161-190 (handler)

  MCP tool handler for 'get_user_badges'. Decorated with @mcp.tool(), defines input schema using Annotated and Field, includes detailed docstring, and delegates execution to the client library.

  @mcp.tool()
  def get_user_badges(
      username: Annotated[
          str,
          Field(description="The user's handle"),
      ],
      grouped: Annotated[
          bool,
          Field(default=True, description="Group badges by type (default: True)"),
      ] = True,
  ) -> UserBadges:
      """
      Fetch badges earned by a user.
  
      Args:
          username: The user's handle
          grouped: Group badges by type (default: True)
  
      Returns a UserBadges object with:
      - badges: List of Badge objects with name, description, granted_at
      - badge_types: Badge type information
  
      Badges indicate:
      - Participation milestones (first post, anniversaries)
      - Community recognition (editor, leader)
      - Special achievements
  
      Use to assess user experience and trustworthiness.
      """
      return get_client().get_user_badges(username, grouped=grouped)

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

  Imports and exposes the get_user_badges tool in the main server entrypoint, making it available for MCP server registration via main().

  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,
  )
  
  __all__ = [
      "MCP_HOST",
      "MCP_PORT",
      "MCP_TRANSPORT",
      "NITAN_TOKEN",
      "SERVER_INSTRUCTIONS",
      "get_client",
      "main",
      "mcp",
      "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",
      "resource_categories",
      "resource_hot_topics",
      "resource_new_topics",
      "search_forum",
      "subscribe_topic",
      "research_topic",
  ]

• src/uscardforum/client.py:376-390 (helper)

  Client library wrapper method that delegates to the users API client.

  def get_user_badges(
      self,
      username: str,
      grouped: bool = True,
  ) -> UserBadges:
      """Fetch user's badges.
  
      Args:
          username: User handle
          grouped: Group badges (default: True)
  
      Returns:
          User badges data
      """
      return self._users.get_user_badges(username, grouped=grouped)

• src/uscardforum/api/users.py:156-186 (helper)

  Core API implementation that performs HTTP GET request to the forum API endpoint /user-badges/{username}.json, parses the response, and constructs UserBadges object.

  def get_user_badges(
      self,
      username: str,
      grouped: bool = True,
  ) -> UserBadges:
      """Fetch user's badges.
  
      Args:
          username: User handle
          grouped: Group badges (default: True)
  
      Returns:
          User badges data
      """
      params_list: list[tuple[str, Any]] = [
          ("grouped", str(bool(grouped)).lower())
      ]
      payload = self._get(f"/user-badges/{username}.json", params=params_list)
  
      badges = []
      for b in payload.get("user_badges", []):
          badges.append(Badge(
              id=b.get("id", 0),
              badge_id=b.get("badge_id", 0),
              name=b.get("name", ""),
              description=b.get("description"),
              granted_at=b.get("granted_at"),
          ))
  
      return UserBadges(badges=badges)

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

  Re-exports the tool from users.py module for convenient import in server.py.

  from .users import (
      get_user_summary,
      get_user_topics,
      get_user_replies,
      get_user_actions,
      get_user_badges,
      get_user_following,
      get_user_followers,
      get_user_reactions,
      list_users_with_badge,
  )