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 by providing a badge ID.

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-300 (handler)

MCP tool handler for 'list_users_with_badge'. Defines input parameters with descriptions (serving as schema) and implements the logic by calling the underlying 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/api/users.py:190-209 (helper)

Underlying API client method that performs the HTTP request to /user_badges.json to retrieve users with the specified badge.

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)

src/uscardforum/server_tools/__init__.py:68-78 (registration)

Import statement in server_tools/__init__.py that includes list_users_with_badge, exporting the tool for use in the MCP server.

from .users import (
    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,
)

src/uscardforum/server.py:36-77 (registration)

Import and __all__ entry in the main server.py entrypoint file, ensuring the tool is registered when the server starts.

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

USCardForum MCP Server