Microsoft 365 Core MCP Server

Instructions

Implementation Reference

• src/handlers.ts:138-251 (handler)

  Core handler function implementing SharePoint site management logic: get, list, search sites; retrieve permissions, drives, subsites; limited update support.

  export async function handleSharePointSite(
    graphClient: Client,
    args: SharePointSiteArgs
  ): Promise<{ content: { type: string; text: string }[] }> {
    switch (args.action) {
      case 'get': {
        let apiPath = '';
        
        if (args.siteId) {
          // Get specific site by ID
          apiPath = `/sites/${args.siteId}`;
        } else if (args.url) {
          // Get site by URL (hostname:path format)
          const urlParts = args.url.replace('https://', '').split('/');
          const hostname = urlParts[0];
          const sitePath = urlParts.slice(1).join('/') || 'sites/root';
          apiPath = `/sites/${hostname}:/${sitePath}`;
        } else {
          throw new McpError(ErrorCode.InvalidParams, 'Either siteId or url is required for get action');
        }
        
        const site = await graphClient.api(apiPath).get();
        return { content: [{ type: 'text', text: JSON.stringify(site, null, 2) }] };
      }
      
      case 'list': {
        // List all sites in the organization
        const sites = await graphClient
          .api('/sites?search=*')
          .get();
        return { content: [{ type: 'text', text: JSON.stringify(sites, null, 2) }] };
      }
      
      case 'search': {
        if (!args.title) {
          throw new McpError(ErrorCode.InvalidParams, 'title (search query) is required for search action');
        }
        
        const sites = await graphClient
          .api(`/sites?search=${encodeURIComponent(args.title)}`)
          .get();
        return { content: [{ type: 'text', text: JSON.stringify(sites, null, 2) }] };
      }
      
      case 'create': {
        // Note: Direct site creation via Graph API is limited
        // This creates a communication site via SharePoint REST API
        throw new McpError(
          ErrorCode.InvalidParams, 
          'Direct site creation is not supported via Graph API. Use SharePoint admin center or PowerShell for site creation. You can use the "get" action to retrieve existing sites.'
        );
      }
      
      case 'update': {
        if (!args.siteId) {
          throw new McpError(ErrorCode.InvalidParams, 'siteId is required for update action');
        }
        
        const updatePayload: any = {};
        if (args.title) updatePayload.displayName = args.title;
        if (args.description) updatePayload.description = args.description;
        
        // Update site properties (limited to displayName and description)
        const result = await graphClient
          .api(`/sites/${args.siteId}`)
          .patch(updatePayload);
        
        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
      }
      
      case 'delete': {
        throw new McpError(
          ErrorCode.InvalidParams, 
          'Site deletion is not supported via Graph API. Use SharePoint admin center or PowerShell for site deletion.'
        );
      }
      
      case 'get_permissions': {
        if (!args.siteId) {
          throw new McpError(ErrorCode.InvalidParams, 'siteId is required for get_permissions action');
        }
        
        const permissions = await graphClient
          .api(`/sites/${args.siteId}/permissions`)
          .get();
        return { content: [{ type: 'text', text: JSON.stringify(permissions, null, 2) }] };
      }
      
      case 'get_drives': {
        if (!args.siteId) {
          throw new McpError(ErrorCode.InvalidParams, 'siteId is required for get_drives action');
        }
        
        const drives = await graphClient
          .api(`/sites/${args.siteId}/drives`)
          .get();
        return { content: [{ type: 'text', text: JSON.stringify(drives, null, 2) }] };
      }
      
      case 'get_subsites': {
        if (!args.siteId) {
          throw new McpError(ErrorCode.InvalidParams, 'siteId is required for get_subsites action');
        }
        
        const subsites = await graphClient
          .api(`/sites/${args.siteId}/sites`)
          .get();
        return { content: [{ type: 'text', text: JSON.stringify(subsites, null, 2) }] };
      }
      
      default:
        throw new McpError(ErrorCode.InvalidParams, `Invalid action: ${args.action}`);
    }
  }

• src/server.ts:478-498 (registration)

  MCP tool registration for 'manage_sharepoint_sites', linking schema to handleSharePointSite handler with annotations.

  this.server.tool(
    "manage_sharepoint_sites",
    "Manage SharePoint sites including creation, configuration, permissions, and site collection administration.",
    sharePointSiteSchema.shape,
    {"readOnlyHint":false,"destructiveHint":true,"idempotentHint":false},
    wrapToolHandler(async (args: SharePointSiteArgs) => {
      // Validate credentials only when tool is executed (lazy loading)
      this.validateCredentials();
      try {
        return await handleSharePointSite(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'}`
        );
      }
    })
  );    // SharePoint Lists - Lazy loading enabled for tool discovery

• src/tool-definitions.ts:6-20 (schema)

  Zod input schema defining parameters for manage_sharepoint_sites tool (action, siteId/url, title, etc.).

  export const sharePointSiteSchema = z.object({
    action: z.enum(['get', 'create', 'update', 'delete', 'add_users', 'remove_users']).describe('Action to perform on SharePoint site'),
    siteId: z.string().optional().describe('SharePoint site ID for existing site operations'),
    url: z.string().optional().describe('URL for the SharePoint site'),
    title: z.string().optional().describe('Title for the SharePoint site'),
    description: z.string().optional().describe('Description of the SharePoint site'),
    template: z.string().optional().describe('Web template ID for site creation (e.g., STS#3 for Modern Team Site)'),
    owners: z.array(z.string()).optional().describe('List of owner email addresses'),
    members: z.array(z.string()).optional().describe('List of member email addresses'),
    settings: z.object({
      isPublic: z.boolean().optional().describe('Whether the site is public'),
      allowSharing: z.boolean().optional().describe('Allow external sharing'),
      storageQuota: z.number().optional().describe('Storage quota in MB'),
    }).optional().describe('Site configuration settings'),
  });

• src/types.ts:92-106 (schema)

  TypeScript interface defining the argument shape for SharePoint site operations, used by handler.

  export interface SharePointSiteArgs {
    action: 'get' | 'list' | 'search' | 'create' | 'update' | 'delete' | 'add_users' | 'remove_users' | 'get_permissions' | 'get_drives' | 'get_subsites';
    siteId?: string;
    url?: string;
    title?: string;
    description?: string;
    template?: string;
    owners?: string[];
    members?: string[];
    settings?: {
      isPublic?: boolean;
      allowSharing?: boolean;
      storageQuota?: number;
    };
  }

• src/tool-metadata.ts:38-41 (helper)

  Tool metadata providing description, title, and annotations for 'manage_sharepoint_sites' used in MCP discovery.

  manage_sharepoint_sites: {
    description: "Manage SharePoint sites including creation, configuration, permissions, and site collection administration.",
    title: "SharePoint Site Manager",
    annotations: { title: "SharePoint Site Manager", readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true }