create_role
Add a new role to a Discord server by specifying its name, permissions, color, and display options to organize members and manage access.
Instructions
Create a new role in a Discord server
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| guildId | Yes | The ID of the server (guild) | |
| name | Yes | Name of the new role | |
| color | No | Hex color code (e.g., #FF0000) | |
| hoist | No | Whether to display the role separately | |
| mentionable | No | Whether the role can be mentioned | |
| permissions | No | Array of permission names | |
| position | No | Position of the role | |
| reason | No | Reason for creating the role |
Implementation Reference
- src/tools/role-tools.ts:96-127 (handler)The main handler function for the 'create_role' tool that executes the logic to create a new Discord role with specified parameters.async ({ guildId, name, color, hoist, mentionable, permissions, position, reason }) => { const result = await withErrorHandling(async () => { const client = await getDiscordClient(); const guild = await client.guilds.fetch(guildId); const roleOptions: Record<string, unknown> = { name }; if (color !== undefined) roleOptions.color = color; if (hoist !== undefined) roleOptions.hoist = hoist; if (mentionable !== undefined) roleOptions.mentionable = mentionable; if (permissions !== undefined) { roleOptions.permissions = new PermissionsBitField(permissions as any); } if (position !== undefined) roleOptions.position = position; if (reason !== undefined) roleOptions.reason = reason; const newRole = await guild.roles.create(roleOptions); return { id: newRole.id, name: newRole.name, color: newRole.hexColor, position: newRole.position, message: 'Role created successfully', }; }); if (!result.success) { return { content: [{ type: 'text', text: result.error }], isError: true }; } return { content: [{ type: 'text', text: JSON.stringify(result.data, null, 2) }] }; } );
- src/tools/role-tools.ts:86-95 (schema)Zod schema defining the input parameters for the 'create_role' tool.{ guildId: z.string().describe('The ID of the server (guild)'), name: z.string().describe('Name of the new role'), color: z.string().optional().describe('Hex color code (e.g., #FF0000)'), hoist: z.boolean().optional().describe('Whether to display the role separately'), mentionable: z.boolean().optional().describe('Whether the role can be mentioned'), permissions: z.array(z.string()).optional().describe('Array of permission names'), position: z.number().optional().describe('Position of the role'), reason: z.string().optional().describe('Reason for creating the role'), },
- src/tools/role-tools.ts:83-128 (registration)The server.tool() call that registers the 'create_role' tool, including name, description, schema, and handler.server.tool( 'create_role', 'Create a new role in a Discord server', { guildId: z.string().describe('The ID of the server (guild)'), name: z.string().describe('Name of the new role'), color: z.string().optional().describe('Hex color code (e.g., #FF0000)'), hoist: z.boolean().optional().describe('Whether to display the role separately'), mentionable: z.boolean().optional().describe('Whether the role can be mentioned'), permissions: z.array(z.string()).optional().describe('Array of permission names'), position: z.number().optional().describe('Position of the role'), reason: z.string().optional().describe('Reason for creating the role'), }, async ({ guildId, name, color, hoist, mentionable, permissions, position, reason }) => { const result = await withErrorHandling(async () => { const client = await getDiscordClient(); const guild = await client.guilds.fetch(guildId); const roleOptions: Record<string, unknown> = { name }; if (color !== undefined) roleOptions.color = color; if (hoist !== undefined) roleOptions.hoist = hoist; if (mentionable !== undefined) roleOptions.mentionable = mentionable; if (permissions !== undefined) { roleOptions.permissions = new PermissionsBitField(permissions as any); } if (position !== undefined) roleOptions.position = position; if (reason !== undefined) roleOptions.reason = reason; const newRole = await guild.roles.create(roleOptions); return { id: newRole.id, name: newRole.name, color: newRole.hexColor, position: newRole.position, message: 'Role created successfully', }; }); if (!result.success) { return { content: [{ type: 'text', text: result.error }], isError: true }; } return { content: [{ type: 'text', text: JSON.stringify(result.data, null, 2) }] }; } );