Microsoft 365 Core MCP Server

Instructions

Implementation Reference

• src/handlers/security-policy-handlers.ts:400-493 (handler)

  The core handler function implementing CRUD (list, get, create, update, delete) and toggle (enable/disable) operations for security alert policies using Microsoft Graph API /security/alerts/policies endpoint. Handles validation, API calls, and response formatting.

  export async function handleSecurityAlertPolicies(
    graphClient: Client,
    args: SecurityAlertPolicyArgs
  ): Promise<{ content: { type: string; text: string }[] }> {
    let apiPath = '';
    let result: any;
  
    switch (args.action) {
      case 'list':
        apiPath = '/security/alerts/policies';
        result = await graphClient.api(apiPath).get();
        break;
  
      case 'get':
        if (!args.policyId) {
          throw new McpError(ErrorCode.InvalidParams, 'policyId is required for get action');
        }
        apiPath = `/security/alerts/policies/${args.policyId}`;
        result = await graphClient.api(apiPath).get();
        break;
  
      case 'create':
        if (!args.displayName) {
          throw new McpError(ErrorCode.InvalidParams, 'displayName is required for create action');
        }
        
        const alertPolicyPayload: any = {
          displayName: args.displayName,
          description: args.description || '',
          category: args.category || 'Others',
          severity: args.severity || 'Medium',
          isEnabled: args.isEnabled !== undefined ? args.isEnabled : true,
          conditions: args.conditions || {},
          actions: args.actions || {}
        };
  
        apiPath = '/security/alerts/policies';
        result = await graphClient.api(apiPath).post(alertPolicyPayload);
        break;
  
      case 'update':
        if (!args.policyId) {
          throw new McpError(ErrorCode.InvalidParams, 'policyId is required for update action');
        }
  
        const updatePayload: any = {};
        if (args.displayName) updatePayload.displayName = args.displayName;
        if (args.description) updatePayload.description = args.description;
        if (args.category) updatePayload.category = args.category;
        if (args.severity) updatePayload.severity = args.severity;
        if (args.isEnabled !== undefined) updatePayload.isEnabled = args.isEnabled;
        if (args.conditions) updatePayload.conditions = args.conditions;
        if (args.actions) updatePayload.actions = args.actions;
  
        apiPath = `/security/alerts/policies/${args.policyId}`;
        result = await graphClient.api(apiPath).patch(updatePayload);
        break;
  
      case 'delete':
        if (!args.policyId) {
          throw new McpError(ErrorCode.InvalidParams, 'policyId is required for delete action');
        }
        apiPath = `/security/alerts/policies/${args.policyId}`;
        await graphClient.api(apiPath).delete();
        result = { message: `Security alert policy ${args.policyId} deleted successfully` };
        break;
  
      case 'enable':
        if (!args.policyId) {
          throw new McpError(ErrorCode.InvalidParams, 'policyId is required for enable action');
        }
        apiPath = `/security/alerts/policies/${args.policyId}`;
        result = await graphClient.api(apiPath).patch({ isEnabled: true });
        break;
  
      case 'disable':
        if (!args.policyId) {
          throw new McpError(ErrorCode.InvalidParams, 'policyId is required for disable action');
        }
        apiPath = `/security/alerts/policies/${args.policyId}`;
        result = await graphClient.api(apiPath).patch({ isEnabled: false });
        break;
  
      default:
        throw new McpError(ErrorCode.InvalidParams, `Unknown action: ${args.action}`);
    }
  
    return {
      content: [{
        type: 'text',
        text: `Security Alert Policy ${args.action} operation completed:\n\n${JSON.stringify(result, null, 2)}`
      }]
    };
  }

• src/schemas/policy-schemas.ts:356-383 (schema)

  Zod schema (securityAlertPolicyArgsSchema) defining input validation and structure for the tool's arguments, including action types, policy details, conditions, and actions.

  export const securityAlertPolicyArgsSchema = z.object({
    action: z.enum(['list', 'get', 'create', 'update', 'delete', 'enable', 'disable']).describe('Action to perform on security alert policy'),
    policyId: z.string().optional().describe('Security alert policy ID for specific operations'),
    displayName: z.string().optional().describe('Display name for the policy'),
    description: z.string().optional().describe('Description of the policy'),
    category: z.enum(['DataLossPrevention', 'ThreatManagement', 'DataGovernance', 'AccessGovernance', 'Others']).optional().describe('Alert category'),
    severity: z.enum(['Low', 'Medium', 'High', 'Informational']).optional().describe('Alert severity'),
    isEnabled: z.boolean().optional().describe('Whether the policy is enabled'),
    conditions: z.object({
      activityType: z.string().optional().describe('Activity type to monitor'),
      objectType: z.string().optional().describe('Object type to monitor'),
      userType: z.enum(['Admin', 'Regular', 'Guest', 'System']).optional().describe('User type to monitor'),
      locationFilter: z.array(z.string()).optional().describe('Location filters'),
      timeRange: z.object({
        startTime: z.string().describe('Start time'),
        endTime: z.string().describe('End time'),
      }).optional().describe('Time range for alerts'),
    }).optional().describe('Alert conditions'),
    actions: z.object({
      notifyUsers: z.array(z.string()).optional().describe('Users to notify'),
      escalateToAdmin: z.boolean().optional().describe('Escalate to admin'),
      suppressRecurringAlerts: z.boolean().optional().describe('Suppress recurring alerts'),
      threshold: z.object({
        value: z.number().describe('Threshold value'),
        timeWindow: z.number().describe('Time window in minutes'),
      }).optional().describe('Alert threshold'),
    }).optional().describe('Alert actions'),
  });

• src/types/policy-types.ts:390-417 (schema)

  TypeScript interface (SecurityAlertPolicyArgs) defining the structure of arguments passed to the handler function.

  export interface SecurityAlertPolicyArgs {
    action: 'list' | 'get' | 'create' | 'update' | 'delete' | 'enable' | 'disable';
    policyId?: string;
    displayName?: string;
    description?: string;
    category?: 'DataLossPrevention' | 'ThreatManagement' | 'DataGovernance' | 'AccessGovernance' | 'Others';
    severity?: 'Low' | 'Medium' | 'High' | 'Informational';
    isEnabled?: boolean;
    conditions?: {
      activityType?: string;
      objectType?: string;
      userType?: 'Admin' | 'Regular' | 'Guest' | 'System';
      locationFilter?: string[];
      timeRange?: {
        startTime: string;
        endTime: string;
      };
    };
    actions?: {
      notifyUsers?: string[];
      escalateToAdmin?: boolean;
      suppressRecurringAlerts?: boolean;
      threshold?: {
        value: number;
        timeWindow: number; // in minutes
      };
    };
  }

• src/tool-metadata.ts:265-268 (registration)

  Tool metadata registration providing description, title, and annotations (readOnlyHint, destructiveHint, etc.) for the MCP tool 'manage_security_alert_policies'.

  manage_security_alert_policies: {
    description: "Manage security alert policies for monitoring threats, suspicious activities, and compliance violations across Microsoft 365.",
    title: "Security Alert Policy Manager",
    annotations: { title: "Security Alert Policy Manager", readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true }