Microsoft 365 Core MCP Server

Instructions

Implementation Reference

• src/handlers.ts:1034-1118 (handler)

  Core handler function implementing manage_distribution_lists tool logic using Microsoft Graph API for CRUD operations on distribution lists (mail-enabled non-security groups) and membership management.

  export async function handleDistributionLists(
    graphClient: Client,
    args: DistributionListArgs
  ): Promise<{ content: { type: string; text: string }[] }> {
    let apiPath = '';
    let result: any;
  
    switch (args.action) {
      case 'get':
        if (!args.listId) {
          throw new McpError(ErrorCode.InvalidParams, 'listId is required for get action');
        }
        apiPath = `/groups/${args.listId}`;
        result = await graphClient.api(apiPath).get();
        break;
  
      case 'create':
        if (!args.displayName || !args.emailAddress) {
          throw new McpError(ErrorCode.InvalidParams, 'displayName and emailAddress are required for create action');
        }
        apiPath = '/groups';
        const createPayload = {
          displayName: args.displayName,
          mailNickname: args.emailAddress.split('@')[0],
          mailEnabled: true,
          securityEnabled: false,
          groupTypes: [], // Empty for distribution lists
          mail: args.emailAddress
        };
        result = await graphClient.api(apiPath).post(createPayload);
        break;
  
      case 'update':
        if (!args.listId) {
          throw new McpError(ErrorCode.InvalidParams, 'listId is required for update action');
        }
        apiPath = `/groups/${args.listId}`;
        const updatePayload: any = {};
        if (args.displayName) updatePayload.displayName = args.displayName;
        result = await graphClient.api(apiPath).patch(updatePayload);
        break;
  
      case 'delete':
        if (!args.listId) {
          throw new McpError(ErrorCode.InvalidParams, 'listId is required for delete action');
        }
        apiPath = `/groups/${args.listId}`;
        await graphClient.api(apiPath).delete();
        result = { message: 'Distribution list deleted successfully' };
        break;
  
      case 'add_members':
        if (!args.listId || !args.members?.length) {
          throw new McpError(ErrorCode.InvalidParams, 'listId and members are required for add_members action');
        }
        
        for (const member of args.members) {
          await graphClient
            .api(`/groups/${args.listId}/members/$ref`)
            .post({
              '@odata.id': `https://graph.microsoft.com/v1.0/users/${member}`
            });
        }
        result = { message: `Added ${args.members.length} members to distribution list` };
        break;
  
      case 'remove_members':
        if (!args.listId || !args.members?.length) {
          throw new McpError(ErrorCode.InvalidParams, 'listId and members are required for remove_members action');
        }
        
        for (const member of args.members) {
          await graphClient
            .api(`/groups/${args.listId}/members/${member}/$ref`)
            .delete();
        }
        result = { message: `Removed ${args.members.length} members from distribution list` };
        break;
  
      default:
        throw new McpError(ErrorCode.InvalidParams, `Invalid action: ${args.action}`);
    }
  
    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
  }

• src/tool-definitions.ts:40-51 (schema)

  Zod schema defining input parameters for the manage_distribution_lists tool, used for validation and MCP tool discovery.

  export const distributionListSchema = z.object({
    action: z.enum(['get', 'create', 'update', 'delete', 'add_members', 'remove_members']).describe('Action to perform on distribution list'),
    listId: z.string().optional().describe('Distribution list ID for existing list operations'),
    displayName: z.string().optional().describe('Display name for the distribution list'),
    emailAddress: z.string().optional().describe('Email address for the distribution list'),
    members: z.array(z.string()).optional().describe('List of member email addresses'),
    settings: z.object({
      hideFromGAL: z.boolean().optional().describe('Hide from Global Address List'),
      requireSenderAuthentication: z.boolean().optional().describe('Require sender authentication'),
      moderatedBy: z.array(z.string()).optional().describe('List of moderator email addresses'),
    }).optional().describe('Distribution list settings'),
  });

• src/server.ts:354-373 (registration)

  MCP server tool registration for manage_distribution_lists, linking schema, metadata, and handler function with error handling and lazy credential validation.

  const distributionListsMeta = getToolMetadata("manage_distribution_lists")!;
  this.server.tool(
    "manage_distribution_lists",
    distributionListsMeta.description,
    distributionListSchema.shape,
    distributionListsMeta.annotations || {},
    wrapToolHandler(async (args: DistributionListArgs) => {
      // Validate credentials only when tool is executed (lazy loading)
      this.validateCredentials();        try {
        return await handleDistributionLists(this.getGraphClient(), args);
      } catch (error) {
        if (error instanceof McpError) {
          throw error;
        }
        throw new McpError(
          ErrorCode.InternalError,
          `Error executing tool: ${error instanceof Error ? error.message : 'Unknown error'}`
        );
      }
    })

• src/types.ts:23-34 (schema)

  TypeScript interface defining the structure of arguments for the distribution lists handler.

  export interface DistributionListArgs {
    action: 'get' | 'create' | 'update' | 'delete' | 'add_members' | 'remove_members';
    listId?: string;
    displayName?: string;
    emailAddress?: string;
    members?: string[];
    settings?: {
      hideFromGAL?: boolean;
      requireSenderAuthentication?: boolean;
      moderatedBy?: string[];
    };
  }

• src/tool-metadata.ts:21-25 (helper)

  Tool metadata providing description, title, and annotations (hints for UI/behavior) for the manage_distribution_lists tool.

  manage_distribution_lists: {
    description: "Manage Exchange distribution lists including creation, updates, member management, and settings configuration.",
    title: "Distribution List Manager",
    annotations: { title: "Distribution List Manager", readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true }
  },