discord-mcp

Instructions

Implementation Reference

• src/tools/event-tools.ts:107-160 (handler)

  The core handler function that implements the 'create_event' tool. It fetches the Discord guild, maps the entity type, constructs event creation options, calls guild.scheduledEvents.create(), and returns the created event details or error.

  async ({ guildId, name, description, scheduledStartTime, scheduledEndTime, entityType, channelId, location, image, reason }) => {
    const result = await withErrorHandling(async () => {
      const client = await getDiscordClient();
      const guild = await client.guilds.fetch(guildId);
  
      const entityTypeMap: Record<string, GuildScheduledEventEntityType> = {
        'STAGE_INSTANCE': GuildScheduledEventEntityType.StageInstance,
        'VOICE': GuildScheduledEventEntityType.Voice,
        'EXTERNAL': GuildScheduledEventEntityType.External,
      };
  
      const eventOptions: {
        name: string;
        scheduledStartTime: string;
        privacyLevel: GuildScheduledEventPrivacyLevel;
        entityType: GuildScheduledEventEntityType;
        description?: string;
        scheduledEndTime?: string;
        channel?: string;
        entityMetadata?: { location: string };
        image?: string;
        reason?: string;
      } = {
        name,
        scheduledStartTime,
        privacyLevel: GuildScheduledEventPrivacyLevel.GuildOnly,
        entityType: entityTypeMap[entityType],
      };
  
      if (description) eventOptions.description = description;
      if (scheduledEndTime) eventOptions.scheduledEndTime = scheduledEndTime;
      if (channelId) eventOptions.channel = channelId;
      if (location) eventOptions.entityMetadata = { location };
      if (image) eventOptions.image = image;
      if (reason) eventOptions.reason = reason;
  
      const event = await guild.scheduledEvents.create(eventOptions);
  
      return {
        id: event.id,
        name: event.name,
        scheduledStartTime: event.scheduledStartAt?.toISOString(),
        entityType: GuildScheduledEventEntityType[event.entityType],
        url: event.url,
        message: 'Event created successfully',
      };
    });
  
    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:96-106 (schema)

  Zod input schema defining parameters for the create_event tool, including guildId, name, times, entityType, etc.

    guildId: z.string().describe('The ID of the server (guild)'),
    name: z.string().describe('Name of the event'),
    description: z.string().optional().describe('Description of the event'),
    scheduledStartTime: z.string().describe('Start time in ISO 8601 format'),
    scheduledEndTime: z.string().optional().describe('End time in ISO 8601 format (required for external events)'),
    entityType: z.enum(['STAGE_INSTANCE', 'VOICE', 'EXTERNAL']).describe('Type of event'),
    channelId: z.string().optional().describe('Channel ID for voice/stage events'),
    location: z.string().optional().describe('Location for external events'),
    image: z.string().optional().describe('URL of the cover image'),
    reason: z.string().optional().describe('Reason for creating'),
  },

• src/tools/event-tools.ts:92-161 (registration)

  The server.tool() invocation that registers the 'create_event' tool on the MCP server, providing name, description, input schema, and handler function.

  server.tool(
    'create_event',
    'Create a scheduled event in a server',
    {
      guildId: z.string().describe('The ID of the server (guild)'),
      name: z.string().describe('Name of the event'),
      description: z.string().optional().describe('Description of the event'),
      scheduledStartTime: z.string().describe('Start time in ISO 8601 format'),
      scheduledEndTime: z.string().optional().describe('End time in ISO 8601 format (required for external events)'),
      entityType: z.enum(['STAGE_INSTANCE', 'VOICE', 'EXTERNAL']).describe('Type of event'),
      channelId: z.string().optional().describe('Channel ID for voice/stage events'),
      location: z.string().optional().describe('Location for external events'),
      image: z.string().optional().describe('URL of the cover image'),
      reason: z.string().optional().describe('Reason for creating'),
    },
    async ({ guildId, name, description, scheduledStartTime, scheduledEndTime, entityType, channelId, location, image, reason }) => {
      const result = await withErrorHandling(async () => {
        const client = await getDiscordClient();
        const guild = await client.guilds.fetch(guildId);
  
        const entityTypeMap: Record<string, GuildScheduledEventEntityType> = {
          'STAGE_INSTANCE': GuildScheduledEventEntityType.StageInstance,
          'VOICE': GuildScheduledEventEntityType.Voice,
          'EXTERNAL': GuildScheduledEventEntityType.External,
        };
  
        const eventOptions: {
          name: string;
          scheduledStartTime: string;
          privacyLevel: GuildScheduledEventPrivacyLevel;
          entityType: GuildScheduledEventEntityType;
          description?: string;
          scheduledEndTime?: string;
          channel?: string;
          entityMetadata?: { location: string };
          image?: string;
          reason?: string;
        } = {
          name,
          scheduledStartTime,
          privacyLevel: GuildScheduledEventPrivacyLevel.GuildOnly,
          entityType: entityTypeMap[entityType],
        };
  
        if (description) eventOptions.description = description;
        if (scheduledEndTime) eventOptions.scheduledEndTime = scheduledEndTime;
        if (channelId) eventOptions.channel = channelId;
        if (location) eventOptions.entityMetadata = { location };
        if (image) eventOptions.image = image;
        if (reason) eventOptions.reason = reason;
  
        const event = await guild.scheduledEvents.create(eventOptions);
  
        return {
          id: event.id,
          name: event.name,
          scheduledStartTime: event.scheduledStartAt?.toISOString(),
          entityType: GuildScheduledEventEntityType[event.entityType],
          url: event.url,
          message: 'Event created successfully',
        };
      });
  
      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 the event tools including 'create_event'.

  registerEventTools(server);

• src/index.ts:20-20 (registration)

  Import of registerEventTools from event-tools.ts, enabling registration of the create_event tool.

  import { registerEventTools } from './tools/event-tools.js';