Microsoft 365 Core MCP Server

Instructions

Implementation Reference

• src/handlers/intune-windows-handler.ts:20-173 (handler)

  Core handler function implementing the manage_intune_windows_devices tool. Handles device actions like listing, getting details, enrollment, retirement, wiping, restarting, syncing, locking, log collection, BitLocker recovery, and Autopilot reset using Microsoft Graph API endpoints under /deviceManagement/managedDevices.

  export async function handleIntuneWindowsDevices(
    graphClient: Client,
    args: IntuneWindowsDeviceArgs
  ): Promise<{ content: { type: string; text: string }[] }> {
    // Create Intune-specific client for proper authentication
    const intuneClient = createIntuneGraphClient(graphClient);
    let apiPath = '';
    let result: any;
  
    switch (args.action) {
      case 'list':
        // List all Windows devices managed by Intune
        apiPath = '/deviceManagement/managedDevices';
        const queryOptions: string[] = [];
        
        // Filter for Windows devices
        queryOptions.push(`$filter=operatingSystem eq 'Windows'`);
        
        if (args.filter) {
          queryOptions.push(`and ${args.filter}`);
        }
  
        if (queryOptions.length > 0) {
          apiPath += `?${queryOptions.join('')}`;
        }
  
        result = (await intuneClient.makeApiCall(apiPath)).data;
        break;
  
      case 'get':
        if (!args.deviceId) {
          throw new McpError(ErrorCode.InvalidParams, 'deviceId is required for get action');
        }
        apiPath = `/deviceManagement/managedDevices/${args.deviceId}`;
        result = await graphClient.api(apiPath).get();
        break;
  
      case 'enroll':
        // Create enrollment invitation for Windows devices
        apiPath = '/deviceManagement/deviceEnrollmentConfigurations';
        const enrollmentPayload = {
          displayName: 'Windows Device Enrollment',
          description: 'Automated Windows device enrollment',
          deviceEnrollmentConfigurationType: 'windows10EnrollmentCompletionPageConfiguration',
          priority: 0,
          showInstallationProgress: true,
          blockDeviceSetupRetryByUser: false,
          allowDeviceResetOnInstallFailure: true,
          allowLogCollectionOnInstallFailure: true,
          customErrorMessage: 'Setup could not be completed. Please try again or contact your support person for help.',
          installProgressTimeoutInMinutes: 60,
          allowDeviceUseOnInstallFailure: true,
          selectedMobileAppIds: [],
          trackInstallProgressForAutopilotOnly: false,
          disableUserStatusTrackingAfterFirstUser: true
        };
  
        if (args.enrollmentType) {
          enrollmentPayload.deviceEnrollmentConfigurationType = 
            args.enrollmentType === 'AzureADJoin' ? 'azureADJoinUsingBulkEnrollment' :
            args.enrollmentType === 'HybridAzureADJoin' ? 'hybridAzureADJoin' :
            'windows10EnrollmentCompletionPageConfiguration';
        }
  
        result = await graphClient.api(apiPath).post(enrollmentPayload);
        break;
  
      case 'retire':
        if (!args.deviceId) {
          throw new McpError(ErrorCode.InvalidParams, 'deviceId is required for retire action');
        }
        apiPath = `/deviceManagement/managedDevices/${args.deviceId}/retire`;
        result = await graphClient.api(apiPath).post({
          keepEnrollmentData: false,
          keepUserData: true
        });
        break;
  
      case 'wipe':
        if (!args.deviceId) {
          throw new McpError(ErrorCode.InvalidParams, 'deviceId is required for wipe action');
        }
        apiPath = `/deviceManagement/managedDevices/${args.deviceId}/wipe`;
        result = await graphClient.api(apiPath).post({
          keepEnrollmentData: false,
          keepUserData: false,
          useProtectedWipe: true
        });
        break;
  
      case 'restart':
        if (!args.deviceId) {
          throw new McpError(ErrorCode.InvalidParams, 'deviceId is required for restart action');
        }
        apiPath = `/deviceManagement/managedDevices/${args.deviceId}/rebootNow`;
        result = await graphClient.api(apiPath).post({});
        break;
  
      case 'sync':
        if (!args.deviceId) {
          throw new McpError(ErrorCode.InvalidParams, 'deviceId is required for sync action');
        }
        apiPath = `/deviceManagement/managedDevices/${args.deviceId}/syncDevice`;
        result = await graphClient.api(apiPath).post({});
        break;
  
      case 'remote_lock':
        if (!args.deviceId) {
          throw new McpError(ErrorCode.InvalidParams, 'deviceId is required for remote_lock action');
        }
        apiPath = `/deviceManagement/managedDevices/${args.deviceId}/remoteLock`;
        result = await graphClient.api(apiPath).post({});
        break;
  
      case 'collect_logs':
        if (!args.deviceId) {
          throw new McpError(ErrorCode.InvalidParams, 'deviceId is required for collect_logs action');
        }
        apiPath = `/deviceManagement/managedDevices/${args.deviceId}/createDeviceLogCollectionRequest`;
        result = await graphClient.api(apiPath).post({
          templateType: 'predefined'
        });
        break;    case 'bitlocker_recovery':
        if (!args.deviceId) {
          throw new McpError(ErrorCode.InvalidParams, 'deviceId is required for bitlocker_recovery action');
        }
        apiPath = `/informationProtection/bitlocker/recoveryKeys`;
        const filter = `$filter=deviceId eq '${args.deviceId}'`;
        result = await graphClient.api(`${apiPath}?${filter}`).get();
        break;
  
      case 'autopilot_reset':
        if (!args.deviceId) {
          throw new McpError(ErrorCode.InvalidParams, 'deviceId is required for autopilot_reset action');
        }
        apiPath = `/deviceManagement/managedDevices/${args.deviceId}/autopilotReset`;
        result = await graphClient.api(apiPath).post({
          keepUserData: false
        });
        break;
  
      default:
        throw new McpError(ErrorCode.InvalidParams, `Unknown action: ${args.action}`);
    }
  
    return {
      content: [
        {
          type: 'text',
          text: `Windows Device Management Result:\n${JSON.stringify(result, null, 2)}`
        }
      ]
    };
  }

• src/types/intune-types.ts:419-433 (schema)

  TypeScript interface defining input arguments for the Intune Windows device management handler, including action type and parameters for specific operations.

  export interface IntuneWindowsDeviceArgs {
    action: 'list' | 'get' | 'enroll' | 'retire' | 'wipe' | 'restart' | 'sync' | 'remote_lock' | 'collect_logs' | 'bitlocker_recovery' | 'autopilot_reset';
    deviceId?: string;
    filter?: string;
    enrollmentType?: 'AzureADJoin' | 'HybridAzureADJoin' | 'AutoPilot' | 'BulkEnrollment';
    assignmentTarget?: {
      groupIds?: string[];
      userIds?: string[];
      deviceIds?: string[];
    };
    bitlockerSettings?: {
      requireBitlockerEncryption?: boolean;
      allowBitlockerRecoveryKeyBackup?: boolean;
    };
  }

• src/tool-definitions.ts:318-332 (schema)

  Zod schema used for input validation and MCP tool schema definition for the manage_intune_windows_devices tool.

  export const intuneWindowsDeviceSchema = z.object({
    action: z.enum(['list', 'get', 'enroll', 'retire', 'wipe', 'restart', 'sync', 'remote_lock', 'collect_logs', 'bitlocker_recovery', 'autopilot_reset']).describe('Intune Windows device management action'),
    deviceId: z.string().optional().describe('Device ID for device-specific operations'),
    filter: z.string().optional().describe('OData filter for device listing'),
    enrollmentType: z.enum(['AzureADJoin', 'HybridAzureADJoin', 'AutoPilot', 'BulkEnrollment']).optional().describe('Windows enrollment type'),
    assignmentTarget: z.object({
      groupIds: z.array(z.string()).optional().describe('Target group IDs'),
      userIds: z.array(z.string()).optional().describe('Target user IDs'),
      deviceIds: z.array(z.string()).optional().describe('Target device IDs'),
    }).optional().describe('Assignment target'),
    bitlockerSettings: z.object({
      requireBitlockerEncryption: z.boolean().optional().describe('Require BitLocker encryption'),
      allowBitlockerRecoveryKeyBackup: z.boolean().optional().describe('Allow recovery key backup'),
    }).optional().describe('BitLocker configuration'),
  });

• src/tool-metadata.ts:149-152 (registration)

  Tool metadata registration providing description, title, and behavioral annotations (readOnlyHint, destructiveHint, etc.) for the manage_intune_windows_devices tool.

  manage_intune_windows_devices: {
    description: "Manage Windows devices in Intune including enrollment, autopilot deployment, device actions, and health monitoring.",
    title: "Intune Windows Device Manager",
    annotations: { title: "Intune Windows Device Manager", readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true }

• src/tool-definitions.ts:510-522 (registration)

  Tool schema registration in the central m365CoreTools object, mapping 'intuneWindowsDevices' schema to the tool registry.

    intuneMacOSCompliance: intuneMacOSComplianceSchema,
    intuneWindowsDevices: intuneWindowsDeviceSchema,
    intuneWindowsPolicies: intuneWindowsPolicySchema,
    intuneWindowsApps: intuneWindowsAppSchema,
    intuneWindowsCompliance: intuneWindowsComplianceSchema,
    complianceFrameworks: complianceFrameworkSchema,
    complianceAssessments: complianceAssessmentSchema,
    complianceMonitoring: complianceMonitoringSchema,
    evidenceCollection: evidenceCollectionSchema,
    gapAnalysis: gapAnalysisSchema,
    auditReports: auditReportSchema,
    cisCompliance: cisComplianceSchema,
  } as const;