Microsoft 365 Core MCP Server

Instructions

Implementation Reference

• src/handlers/compliance-handler.ts:202-245 (handler)

  Main handler function that executes the manage_evidence_collection tool logic. Handles actions like collect, schedule, get_status, and download evidence using a switch statement on args.action.

  export async function handleEvidenceCollection(
    graphClient: Client,
    args: EvidenceCollectionArgs
  ): Promise<{ content: { type: string; text: string }[] }> {
    let result: any;
  
    switch (args.action) {
      case 'collect':
        // Start evidence collection
        const collectionId = `collection-${Date.now()}`;
        result = await startEvidenceCollection(graphClient, collectionId, args);
        break;
  
      case 'schedule':
        result = {
          collectionId: args.collectionId,
          scheduledTime: args.settings?.scheduledTime,
          status: 'scheduled',
          message: 'Evidence collection scheduled successfully'
        };
        break;
  
      case 'get_status':
        if (!args.collectionId) {
          throw new McpError(ErrorCode.InvalidParams, 'collectionId is required for get_status action');
        }
        
        result = await getCollectionStatus(args.collectionId);
        break;
  
      case 'download':
        if (!args.collectionId) {
          throw new McpError(ErrorCode.InvalidParams, 'collectionId is required for download action');
        }
        
        result = await downloadEvidence(args.collectionId);
        break;
  
      default:
        throw new McpError(ErrorCode.InvalidParams, `Invalid action: ${args.action}`);
    }
  
    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
  }

• src/server.ts:964-983 (registration)

  MCP server tool registration for 'manage_evidence_collection'. Registers the handler with schema, metadata annotations, and error handling wrapper.

  this.server.tool(
    "manage_evidence_collection",
    "Collect and preserve compliance evidence including audit logs, configuration snapshots, and attestation records.",
    evidenceCollectionSchema.shape,
    {"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true},
    wrapToolHandler(async (args: EvidenceCollectionArgs) => {
      this.validateCredentials();
      try {
        return await handleEvidenceCollection(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:422-430 (schema)

  Zod schema definition for the tool input parameters (EvidenceCollectionArgs), used in MCP registration for validation.

  export const evidenceCollectionSchema = z.object({
    action: z.enum(['get_status', 'schedule', 'collect', 'download']).describe('Evidence collection action'),
    evidenceType: z.enum(['configuration', 'logs', 'policies', 'certificates', 'reports']).optional().describe('Type of evidence to collect'),
    timeRange: z.object({
      start: z.string().describe('Start date (ISO format)'),
      end: z.string().describe('End date (ISO format)'),
    }).optional().describe('Time range for evidence collection'),
    systems: z.array(z.string()).optional().describe('Specific systems to collect evidence from'),
  });

• src/types/compliance-types.ts:326-370 (schema)

  TypeScript interface defining the input arguments for the evidence collection tool, imported and used by the handler.

  export interface EvidenceCollectionArgs {
    action: 'collect' | 'schedule' | 'get_status' | 'download';
    collectionId?: string;
    framework?: 'hitrust' | 'iso27001' | 'soc2';
    controlIds?: string[];
    evidenceTypes?: ('configuration' | 'logs' | 'policies' | 'screenshots' | 'documents')[];
    settings?: {
      automated: boolean;
      scheduledTime?: string;
      retention: number; // days
      encryption: boolean;
      compression: boolean;
    };
  }
  
  export interface EvidenceCollection {
    id: string;
    name: string;
    status: 'scheduled' | 'running' | 'completed' | 'failed';
    framework: string;
    startedDate: string;
    completedDate?: string;
    progress: number;
    totalItems: number;
    collectedItems: number;
    failedItems: number;
    evidence: CollectedEvidence[];
    errors?: string[];
  }
  
  export interface CollectedEvidence {
    id: string;
    controlId: string;
    type: string;
    name: string;
    source: string;
    collectedDate: string;
    size: number; // bytes
    format: string;
    encrypted: boolean;
    filePath: string;
    checksum: string;
    metadata: Record<string, any>;
  }

• src/tool-metadata.ts:186-189 (schema)

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

  manage_evidence_collection: {
    description: "Collect and preserve compliance evidence including audit logs, configuration snapshots, and attestation records.",
    title: "Evidence Collection Tool",
    annotations: { title: "Evidence Collection Tool", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }