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