Microsoft 365 Core MCP Server

Instructions

Implementation Reference

• src/handlers/compliance-handler.ts:248-282 (handler)

  Main handler function for manage_gap_analysis tool. Dispatches to generate, get_results, or export actions, calling helper functions for gap analysis logic.

  export async function handleGapAnalysis(
    graphClient: Client,
    args: GapAnalysisArgs
  ): Promise<{ content: { type: string; text: string }[] }> {
    let result: any;
  
    switch (args.action) {
      case 'generate':
        // Generate gap analysis
        const analysisId = `gap-analysis-${Date.now()}`;
        result = await generateGapAnalysis(graphClient, analysisId, args);
        break;
  
      case 'get_results':
        if (!args.analysisId) {
          throw new McpError(ErrorCode.InvalidParams, 'analysisId is required for get_results action');
        }
        
        result = await getGapAnalysisResults(args.analysisId);
        break;
  
      case 'export':
        if (!args.analysisId) {
          throw new McpError(ErrorCode.InvalidParams, 'analysisId is required for export action');
        }
        
        result = await exportGapAnalysis(args.analysisId);
        break;
  
      default:
        throw new McpError(ErrorCode.InvalidParams, `Invalid action: ${args.action}`);
    }
  
    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
  }

• src/server.ts:985-1005 (registration)

  MCP server tool registration for 'manage_gap_analysis'. Links the schema, metadata annotations, and handler function.

  // Gap Analysis - Lazy loading enabled for tool discovery
  this.server.tool(
    "manage_gap_analysis",
    "Perform gap analysis to identify compliance deficiencies and generate remediation recommendations.",
    gapAnalysisSchema.shape,
    {"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true},
    wrapToolHandler(async (args: GapAnalysisArgs) => {
      this.validateCredentials();
      try {
        return await handleGapAnalysis(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/tool-definitions.ts:432-447 (schema)

  Zod input schema definition for the manage_gap_analysis tool, defining parameters like action, framework, scope, and settings.

  export const gapAnalysisSchema = z.object({
    action: z.enum(['generate', 'get_results', 'export']).describe('Gap analysis action'),
    analysisId: z.string().optional().describe('Analysis ID'),
    framework: z.enum(['hitrust', 'iso27001', 'soc2']).describe('Framework for gap analysis'),
    targetFramework: z.enum(['hitrust', 'iso27001', 'soc2']).optional().describe('Target framework for cross-framework mapping'),
    scope: z.object({
      controlIds: z.array(z.string()).optional().describe('Control IDs'),
      categories: z.array(z.string()).optional().describe('Categories'),
    }).optional().describe('Analysis scope'),
    settings: z.object({
      includeRecommendations: z.boolean().describe('Include recommendations'),
      prioritizeByRisk: z.boolean().describe('Prioritize by risk'),
      includeTimeline: z.boolean().describe('Include timeline'),
      includeCostEstimate: z.boolean().describe('Include cost estimate'),
    }).optional().describe('Analysis settings'),
  });

• src/types/compliance-types.ts:601-616 (schema)

  TypeScript interface defining the input arguments structure (GapAnalysisArgs) used by the handler and schema.

  export interface GapAnalysisArgs {
    action: 'generate' | 'get_results' | 'export';
    analysisId?: string;
    framework: 'hitrust' | 'iso27001' | 'soc2';
    targetFramework?: 'hitrust' | 'iso27001' | 'soc2'; // For cross-framework mapping
    scope?: {
      controlIds?: string[];
      categories?: string[];
    };
    settings?: {
      includeRecommendations: boolean;
      prioritizeByRisk: boolean;
      includeTimeline: boolean;
      includeCostEstimate: boolean;
    };
  }

• src/handlers.ts:47-60 (registration)

  Import statement bringing the handleGapAnalysis handler into the main handlers file, making it available for server registration.

  import {
    handleComplianceFrameworks,
    handleComplianceAssessments,
    handleComplianceMonitoring,
    handleEvidenceCollection,
    handleGapAnalysis
  } from './handlers/compliance-handler.js';
  import {
    ComplianceFrameworkArgs,
    ComplianceAssessmentArgs,
    ComplianceMonitoringArgs,
    EvidenceCollectionArgs,
    GapAnalysisArgs
  } from './types/compliance-types.js';

• src/tool-metadata.ts:191-194 (schema)

  Tool metadata including description, title, and annotations (readOnlyHint, destructiveHint, etc.) used in registration.

  manage_gap_analysis: {
    description: "Perform gap analysis to identify compliance deficiencies and generate remediation recommendations.",
    title: "Compliance Gap Analyzer",
    annotations: { title: "Compliance Gap Analyzer", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }