Microsoft 365 Core MCP Server

Instructions

Implementation Reference

• src/handlers.ts:253-335 (handler)

  Main handler function implementing SharePoint list management operations: get, create (with columns), update, delete, add_items, get_items using Microsoft Graph API.

  // SharePoint List Handler
  export async function handleSharePointList(
    graphClient: Client,
    args: SharePointListArgs
  ): Promise<{ content: { type: string; text: string }[] }> {
    switch (args.action) {
      case 'get': {
        const list = await graphClient
          .api(`/sites/${args.siteId}/lists/${args.listId}`)
          .get();
        return { content: [{ type: 'text', text: JSON.stringify(list, null, 2) }] };
      }
      case 'create': {
        // Create a new list
        const list = await graphClient
          .api(`/sites/${args.siteId}/lists`)
          .post({
            displayName: args.title,
            description: args.description,
            template: args.template || 'genericList',
          });
        
        // Add columns if provided
        if (args.columns?.length) {
          for (const column of args.columns) {
            await graphClient
              .api(`/sites/${args.siteId}/lists/${list.id}/columns`)
              .post({
                name: column.name,
                columnType: column.type,
                required: column.required || false,
                defaultValue: column.defaultValue,
              });
          }
        }
        
        return { content: [{ type: 'text', text: JSON.stringify(list, null, 2) }] };
      }
      case 'update': {
        await graphClient
          .api(`/sites/${args.siteId}/lists/${args.listId}`)
          .patch({
            displayName: args.title,
            description: args.description,
          });
        
        return { content: [{ type: 'text', text: 'SharePoint list updated successfully' }] };
      }
      case 'delete': {
        await graphClient
          .api(`/sites/${args.siteId}/lists/${args.listId}`)
          .delete();
        
        return { content: [{ type: 'text', text: 'SharePoint list deleted successfully' }] };
      }
      case 'add_items': {
        if (!args.items?.length) {
          throw new McpError(ErrorCode.InvalidParams, 'No items specified to add');
        }
        
        const results = [];
        for (const item of args.items) {
          const result = await graphClient
            .api(`/sites/${args.siteId}/lists/${args.listId}/items`)
            .post({
              fields: item,
            });
          
          results.push(result);
        }
        
        return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
      }
      case 'get_items': {
        const items = await graphClient
          .api(`/sites/${args.siteId}/lists/${args.listId}/items?expand=fields`)
          .get();
        
        return { content: [{ type: 'text', text: JSON.stringify(items, null, 2) }] };
      }
      default:
        throw new McpError(ErrorCode.InvalidParams, `Invalid action: ${args.action}`);
    }

• src/server.ts:499-518 (registration)

  MCP server tool registration for 'manage_sharepoint_lists' with schema, annotations, and handler invocation.

  this.server.tool(
    "manage_sharepoint_lists",
    "Manage SharePoint lists and libraries including schema definition, items, views, and permissions.",
    sharePointListSchema.shape,
    {"readOnlyHint":false,"destructiveHint":true,"idempotentHint":false},
    wrapToolHandler(async (args: SharePointListArgs) => {
      // Validate credentials only when tool is executed (lazy loading)
      this.validateCredentials();
      try {
        return await handleSharePointList(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:23-37 (schema)

  Zod input schema defining parameters for SharePoint list operations including siteId, listId, title, columns, and items.

  export const sharePointListSchema = z.object({
    action: z.enum(['get', 'create', 'update', 'delete', 'add_items', 'get_items']).describe('Action to perform on SharePoint list'),
    siteId: z.string().describe('SharePoint site ID containing the list'),
    listId: z.string().optional().describe('SharePoint list ID for existing list operations'),
    title: z.string().optional().describe('Title for the SharePoint list'),
    description: z.string().optional().describe('Description of the SharePoint list'),
    template: z.string().optional().describe('Template to use for list creation'),
    columns: z.array(z.object({
      name: z.string().describe('Column name'),
      type: z.string().describe('Column type (Text, Number, DateTime, etc.)'),
      required: z.boolean().optional().describe('Whether the column is required'),
      defaultValue: z.any().optional().describe('Default value for the column'),
    })).optional().describe('List column definitions'),
    items: z.array(z.record(z.string(), z.any())).optional().describe('Items to add to the list'),
  });

• src/tool-metadata.ts:43-46 (schema)

  Tool metadata with description, title, and annotations (readOnlyHint, destructiveHint, etc.) for 'manage_sharepoint_lists'.

  manage_sharepoint_lists: {
    description: "Manage SharePoint lists and libraries including schema definition, items, views, and permissions.",
    title: "SharePoint List Manager",
    annotations: { title: "SharePoint List Manager", readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true }

• src/types.ts:108-123 (schema)

  TypeScript interface SharePointListArgs defining the input parameters for the SharePoint list handler.

  // SharePoint List Types
  export interface SharePointListArgs {
    action: 'get' | 'create' | 'update' | 'delete' | 'add_items' | 'get_items';
    siteId: string;
    listId?: string;
    title?: string;
    description?: string;
    template?: string;
    columns?: {
      name: string;
      type: string;
      required?: boolean;
      defaultValue?: any;
    }[];
    items?: Record<string, any>[];
  }