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 } },