@mahesvara/discord-mcpserver 1.0.8 → 1.1.0

package/dist/tools/role.js

@@ -0,0 +1,420 @@
+import { ListRolesSchema, AddRoleSchema, RemoveRoleSchema, CreateRoleSchema, DeleteRoleSchema, EditRoleSchema, SetRolePositionsSchema, } from "../schemas/index.js";
+import { getClient, formatRole, roleToMarkdown, formatResponse, truncateIfNeeded, } from "../services/discord.js";
+import { PermissionsBitField } from "discord.js";
+// Full list of role permissions for reference
+const ROLE_PERMISSION_LIST = [
+    // General Server Permissions
+    'Administrator', 'ViewAuditLog', 'ViewGuildInsights', 'ManageGuild', 'ManageRoles',
+    'ManageChannels', 'KickMembers', 'BanMembers', 'CreateInstantInvite', 'ChangeNickname',
+    'ManageNicknames', 'ManageEmojisAndStickers', 'ManageWebhooks', 'ManageGuildExpressions',
+    'ViewCreatorMonetizationAnalytics', 'ModerateMembers',
+    // Text Channel Permissions
+    'ViewChannel', 'SendMessages', 'SendTTSMessages', 'ManageMessages', 'EmbedLinks',
+    'AttachFiles', 'ReadMessageHistory', 'MentionEveryone', 'UseExternalEmojis',
+    'AddReactions', 'UseApplicationCommands', 'ManageThreads', 'CreatePublicThreads',
+    'CreatePrivateThreads', 'UseExternalStickers', 'SendMessagesInThreads', 'SendVoiceMessages',
+    'SendPolls', 'UseExternalApps',
+    // Voice Channel Permissions
+    'Connect', 'Speak', 'MuteMembers', 'DeafenMembers', 'MoveMembers', 'UseVAD',
+    'PrioritySpeaker', 'Stream', 'UseSoundboard', 'UseExternalSounds', 'UseEmbeddedActivities',
+    // Stage Channel Permissions
+    'RequestToSpeak',
+    // Events Permissions
+    'ManageEvents', 'CreateEvents'
+];
+export function registerRoleTools(server) {
+    server.registerTool("discord_list_roles", {
+        title: "List Discord Roles",
+        description: `List all roles in a Discord server.
+
+Args:
+  - guild_id (string): Discord server/guild ID
+  - response_format ('markdown' | 'json'): Output format (default: 'json')
+
+Returns:
+  List of roles with name, color, position, permissions`,
+        inputSchema: ListRolesSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async (params) => {
+        try {
+            const client = await getClient();
+            const guild = client.guilds.cache.get(params.guild_id);
+            if (!guild) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `Guild not found: ${params.guild_id}` }],
+                };
+            }
+            const roles = guild.roles.cache
+                .filter(r => r.name !== "@everyone")
+                .sort((a, b) => b.position - a.position)
+                .map(formatRole);
+            const text = formatResponse(Array.from(roles.values()), params.response_format, (items) => items.map(roleToMarkdown).join("\n\n"));
+            return {
+                content: [{ type: "text", text: truncateIfNeeded(text) }],
+            };
+        }
+        catch (error) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: `Error listing roles: ${error.message}` }],
+            };
+        }
+    });
+    server.registerTool("discord_add_role", {
+        title: "Add Role to Member",
+        description: `Add a role to a Discord member.
+
+Args:
+  - guild_id (string): Discord server/guild ID
+  - user_id (string): Discord user ID
+  - role_id (string): Discord role ID to add
+
+Returns:
+  Confirmation of role added`,
+        inputSchema: AddRoleSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async (params) => {
+        try {
+            const client = await getClient();
+            const guild = client.guilds.cache.get(params.guild_id);
+            if (!guild) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `Guild not found: ${params.guild_id}` }],
+                };
+            }
+            const member = await guild.members.fetch(params.user_id);
+            const role = guild.roles.cache.get(params.role_id);
+            if (!role) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `Role not found: ${params.role_id}` }],
+                };
+            }
+            await member.roles.add(role);
+            return {
+                content: [{ type: "text", text: `Added role "${role.name}" to user ${params.user_id}` }],
+            };
+        }
+        catch (error) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: `Error adding role: ${error.message}` }],
+            };
+        }
+    });
+    server.registerTool("discord_remove_role", {
+        title: "Remove Role from Member",
+        description: `Remove a role from a Discord member.
+
+Args:
+  - guild_id (string): Discord server/guild ID
+  - user_id (string): Discord user ID
+  - role_id (string): Discord role ID to remove
+
+Returns:
+  Confirmation of role removed`,
+        inputSchema: RemoveRoleSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async (params) => {
+        try {
+            const client = await getClient();
+            const guild = client.guilds.cache.get(params.guild_id);
+            if (!guild) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `Guild not found: ${params.guild_id}` }],
+                };
+            }
+            const member = await guild.members.fetch(params.user_id);
+            const role = guild.roles.cache.get(params.role_id);
+            if (!role) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `Role not found: ${params.role_id}` }],
+                };
+            }
+            await member.roles.remove(role);
+            return {
+                content: [{ type: "text", text: `Removed role "${role.name}" from user ${params.user_id}` }],
+            };
+        }
+        catch (error) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: `Error removing role: ${error.message}` }],
+            };
+        }
+    });
+    server.registerTool("discord_create_role", {
+        title: "Create Discord Role",
+        description: `Create a new role in a Discord server.
+
+Args:
+  - guild_id (string): Discord server/guild ID
+  - name (string): Role name
+  - color (number, optional): Role color as decimal integer (e.g., 16711680 for red)
+  - mentionable (boolean): Whether the role can be mentioned (default: false)
+  - hoist (boolean): Whether to display role members separately (default: false)
+
+Returns:
+  The created role's details`,
+        inputSchema: CreateRoleSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async (params) => {
+        try {
+            const client = await getClient();
+            const guild = client.guilds.cache.get(params.guild_id);
+            if (!guild) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `Guild not found: ${params.guild_id}` }],
+                };
+            }
+            const role = await guild.roles.create({
+                name: params.name,
+                color: params.color,
+                mentionable: params.mentionable,
+                hoist: params.hoist,
+            });
+            return {
+                content: [{ type: "text", text: `Created role "${role.name}" (ID: ${role.id})` }],
+            };
+        }
+        catch (error) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: `Error creating role: ${error.message}` }],
+            };
+        }
+    });
+    server.registerTool("discord_delete_role", {
+        title: "Delete Discord Role",
+        description: `Delete a role from a Discord server. This action is permanent!
+
+Args:
+  - guild_id (string): Discord server/guild ID
+  - role_id (string): Discord role ID to delete
+
+Returns:
+  Confirmation of deletion`,
+        inputSchema: DeleteRoleSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async (params) => {
+        try {
+            const client = await getClient();
+            const guild = client.guilds.cache.get(params.guild_id);
+            if (!guild) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `Guild not found: ${params.guild_id}` }],
+                };
+            }
+            const role = guild.roles.cache.get(params.role_id);
+            if (!role) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `Role not found: ${params.role_id}` }],
+                };
+            }
+            const name = role.name;
+            await role.delete();
+            return {
+                content: [{ type: "text", text: `Deleted role: ${name}` }],
+            };
+        }
+        catch (error) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: `Error deleting role: ${error.message}` }],
+            };
+        }
+    });
+    server.registerTool("discord_edit_role", {
+        title: "Edit Discord Role",
+        description: `Edit a role's properties including name, color, and permissions.
+
+Common permission names:
+- Admin: Administrator (grants all permissions)
+- General: ManageGuild, ManageRoles, ManageChannels, KickMembers, BanMembers, ModerateMembers
+- Messages: SendMessages, ManageMessages, EmbedLinks, AttachFiles, ReadMessageHistory, MentionEveryone
+- Voice: Connect, Speak, MuteMembers, DeafenMembers, MoveMembers, Stream
+- Other: ManageEmojisAndStickers, ManageWebhooks, ManageEvents, ViewAuditLog
+
+Args:
+  - guild_id (string): Discord server/guild ID
+  - role_id (string): Discord role ID to edit
+  - name (string, optional): New role name
+  - color (number, optional): Role color as decimal integer (e.g., 16711680 for red)
+  - mentionable (boolean, optional): Whether the role can be mentioned
+  - hoist (boolean, optional): Whether to display role members separately
+  - permissions (string[], optional): Permissions to grant (replaces existing). Examples: ['SendMessages', 'ViewChannel']
+
+Returns:
+  Updated role details`,
+        inputSchema: EditRoleSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async (params) => {
+        try {
+            const client = await getClient();
+            const guild = client.guilds.cache.get(params.guild_id);
+            if (!guild) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `Guild not found: ${params.guild_id}` }],
+                };
+            }
+            const role = guild.roles.cache.get(params.role_id);
+            if (!role) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `Role not found: ${params.role_id}` }],
+                };
+            }
+            // Build the edit options
+            const editOptions = {};
+            if (params.name !== undefined)
+                editOptions.name = params.name;
+            if (params.color !== undefined)
+                editOptions.color = params.color;
+            if (params.mentionable !== undefined)
+                editOptions.mentionable = params.mentionable;
+            if (params.hoist !== undefined)
+                editOptions.hoist = params.hoist;
+            // Handle permissions if provided
+            if (params.permissions !== undefined) {
+                const permissionBits = new PermissionsBitField();
+                for (const perm of params.permissions) {
+                    try {
+                        permissionBits.add(perm);
+                    }
+                    catch {
+                        return {
+                            isError: true,
+                            content: [{ type: "text", text: `Invalid permission: ${perm}. Valid permissions include: ${ROLE_PERMISSION_LIST.slice(0, 10).join(', ')}, ...` }],
+                        };
+                    }
+                }
+                editOptions.permissions = permissionBits.bitfield;
+            }
+            const updatedRole = await role.edit(editOptions);
+            const changes = [];
+            if (params.name !== undefined)
+                changes.push(`name: "${updatedRole.name}"`);
+            if (params.color !== undefined)
+                changes.push(`color: ${updatedRole.hexColor}`);
+            if (params.mentionable !== undefined)
+                changes.push(`mentionable: ${updatedRole.mentionable}`);
+            if (params.hoist !== undefined)
+                changes.push(`hoist: ${updatedRole.hoist}`);
+            if (params.permissions !== undefined)
+                changes.push(`permissions updated`);
+            return {
+                content: [{ type: "text", text: `Updated role "${updatedRole.name}" (ID: ${updatedRole.id})\nChanges: ${changes.join(', ')}` }],
+            };
+        }
+        catch (error) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: `Error editing role: ${error.message}` }],
+            };
+        }
+    });
+    server.registerTool("discord_set_role_positions", {
+        title: "Set Role Positions",
+        description: `Reorder role hierarchy by setting role positions.
+
+Higher position = more authority in the hierarchy. The @everyone role is always at position 0.
+Roles can only manage other roles below them in the hierarchy.
+
+IMPORTANT: The bot can only move roles that are below its own highest role in the hierarchy.
+
+Args:
+  - guild_id (string): Discord server/guild ID
+  - positions (array): Array of objects with:
+    - role_id (string): Discord role ID
+    - position (number): New position for the role (higher = more authority)
+
+Returns:
+  Confirmation of position changes`,
+        inputSchema: SetRolePositionsSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async (params) => {
+        try {
+            const client = await getClient();
+            const guild = client.guilds.cache.get(params.guild_id);
+            if (!guild) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `Guild not found: ${params.guild_id}` }],
+                };
+            }
+            // Validate all roles exist before making changes
+            for (const pos of params.positions) {
+                const role = guild.roles.cache.get(pos.role_id);
+                if (!role) {
+                    return {
+                        isError: true,
+                        content: [{ type: "text", text: `Role not found: ${pos.role_id}` }],
+                    };
+                }
+            }
+            // Format positions for Discord API
+            const positionUpdates = params.positions.map(pos => ({
+                role: pos.role_id,
+                position: pos.position,
+            }));
+            await guild.roles.setPositions(positionUpdates);
+            // Build response with updated positions
+            const updatedRoles = params.positions.map(pos => {
+                const role = guild.roles.cache.get(pos.role_id);
+                return `"${role?.name}" → position ${pos.position}`;
+            });
+            return {
+                content: [{ type: "text", text: `Updated role positions:\n${updatedRoles.join('\n')}` }],
+            };
+        }
+        catch (error) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: `Error setting role positions: ${error.message}` }],
+            };
+        }
+    });
+}

