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 |
Implementation Reference
- src/discord_mcp/server.py:612-629 (handler)The main handler function for the 'list_roles' tool. It resolves the guild, filters out the default '@everyone' role, sorts roles by position (highest first), formats each using _format_role, and returns a formatted list.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-459 (helper)Helper function used by list_roles to format individual role details including name, ID, position, member count, color, hoist/mentionable/managed flags, 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:435-442 (helper)Helper function used by _format_role to create a concise summary of role permissions, listing up to 6 allowed permissions.def _summarize_permissions(perms: discord.Permissions, *, max_entries: int = 6) -> str: allowed = [name.replace("_", " ") for name, value in perms if value] if not allowed: return "No permissions" if len(allowed) > max_entries: return ", ".join(allowed[:max_entries]) + ", ..." return ", ".join(allowed)
- 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]