list_users_with_badge

Find community members who have earned a specific achievement badge on USCardForum. Use this tool to identify users with particular recognition levels or accomplishments.

Instructions

List all users who have earned a specific badge.

Args:
    badge_id: The numeric badge ID
    offset: Pagination offset (optional)

Returns a dictionary with user badge information.

Use to find community members with specific achievements
or recognition levels.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`badge_id`	Yes	The numeric badge ID
`offset`	No	Pagination offset

Implementation Reference

src/uscardforum/server_tools/users.py:277-301 (handler)

MCP tool handler for 'list_users_with_badge'. Defines input schema using Pydantic Annotated fields and implements the logic by calling the client API.

@mcp.tool()
def list_users_with_badge(
    badge_id: Annotated[
        int,
        Field(description="The numeric badge ID"),
    ],
    offset: Annotated[
        int | None,
        Field(default=None, description="Pagination offset"),
    ] = None,
) -> dict[str, Any]:
    """
    List all users who have earned a specific badge.

    Args:
        badge_id: The numeric badge ID
        offset: Pagination offset (optional)

    Returns a dictionary with user badge information.

    Use to find community members with specific achievements
    or recognition levels.
    """
    return get_client().list_user_badges(badge_id, offset=offset)

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

Imports all MCP tools including 'list_users_with_badge' from server_tools, registering them via the @mcp.tool decorators when the server starts.

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 'list_users_with_badge' from the users module, making it available for import in higher-level modules like 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,
)

src/uscardforum/api/users.py:187-206 (helper)

Core API client method that performs the HTTP GET request to '/user_badges.json' to retrieve users holding a specific badge. Called by the MCP handler via the client proxy.

def list_users_with_badge(
    self,
    badge_id: int,
    offset: int | None = None,
) -> dict[str, Any]:
    """List users with a specific badge.

    Args:
        badge_id: Badge ID
        offset: Optional pagination offset

    Returns:
        Raw API response with users
    """
    params_list: list[tuple[str, Any]] = [("badge_id", int(badge_id))]
    if offset is not None:
        params_list.append(("offset", int(offset)))

    return self._get("/user_badges.json", params=params_list)

USCardForum MCP Server