package/dist/tools/webhook.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerWebhookTools(server: McpServer): void;

package/dist/tools/webhook.js

@@ -0,0 +1,199 @@
+import { ListWebhooksSchema, CreateWebhookSchema, EditWebhookSchema, DeleteWebhookSchema, } from "../schemas/index.js";
+import { getClient, formatResponse, truncateIfNeeded, } from "../services/discord.js";
+export function registerWebhookTools(server) {
+    server.registerTool("discord_list_webhooks", {
+        title: "List Webhooks",
+        description: `List webhooks in a guild or channel.
+
+Args:
+  - guild_id (string, optional): List all webhooks in the server
+  - channel_id (string, optional): List webhooks for a specific channel
+  - response_format ('json' | 'markdown'): Output format
+
+Returns:
+  List of webhooks with name, channel, and URL`,
+        inputSchema: ListWebhooksSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async (params) => {
+        try {
+            const client = await getClient();
+            let webhooks;
+            if (params.channel_id) {
+                const channel = client.channels.cache.get(params.channel_id);
+                if (!channel || !('fetchWebhooks' in channel)) {
+                    return {
+                        isError: true,
+                        content: [{ type: "text", text: `Channel not found or doesn't support webhooks: ${params.channel_id}` }],
+                    };
+                }
+                webhooks = await channel.fetchWebhooks();
+            }
+            else if (params.guild_id) {
+                const guild = client.guilds.cache.get(params.guild_id);
+                if (!guild) {
+                    return {
+                        isError: true,
+                        content: [{ type: "text", text: `Guild not found: ${params.guild_id}` }],
+                    };
+                }
+                webhooks = await guild.fetchWebhooks();
+            }
+            else {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `Must provide either guild_id or channel_id` }],
+                };
+            }
+            const webhookList = webhooks.map(wh => ({
+                id: wh.id,
+                name: wh.name,
+                channel: wh.channel?.id,
+                url: wh.url,
+                owner: wh.owner?.username || 'Unknown',
+                avatar: wh.avatarURL(),
+            }));
+            const result = formatResponse(webhookList, params.response_format, (items) => items.map(w => `**${w.name}** (ID: ${w.id})\nChannel: <#${w.channel}>\nOwner: ${w.owner}`).join('\n\n'));
+            return {
+                content: [{ type: "text", text: truncateIfNeeded(result) }],
+            };
+        }
+        catch (error) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: `Error listing webhooks: ${error.message}` }],
+            };
+        }
+    });
+    server.registerTool("discord_create_webhook", {
+        title: "Create Webhook",
+        description: `Create a webhook in a channel.
+
+Args:
+  - channel_id (string): Discord channel ID
+  - name (string): Webhook name
+  - avatar_url (string, optional): Avatar image URL
+
+Returns:
+  Created webhook details including URL`,
+        inputSchema: CreateWebhookSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async (params) => {
+        try {
+            const client = await getClient();
+            const channel = client.channels.cache.get(params.channel_id);
+            if (!channel || !('createWebhook' in channel)) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `Channel not found or doesn't support webhooks: ${params.channel_id}` }],
+                };
+            }
+            const webhook = await channel.createWebhook({
+                name: params.name,
+                avatar: params.avatar_url,
+            });
+            return {
+                content: [{ type: "text", text: `Created webhook "${webhook.name}" (ID: ${webhook.id})\nURL: ${webhook.url}` }],
+            };
+        }
+        catch (error) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: `Error creating webhook: ${error.message}` }],
+            };
+        }
+    });
+    server.registerTool("discord_edit_webhook", {
+        title: "Edit Webhook",
+        description: `Edit an existing webhook.
+
+Args:
+  - webhook_id (string): Discord webhook ID
+  - name (string, optional): New webhook name
+  - channel_id (string, optional): Move webhook to different channel
+
+Returns:
+  Updated webhook details`,
+        inputSchema: EditWebhookSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async (params) => {
+        try {
+            const client = await getClient();
+            const webhook = await client.fetchWebhook(params.webhook_id).catch(() => null);
+            if (!webhook) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `Webhook not found: ${params.webhook_id}` }],
+                };
+            }
+            const editOptions = {};
+            if (params.name !== undefined)
+                editOptions.name = params.name;
+            if (params.channel_id !== undefined)
+                editOptions.channel = params.channel_id;
+            await webhook.edit(editOptions);
+            return {
+                content: [{ type: "text", text: `Updated webhook "${webhook.name}" (ID: ${webhook.id})` }],
+            };
+        }
+        catch (error) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: `Error editing webhook: ${error.message}` }],
+            };
+        }
+    });
+    server.registerTool("discord_delete_webhook", {
+        title: "Delete Webhook",
+        description: `Delete a webhook.
+
+Args:
+  - webhook_id (string): Discord webhook ID
+
+Returns:
+  Confirmation of deletion`,
+        inputSchema: DeleteWebhookSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async (params) => {
+        try {
+            const client = await getClient();
+            const webhook = await client.fetchWebhook(params.webhook_id).catch(() => null);
+            if (!webhook) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `Webhook not found: ${params.webhook_id}` }],
+                };
+            }
+            const name = webhook.name;
+            await webhook.delete();
+            return {
+                content: [{ type: "text", text: `Deleted webhook: ${name}` }],
+            };
+        }
+        catch (error) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: `Error deleting webhook: ${error.message}` }],
+            };
+        }
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mahesvara/discord-mcpserver",
-  "version": "1.0.8",
+  "version": "1.1.0",
   "description": "MCP server for controlling Discord servers via bot token",
   "author": "Mahesvara",
   "repository": {