discord-mcp

Instructions

Implementation Reference

• src/tools/audit-tools.ts:19-63 (handler)

  The handler function that implements the core logic for fetching, filtering, formatting, and returning Discord audit logs as JSON.

  async ({ guildId, limit = 50, userId, actionType, before }) => {
    const result = await withErrorHandling(async () => {
      const client = await getDiscordClient();
      const guild = await client.guilds.fetch(guildId);
  
      const fetchOptions: { limit: number; user?: string; type?: AuditLogEvent; before?: string } = {
        limit: Math.min(Math.max(1, limit), 100),
      };
      if (userId) fetchOptions.user = userId;
      if (before) fetchOptions.before = before;
      if (actionType) {
        const eventType = AuditLogEvent[actionType as keyof typeof AuditLogEvent];
        if (eventType !== undefined) fetchOptions.type = eventType;
      }
  
      const auditLogs = await guild.fetchAuditLogs(fetchOptions);
  
      return auditLogs.entries.map((entry) => ({
        id: entry.id,
        action: AuditLogEvent[entry.action],
        actionType: entry.actionType,
        targetType: entry.targetType,
        targetId: entry.targetId,
        executorId: entry.executorId,
        executor: entry.executor ? {
          id: entry.executor.id,
          username: entry.executor.username,
        } : null,
        reason: entry.reason,
        createdAt: entry.createdAt.toISOString(),
        changes: entry.changes.map((change) => ({
          key: change.key,
          old: change.old,
          new: change.new,
        })),
        extra: entry.extra,
      }));
    });
  
    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/audit-tools.ts:12-18 (schema)

  Input schema using Zod for validating parameters: guildId (required), limit, userId, actionType, before (optional).

  {
    guildId: z.string().describe('The ID of the server (guild)'),
    limit: z.number().optional().describe('Number of entries to fetch (1-100, default 50)'),
    userId: z.string().optional().describe('Filter by user who performed action'),
    actionType: z.string().optional().describe('Filter by action type (e.g., MEMBER_BAN_ADD, CHANNEL_CREATE)'),
    before: z.string().optional().describe('Get entries before this audit log entry ID'),
  },

• src/tools/audit-tools.ts:10-64 (registration)

  Registers the 'get_audit_logs' tool on the MCP server with name, description, input schema, and handler function.

    'get_audit_logs',
    'Get audit logs from a server',
    {
      guildId: z.string().describe('The ID of the server (guild)'),
      limit: z.number().optional().describe('Number of entries to fetch (1-100, default 50)'),
      userId: z.string().optional().describe('Filter by user who performed action'),
      actionType: z.string().optional().describe('Filter by action type (e.g., MEMBER_BAN_ADD, CHANNEL_CREATE)'),
      before: z.string().optional().describe('Get entries before this audit log entry ID'),
    },
    async ({ guildId, limit = 50, userId, actionType, before }) => {
      const result = await withErrorHandling(async () => {
        const client = await getDiscordClient();
        const guild = await client.guilds.fetch(guildId);
  
        const fetchOptions: { limit: number; user?: string; type?: AuditLogEvent; before?: string } = {
          limit: Math.min(Math.max(1, limit), 100),
        };
        if (userId) fetchOptions.user = userId;
        if (before) fetchOptions.before = before;
        if (actionType) {
          const eventType = AuditLogEvent[actionType as keyof typeof AuditLogEvent];
          if (eventType !== undefined) fetchOptions.type = eventType;
        }
  
        const auditLogs = await guild.fetchAuditLogs(fetchOptions);
  
        return auditLogs.entries.map((entry) => ({
          id: entry.id,
          action: AuditLogEvent[entry.action],
          actionType: entry.actionType,
          targetType: entry.targetType,
          targetId: entry.targetId,
          executorId: entry.executorId,
          executor: entry.executor ? {
            id: entry.executor.id,
            username: entry.executor.username,
          } : null,
          reason: entry.reason,
          createdAt: entry.createdAt.toISOString(),
          changes: entry.changes.map((change) => ({
            key: change.key,
            old: change.old,
            new: change.new,
          })),
          extra: entry.extra,
        }));
      });
  
      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:65-65 (registration)

  Top-level call to register all audit tools, including get_audit_logs, on the MCP server instance.

  registerAuditTools(server);