Microsoft 365 Core MCP Server

Instructions

Implementation Reference

• src/handlers/intune-windows-handler.ts:661-767 (handler)

  Main execution logic for the manage_intune_windows_compliance tool. Handles compliance status checks, details retrieval, policy updates, force evaluations, and BitLocker key retrieval using Microsoft Graph API endpoints.

  export async function handleIntuneWindowsCompliance(
    graphClient: Client,
    args: IntuneWindowsComplianceArgs
  ): Promise<{ content: { type: string; text: string }[] }> {
    let apiPath = '';
    let result: any;
  
    switch (args.action) {
      case 'get_status':
        if (args.deviceId) {
          apiPath = `/deviceManagement/managedDevices/${args.deviceId}/deviceCompliancePolicyStates`;
        } else {
          apiPath = '/deviceManagement/deviceCompliancePolicyDeviceStateSummary';
        }
        result = await graphClient.api(apiPath).get();
        break;
  
      case 'get_details':
        if (!args.deviceId) {
          throw new McpError(ErrorCode.InvalidParams, 'deviceId is required for get_details action');
        }
        
        if (args.complianceType === 'bitlocker') {
          apiPath = `/informationProtection/bitlocker/recoveryKeys`;
          const filter = `$filter=deviceId eq '${args.deviceId}'`;
          result = await graphClient.api(`${apiPath}?${filter}`).get();
        } else {
          apiPath = `/deviceManagement/managedDevices/${args.deviceId}/deviceConfigurationStates`;
          if (args.policies && args.policies.length > 0) {
            const policyFilter = args.policies.map(p => `id eq '${p}'`).join(' or ');
            apiPath += `?$filter=${policyFilter}`;
          }
          result = await graphClient.api(apiPath).get();
        }
        break;
  
      case 'update_policy':
        if (!args.policies || args.policies.length === 0) {
          throw new McpError(ErrorCode.InvalidParams, 'policies array is required for update_policy action');
        }
  
        const updateResults = [];
        for (const policyId of args.policies) {
          try {
            apiPath = `/deviceManagement/deviceCompliancePolicies/${policyId}`;
            const policy = await graphClient.api(apiPath).get();
            
            // Force policy refresh
            const refreshPath = `/deviceManagement/deviceCompliancePolicies/${policyId}/scheduleActionsForRules`;
            await graphClient.api(refreshPath).post({
              deviceCompliancePolicyId: policyId
            });
            
            updateResults.push({
              policyId: policyId,
              status: 'updated',
              name: policy.displayName
            });
          } catch (error) {
            updateResults.push({
              policyId: policyId,
              status: 'failed',
              error: error instanceof Error ? error.message : 'Unknown error'
            });
          }
        }
        
        result = { updatedPolicies: updateResults };
        break;
  
      case 'force_evaluation':
        if (!args.deviceId) {
          throw new McpError(ErrorCode.InvalidParams, 'deviceId is required for force_evaluation action');
        }
  
        // Trigger compliance evaluation
        apiPath = `/deviceManagement/managedDevices/${args.deviceId}/syncDevice`;
        await graphClient.api(apiPath).post({});
        
        // Also trigger policy refresh
        const refreshPath = `/deviceManagement/managedDevices/${args.deviceId}/refreshDeviceComplianceReportSummarization`;
        result = await graphClient.api(refreshPath).post({});
        break;
  
      case 'get_bitlocker_keys':
        if (!args.deviceId) {
          throw new McpError(ErrorCode.InvalidParams, 'deviceId is required for get_bitlocker_keys action');
        }
        
        apiPath = `/informationProtection/bitlocker/recoveryKeys`;
        const filter = `$filter=deviceId eq '${args.deviceId}'`;
        result = await graphClient.api(`${apiPath}?${filter}`).get();
        break;
  
      default:
        throw new McpError(ErrorCode.InvalidParams, `Unknown action: ${args.action}`);
    }
  
    return {
      content: [
        {
          type: 'text',
          text: `Windows Compliance Management Result:\n${JSON.stringify(result, null, 2)}`
        }
      ]
    };
  }

• src/types/intune-types.ts:840-854 (schema)

  Input schema (TypeScript interface) defining parameters for the tool handler, including action types and optional fields like deviceId, complianceType, and policies.

  export interface IntuneWindowsComplianceArgs {
    action: 'get_status' | 'get_details' | 'update_policy' | 'force_evaluation' | 'get_bitlocker_keys';
    deviceId?: string;
    complianceType?: 'security' | 'configuration' | 'update' | 'bitlocker';
    policies?: string[];
    complianceData?: {
      passwordCompliant?: boolean;
      encryptionCompliant?: boolean;
      osVersionCompliant?: boolean;
      threatProtectionCompliant?: boolean;
      bitlockerCompliant?: boolean;
      firewallCompliant?: boolean;
      antivirusCompliant?: boolean;
    };
  }

• src/tool-metadata.ts:164-167 (registration)

  Tool metadata registration with description, title, and annotations (read-only, idempotent) for the manage_intune_windows_compliance tool.

  manage_intune_windows_compliance: {
    description: "Assess Windows device compliance status including BitLocker encryption, antivirus status, and security configurations.",
    title: "Intune Windows Compliance Checker",
    annotations: { title: "Intune Windows Compliance Checker", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }

• src/handlers/intune-windows-handler.ts:10-17 (helper)

  Imports policy templates and validation helpers used within the compliance handler for settings catalog and PPC policies.

  import {
    SETTINGS_CATALOG_POLICY_TEMPLATES,
    PPC_POLICY_TEMPLATES,
    validateSettingsCatalogPolicy,
    validatePPCPolicy,
    SettingsCatalogPolicy,
    PPCPolicyConfig
  } from './intune-policy-templates.js';