discord-mcp

Instructions

Implementation Reference

• src/tools/event-tools.ts:16-46 (handler)

  The handler function that lists all scheduled events in a Discord server/guild. It fetches the guild, retrieves events (optionally with user count), maps event data to a structured format, handles errors using withErrorHandling, and returns a JSON-formatted text response.

  async ({ guildId, withUserCount = true }) => {
    const result = await withErrorHandling(async () => {
      const client = await getDiscordClient();
      const guild = await client.guilds.fetch(guildId);
      const events = await guild.scheduledEvents.fetch({ withUserCount });
  
      return events.map((event) => ({
        id: event.id,
        name: event.name,
        description: event.description,
        scheduledStartTime: event.scheduledStartAt?.toISOString(),
        scheduledEndTime: event.scheduledEndAt?.toISOString(),
        privacyLevel: GuildScheduledEventPrivacyLevel[event.privacyLevel],
        status: GuildScheduledEventStatus[event.status],
        entityType: GuildScheduledEventEntityType[event.entityType],
        entityId: event.entityId,
        channelId: event.channelId,
        creatorId: event.creatorId,
        userCount: event.userCount,
        location: event.entityMetadata?.location,
        image: event.coverImageURL(),
        url: event.url,
      }));
    });
  
    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/event-tools.ts:12-15 (schema)

  Zod input schema defining parameters for the list_events tool: required guildId (string) and optional withUserCount (boolean, defaults to true).

  {
    guildId: z.string().describe('The ID of the server (guild)'),
    withUserCount: z.boolean().optional().describe('Include user count (default true)'),
  },

• src/tools/event-tools.ts:9-47 (registration)

  The server.tool() call that registers the list_events tool on the MCP server, including name, description, input schema, and handler function.

  server.tool(
    'list_events',
    'List all scheduled events in a server',
    {
      guildId: z.string().describe('The ID of the server (guild)'),
      withUserCount: z.boolean().optional().describe('Include user count (default true)'),
    },
    async ({ guildId, withUserCount = true }) => {
      const result = await withErrorHandling(async () => {
        const client = await getDiscordClient();
        const guild = await client.guilds.fetch(guildId);
        const events = await guild.scheduledEvents.fetch({ withUserCount });
  
        return events.map((event) => ({
          id: event.id,
          name: event.name,
          description: event.description,
          scheduledStartTime: event.scheduledStartAt?.toISOString(),
          scheduledEndTime: event.scheduledEndAt?.toISOString(),
          privacyLevel: GuildScheduledEventPrivacyLevel[event.privacyLevel],
          status: GuildScheduledEventStatus[event.status],
          entityType: GuildScheduledEventEntityType[event.entityType],
          entityId: event.entityId,
          channelId: event.channelId,
          creatorId: event.creatorId,
          userCount: event.userCount,
          location: event.entityMetadata?.location,
          image: event.coverImageURL(),
          url: event.url,
        }));
      });
  
      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:63-63 (registration)

  Invocation of registerEventTools(server) in the main MCP server setup, which registers all event-related tools including list_events.

  registerEventTools(server);