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, ChannelNotFoundError, MessageNotFoundError, } from "../errors/discord.js"; import { embedSchema, messageSchema } from "../types/schemas.js"; import { PermissionFlagsBits } from "discord.js"; export function registerMessagingTools( server: McpServer, discordManager: DiscordClientManager, logger: Logger, ) { // Send Message Tool server.registerTool( "send_message", { title: "Send Discord Message", description: "Send a message to a Discord channel", inputSchema: { channelId: z.string().describe("Channel ID (snowflake) or name"), content: z.string().max(2000).describe("Message content"), embeds: z .array(embedSchema) .max(10) .optional() .describe("Optional embeds (max 10)"), }, outputSchema: { success: z.boolean(), messageId: z.string().optional(), channelId: z.string().optional(), timestamp: z.string().optional(), error: z.string().optional(), }, }, async ({ channelId, content, embeds }) => { try { const client = discordManager.getClient(); // Resolve channel const channel = await client.channels .fetch(channelId) .catch(() => null); if (!channel || !channel.isTextBased()) { throw new ChannelNotFoundError(channelId); } // Check permissions if ("guild" in channel && channel.guild) { const permissions = channel.permissionsFor(client.user!); if (!permissions?.has(PermissionFlagsBits.SendMessages)) { throw new PermissionDeniedError("SendMessages", channelId); } if ( channel.isThread() && !permissions?.has(PermissionFlagsBits.SendMessagesInThreads) ) { throw new PermissionDeniedError("SendMessagesInThreads", channelId); } } // Send message (type narrowing for send method) if (!("send" in channel)) { throw new ChannelNotFoundError(channelId); } const message = await channel.send({ content, embeds: embeds || [], }); const output = { success: true, messageId: message.id, channelId: channel.id, timestamp: message.createdAt.toISOString(), }; logger.info("Message sent", { channelId, messageId: message.id }); return { content: [ { type: "text" as const, text: `Message sent successfully to <#${channel.id}>`, }, ], structuredContent: output, }; } catch (error: any) { logger.error("Failed to send message", { error: error.message, channelId, }); const output = { success: false, error: error.message, }; return { content: [ { type: "text" as const, text: `Failed to send message: ${error.message}`, }, ], structuredContent: output, isError: true, }; } }, ); // Read Messages Tool server.registerTool( "read_messages", { title: "Read Discord Messages", description: "Retrieve recent message history from a channel", inputSchema: { channelId: z.string().describe("Channel ID or name"), limit: z .number() .int() .min(1) .max(100) .default(50) .describe("Number of messages to retrieve"), before: z .string() .optional() .describe("Get messages before this message ID"), after: z .string() .optional() .describe("Get messages after this message ID"), }, outputSchema: { success: z.boolean(), messages: z.array(messageSchema).optional(), hasMore: z.boolean().optional(), error: z.string().optional(), }, }, async ({ channelId, limit, before, after }) => { try { const client = discordManager.getClient(); const channel = await client.channels .fetch(channelId) .catch(() => null); if (!channel || !channel.isTextBased()) { throw new ChannelNotFoundError(channelId); } // Check permissions if ("guild" in channel && channel.guild) { const permissions = channel.permissionsFor(client.user!); if (!permissions?.has(PermissionFlagsBits.ViewChannel)) { throw new PermissionDeniedError("ViewChannel", channelId); } if (!permissions?.has(PermissionFlagsBits.ReadMessageHistory)) { throw new PermissionDeniedError("ReadMessageHistory", channelId); } } // Fetch messages const messages = await channel.messages.fetch({ limit, before, after, }); const formattedMessages = messages.map((msg) => ({ id: msg.id, content: msg.content, author: { id: msg.author.id, username: msg.author.username, discriminator: msg.author.discriminator, bot: msg.author.bot, avatar: msg.author.avatar, }, timestamp: msg.createdAt.toISOString(), editedTimestamp: msg.editedAt?.toISOString() || null, attachments: msg.attachments.map((att) => ({ id: att.id, filename: att.name, size: att.size, url: att.url, contentType: att.contentType || undefined, })), embeds: msg.embeds.map((embed) => ({ title: embed.title || undefined, description: embed.description || undefined, url: embed.url || undefined, color: embed.color || undefined, timestamp: embed.timestamp ? new Date(embed.timestamp).toISOString() : undefined, })), reactions: msg.reactions.cache.map((reaction) => ({ emoji: reaction.emoji.name || reaction.emoji.id || "", count: reaction.count, me: reaction.me, })), })); const output = { success: true, messages: formattedMessages, hasMore: messages.size === limit, }; logger.info("Messages retrieved", { channelId, count: messages.size }); return { content: [ { type: "text" as const, text: `Retrieved ${messages.size} message(s) from <#${channel.id}>`, }, ], structuredContent: output, }; } catch (error: any) { logger.error("Failed to read messages", { error: error.message, channelId, }); const output = { success: false, error: error.message, }; return { content: [ { type: "text" as const, text: `Failed to read messages: ${error.message}`, }, ], structuredContent: output, isError: true, }; } }, ); // Delete Message Tool server.registerTool( "delete_message", { title: "Delete Discord Message", description: "Delete a specific message from a channel", inputSchema: { channelId: z.string().describe("Channel ID"), messageId: z.string().describe("Message ID to delete"), reason: z .string() .optional() .describe("Reason for deletion (audit log)"), }, outputSchema: { success: z.boolean(), deletedMessageId: z.string().optional(), error: z.string().optional(), }, }, async ({ channelId, messageId, reason }) => { try { const client = discordManager.getClient(); const channel = await client.channels .fetch(channelId) .catch(() => null); if (!channel || !channel.isTextBased()) { throw new ChannelNotFoundError(channelId); } const message = await channel.messages .fetch(messageId) .catch(() => null); if (!message) { throw new MessageNotFoundError(messageId); } // Check permissions (bot can always delete own messages) if (message.author.id !== client.user!.id) { if ("guild" in channel && channel.guild) { const permissions = channel.permissionsFor(client.user!); if (!permissions?.has(PermissionFlagsBits.ManageMessages)) { throw new PermissionDeniedError("ManageMessages", channelId); } } } await message.delete(); const output = { success: true, deletedMessageId: messageId, }; logger.info("Message deleted", { channelId, messageId, reason }); return { content: [ { type: "text" as const, text: `Message ${messageId} deleted successfully`, }, ], structuredContent: output, }; } catch (error: any) { logger.error("Failed to delete message", { error: error.message, channelId, messageId, }); const output = { success: false, error: error.message, }; return { content: [ { type: "text" as const, text: `Failed to delete message: ${error.message}`, }, ], structuredContent: output, isError: true, }; } }, ); // Add Reaction Tool server.registerTool( "add_reaction", { title: "Add Reaction to Message", description: "Add an emoji reaction to a message", inputSchema: { channelId: z.string().describe("Channel ID"), messageId: z.string().describe("Message ID"), emoji: z .string() .describe("Unicode emoji or custom emoji format (name:id)"), }, outputSchema: { success: z.boolean(), error: z.string().optional(), }, }, async ({ channelId, messageId, emoji }) => { try { const client = discordManager.getClient(); const channel = await client.channels .fetch(channelId) .catch(() => null); if (!channel || !channel.isTextBased()) { throw new ChannelNotFoundError(channelId); } const message = await channel.messages .fetch(messageId) .catch(() => null); if (!message) { throw new MessageNotFoundError(messageId); } // Check permissions if ("guild" in channel && channel.guild) { const permissions = channel.permissionsFor(client.user!); if (!permissions?.has(PermissionFlagsBits.AddReactions)) { throw new PermissionDeniedError("AddReactions", channelId); } } await message.react(emoji); const output = { success: true }; logger.info("Reaction added", { channelId, messageId, emoji }); return { content: [ { type: "text" as const, text: `Reaction ${emoji} added to message`, }, ], structuredContent: output, }; } catch (error: any) { logger.error("Failed to add reaction", { error: error.message, channelId, messageId, emoji, }); const output = { success: false, error: error.message, }; return { content: [ { type: "text" as const, text: `Failed to add reaction: ${error.message}`, }, ], structuredContent: output, isError: true, }; } }, ); // Edit Message Tool server.registerTool( "edit_message", { title: "Edit Discord Message", description: "Edit an existing message sent by the bot", inputSchema: { channelId: z.string().describe("Channel ID"), messageId: z.string().describe("Message ID to edit"), content: z .string() .max(2000) .optional() .describe("New message content"), embeds: z .array(embedSchema) .max(10) .optional() .describe("New embeds (max 10)"), }, outputSchema: { success: z.boolean(), messageId: z.string().optional(), editedTimestamp: z.string().optional(), error: z.string().optional(), }, }, async ({ channelId, messageId, content, embeds }) => { try { const client = discordManager.getClient(); const channel = await client.channels .fetch(channelId) .catch(() => null); if (!channel || !channel.isTextBased()) { throw new ChannelNotFoundError(channelId); } const message = await channel.messages .fetch(messageId) .catch(() => null); if (!message) { throw new MessageNotFoundError(messageId); } // Check if message was sent by the bot if (message.author.id !== client.user!.id) { throw new Error( "Can only edit messages sent by the bot. This message belongs to another user.", ); } // Edit message const editedMessage = await message.edit({ content: content || message.content, embeds: embeds || message.embeds, }); const output = { success: true, messageId: editedMessage.id, editedTimestamp: editedMessage.editedAt?.toISOString(), }; logger.info("Message edited", { channelId, messageId }); return { content: [ { type: "text" as const, text: `Message ${messageId} edited successfully`, }, ], structuredContent: output, }; } catch (error: any) { logger.error("Failed to edit message", { error: error.message, channelId, messageId, }); const output = { success: false, error: error.message, }; return { content: [ { type: "text" as const, text: `Failed to edit message: ${error.message}`, }, ], structuredContent: output, isError: true, }; } }, ); // Send Message with File Tool server.registerTool( "send_message_with_file", { title: "Send Discord Message with File", description: "Send a message with file attachment to a Discord channel", inputSchema: { channelId: z.string().describe("Channel ID (snowflake) or name"), content: z .string() .max(2000) .optional() .describe("Message content (optional if file provided)"), filePath: z.string().describe("Absolute path to file to attach"), fileName: z .string() .optional() .describe( "Custom filename (optional, uses original if not provided)", ), embeds: z .array(embedSchema) .max(10) .optional() .describe("Optional embeds (max 10)"), }, outputSchema: { success: z.boolean(), messageId: z.string().optional(), channelId: z.string().optional(), timestamp: z.string().optional(), attachmentUrl: z.string().optional(), error: z.string().optional(), }, }, async ({ channelId, content, filePath, fileName, embeds }) => { try { const client = discordManager.getClient(); // Resolve channel const channel = await client.channels .fetch(channelId) .catch(() => null); if (!channel || !channel.isTextBased()) { throw new ChannelNotFoundError(channelId); } // Check permissions if ("guild" in channel && channel.guild) { const permissions = channel.permissionsFor(client.user!); if (!permissions?.has(PermissionFlagsBits.SendMessages)) { throw new PermissionDeniedError("SendMessages", channelId); } if (!permissions?.has(PermissionFlagsBits.AttachFiles)) { throw new PermissionDeniedError("AttachFiles", channelId); } if ( channel.isThread() && !permissions?.has(PermissionFlagsBits.SendMessagesInThreads) ) { throw new PermissionDeniedError("SendMessagesInThreads", channelId); } } // Import fs module dynamically const fs = await import("fs"); const path = await import("path"); // Check if file exists if (!fs.existsSync(filePath)) { throw new Error(`File not found: ${filePath}`); } // Prepare attachment const attachment = { attachment: filePath, name: fileName || path.basename(filePath), }; // Send message (type narrowing for send method) if (!("send" in channel)) { throw new ChannelNotFoundError(channelId); } const message = await channel.send({ content: content || undefined, embeds: embeds || [], files: [attachment], }); const attachmentUrl = message.attachments.first()?.url || "No attachment URL"; const output = { success: true, messageId: message.id, channelId: channel.id, timestamp: message.createdAt.toISOString(), attachmentUrl, }; logger.info("Message with file sent", { channelId, messageId: message.id, filePath, }); return { content: [ { type: "text" as const, text: `Message with file sent successfully to <#${channel.id}>`, }, ], structuredContent: output, }; } catch (error: any) { logger.error("Failed to send message with file", { error: error.message, channelId, filePath, }); const output = { success: false, error: error.message, }; return { content: [ { type: "text" as const, text: `Failed to send message with file: ${error.message}`, }, ], structuredContent: output, isError: true, }; } }, ); // Pin Message Tool server.registerTool( "pin_message", { title: "Pin Discord Message", description: "Pin a message to the channel", inputSchema: { channelId: z.string().describe("Channel ID"), messageId: z.string().describe("Message ID to pin"), reason: z .string() .optional() .describe("Reason for pinning (audit log)"), }, outputSchema: { success: z.boolean(), pinnedMessageId: z.string().optional(), error: z.string().optional(), }, }, async ({ channelId, messageId, reason }) => { try { const client = discordManager.getClient(); const channel = await client.channels .fetch(channelId) .catch(() => null); if (!channel || !channel.isTextBased()) { throw new ChannelNotFoundError(channelId); } const message = await channel.messages .fetch(messageId) .catch(() => null); if (!message) { throw new MessageNotFoundError(messageId); } // Check permissions if ("guild" in channel && channel.guild) { const permissions = channel.permissionsFor(client.user!); if (!permissions?.has(PermissionFlagsBits.ManageMessages)) { throw new PermissionDeniedError("ManageMessages", channelId); } } await message.pin(reason); const output = { success: true, pinnedMessageId: messageId, }; logger.info("Message pinned", { channelId, messageId, reason }); return { content: [ { type: "text" as const, text: `Message ${messageId} pinned successfully`, }, ], structuredContent: output, }; } catch (error: any) { logger.error("Failed to pin message", { error: error.message, channelId, messageId, }); const output = { success: false, error: error.message, }; return { content: [ { type: "text" as const, text: `Failed to pin message: ${error.message}`, }, ], structuredContent: output, isError: true, }; } }, ); // Send Rich Message Tool server.registerTool( "send_rich_message", { title: "Send Rich Discord Message", description: "Send a richly formatted message with embeds, images, and advanced formatting. Supports full Discord markdown and embed features.", inputSchema: { channelId: z.string().describe("Channel ID (snowflake) or name"), content: z .string() .max(2000) .optional() .describe( "Message content with Discord markdown formatting (bold: **text**, italic: *text*, underline: __text__, strikethrough: ~~text~~, code: `code`, code block: ```language\\ncode\\n```)", ), embed: z .object({ title: z.string().max(256).optional(), description: z.string().max(4096).optional(), url: z.string().url().optional(), color: z .number() .int() .min(0) .max(0xffffff) .optional() .describe("Hex color as integer (e.g., 0x00ff00 for green)"), image: z .string() .url() .optional() .describe("Large image URL at bottom of embed"), thumbnail: z .string() .url() .optional() .describe("Small image URL at top-right of embed"), author: z .object({ name: z.string().max(256), url: z.string().url().optional(), iconURL: z.string().url().optional(), }) .optional(), footer: z .object({ text: z.string().max(2048), iconURL: z.string().url().optional(), }) .optional(), fields: z .array( z.object({ name: z.string().max(256), value: z.string().max(1024), inline: z.boolean().optional(), }), ) .max(25) .optional(), timestamp: z.boolean().optional().describe("Add current timestamp"), }) .optional() .describe("Rich embed object with images and formatting"), }, outputSchema: { success: z.boolean(), messageId: z.string().optional(), channelId: z.string().optional(), timestamp: z.string().optional(), error: z.string().optional(), }, }, async ({ channelId, content, embed }) => { try { const client = discordManager.getClient(); // Resolve channel const channel = await client.channels .fetch(channelId) .catch(() => null); if (!channel || !channel.isTextBased()) { throw new ChannelNotFoundError(channelId); } // Check permissions if ("guild" in channel && channel.guild) { const permissions = channel.permissionsFor(client.user!); if (!permissions?.has(PermissionFlagsBits.SendMessages)) { throw new PermissionDeniedError("SendMessages", channelId); } if (embed && !permissions?.has(PermissionFlagsBits.EmbedLinks)) { throw new PermissionDeniedError("EmbedLinks", channelId); } if ( channel.isThread() && !permissions?.has(PermissionFlagsBits.SendMessagesInThreads) ) { throw new PermissionDeniedError("SendMessagesInThreads", channelId); } } // Build embed if provided let embedPayload: any[] = []; if (embed) { const embedObj: any = {}; if (embed.title) embedObj.title = embed.title; if (embed.description) embedObj.description = embed.description; if (embed.url) embedObj.url = embed.url; if (embed.color !== undefined) embedObj.color = embed.color; if (embed.author) { embedObj.author = { name: embed.author.name, url: embed.author.url, icon_url: embed.author.iconURL, }; } if (embed.footer) { embedObj.footer = { text: embed.footer.text, icon_url: embed.footer.iconURL, }; } if (embed.image) { embedObj.image = { url: embed.image }; } if (embed.thumbnail) { embedObj.thumbnail = { url: embed.thumbnail }; } if (embed.fields) { embedObj.fields = embed.fields; } if (embed.timestamp) { embedObj.timestamp = new Date().toISOString(); } embedPayload = [embedObj]; } // Send message (type narrowing for send method) if (!("send" in channel)) { throw new ChannelNotFoundError(channelId); } const message = await channel.send({ content: content || undefined, embeds: embedPayload, }); const output = { success: true, messageId: message.id, channelId: channel.id, timestamp: message.createdAt.toISOString(), }; logger.info("Rich message sent", { channelId, messageId: message.id }); return { content: [ { type: "text" as const, text: `Rich message sent successfully to <#${channel.id}>`, }, ], structuredContent: output, }; } catch (error: any) { logger.error("Failed to send rich message", { error: error.message, channelId, }); const output = { success: false, error: error.message, }; return { content: [ { type: "text" as const, text: `Failed to send rich message: ${error.message}`, }, ], structuredContent: output, isError: true, }; } }, ); // Unpin Message Tool server.registerTool( "unpin_message", { title: "Unpin Discord Message", description: "Unpin a message from the channel", inputSchema: { channelId: z.string().describe("Channel ID"), messageId: z.string().describe("Message ID to unpin"), reason: z .string() .optional() .describe("Reason for unpinning (audit log)"), }, outputSchema: { success: z.boolean(), unpinnedMessageId: z.string().optional(), error: z.string().optional(), }, }, async ({ channelId, messageId, reason }) => { try { const client = discordManager.getClient(); const channel = await client.channels .fetch(channelId) .catch(() => null); if (!channel || !channel.isTextBased()) { throw new ChannelNotFoundError(channelId); } const message = await channel.messages .fetch(messageId) .catch(() => null); if (!message) { throw new MessageNotFoundError(messageId); } // Check permissions if ("guild" in channel && channel.guild) { const permissions = channel.permissionsFor(client.user!); if (!permissions?.has(PermissionFlagsBits.ManageMessages)) { throw new PermissionDeniedError("ManageMessages", channelId); } } await message.unpin(reason); const output = { success: true, unpinnedMessageId: messageId, }; logger.info("Message unpinned", { channelId, messageId, reason }); return { content: [ { type: "text" as const, text: `Message ${messageId} unpinned successfully`, }, ], structuredContent: output, }; } catch (error: any) { logger.error("Failed to unpin message", { error: error.message, channelId, messageId, }); const output = { success: false, error: error.message, }; return { content: [ { type: "text" as const, text: `Failed to unpin message: ${error.message}`, }, ], structuredContent: output, isError: true, }; } }, ); }