Microsoft 365 Core MCP Server

Instructions

Implementation Reference

• src/exchange-handler.ts:5-70 (handler)

  The core handler function 'handleExchangeSettings' that implements the tool logic for managing Exchange Online settings (mailbox, transport rules, organization, retention) using Microsoft Graph API endpoints.
  export async function handleExchangeSettings( graphClient: Client, args: ExchangeSettingsArgs ): Promise<{ content: { type: string; text: string; }[]; }> { switch (args.settingType) { case 'mailbox': { if (args.action === 'get') { const settings = await graphClient .api(`/users/${args.target}/mailboxSettings`) .get(); return { content: [{ type: 'text', text: JSON.stringify(settings, null, 2) }] }; } else { await graphClient .api(`/users/${args.target}/mailboxSettings`) .patch(args.settings); return { content: [{ type: 'text', text: 'Mailbox settings updated successfully' }] }; } } case 'transport': { if (args.action === 'get') { const rules = await graphClient .api('/admin/transportRules') .get(); return { content: [{ type: 'text', text: JSON.stringify(rules, null, 2) }] }; } else { await graphClient .api('/admin/transportRules') .post(args.settings?.rules); return { content: [{ type: 'text', text: 'Transport rules updated successfully' }] }; } } case 'organization': { if (args.action === 'get') { const settings = await graphClient .api('/admin/organization/settings') .get(); return { content: [{ type: 'text', text: JSON.stringify(settings, null, 2) }] }; } else { await graphClient .api('/admin/organization/settings') .patch(args.settings?.sharingPolicy); return { content: [{ type: 'text', text: 'Organization settings updated successfully' }] }; } } case 'retention': { if (args.action === 'get') { const tags = await graphClient .api('/admin/retentionTags') .get(); return { content: [{ type: 'text', text: JSON.stringify(tags, null, 2) }] }; } else { if (!args.settings?.retentionTags?.length) { throw new McpError(ErrorCode.InvalidParams, 'No retention tags specified'); } for (const tag of args.settings.retentionTags) { await graphClient .api('/admin/retentionTags') .post(tag); } return { content: [{ type: 'text', text: 'Retention tags updated successfully' }] }; } } default: throw new McpError(ErrorCode.InvalidParams, `Invalid setting type: ${args.settingType}`); } }
• src/server.ts:415-435 (registration)

  MCP server registration of the 'manage_exchange_settings' tool, including name, description, input schema from exchangeSettingsSchema, annotations, and wrapped handler that calls handleExchangeSettings.
  this.server.tool( "manage_exchange_settings", "Manage Exchange Online settings including mailbox configuration, transport rules, and organization policies.", exchangeSettingsSchema.shape, {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true}, wrapToolHandler(async (args: ExchangeSettingsArgs) => { // Validate credentials only when tool is executed (lazy loading) this.validateCredentials(); try { return await handleExchangeSettings(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'}` ); } }) ); // User Management - Lazy loading enabled for tool discovery
• src/tool-definitions.ts:82-106 (schema)

  Zod schema 'exchangeSettingsSchema' defining the input validation structure for the tool, including actions, setting types, and detailed settings objects.
  export const exchangeSettingsSchema = z.object({ action: z.enum(['get', 'update']).describe('Action to perform on Exchange settings'), settingType: z.enum(['mailbox', 'transport', 'organization', 'retention']).describe('Type of Exchange settings to manage'), target: z.string().optional().describe('User/Group ID for mailbox settings'), settings: z.object({ automateProcessing: z.object({ autoForwardEnabled: z.boolean().optional().describe('Enable auto-forwarding'), autoReplyEnabled: z.boolean().optional().describe('Enable auto-reply'), }).optional().describe('Automated processing settings'), rules: z.array(z.object({ name: z.string().describe('Rule name'), conditions: z.record(z.string(), z.any()).describe('Rule conditions'), actions: z.record(z.string(), z.any()).describe('Rule actions'), })).optional().describe('Transport rules'), sharingPolicy: z.object({ enabled: z.boolean().optional().describe('Enable sharing policy'), domains: z.array(z.string()).optional().describe('Allowed domains'), }).optional().describe('Sharing policy settings'), retentionTags: z.array(z.object({ name: z.string().describe('Retention tag name'), type: z.string().describe('Retention tag type'), retentionDays: z.number().describe('Retention period in days'), })).optional().describe('Retention tag definitions'), }).optional().describe('Exchange configuration settings'), });
• src/types.ts:65-89 (helper)

  TypeScript interface 'ExchangeSettingsArgs' providing type safety for the tool arguments, matching the Zod schema used in registration and handler.
  export interface ExchangeSettingsArgs { action: 'get' | 'update'; settingType: 'mailbox' | 'transport' | 'organization' | 'retention'; target?: string; settings?: { automateProcessing?: { autoForwardEnabled?: boolean; autoReplyEnabled?: boolean; }; rules?: { name: string; conditions: Record<string, any>; actions: Record<string, any>; }[]; sharingPolicy?: { enabled?: boolean; domains?: string[]; }; retentionTags?: { name: string; type: string; retentionDays: number; }[]; }; }
• src/tool-metadata.ts:62-66 (schema)

  Tool metadata entry providing enhanced description, title, and MCP annotations for the 'manage_exchange_settings' tool.
  manage_exchange_settings: { description: "Manage Exchange Online settings including mailbox configuration, transport rules, and organization policies.", title: "Exchange Settings Manager", annotations: { title: "Exchange Settings Manager", readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true } },