Microsoft 365 Core MCP Server

Instructions

Implementation Reference

• src/utils/graph-advanced-features.ts:16-53 (handler)

  Core handler function that executes multiple Microsoft Graph API requests in a batch using the /$batch endpoint. Validates input, constructs batch payload, sends request, and processes responses with success/error counts.

  async executeBatch(requests: BatchRequest[]): Promise<BatchResponse> {
    if (requests.length === 0) {
      throw new McpError(ErrorCode.InvalidParams, 'At least one request is required for batch operation');
    }
  
    if (requests.length > 20) {
      throw new McpError(ErrorCode.InvalidParams, 'Maximum 20 requests allowed per batch');
    }
  
    const batchPayload = {
      requests: requests.map((req, index) => ({
        id: req.id || index.toString(),
        method: req.method.toUpperCase(),
        url: req.url,
        headers: req.headers || {},
        body: req.body
      }))
    };
  
    try {
      const response = await this.graphClient
        .api('/$batch')
        .post(batchPayload);
  
      return {
        responses: response.responses,
        executedAt: new Date().toISOString(),
        totalRequests: requests.length,
        successCount: response.responses.filter((r: any) => r.status >= 200 && r.status < 300).length,
        errorCount: response.responses.filter((r: any) => r.status >= 400).length
      };
    } catch (error) {
      throw new McpError(
        ErrorCode.InternalError,
        `Batch operation failed: ${error instanceof Error ? error.message : 'Unknown error'}`
      );
    }
  }

• src/utils/graph-advanced-features.ts:400-407 (schema)

  Zod schema for validating the input parameters of the execute_graph_batch tool, defining the structure of batch requests with validation for 1-20 requests.

  export const batchRequestSchema = z.object({
    requests: z.array(z.object({
      id: z.string().optional(),
      method: z.enum(['GET', 'POST', 'PATCH', 'PUT', 'DELETE']),
      url: z.string(),
      headers: z.record(z.string(), z.string()).optional(),
      body: z.any().optional()
    })).min(1).max(20)

• src/server.ts:1387-1408 (registration)

  MCP server tool registration for 'execute_graph_batch', which instantiates GraphAdvancedFeatures and calls executeBatch with validated args.

  // Batch Operations
  this.server.tool(
    "execute_graph_batch",
    "Execute multiple Microsoft Graph API requests in a single batch operation for improved performance and efficiency.",
    batchRequestSchema.shape,
    {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false},
    wrapToolHandler(async (args: any) => {
      this.validateCredentials();
      try {
        const advancedFeatures = new GraphAdvancedFeatures(this.getGraphClient(), this.getAccessToken.bind(this));
        const result = await advancedFeatures.executeBatch(args.requests);
        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
      } catch (error) {
        if (error instanceof McpError) {
          throw error;
        }
        throw new McpError(
          ErrorCode.InternalError,
          `Error executing batch operation: ${error instanceof Error ? error.message : 'Unknown error'}`
        );
      }
    })

• src/tool-metadata.ts:208-211 (schema)

  Tool metadata entry providing description, title, and annotations for the execute_graph_batch tool.

  execute_graph_batch: {
    description: "Execute multiple Microsoft Graph API requests in a single batch operation for improved performance and efficiency.",
    title: "Graph Batch Executor",
    annotations: { title: "Graph Batch Executor", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }

• src/utils/graph-advanced-features.ts:301-320 (helper)

  TypeScript interfaces defining the input BatchRequest and output BatchResponse structures used by the executeBatch handler.

  export interface BatchRequest {
    id?: string;
    method: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
    url: string;
    headers?: Record<string, string>;
    body?: any;
  }
  
  export interface BatchResponse {
    responses: Array<{
      id: string;
      status: number;
      headers: Record<string, string>;
      body: any;
    }>;
    executedAt: string;
    totalRequests: number;
    successCount: number;
    errorCount: number;
  }