Discord Agent MCP

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { DiscordClientManager } from "../discord/client.js"; import { Logger } from "../utils/logger.js"; import { z } from "zod"; import { PermissionDeniedError, GuildNotFoundError, } from "../errors/discord.js"; import { PermissionFlagsBits, PermissionsBitField } from "discord.js"; export function registerRoleTools( server: McpServer, discordManager: DiscordClientManager, logger: Logger, ) { // Create Role Tool server.registerTool( "create_role", { title: "Create Server Role", description: "Create a new role in the server with specified permissions", inputSchema: { guildId: z.string().describe("Server/Guild ID"), name: z.string().max(100).describe("Role name"), color: z .number() .int() .min(0) .max(0xffffff) .optional() .describe("Role color as hex integer (e.g., 0x00ff00 for green)"), hoist: z .boolean() .optional() .describe("Display role members separately in sidebar"), mentionable: z .boolean() .optional() .describe("Allow anyone to @mention this role"), permissions: z .array(z.string()) .optional() .describe( 'Array of permission names (e.g., ["SendMessages", "ManageMessages"])', ), reason: z .string() .optional() .describe("Reason for role creation (shown in audit log)"), }, outputSchema: { success: z.boolean(), role: z .object({ id: z.string(), name: z.string(), color: z.number(), position: z.number(), permissions: z.array(z.string()), }) .optional(), error: z.string().optional(), }, }, async ({ guildId, name, color, hoist, mentionable, permissions, reason, }) => { try { const client = discordManager.getClient(); const guild = await client.guilds.fetch(guildId).catch(() => null); if (!guild) { throw new GuildNotFoundError(guildId); } // Check bot permissions const botMember = await guild.members.fetchMe(); if (!botMember.permissions.has(PermissionFlagsBits.ManageRoles)) { throw new PermissionDeniedError("ManageRoles", guildId); } // Build permissions bitfield let permissionsBitField: bigint | undefined; if (permissions && permissions.length > 0) { permissionsBitField = new PermissionsBitField(permissions as any) .bitfield; } // Create role const role = await guild.roles.create({ name, color, hoist, mentionable, permissions: permissionsBitField, reason, }); const roleData = { id: role.id, name: role.name, color: role.color, position: role.position, permissions: role.permissions.toArray(), }; const output = { success: true, role: roleData, }; logger.info("Role created", { guildId, roleId: role.id, name }); return { content: [ { type: "text" as const, text: `Successfully created role "${name}" (ID: ${role.id})`, }, ], structuredContent: output, }; } catch (error: any) { logger.error("Failed to create role", { error: error.message, guildId, name, }); const output = { success: false, error: error.message, }; return { content: [ { type: "text" as const, text: `Failed to create role: ${error.message}`, }, ], structuredContent: output, isError: true, }; } }, ); // Delete Role Tool server.registerTool( "delete_role", { title: "Delete Server Role", description: "Delete a role from the server", inputSchema: { guildId: z.string().describe("Server/Guild ID"), roleId: z.string().describe("Role ID to delete"), reason: z .string() .optional() .describe("Reason for role deletion (shown in audit log)"), }, outputSchema: { success: z.boolean(), roleId: z.string().optional(), roleName: z.string().optional(), error: z.string().optional(), }, }, async ({ guildId, roleId, reason }) => { try { const client = discordManager.getClient(); const guild = await client.guilds.fetch(guildId).catch(() => null); if (!guild) { throw new GuildNotFoundError(guildId); } // Check bot permissions const botMember = await guild.members.fetchMe(); if (!botMember.permissions.has(PermissionFlagsBits.ManageRoles)) { throw new PermissionDeniedError("ManageRoles", guildId); } // Fetch role const role = await guild.roles.fetch(roleId).catch(() => null); if (!role) { throw new Error(`Role ${roleId} not found in server`); } // Check if it's @everyone if (role.id === guild.id) { throw new Error("Cannot delete @everyone role"); } // Check role hierarchy if (role.position >= botMember.roles.highest.position) { throw new Error( "Cannot delete this role - it is equal to or higher than the bot's highest role", ); } const roleName = role.name; await role.delete(reason); const output = { success: true, roleId, roleName, }; logger.info("Role deleted", { guildId, roleId, roleName, reason }); return { content: [ { type: "text" as const, text: `Successfully deleted role "${roleName}"`, }, ], structuredContent: output, }; } catch (error: any) { logger.error("Failed to delete role", { error: error.message, guildId, roleId, }); const output = { success: false, error: error.message, }; return { content: [ { type: "text" as const, text: `Failed to delete role: ${error.message}`, }, ], structuredContent: output, isError: true, }; } }, ); // Modify Role Tool server.registerTool( "modify_role", { title: "Modify Server Role", description: "Update a role's name, color, permissions, or other settings", inputSchema: { guildId: z.string().describe("Server/Guild ID"), roleId: z.string().describe("Role ID to modify"), name: z.string().max(100).optional().describe("New role name"), color: z .number() .int() .min(0) .max(0xffffff) .optional() .describe("New role color as hex integer"), hoist: z .boolean() .optional() .describe("Display role members separately in sidebar"), mentionable: z .boolean() .optional() .describe("Allow anyone to @mention this role"), permissions: z .array(z.string()) .optional() .describe( "Array of permission names to set (replaces all permissions)", ), reason: z .string() .optional() .describe("Reason for modification (shown in audit log)"), }, outputSchema: { success: z.boolean(), role: z .object({ id: z.string(), name: z.string(), color: z.number(), permissions: z.array(z.string()), }) .optional(), error: z.string().optional(), }, }, async ({ guildId, roleId, name, color, hoist, mentionable, permissions, reason, }) => { try { const client = discordManager.getClient(); const guild = await client.guilds.fetch(guildId).catch(() => null); if (!guild) { throw new GuildNotFoundError(guildId); } // Check bot permissions const botMember = await guild.members.fetchMe(); if (!botMember.permissions.has(PermissionFlagsBits.ManageRoles)) { throw new PermissionDeniedError("ManageRoles", guildId); } // Fetch role const role = await guild.roles.fetch(roleId).catch(() => null); if (!role) { throw new Error(`Role ${roleId} not found in server`); } // Check if it's @everyone and trying to change name if (role.id === guild.id && name) { throw new Error("Cannot rename @everyone role"); } // Check role hierarchy if (role.position >= botMember.roles.highest.position) { throw new Error( "Cannot modify this role - it is equal to or higher than the bot's highest role", ); } // Build update options const updateOptions: any = {}; if (name !== undefined) updateOptions.name = name; if (color !== undefined) updateOptions.color = color; if (hoist !== undefined) updateOptions.hoist = hoist; if (mentionable !== undefined) updateOptions.mentionable = mentionable; if (permissions !== undefined) { updateOptions.permissions = new PermissionsBitField( permissions as any, ).bitfield; } if (reason !== undefined) updateOptions.reason = reason; // Update role const updatedRole = await role.edit(updateOptions); const roleData = { id: updatedRole.id, name: updatedRole.name, color: updatedRole.color, permissions: updatedRole.permissions.toArray(), }; const output = { success: true, role: roleData, }; logger.info("Role modified", { guildId, roleId, reason }); return { content: [ { type: "text" as const, text: `Successfully modified role "${updatedRole.name}"`, }, ], structuredContent: output, }; } catch (error: any) { logger.error("Failed to modify role", { error: error.message, guildId, roleId, }); const output = { success: false, error: error.message, }; return { content: [ { type: "text" as const, text: `Failed to modify role: ${error.message}`, }, ], structuredContent: output, isError: true, }; } }, ); // List Roles Tool server.registerTool( "list_roles", { title: "List Server Roles", description: "Get all roles in the server with their permissions", inputSchema: { guildId: z.string().describe("Server/Guild ID"), includeEveryone: z .boolean() .optional() .default(false) .describe("Include @everyone role in results"), }, outputSchema: { success: z.boolean(), roles: z .array( z.object({ id: z.string(), name: z.string(), color: z.number(), position: z.number(), memberCount: z.number(), permissions: z.array(z.string()), hoist: z.boolean(), mentionable: z.boolean(), managed: z.boolean(), }), ) .optional(), totalCount: z.number().optional(), error: z.string().optional(), }, }, async ({ guildId, includeEveryone = false }) => { try { const client = discordManager.getClient(); const guild = await client.guilds.fetch(guildId).catch(() => null); if (!guild) { throw new GuildNotFoundError(guildId); } // Fetch all roles const roles = await guild.roles.fetch(); // Filter out @everyone if requested let roleList = Array.from(roles.values()); if (!includeEveryone) { roleList = roleList.filter((r) => r.id !== guild.id); } // Sort by position (highest first) roleList.sort((a, b) => b.position - a.position); const rolesData = roleList.map((role) => ({ id: role.id, name: role.name, color: role.color, position: role.position, memberCount: role.members.size, permissions: role.permissions.toArray(), hoist: role.hoist, mentionable: role.mentionable, managed: role.managed, })); const output = { success: true, roles: rolesData, totalCount: rolesData.length, }; logger.info("Roles listed", { guildId, count: rolesData.length }); return { content: [ { type: "text" as const, text: `Found ${rolesData.length} role(s) in server`, }, ], structuredContent: output, }; } catch (error: any) { logger.error("Failed to list roles", { error: error.message, guildId, }); const output = { success: false, error: error.message, }; return { content: [ { type: "text" as const, text: `Failed to list roles: ${error.message}`, }, ], structuredContent: output, isError: true, }; } }, ); // Get Role Info Tool server.registerTool( "get_role_info", { title: "Get Role Information", description: "Get detailed information about a specific role", inputSchema: { guildId: z.string().describe("Server/Guild ID"), roleId: z.string().describe("Role ID to get info for"), }, outputSchema: { success: z.boolean(), role: z .object({ id: z.string(), name: z.string(), color: z.number(), position: z.number(), memberCount: z.number(), permissions: z.array(z.string()), hoist: z.boolean(), mentionable: z.boolean(), managed: z.boolean(), createdAt: z.string(), }) .optional(), error: z.string().optional(), }, }, async ({ guildId, roleId }) => { try { const client = discordManager.getClient(); const guild = await client.guilds.fetch(guildId).catch(() => null); if (!guild) { throw new GuildNotFoundError(guildId); } // Fetch role const role = await guild.roles.fetch(roleId).catch(() => null); if (!role) { throw new Error(`Role ${roleId} not found in server`); } const roleData = { id: role.id, name: role.name, color: role.color, position: role.position, memberCount: role.members.size, permissions: role.permissions.toArray(), hoist: role.hoist, mentionable: role.mentionable, managed: role.managed, createdAt: role.createdAt.toISOString(), }; const output = { success: true, role: roleData, }; logger.info("Role info retrieved", { guildId, roleId }); return { content: [ { type: "text" as const, text: `Role: ${role.name}\nMembers: ${roleData.memberCount}\nPermissions: ${roleData.permissions.length}`, }, ], structuredContent: output, }; } catch (error: any) { logger.error("Failed to get role info", { error: error.message, guildId, roleId, }); const output = { success: false, error: error.message, }; return { content: [ { type: "text" as const, text: `Failed to get role info: ${error.message}`, }, ], structuredContent: output, isError: true, }; } }, ); }