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;