Microsoft 365 Core MCP Server

Instructions

Implementation Reference

• src/handlers/intune-macos-handler.ts:587-682 (handler)

  The core handler function that implements all logic for the manage_intune_macos_apps tool, handling actions like list, get, deploy, update, remove, and sync_status using Microsoft Graph API endpoints for Intune macOS app management.

  export async function handleIntuneMacOSApps(
    graphClient: Client,
    args: IntuneMacOSAppArgs
  ): Promise<{ content: { type: string; text: string }[] }> {
    let apiPath = '';
    let result: any;
  
    switch (args.action) {
      case 'list':
        // List macOS applications
        apiPath = '/deviceAppManagement/mobileApps';
        apiPath += `?$filter=deviceType eq 'macOS'`;
        
        if (args.appType) {
          apiPath += ` and microsoft.graph.${args.appType}`;
        }
  
        result = await graphClient.api(apiPath).get();
        break;
  
      case 'get':
        if (!args.appId) {
          throw new McpError(ErrorCode.InvalidParams, 'appId is required for get action');
        }
        apiPath = `/deviceAppManagement/mobileApps/${args.appId}`;
        result = await graphClient.api(apiPath).get();
        break;
  
      case 'deploy':
        if (!args.appId || !args.assignment) {
          throw new McpError(ErrorCode.InvalidParams, 'appId and assignment are required for deploy action');
        }
  
        apiPath = `/deviceAppManagement/mobileApps/${args.appId}/assignments`;
        const deploymentPayload = {
          mobileAppAssignments: args.assignment.groupIds.map(groupId => ({
            target: {
              '@odata.type': '#microsoft.graph.groupAssignmentTarget',
              groupId: groupId
            },
            intent: args.assignment?.installIntent || 'available',
            settings: {
              '@odata.type': '#microsoft.graph.macOSLobAppAssignmentSettings',
              uninstallOnDeviceRemoval: true
            }
          }))
        };
  
        result = await graphClient.api(apiPath).post(deploymentPayload);
        break;
  
      case 'update':
        if (!args.appId) {
          throw new McpError(ErrorCode.InvalidParams, 'appId is required for update action');
        }
  
        apiPath = `/deviceAppManagement/mobileApps/${args.appId}`;
        const updatePayload = {
          displayName: args.appInfo?.displayName,
          description: args.appInfo?.description,
          publisher: args.appInfo?.publisher,
          bundleId: args.appInfo?.bundleId,
          buildNumber: args.appInfo?.buildNumber,
          versionNumber: args.appInfo?.versionNumber,
          minimumSupportedOperatingSystem: args.appInfo?.minimumSupportedOperatingSystem
        };
  
        result = await graphClient.api(apiPath).patch(updatePayload);
        break;
  
      case 'remove':
        if (!args.appId) {
          throw new McpError(ErrorCode.InvalidParams, 'appId is required for remove action');
        }
  
        apiPath = `/deviceAppManagement/mobileApps/${args.appId}`;
        await graphClient.api(apiPath).delete();
        result = { message: 'App removed successfully' };
        break;
  
      case 'sync_status':
        if (!args.appId) {
          throw new McpError(ErrorCode.InvalidParams, 'appId is required for sync_status action');
        }
  
        // Get app installation status across devices
        apiPath = `/deviceAppManagement/mobileApps/${args.appId}/deviceStatuses`;
        result = await graphClient.api(apiPath).get();
        break;
  
      default:
        throw new McpError(ErrorCode.InvalidParams, `Invalid action: ${args.action}`);
    }
  
    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
  }

• src/server.ts:767-785 (registration)

  MCP server registration of the manage_intune_macos_apps tool, specifying description, input schema, annotations, and the wrapped handler function.

    "manage_intune_macos_apps",
    "Manage macOS application deployment including app assignments, updates, and installation requirements.",
    intuneMacOSAppSchema.shape,
    {"readOnlyHint":false,"destructiveHint":true,"idempotentHint":false},
    wrapToolHandler(async (args: IntuneMacOSAppArgs) => {
      this.validateCredentials();
      try {
        return await handleIntuneMacOSApps(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/types/intune-types.ts:339-360 (schema)

  TypeScript interface defining the input parameters (IntuneMacOSAppArgs) for the tool handler, including actions and app deployment configurations.

  export interface IntuneMacOSAppArgs {
    action: 'list' | 'get' | 'deploy' | 'update' | 'remove' | 'sync_status';
    appId?: string;
    appType?: 'webApp' | 'officeSuiteApp' | 'microsoftEdgeApp' | 'microsoftDefenderApp' | 'managedIOSApp' | 'managedAndroidApp' | 'managedMobileLobApp' | 'macOSLobApp' | 'macOSMicrosoftEdgeApp' | 'macOSMicrosoftDefenderApp' | 'macOSOfficeSuiteApp' | 'macOSWebClip' | 'managedApp';
    assignment?: {
      groupIds: string[];
      installIntent: 'available' | 'required' | 'uninstall' | 'availableWithoutEnrollment';
      deliveryOptimizationPriority?: 'notConfigured' | 'foreground';
    };
    appInfo?: {
      displayName: string;
      description?: string;
      publisher: string;
      bundleId?: string;
      buildNumber?: string;
      versionNumber?: string;
      packageFilePath?: string;
      minimumSupportedOperatingSystem?: string;
      ignoreVersionDetection?: boolean;
      installAsManaged?: boolean;
    };
  }

• src/tool-definitions.ts:301-308 (schema)

  Zod schema (intuneMacOSAppSchema) used for input validation and MCP tool discovery, defining parameters for macOS app management actions.

  export const intuneMacOSAppSchema = z.object({
    action: z.enum(['list', 'get', 'deploy', 'update', 'remove']).describe('Intune macOS app management action'),
    appId: z.string().optional().describe('App ID for app-specific operations'),
    bundleId: z.string().optional().describe('macOS app bundle identifier'),
    name: z.string().optional().describe('Application name'),
    version: z.string().optional().describe('Application version'),
    assignmentGroups: z.array(z.string()).optional().describe('Target groups for app deployment'),
  });

• src/tool-metadata.ts:137-140 (schema)

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

  manage_intune_macos_apps: {
    description: "Manage macOS application deployment including app assignments, updates, and installation requirements.",
    title: "Intune macOS App Manager",
    annotations: { title: "Intune macOS App Manager", readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true }