discord_read_dms

Instructions

Implementation Reference

• src/tools/dm.ts:225-240 (handler)

  The handler function for discord_read_dms. Fetches the DM channel, retrieves up to 'limit' messages (1-100, default 20), sorts them chronologically, and returns them as a JSON string with id, author, content, embed count, and timestamp.

  case "discord_read_dms": {
    const user = await discord.users.fetch(validateId(args.user_id, "user_id"));
    const dm = await user.createDM();
    const limit = Math.min(Math.max(Number(args.limit ?? 20), 1), 100);
    const messages = await dm.messages.fetch({ limit });
    const result = [...messages.values()]
      .sort((a, b) => a.createdTimestamp - b.createdTimestamp)
      .map((m) => ({
        id: m.id,
        author: m.author.username,
        content: m.content,
        embeds: m.embeds.length,
        timestamp: m.createdAt.toISOString(),
      }));
    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
  }

• src/tools/dm.ts:140-152 (schema)

  The input schema definition for discord_read_dms: requires user_id (string), optional limit (number, 1-100, default 20).

  {
    name: "discord_read_dms",
    description:
      "Read the last N messages from a DM conversation with a user.",
    inputSchema: {
      type: "object",
      properties: {
        ...userIdProp,
        limit: { type: "number", description: "1–100, default 20." },
      },
      required: ["user_id"],
    },
  },

• src/tools/index.ts:26-42 (registration)

  The dm module is imported and added to the modules array, registering all DM tools (including discord_read_dms) with the tool registry.

  import dm from "./dm.js";
  
  const modules: ToolModule[] = [
    discovery,
    messages,
    channels,
    permissions,
    members,
    roles,
    moderation,
    screening,
    stats,
    forums,
    webhooks,
    scheduledEvents,
    invites,
    dm,

• src/client.ts:97-101 (helper)

  The validateId helper used to validate the user_id argument in the discord_read_dms handler.

  export function validateId(value: unknown, label: string): string {
    const id = String(value ?? "");
    if (!/^\d{17,20}$/.test(id)) throw new Error(`Invalid ${label}: "${id}". Must be a Discord snowflake ID (17-20 digits).`);
    return id;
  }

• src/tools/dm.ts:170-254 (handler)

  The surrounding handle() function that dispatches tool names via switch statement, where discord_read_dms is one case.

  async function handle(
    name: string,
    args: Record<string, unknown>
  ): Promise<ToolResult | null> {
    switch (name) {
      case "discord_send_dm": {
        const user = await discord.users.fetch(validateId(args.user_id, "user_id"));
        const sent = await user.send(args.content as string);
        return { content: [{ type: "text", text: `✅ DM sent to ${user.username} (message id: ${sent.id}).` }] };
      }
  
      case "discord_send_dm_embed": {
        const user = await discord.users.fetch(validateId(args.user_id, "user_id"));
        const embed = buildEmbed(args);
        const sent = await user.send({
          content: (args.content as string) || undefined,
          embeds: [embed],
        });
        return { content: [{ type: "text", text: `✅ DM embed sent to ${user.username} (message id: ${sent.id}).` }] };
      }
  
      case "discord_edit_dm": {
        const user = await discord.users.fetch(validateId(args.user_id, "user_id"));
        const dm = await user.createDM();
        const msgId = validateId(args.message_id, "message_id");
        const msg = await dm.messages.fetch(msgId);
        if (msg.author.id !== discord.user?.id) throw new Error("Can only edit messages sent by the bot.");
        await msg.edit(args.content as string);
        return { content: [{ type: "text", text: `✅ DM message ${msgId} edited for ${user.username}.` }] };
      }
  
      case "discord_edit_dm_embed": {
        const user = await discord.users.fetch(validateId(args.user_id, "user_id"));
        const dm = await user.createDM();
        const msgId = validateId(args.message_id, "message_id");
        const msg = await dm.messages.fetch(msgId);
        if (msg.author.id !== discord.user?.id) throw new Error("Can only edit embeds sent by the bot.");
        const embed = buildEmbed(args);
        await msg.edit({
          content: (args.content as string) || undefined,
          embeds: [embed],
        });
        return { content: [{ type: "text", text: `✅ DM embed edited on message ${msgId} for ${user.username}.` }] };
      }
  
      case "discord_delete_dm": {
        const user = await discord.users.fetch(validateId(args.user_id, "user_id"));
        const dm = await user.createDM();
        const msgId = validateId(args.message_id, "message_id");
        const msg = await dm.messages.fetch(msgId);
        if (msg.author.id !== discord.user?.id) throw new Error("Can only delete messages sent by the bot.");
        await msg.delete();
        return { content: [{ type: "text", text: `✅ DM message ${msgId} deleted for ${user.username}.` }] };
      }
  
      case "discord_read_dms": {
        const user = await discord.users.fetch(validateId(args.user_id, "user_id"));
        const dm = await user.createDM();
        const limit = Math.min(Math.max(Number(args.limit ?? 20), 1), 100);
        const messages = await dm.messages.fetch({ limit });
        const result = [...messages.values()]
          .sort((a, b) => a.createdTimestamp - b.createdTimestamp)
          .map((m) => ({
            id: m.id,
            author: m.author.username,
            content: m.content,
            embeds: m.embeds.length,
            timestamp: m.createdAt.toISOString(),
          }));
        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
      }
  
      case "discord_reply_dm": {
        const user = await discord.users.fetch(validateId(args.user_id, "user_id"));
        const dm = await user.createDM();
        const msgId = validateId(args.message_id, "message_id");
        const target = await dm.messages.fetch(msgId);
        const sent = await target.reply(args.content as string);
        return { content: [{ type: "text", text: `✅ DM reply sent to ${user.username} (message id: ${sent.id}).` }] };
      }
  
      default:
        return null;
    }
  }