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 via Annotated[Field] and delegates execution to the DiscourseClient.get_user_badges() method.

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

  Imports get_user_badges (line 30) along with other MCP tools into the FastMCP server entrypoint, ensuring auto-registration via @mcp.tool() decorators.

  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/server_tools/__init__.py:37-47 (registration)

  Re-exports get_user_badges from users.py module, making it available for import in server.py for MCP tool registration.

  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,
  )

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

  Core helper implementation in UsersAPI class that performs the HTTP GET request to Discourse API endpoint /user-badges/{username}.json, parses the response, constructs Badge objects, and returns UserBadges instance. Called by client.get_user_badges().

  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/users.py:162-190 (schema)

  Input schema defined via Pydantic Annotated[str, Field(...)] for username and grouped parameters, with return type UserBadges for output validation.

  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)