discord-mcp

Instructions

Implementation Reference

• src/tools/role-tools.ts:96-126 (handler)

  The handler function for the 'create_role' tool. It fetches the Discord guild, constructs role creation options based on input parameters, creates the role using guild.roles.create(), handles errors with withErrorHandling, and returns the new role information or an error response.

  async ({ guildId, name, color, hoist, mentionable, permissions, position, reason }) => {
    const result = await withErrorHandling(async () => {
      const client = await getDiscordClient();
      const guild = await client.guilds.fetch(guildId);
  
      const roleOptions: Record<string, unknown> = { name };
      if (color !== undefined) roleOptions.color = color;
      if (hoist !== undefined) roleOptions.hoist = hoist;
      if (mentionable !== undefined) roleOptions.mentionable = mentionable;
      if (permissions !== undefined) {
        roleOptions.permissions = new PermissionsBitField(permissions as any);
      }
      if (position !== undefined) roleOptions.position = position;
      if (reason !== undefined) roleOptions.reason = reason;
  
      const newRole = await guild.roles.create(roleOptions);
      return {
        id: newRole.id,
        name: newRole.name,
        color: newRole.hexColor,
        position: newRole.position,
        message: 'Role 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/role-tools.ts:86-95 (schema)

  Input schema for the 'create_role' tool defined using Zod, specifying parameters like guildId, name, optional color, permissions, etc.

  {
    guildId: z.string().describe('The ID of the server (guild)'),
    name: z.string().describe('Name of the new role'),
    color: z.string().optional().describe('Hex color code (e.g., #FF0000)'),
    hoist: z.boolean().optional().describe('Whether to display the role separately'),
    mentionable: z.boolean().optional().describe('Whether the role can be mentioned'),
    permissions: z.array(z.string()).optional().describe('Array of permission names'),
    position: z.number().optional().describe('Position of the role'),
    reason: z.string().optional().describe('Reason for creating the role'),
  },

• src/tools/role-tools.ts:83-127 (registration)

  The server.tool() call within registerRoleTools that registers the 'create_role' tool, providing name, description, input schema, and handler function.

  server.tool(
    'create_role',
    'Create a new role in a Discord server',
    {
      guildId: z.string().describe('The ID of the server (guild)'),
      name: z.string().describe('Name of the new role'),
      color: z.string().optional().describe('Hex color code (e.g., #FF0000)'),
      hoist: z.boolean().optional().describe('Whether to display the role separately'),
      mentionable: z.boolean().optional().describe('Whether the role can be mentioned'),
      permissions: z.array(z.string()).optional().describe('Array of permission names'),
      position: z.number().optional().describe('Position of the role'),
      reason: z.string().optional().describe('Reason for creating the role'),
    },
    async ({ guildId, name, color, hoist, mentionable, permissions, position, reason }) => {
      const result = await withErrorHandling(async () => {
        const client = await getDiscordClient();
        const guild = await client.guilds.fetch(guildId);
  
        const roleOptions: Record<string, unknown> = { name };
        if (color !== undefined) roleOptions.color = color;
        if (hoist !== undefined) roleOptions.hoist = hoist;
        if (mentionable !== undefined) roleOptions.mentionable = mentionable;
        if (permissions !== undefined) {
          roleOptions.permissions = new PermissionsBitField(permissions as any);
        }
        if (position !== undefined) roleOptions.position = position;
        if (reason !== undefined) roleOptions.reason = reason;
  
        const newRole = await guild.roles.create(roleOptions);
        return {
          id: newRole.id,
          name: newRole.name,
          color: newRole.hexColor,
          position: newRole.position,
          message: 'Role 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:57-57 (registration)

  Invocation of registerRoleTools(server) in the main MCP server setup, which triggers the registration of the 'create_role' tool among others.

  registerRoleTools(server);