modify_role
Update Discord server role properties including name, color, permissions, position, and display settings to manage user access and organization.
Instructions
Modify role properties (name, color, permissions, position, etc.)
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| guildId | Yes | The ID of the server (guild) | |
| roleId | Yes | The ID of the role to modify | |
| name | No | New role name | |
| color | No | New hex color code | |
| hoist | No | Whether to display separately | |
| mentionable | No | Whether the role can be mentioned | |
| permissions | No | Array of permission names | |
| position | No | New position | |
| reason | No | Reason for the modification |
Implementation Reference
- src/tools/role-tools.ts:173-206 (handler)Executes the modify_role tool: fetches Discord guild and role, conditionally updates properties like name, color, permissions, etc., using role.edit(), handles errors with withErrorHandling, and returns JSON response.async ({ guildId, roleId, name, color, hoist, mentionable, permissions, position, reason }) => { const result = await withErrorHandling(async () => { const client = await getDiscordClient(); const guild = await client.guilds.fetch(guildId); const role = await guild.roles.fetch(roleId); if (!role) throw new Error('Role not found'); const updateData: Record<string, unknown> = {}; if (name !== undefined) updateData.name = name; if (color !== undefined) updateData.color = color; if (hoist !== undefined) updateData.hoist = hoist; if (mentionable !== undefined) updateData.mentionable = mentionable; if (permissions !== undefined) { updateData.permissions = new PermissionsBitField(permissions as any); } if (position !== undefined) updateData.position = position; if (reason !== undefined) updateData.reason = reason; const updatedRole = await role.edit(updateData); return { id: updatedRole.id, name: updatedRole.name, color: updatedRole.hexColor, position: updatedRole.position, message: 'Role updated 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:162-172 (schema)Input schema using Zod for validating parameters to the modify_role tool.{ guildId: z.string().describe('The ID of the server (guild)'), roleId: z.string().describe('The ID of the role to modify'), name: z.string().optional().describe('New role name'), color: z.string().optional().describe('New hex color code'), hoist: z.boolean().optional().describe('Whether to display 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('New position'), reason: z.string().optional().describe('Reason for the modification'), },
- src/tools/role-tools.ts:159-207 (registration)Registers the 'modify_role' tool on the MCP server with description, input schema, and handler function.server.tool( 'modify_role', 'Modify role properties (name, color, permissions, position, etc.)', { guildId: z.string().describe('The ID of the server (guild)'), roleId: z.string().describe('The ID of the role to modify'), name: z.string().optional().describe('New role name'), color: z.string().optional().describe('New hex color code'), hoist: z.boolean().optional().describe('Whether to display 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('New position'), reason: z.string().optional().describe('Reason for the modification'), }, async ({ guildId, roleId, name, color, hoist, mentionable, permissions, position, reason }) => { const result = await withErrorHandling(async () => { const client = await getDiscordClient(); const guild = await client.guilds.fetch(guildId); const role = await guild.roles.fetch(roleId); if (!role) throw new Error('Role not found'); const updateData: Record<string, unknown> = {}; if (name !== undefined) updateData.name = name; if (color !== undefined) updateData.color = color; if (hoist !== undefined) updateData.hoist = hoist; if (mentionable !== undefined) updateData.mentionable = mentionable; if (permissions !== undefined) { updateData.permissions = new PermissionsBitField(permissions as any); } if (position !== undefined) updateData.position = position; if (reason !== undefined) updateData.reason = reason; const updatedRole = await role.edit(updateData); return { id: updatedRole.id, name: updatedRole.name, color: updatedRole.hexColor, position: updatedRole.position, message: 'Role updated 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/index.ts:56-56 (registration)Invokes registerRoleTools(server) which sets up all role tools including modify_role.registerRoleTools(server);