Microsoft 365 Core MCP Server

Instructions

Implementation Reference

• src/handlers/purview-compliance-handler.ts:106-180 (handler)

  The main handler function that implements CRUD operations (list, get, create, update, delete) for retention policies using the Microsoft Graph API endpoint '/security/informationProtection/retentionPolicies'.
  export async function handleRetentionPolicies( graphClient: Client, args: RetentionPolicyArgs ): Promise<{ content: { type: string; text: string }[] }> { let apiPath = ''; let result: any; switch (args.action) { case 'list': // List all retention policies apiPath = '/security/informationProtection/retentionPolicies'; 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/informationProtection/retentionPolicies/${args.policyId}`; result = await graphClient.api(apiPath).get(); break; case 'create': if (!args.displayName || !args.retentionSettings) { throw new McpError(ErrorCode.InvalidParams, 'displayName and retentionSettings are required for create action'); } const retentionPolicyPayload = { displayName: args.displayName, description: args.description || '', isEnabled: args.isEnabled !== undefined ? args.isEnabled : true, retentionSettings: args.retentionSettings, locations: args.locations || {} }; apiPath = '/security/informationProtection/retentionPolicies'; result = await graphClient.api(apiPath).post(retentionPolicyPayload); 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.isEnabled !== undefined) updatePayload.isEnabled = args.isEnabled; if (args.retentionSettings) updatePayload.retentionSettings = args.retentionSettings; if (args.locations) updatePayload.locations = args.locations; apiPath = `/security/informationProtection/retentionPolicies/${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/informationProtection/retentionPolicies/${args.policyId}`; await graphClient.api(apiPath).delete(); result = { message: `Retention policy ${args.policyId} deleted successfully` }; break; default: throw new McpError(ErrorCode.InvalidParams, `Unknown action: ${args.action}`); } return { content: [{ type: 'text', text: `Retention Policy ${args.action} operation completed:\n\n${JSON.stringify(result, null, 2)}` }] }; }
• src/server.ts:1054-1073 (registration)

  Registers the 'manage_retention_policies' tool with the MCP server, linking the retentionPolicyArgsSchema input schema to the handleRetentionPolicies handler function.
  this.server.tool( "manage_retention_policies", "Manage retention policies for content across Exchange, SharePoint, OneDrive, and Teams with lifecycle rules.", retentionPolicyArgsSchema.shape, {"readOnlyHint":false,"destructiveHint":true,"idempotentHint":false}, wrapToolHandler(async (args: RetentionPolicyArgs) => { this.validateCredentials(); try { return await handleRetentionPolicies(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/schemas/policy-schemas.ts:38-56 (schema)

  Zod schema defining the input parameters for retention policy operations, including action type, policy details, retention settings, and applicable locations.
  export const retentionPolicyArgsSchema = z.object({ action: z.enum(['list', 'get', 'create', 'update', 'delete']).describe('Action to perform on retention policy'), policyId: z.string().optional().describe('Retention policy ID for specific operations'), displayName: z.string().optional().describe('Display name for the retention policy'), description: z.string().optional().describe('Description of the retention policy'), isEnabled: z.boolean().optional().describe('Whether the policy is enabled'), retentionSettings: z.object({ retentionDuration: z.number().describe('Retention duration in days'), retentionAction: z.enum(['Delete', 'Keep', 'KeepAndDelete']).describe('Action to take after retention period'), deletionType: z.enum(['Immediately', 'AfterRetentionPeriod']).optional().describe('When to delete content'), }).describe('Retention policy settings'), locations: z.object({ sharePointSites: z.array(z.string()).optional().describe('SharePoint sites to include'), exchangeEmail: z.boolean().optional().describe('Include Exchange email'), teamsChannels: z.boolean().optional().describe('Include Teams channels'), teamsChats: z.boolean().optional().describe('Include Teams chats'), oneDriveAccounts: z.array(z.string()).optional().describe('OneDrive accounts to include'), }).optional().describe('Locations where the policy applies'), });
• src/types/policy-types.ts:38-56 (helper)

  TypeScript interface defining the structure of arguments passed to the retention policy handler.
  export interface RetentionPolicyArgs { action: 'list' | 'get' | 'create' | 'update' | 'delete'; policyId?: string; displayName?: string; description?: string; isEnabled?: boolean; retentionSettings: { retentionDuration: number; // in days retentionAction: 'Delete' | 'Keep' | 'KeepAndDelete'; deletionType?: 'Immediately' | 'AfterRetentionPeriod'; }; locations?: { sharePointSites?: string[]; exchangeEmail?: boolean; teamsChannels?: boolean; teamsChats?: boolean; oneDriveAccounts?: string[]; }; }
• src/tool-metadata.ts:230-233 (helper)

  Metadata configuration for the manage_retention_policies tool, including description, title, and execution hints used by the MCP server.
  manage_retention_policies: { description: "Manage retention policies for content across Exchange, SharePoint, OneDrive, and Teams with lifecycle rules.", title: "Retention Policy Manager", annotations: { title: "Retention Policy Manager", readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true }