Microsoft 365 Core MCP Server

Instructions

Implementation Reference

• src/handlers/security-policy-handlers.ts:313-396 (handler)

  The core handler function implementing the manage_sharepoint_governance_policies tool. Handles actions like list, get, create, update, delete for SharePoint governance policies using mapped Graph API endpoints for sharing, access, information barriers, and retention labels.

  export async function handleSharePointGovernancePolicies(
    graphClient: Client,
    args: SharePointGovernancePolicyArgs
  ): Promise<{ content: { type: string; text: string }[] }> {
    let apiPath = '';
    let result: any;
  
    // Map policy types to API endpoints
    const policyEndpoints = {
      sharingPolicy: '/admin/sharepoint/settings/sharing',
      accessPolicy: '/admin/sharepoint/settings/conditionalAccess',
      informationBarrier: '/admin/sharepoint/settings/informationBarriers',
      retentionLabel: '/admin/sharepoint/settings/retentionLabels'
    };
  
    const endpoint = policyEndpoints[args.policyType];
    if (!endpoint) {
      throw new McpError(ErrorCode.InvalidParams, `Unsupported policy type: ${args.policyType}`);
    }
  
    switch (args.action) {
      case 'list':
        apiPath = endpoint;
        result = await graphClient.api(apiPath).get();
        break;
  
      case 'get':
        if (!args.policyId) {
          throw new McpError(ErrorCode.InvalidParams, 'policyId is required for get action');
        }
        apiPath = `${endpoint}/${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 spPolicyPayload: any = {
          displayName: args.displayName,
          description: args.description || '',
          scope: args.scope || {},
          settings: args.settings || {}
        };
  
        apiPath = endpoint;
        result = await graphClient.api(apiPath).post(spPolicyPayload);
        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.scope) updatePayload.scope = args.scope;
        if (args.settings) updatePayload.settings = args.settings;
  
        apiPath = `${endpoint}/${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 = `${endpoint}/${args.policyId}`;
        await graphClient.api(apiPath).delete();
        result = { message: `SharePoint ${args.policyType} policy ${args.policyId} deleted successfully` };
        break;
  
      default:
        throw new McpError(ErrorCode.InvalidParams, `Unknown action: ${args.action}`);
    }
  
    return {
      content: [{
        type: 'text',
        text: `SharePoint ${args.policyType} Policy ${args.action} operation completed:\n\n${JSON.stringify(result, null, 2)}`
      }]
    };

• src/schemas/policy-schemas.ts:322-353 (schema)

  Zod schema defining input validation for the tool, including action, policyType (sharingPolicy, accessPolicy, etc.), policyId, displayName, scope, and detailed settings.

  export const sharePointGovernancePolicyArgsSchema = z.object({
    action: z.enum(['list', 'get', 'create', 'update', 'delete']).describe('Action to perform on SharePoint governance policy'),
    policyType: z.enum(['sharingPolicy', 'accessPolicy', 'informationBarrier', 'retentionLabel']).describe('Type of SharePoint governance policy'),
    policyId: z.string().optional().describe('SharePoint governance policy ID for specific operations'),
    displayName: z.string().optional().describe('Display name for the policy'),
    description: z.string().optional().describe('Description of the policy'),
    scope: z.object({
      sites: z.array(z.string()).optional().describe('Sites the policy applies to'),
      siteCollections: z.array(z.string()).optional().describe('Site collections the policy applies to'),
      webApplications: z.array(z.string()).optional().describe('Web applications the policy applies to'),
    }).optional().describe('Policy scope'),
    settings: z.object({
      sharingCapability: z.enum(['Disabled', 'ExternalUserSharingOnly', 'ExternalUserAndGuestSharing', 'ExistingExternalUserSharingOnly']).optional().describe('Sharing capability'),
      requireAcceptanceForExternalUsers: z.boolean().optional().describe('Require acceptance for external users'),
      requireAnonymousLinksExpireInDays: z.number().optional().describe('Anonymous links expiration in days'),
      fileAnonymousLinkType: z.enum(['None', 'View', 'Edit']).optional().describe('File anonymous link type'),
      folderAnonymousLinkType: z.enum(['None', 'View', 'Edit']).optional().describe('Folder anonymous link type'),
      defaultSharingLinkType: z.enum(['None', 'Direct', 'Internal', 'AnonymousAccess']).optional().describe('Default sharing link type'),
      preventExternalUsersFromResharing: z.boolean().optional().describe('Prevent external users from resharing'),
      conditionalAccessPolicy: z.enum(['AllowFullAccess', 'AllowLimitedAccess', 'BlockAccess']).optional().describe('Conditional access policy'),
      limitedAccessFileType: z.enum(['OfficeOnlineFilesOnly', 'WebPreviewableFiles', 'OtherFiles']).optional().describe('Limited access file type'),
      allowDownload: z.boolean().optional().describe('Allow download'),
      allowPrint: z.boolean().optional().describe('Allow print'),
      allowCopy: z.boolean().optional().describe('Allow copy'),
      informationBarrierMode: z.enum(['Open', 'Owner', 'Members', 'Explicit']).optional().describe('Information barrier mode'),
      retentionLabels: z.array(z.object({
        labelId: z.string().describe('Retention label ID'),
        isDefault: z.boolean().describe('Is default label'),
        autoApply: z.boolean().optional().describe('Auto-apply label'),
      })).optional().describe('Retention labels'),
    }).optional().describe('Policy settings'),
  });

• src/server.ts:1208-1228 (registration)

  Registers the tool with the MCP server using server.tool(), providing the tool name, description, input schema shape, annotations, and wrapped handler function that calls handleSharePointGovernancePolicies.

  // SharePoint Governance Policy Management - Lazy loading enabled for tool discovery
  this.server.tool(
    "manage_sharepoint_governance_policies",
    "Manage SharePoint governance policies including sharing controls, access restrictions, and site lifecycle management.",
    sharePointGovernancePolicyArgsSchema.shape,
    {"readOnlyHint":false,"destructiveHint":true,"idempotentHint":false},
    wrapToolHandler(async (args: SharePointGovernancePolicyArgs) => {
      this.validateCredentials();
      try {
        return await handleSharePointGovernancePolicies(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/policy-types.ts:348-386 (helper)

  TypeScript interface defining the structure of arguments passed to the handler, matching the Zod schema.

  export interface SharePointGovernancePolicyArgs {
    action: 'list' | 'get' | 'create' | 'update' | 'delete';
    policyType: 'sharingPolicy' | 'accessPolicy' | 'informationBarrier' | 'retentionLabel';
    policyId?: string;
    displayName?: string;
    description?: string;
    scope?: {
      sites?: string[];
      siteCollections?: string[];
      webApplications?: string[];
    };
    settings?: {
      // Sharing Policy settings
      sharingCapability?: 'Disabled' | 'ExternalUserSharingOnly' | 'ExternalUserAndGuestSharing' | 'ExistingExternalUserSharingOnly';
      requireAcceptanceForExternalUsers?: boolean;
      requireAnonymousLinksExpireInDays?: number;
      fileAnonymousLinkType?: 'None' | 'View' | 'Edit';
      folderAnonymousLinkType?: 'None' | 'View' | 'Edit';
      defaultSharingLinkType?: 'None' | 'Direct' | 'Internal' | 'AnonymousAccess';
      preventExternalUsersFromResharing?: boolean;
      
      // Access Policy settings
      conditionalAccessPolicy?: 'AllowFullAccess' | 'AllowLimitedAccess' | 'BlockAccess';
      limitedAccessFileType?: 'OfficeOnlineFilesOnly' | 'WebPreviewableFiles' | 'OtherFiles';
      allowDownload?: boolean;
      allowPrint?: boolean;
      allowCopy?: boolean;
      
      // Information Barrier settings
      informationBarrierMode?: 'Open' | 'Owner' | 'Members' | 'Explicit';
      
      // Retention Label settings
      retentionLabels?: {
        labelId: string;
        isDefault: boolean;
        autoApply?: boolean;
      }[];
    };
  }