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.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "list_roles"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| server_id | No |
Output 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]