Discord MCP Server

Instructions

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]