list_roles
Retrieve all role definitions from a Discord server to manage permissions and organize members effectively.
Instructions
List all roles defined in the Discord server.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| server_id | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- src/discord_mcp/server.py:612-628 (handler)The handler function for the 'list_roles' tool. Fetches guild roles excluding default @everyone, sorts by position descending, formats using _format_role helper, and returns formatted string.
async def list_roles(server_id: str | int | None = None, ctx: Context = None) -> str: # type: ignore[override] """List all roles defined in the Discord server.""" assert ctx is not None bot, config = await _acquire(ctx) guild_id = _resolve_guild_id(config, server_id) guild = await _ensure_guild(bot, guild_id) roles = [role for role in guild.roles if role != guild.default_role] if not roles: return f"{guild.name} has no custom roles." lines = [f"**Roles for {guild.name} (excluding @everyone):**"] for role in sorted(roles, key=lambda item: item.position, reverse=True): lines.append(_format_role(role)) return "\n".join(lines) - src/discord_mcp/server.py:444-458 (helper)Helper function used by list_roles to format each role's details: name, ID, position, member count, color, flags (managed/hoisted/mentionable), and summarized permissions.
def _format_role(role: discord.Role) -> str: colour = f"#{role.colour.value:06X}" if role.colour.value else "default" flags: list[str] = [] if role.managed: flags.append("managed") if role.hoist: flags.append("hoisted") if role.mentionable: flags.append("mentionable") flag_str = f" ({', '.join(flags)})" if flags else "" permissions = _summarize_permissions(role.permissions) return ( f"• {role.name} (ID: {role.id}) – Position: {role.position} – Members: {len(role.members)} – " f"Colour: {colour}{flag_str}\n Permissions: {permissions}" ) - src/discord_mcp/server.py:612-612 (registration)The @server.tool() decorator registers the list_roles function as an MCP tool.
async def list_roles(server_id: str | int | None = None, ctx: Context = None) -> str: # type: ignore[override]