Microsoft 365 Core MCP Server

Instructions

Implementation Reference

• src/handlers/intune-macos-handler.ts:125-584 (handler)

  The core handler function that implements the logic for the 'manage_intune_macos_policies' tool. It handles various actions including list, get, create, update, delete, assign, and deploy for macOS configuration and compliance policies using Microsoft Graph API.
  export async function handleIntuneMacOSPolicies( graphClient: Client, args: IntuneMacOSPolicyArgs ): Promise<{ content: { type: string; text: string }[] }> { let apiPath = ''; let result: any; switch (args.action) { case 'list': // List policies based on type - using correct endpoints without invalid filters switch (args.policyType) { case 'Configuration': apiPath = '/deviceManagement/deviceConfigurations'; try { // First try with beta endpoint for more comprehensive results try { const allConfigs = await graphClient.api(apiPath).version('beta').get(); // Improved client-side filtering for macOS configuration policies const macOSPolicies = allConfigs.value?.filter((config: any) => { // Check for known macOS odata types if (config['@odata.type'] && ( config['@odata.type'].includes('macOS') || config['@odata.type'] === '#microsoft.graph.macOSCustomConfiguration' || config['@odata.type'] === '#microsoft.graph.macOSGeneralDeviceConfiguration' || config['@odata.type'] === '#microsoft.graph.macOSDeviceFeaturesConfiguration' || config['@odata.type'] === '#microsoft.graph.macOSEndpointProtectionConfiguration' )) { return true; } // Check display name and description for macOS indicators if ((config.displayName && ( config.displayName.toLowerCase().includes('mac') || config.displayName.toLowerCase().includes('macos'))) || (config.description && ( config.description.toLowerCase().includes('mac') || config.description.toLowerCase().includes('macos')))) { return true; } return false; }) || []; result = { ...allConfigs, value: macOSPolicies }; } catch (betaError) { // Fall back to v1.0 endpoint if beta fails console.log(`Beta API failed, falling back to v1.0: ${betaError}`); const allConfigs = await graphClient.api(apiPath).get(); // Same improved filtering logic for v1.0 const macOSPolicies = allConfigs.value?.filter((config: any) => { // Check for known macOS odata types if (config['@odata.type'] && ( config['@odata.type'].includes('macOS') || config['@odata.type'] === '#microsoft.graph.macOSCustomConfiguration' || config['@odata.type'] === '#microsoft.graph.macOSGeneralDeviceConfiguration' || config['@odata.type'] === '#microsoft.graph.macOSDeviceFeaturesConfiguration' )) { return true; } // Check display name and description for macOS indicators if ((config.displayName && ( config.displayName.toLowerCase().includes('mac') || config.displayName.toLowerCase().includes('macos'))) || (config.description && ( config.description.toLowerCase().includes('mac') || config.description.toLowerCase().includes('macos')))) { return true; } return false; }) || []; result = { ...allConfigs, value: macOSPolicies }; } // If no policies found, check configuration profiles endpoint as fallback if (result.value.length === 0) { try { apiPath = '/deviceManagement/configurationPolicies'; const configProfiles = await graphClient.api(apiPath).version('beta').get(); const macOSProfiles = configProfiles.value?.filter((profile: any) => profile.platforms?.includes('macOS') || profile.platforms?.includes('Mac') || (profile.name && ( profile.name.toLowerCase().includes('mac') || profile.name.toLowerCase().includes('macos'))) ) || []; result = { ...configProfiles, value: macOSProfiles }; } catch (profilesError) { console.log(`Configuration profiles endpoint failed: ${profilesError}`); // Keep the empty result from deviceConfigurations } } } catch (error) { throw new McpError(ErrorCode.InternalError, `Failed to fetch device configurations: ${error}`); } break; case 'Compliance': apiPath = '/deviceManagement/deviceCompliancePolicies'; try { // First try with beta endpoint for more comprehensive results try { const allPolicies = await graphClient.api(apiPath).version('beta').get(); // Improved client-side filtering for macOS compliance policies const macOSPolicies = allPolicies.value?.filter((policy: any) => { // Check for known macOS odata types if (policy['@odata.type'] && ( policy['@odata.type'].includes('macOS') || policy['@odata.type'] === '#microsoft.graph.macOSCompliancePolicy' )) { return true; } // Check display name and description for macOS indicators if ((policy.displayName && ( policy.displayName.toLowerCase().includes('mac') || policy.displayName.toLowerCase().includes('macos'))) || (policy.description && ( policy.description.toLowerCase().includes('mac') || policy.description.toLowerCase().includes('macos')))) { return true; } return false; }) || []; result = { ...allPolicies, value: macOSPolicies }; } catch (betaError) { // Fall back to v1.0 endpoint if beta fails console.log(`Beta API failed, falling back to v1.0: ${betaError}`); const allPolicies = await graphClient.api(apiPath).get(); // Same improved filtering logic for v1.0 const macOSPolicies = allPolicies.value?.filter((policy: any) => { // Check for known macOS odata types if (policy['@odata.type'] && ( policy['@odata.type'].includes('macOS') || policy['@odata.type'] === '#microsoft.graph.macOSCompliancePolicy' )) { return true; } // Check display name and description for macOS indicators if ((policy.displayName && ( policy.displayName.toLowerCase().includes('mac') || policy.displayName.toLowerCase().includes('macos'))) || (policy.description && ( policy.description.toLowerCase().includes('mac') || policy.description.toLowerCase().includes('macos')))) { return true; } return false; }) || []; result = { ...allPolicies, value: macOSPolicies }; } } catch (error) { throw new McpError(ErrorCode.InternalError, `Failed to fetch compliance policies: ${error}`); } break; case 'Security': // Use configuration policies for security settings apiPath = '/deviceManagement/configurationPolicies'; try { const allSecurityPolicies = await graphClient.api(apiPath).get(); // Client-side filtering for macOS security policies result = { ...allSecurityPolicies, value: allSecurityPolicies.value?.filter((policy: any) => policy.platforms?.includes('macOS') || policy.platforms?.includes('Mac') || policy.name?.toLowerCase().includes('macos') || policy.name?.toLowerCase().includes('mac') ) || [] }; } catch (error) { // Fallback to device configurations if configurationPolicies doesn't exist try { apiPath = '/deviceManagement/deviceConfigurations'; const allConfigs = await graphClient.api(apiPath).get(); result = { ...allConfigs, value: allConfigs.value?.filter((config: any) => config['@odata.type']?.includes('macOS') && (config.displayName?.toLowerCase().includes('security') || config.description?.toLowerCase().includes('security')) ) || [] }; } catch (fallbackError) { throw new McpError(ErrorCode.InternalError, `Failed to fetch security policies: ${fallbackError}`); } } break; case 'Update': // Try multiple potential endpoints for update policies try { // First try the beta endpoint for software update policies apiPath = '/deviceManagement/deviceConfigurations'; const allConfigs = await graphClient.api(apiPath).version('beta').get(); result = { ...allConfigs, value: allConfigs.value?.filter((config: any) => config['@odata.type'] === 'microsoft.graph.macOSSoftwareUpdateConfiguration' || config['@odata.type']?.includes('SoftwareUpdate') && config['@odata.type']?.includes('macOS') ) || [] }; } catch (error) { // Fallback to regular configurations try { apiPath = '/deviceManagement/deviceConfigurations'; const allConfigs = await graphClient.api(apiPath).get(); result = { ...allConfigs, value: allConfigs.value?.filter((config: any) => config.displayName?.toLowerCase().includes('update') && (config['@odata.type']?.includes('macOS') || config.displayName?.toLowerCase().includes('macos')) ) || [] }; } catch (fallbackError) { throw new McpError(ErrorCode.InternalError, `Failed to fetch update policies: ${fallbackError}`); } } break; case 'AppProtection': // Try app protection policies try { apiPath = '/deviceAppManagement/managedAppPolicies'; const allAppPolicies = await graphClient.api(apiPath).get(); result = { ...allAppPolicies, value: allAppPolicies.value?.filter((policy: any) => policy['@odata.type'] === 'microsoft.graph.macOSManagedAppProtection' || (policy.displayName?.toLowerCase().includes('macos') || policy.displayName?.toLowerCase().includes('mac')) ) || [] }; } catch (error) { throw new McpError(ErrorCode.InternalError, `Failed to fetch app protection policies: ${error}`); } break; default: throw new McpError(ErrorCode.InvalidParams, `Invalid policyType: ${args.policyType}`); } break; case 'get': if (!args.policyId) { throw new McpError(ErrorCode.InvalidParams, 'policyId is required for get action'); } switch (args.policyType) { case 'Configuration': apiPath = `/deviceManagement/deviceConfigurations/${args.policyId}`; break; case 'Compliance': apiPath = `/deviceManagement/deviceCompliancePolicies/${args.policyId}`; break; case 'Security': apiPath = `/deviceManagement/intents/${args.policyId}`; break; case 'Update': apiPath = `/deviceManagement/macOSSoftwareUpdatePolicies/${args.policyId}`; break; case 'AppProtection': apiPath = `/deviceAppManagement/macOSManagedAppProtections/${args.policyId}`; break; default: throw new McpError(ErrorCode.InvalidParams, `Get operation not supported for policyType: ${args.policyType}`); } result = await graphClient.api(apiPath).get(); break; case 'create': if (!args.name) { throw new McpError(ErrorCode.InvalidParams, 'name is required for create action'); } switch (args.policyType) { case 'Configuration': apiPath = '/deviceManagement/deviceConfigurations'; const configPayload = { '@odata.type': '#microsoft.graph.macOSCustomConfiguration', displayName: args.name, description: args.description || '', payloadFileName: args.settings?.customConfiguration?.payloadFileName || 'config.mobileconfig', payload: args.settings?.customConfiguration?.payload || '', platformType: 'macOS', version: 1 }; result = await graphClient.api(apiPath).post(configPayload); break; case 'Compliance': apiPath = '/deviceManagement/deviceCompliancePolicies'; const compliancePayload = { '@odata.type': '#microsoft.graph.macOSCompliancePolicy', displayName: args.name, description: args.description || '', platformType: 'macOS', passwordRequired: args.settings?.compliance?.passwordRequired ?? false, passwordMinimumLength: args.settings?.compliance?.passwordMinimumLength ?? 4, passwordMinutesOfInactivityBeforeLock: args.settings?.compliance?.passwordMinutesOfInactivityBeforeLock ?? 15, storageRequireEncryption: args.settings?.compliance?.storageRequireEncryption ?? true, osMinimumVersion: args.settings?.compliance?.osMinimumVersion, osMaximumVersion: args.settings?.compliance?.osMaximumVersion, systemIntegrityProtectionEnabled: args.settings?.compliance?.systemIntegrityProtectionEnabled ?? true, firewallEnabled: args.settings?.compliance?.firewallEnabled ?? true, gatekeeperAllowedAppSource: args.settings?.compliance?.gatekeeperAllowedAppSource ?? 'macAppStoreAndIdentifiedDevelopers' }; result = await graphClient.api(apiPath).post(compliancePayload); break; default: throw new McpError(ErrorCode.InvalidParams, `Create operation not supported for policyType: ${args.policyType}`); } break; case 'update': if (!args.policyId) { throw new McpError(ErrorCode.InvalidParams, 'policyId is required for update action'); } switch (args.policyType) { case 'Configuration': apiPath = `/deviceManagement/deviceConfigurations/${args.policyId}`; const updateConfigPayload = { displayName: args.name, description: args.description, payloadFileName: args.settings?.customConfiguration?.payloadFileName, payload: args.settings?.customConfiguration?.payload }; result = await graphClient.api(apiPath).patch(updateConfigPayload); break; case 'Compliance': apiPath = `/deviceManagement/deviceCompliancePolicies/${args.policyId}`; const updateCompliancePayload = { displayName: args.name, description: args.description, passwordRequired: args.settings?.compliance?.passwordRequired, passwordMinimumLength: args.settings?.compliance?.passwordMinimumLength, storageRequireEncryption: args.settings?.compliance?.storageRequireEncryption, osMinimumVersion: args.settings?.compliance?.osMinimumVersion, osMaximumVersion: args.settings?.compliance?.osMaximumVersion }; result = await graphClient.api(apiPath).patch(updateCompliancePayload); break; default: throw new McpError(ErrorCode.InvalidParams, `Update operation not supported for policyType: ${args.policyType}`); } break; case 'delete': if (!args.policyId) { throw new McpError(ErrorCode.InvalidParams, 'policyId is required for delete action'); } switch (args.policyType) { case 'Configuration': apiPath = `/deviceManagement/deviceConfigurations/${args.policyId}`; break; case 'Compliance': apiPath = `/deviceManagement/deviceCompliancePolicies/${args.policyId}`; break; default: throw new McpError(ErrorCode.InvalidParams, `Delete operation not supported for policyType: ${args.policyType}`); } await graphClient.api(apiPath).delete(); result = { message: `${args.policyType} policy deleted successfully` }; break; case 'assign': if (!args.policyId || !args.assignments) { throw new McpError(ErrorCode.InvalidParams, 'policyId and assignments are required for assign action'); } switch (args.policyType) { case 'Configuration': apiPath = `/deviceManagement/deviceConfigurations/${args.policyId}/assignments`; break; case 'Compliance': apiPath = `/deviceManagement/deviceCompliancePolicies/${args.policyId}/assignments`; break; default: throw new McpError(ErrorCode.InvalidParams, `Assign operation not supported for policyType: ${args.policyType}`); } const assignmentPayload = { assignments: args.assignments.map(assignment => ({ target: { '@odata.type': assignment.target.groupId ? '#microsoft.graph.groupAssignmentTarget' : '#microsoft.graph.allDevicesAssignmentTarget', groupId: assignment.target.groupId }, intent: assignment.intent || 'apply' })) }; result = await graphClient.api(apiPath).post(assignmentPayload); break; case 'deploy': if (!args.policyId) { throw new McpError(ErrorCode.InvalidParams, 'policyId is required for deploy action'); } // For deploy action, we'll assign to all devices or specified groups const deployApiPath = args.policyType === 'Configuration' ? `/deviceManagement/deviceConfigurations/${args.policyId}/assignments` : `/deviceManagement/deviceCompliancePolicies/${args.policyId}/assignments`; const deployPayload = { assignments: [{ target: { '@odata.type': '#microsoft.graph.allDevicesAssignmentTarget' }, intent: 'apply' }] }; result = await graphClient.api(deployApiPath).post(deployPayload); break; default: throw new McpError(ErrorCode.InvalidParams, `Invalid action: ${args.action}`); } return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] }; }
• src/server.ts:743-762 (registration)

  The MCP tool registration in the server setup, associating the tool name 'manage_intune_macos_policies' with the handleIntuneMacOSPolicies handler function, input schema, and metadata annotations.
  // Intune macOS Policy Management - Lazy loading enabled for tool discovery this.server.tool( "manage_intune_macos_policies", "Manage macOS configuration profiles and compliance policies for device security and management settings.", intuneMacOSPolicySchema.shape, {"readOnlyHint":false,"destructiveHint":true,"idempotentHint":false}, wrapToolHandler(async (args: IntuneMacOSPolicyArgs) => { this.validateCredentials(); try { return await handleIntuneMacOSPolicies(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/tool-definitions.ts:277-299 (schema)

  Zod schema defining the input parameters and validation for the 'manage_intune_macos_policies' tool, including actions, policy types, settings, and assignments.
  export const intuneMacOSPolicySchema = z.object({ action: z.enum(['list', 'get', 'create', 'update', 'delete', 'assign', 'deploy']).describe('Intune macOS policy management action'), policyId: z.string().optional().describe('Policy ID for policy-specific operations'), policyType: z.enum(['Configuration', 'Compliance', 'Security', 'Update', 'AppProtection']).describe('Type of macOS policy'), name: z.string().optional().describe('Policy name'), description: z.string().optional().describe('Policy description'), settings: z.record(z.string(), z.any()).optional().describe('Policy configuration settings'), assignments: z.array(z.object({ target: z.object({ deviceAndAppManagementAssignmentFilterId: z.string().optional().describe('Filter ID'), deviceAndAppManagementAssignmentFilterType: z.enum(['none', 'include', 'exclude']).optional().describe('Filter type'), groupId: z.string().optional().describe('Group ID'), collectionId: z.string().optional().describe('Collection ID'), }).describe('Assignment target'), intent: z.enum(['apply', 'remove']).optional().describe('Assignment intent'), settings: z.record(z.string(), z.any()).optional().describe('Assignment settings'), })).optional().describe('Policy assignments'), deploymentSettings: z.object({ installBehavior: z.enum(['doNotInstall', 'installAsManaged', 'installAsUnmanaged']).optional().describe('Install behavior'), uninstallOnDeviceRemoval: z.boolean().optional().describe('Uninstall on device removal'), installAsManaged: z.boolean().optional().describe('Install as managed'), }).optional().describe('Deployment settings'), });
• src/tool-metadata.ts:132-136 (schema)

  Tool metadata providing description, title, and behavioral annotations (readOnlyHint, destructiveHint, etc.) for the 'manage_intune_macos_policies' tool.
  manage_intune_macos_policies: { description: "Manage macOS configuration profiles and compliance policies for device security and management settings.", title: "Intune macOS Policy Manager", annotations: { title: "Intune macOS Policy Manager", readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true } },