Microsoft 365 Core MCP Server

Instructions

Implementation Reference

• src/utils/graph-advanced-features.ts:56-98 (handler)

  Core handler function executeDeltaQuery that performs Microsoft Graph delta queries, handles delta tokens, extracts response metadata, and returns formatted DeltaQueryResponse.

  async executeDeltaQuery(resource: string, deltaToken?: string): Promise<DeltaQueryResponse> {
    let apiPath = resource;
    
    // Add delta function to the path
    if (!apiPath.includes('/delta')) {
      apiPath = apiPath.endsWith('/') ? `${apiPath}delta` : `${apiPath}/delta`;
    }
  
    try {
      let request = this.graphClient.api(apiPath);
  
      // If we have a delta token, use it to get only changes since last query
      if (deltaToken) {
        request = request.query({ $deltatoken: deltaToken });
      }
  
      const response = await request.get();
  
      // Extract delta link and delta token from response
      const deltaLink = response['@odata.deltaLink'];
      const nextLink = response['@odata.nextLink'];
      
      let extractedDeltaToken = '';
      if (deltaLink) {
        const tokenMatch = deltaLink.match(/\$deltatoken=([^&]+)/);
        extractedDeltaToken = tokenMatch ? decodeURIComponent(tokenMatch[1]) : '';
      }
  
      return {
        value: response.value || [],
        deltaToken: extractedDeltaToken,
        deltaLink: deltaLink,
        nextLink: nextLink,
        hasMoreChanges: !!nextLink,
        changeCount: response.value ? response.value.length : 0,
        queriedAt: new Date().toISOString()
      };
    } catch (error) {
      throw new McpError(
        ErrorCode.InternalError,
        `Delta query failed: ${error instanceof Error ? error.message : 'Unknown error'}`
      );
    }

• src/server.ts:1412-1434 (registration)

  Registers the execute_delta_query tool on the MCP server, using deltaQuerySchema for input validation, instantiates GraphAdvancedFeatures class, and calls executeDeltaQuery method with parsed arguments.

  this.server.tool(
    "execute_delta_query",
    "Track incremental changes to Microsoft Graph resources using delta queries for efficient synchronization.",
    deltaQuerySchema.shape,
    {"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true},
    wrapToolHandler(async (args: any) => {
      this.validateCredentials();
      try {
        const advancedFeatures = new GraphAdvancedFeatures(this.getGraphClient(), this.getAccessToken.bind(this));
        const result = await advancedFeatures.executeDeltaQuery(args.resource, args.deltaToken);
        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 delta query: ${error instanceof Error ? error.message : 'Unknown error'}`
        );
      }
    })
  );

• src/utils/graph-advanced-features.ts:410-413 (schema)

  Zod input schema defining 'resource' (required string: Graph endpoint) and 'deltaToken' (optional string from previous query). Used for tool parameter validation.

  export const deltaQuerySchema = z.object({
    resource: z.string().describe('Graph resource path (e.g., /users, /groups)'),
    deltaToken: z.string().optional().describe('Delta token from previous query')
  });

• src/tool-metadata.ts:213-217 (helper)

  Tool metadata providing description, title, and annotations (readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true) for the execute_delta_query tool.

  execute_delta_query: {
    description: "Track incremental changes to Microsoft Graph resources using delta queries for efficient synchronization.",
    title: "Graph Delta Query",
    annotations: { title: "Graph Delta Query", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }
  },