@softeria/ms-365-mcp-server 0.122.0 → 0.124.0

package/bin/modules/simplified-openapi.mjs

@@ -17,11 +17,27 @@ export function createAndSaveSimplifiedOpenAPI(endpointsFile, openapiFile, opena
     }
   }
 
-  // Synthesize operations on existing paths when the method is missing.
+  // Two cases handled here:
+  //  1. The method is missing entirely (Microsoft never published this operation):
+  //     synthesize the whole operation from endpoints.json.
+  //  2. The method exists but the endpoint declares its own requestBodySchema
+  //     (Microsoft published a deprecated/malformed/private-preview body our generator
+  //     can't consume): override ONLY the request body and keep Microsoft's published
+  //     responses/parameters intact, so we don't silently drop upstream fields or mask
+  //     a future upstream fix. requestBodySchema is explicit opt-in per endpoint.
   for (const endpoint of endpoints) {
     const pathSpec = openApiSpec.paths[endpoint.pathPattern];
     const methodLower = endpoint.method.toLowerCase();
-    if (pathSpec && !pathSpec[methodLower]) {
+    if (!pathSpec) continue;
+
+    const operationMissing = !pathSpec[methodLower];
+    const overrideBodyOnly =
+      !operationMissing &&
+      endpoint.requestBodySchema &&
+      methodLower !== 'get' &&
+      methodLower !== 'delete';
+
+    if (operationMissing) {
       const pathParamMatches = [...endpoint.pathPattern.matchAll(/\{([^}]+)\}/g)].map((m) => m[1]);
       const synthesizedParameters = pathParamMatches.map((paramName) => ({
         name: paramName,
@@ -44,7 +60,14 @@ export function createAndSaveSimplifiedOpenAPI(endpointsFile, openapiFile, opena
                 required: true,
                 content: {
                   'application/json': {
-                    schema: { type: 'object', additionalProperties: true },
+                    // When an endpoint declares a typed body schema in endpoints.json
+                    // (for APIs Microsoft hasn't published in its OpenAPI metadata),
+                    // use it so the generated client gets a validated `body` param.
+                    // Otherwise fall back to a permissive object.
+                    schema: endpoint.requestBodySchema ?? {
+                      type: 'object',
+                      additionalProperties: true,
+                    },
                   },
                 },
               },
@@ -61,6 +84,24 @@ export function createAndSaveSimplifiedOpenAPI(endpointsFile, openapiFile, opena
           '5XX': { $ref: '#/components/responses/error' },
         },
       };
+    } else if (overrideBodyOnly) {
+      // Surgical override: replace only the request body, leaving Microsoft's
+      // published responses and parameters for this operation untouched.
+      pathSpec[methodLower].requestBody = {
+        description: pathSpec[methodLower].requestBody?.description || 'Operation payload',
+        required: true,
+        content: {
+          'application/json': {
+            schema: endpoint.requestBodySchema,
+          },
+        },
+      };
+      // These operations are often published as deprecated/private-preview, which
+      // openapi-zod-client skips by default. Declaring a requestBodySchema means we
+      // deliberately vouch for the endpoint, so clear the deprecation markers to keep
+      // it in the generated client.
+      delete pathSpec[methodLower].deprecated;
+      delete pathSpec[methodLower]['x-ms-deprecation'];
     }
   }
 

package/dist/__tests__/graph-tools.test.js

@@ -914,118 +914,4 @@ describe("graph-tools", () => {
       expect(server.tools.has("parse-teams-url")).toBe(true);
     });
   });
-  describe("copilot-retrieve", () => {
-    const retrievalResponse = {
-      content: [
-        {
-          type: "text",
-          text: JSON.stringify({
-            retrievalHits: [
-              {
-                webUrl: "https://contoso.sharepoint.com/sites/HR/VPNAccess.docx",
-                extracts: [{ text: "To configure the VPN...", relevanceScore: 0.83 }],
-                resourceType: "listItem",
-                resourceMetadata: { title: "VPN Access" }
-              }
-            ]
-          })
-        }
-      ]
-    };
-    it("POSTs queryString + dataSource to /copilot/retrieval on v1.0 and returns the hits", async () => {
-      mockEndpoints.length = 0;
-      mockEndpointsJson = [];
-      const graphClient = { graphRequest: vi.fn().mockResolvedValue(retrievalResponse) };
-      const server = createMockServer();
-      const { registerGraphTools } = await loadModule();
-      registerGraphTools(server, graphClient);
-      const tool = server.tools.get("copilot-retrieve");
-      expect(tool).toBeDefined();
-      const result = await tool.handler({
-        queryString: "How to setup corporate VPN?",
-        dataSource: "sharePoint"
-      });
-      expect(graphClient.graphRequest).toHaveBeenCalledTimes(1);
-      const [endpoint, options] = graphClient.graphRequest.mock.calls[0];
-      expect(endpoint).toBe("/copilot/retrieval");
-      expect(options.method).toBe("POST");
-      expect(options.apiVersion === void 0 || options.apiVersion === "v1.0").toBe(true);
-      const body = JSON.parse(options.body);
-      expect(body).toEqual({
-        queryString: "How to setup corporate VPN?",
-        dataSource: "sharePoint"
-      });
-      const payload = JSON.parse(result.content[0].text);
-      expect(payload.retrievalHits[0].webUrl).toBe(
-        "https://contoso.sharepoint.com/sites/HR/VPNAccess.docx"
-      );
-    });
-    it("includes optional filterExpression, resourceMetadata, and maximumNumberOfResults only when provided", async () => {
-      mockEndpoints.length = 0;
-      mockEndpointsJson = [];
-      const graphClient = { graphRequest: vi.fn().mockResolvedValue(retrievalResponse) };
-      const server = createMockServer();
-      const { registerGraphTools } = await loadModule();
-      registerGraphTools(server, graphClient);
-      const tool = server.tools.get("copilot-retrieve");
-      await tool.handler({
-        queryString: "corporate VPN",
-        dataSource: "sharePoint",
-        filterExpression: 'Author:"Megan Bowen"',
-        resourceMetadata: ["title", "author"],
-        maximumNumberOfResults: 5
-      });
-      const [, options] = graphClient.graphRequest.mock.calls[0];
-      const body = JSON.parse(options.body);
-      expect(body.filterExpression).toBe('Author:"Megan Bowen"');
-      expect(body.resourceMetadata).toEqual(["title", "author"]);
-      expect(body.maximumNumberOfResults).toBe(5);
-    });
-    it("requires a non-empty queryString", async () => {
-      mockEndpoints.length = 0;
-      mockEndpointsJson = [];
-      const graphClient = { graphRequest: vi.fn() };
-      const server = createMockServer();
-      const { registerGraphTools } = await loadModule();
-      registerGraphTools(server, graphClient);
-      const tool = server.tools.get("copilot-retrieve");
-      const result = await tool.handler({ queryString: "   ", dataSource: "sharePoint" });
-      expect(result.isError).toBe(true);
-      expect(graphClient.graphRequest).not.toHaveBeenCalled();
-      const payload = JSON.parse(result.content[0].text);
-      expect(payload.error).toMatch(/queryString/);
-    });
-    it("rejects an invalid dataSource", async () => {
-      mockEndpoints.length = 0;
-      mockEndpointsJson = [];
-      const graphClient = { graphRequest: vi.fn() };
-      const server = createMockServer();
-      const { registerGraphTools } = await loadModule();
-      registerGraphTools(server, graphClient);
-      const tool = server.tools.get("copilot-retrieve");
-      const result = await tool.handler({ queryString: "vpn", dataSource: "mailbox" });
-      expect(result.isError).toBe(true);
-      expect(graphClient.graphRequest).not.toHaveBeenCalled();
-      const payload = JSON.parse(result.content[0].text);
-      expect(payload.error).toMatch(/dataSource/);
-    });
-    it("rejects maximumNumberOfResults outside the 1-25 range", async () => {
-      mockEndpoints.length = 0;
-      mockEndpointsJson = [];
-      const graphClient = { graphRequest: vi.fn() };
-      const server = createMockServer();
-      const { registerGraphTools } = await loadModule();
-      registerGraphTools(server, graphClient);
-      const tool = server.tools.get("copilot-retrieve");
-      const result = await tool.handler({
-        queryString: "vpn",
-        dataSource: "sharePoint",
-        maximumNumberOfResults: 50
-      });
-      expect(result.isError).toBe(true);
-      expect(graphClient.graphRequest).not.toHaveBeenCalled();
-      const payload = JSON.parse(result.content[0].text);
-      expect(payload.error).toMatch(/maximumNumberOfResults/);
-    });
-  });
 });

package/dist/auth.js

@@ -49,13 +49,47 @@ function getEndpointRequiredScopes(endpoint, includeWorkAccountScopes = false) {
     return [];
   }
   const scopes = /* @__PURE__ */ new Set();
-  if (endpoint.scopes && Array.isArray(endpoint.scopes)) {
-    endpoint.scopes.forEach((scope) => scopes.add(scope));
+  getEndpointScopeGroups(endpoint, includeWorkAccountScopes).forEach(
+    (group) => group.forEach((scope) => scopes.add(scope))
+  );
+  return Array.from(scopes);
+}
+function toScopeGroups(value) {
+  if (!value || value.length === 0) {
+    return [];
   }
-  if (includeWorkAccountScopes && endpoint.workScopes && Array.isArray(endpoint.workScopes)) {
-    endpoint.workScopes.forEach((scope) => scopes.add(scope));
+  return Array.isArray(value[0]) ? value : [value];
+}
+function getEndpointScopeGroups(endpoint, includeWorkAccountScopes = false) {
+  if (!endpoint) {
+    return [];
   }
-  return Array.from(scopes);
+  const groups = [...toScopeGroups(endpoint.scopes)];
+  if (includeWorkAccountScopes) {
+    groups.push(...toScopeGroups(endpoint.workScopes));
+  }
+  return groups;
+}
+function getEndpointLoginScopes(endpoint, includeWorkAccountScopes = false) {
+  const groups = getEndpointScopeGroups(endpoint, includeWorkAccountScopes);
+  return groups.length > 0 ? groups[0] : [];
+}
+function getMissingAllowedScopesForGroups(scopeGroups, allowedScopes) {
+  if (allowedScopes === void 0 || scopeGroups.length === 0) {
+    return [];
+  }
+  const coveredAllowedScopes = new Set(collapseScopeHierarchy(allowedScopes));
+  let closest;
+  for (const group of scopeGroups) {
+    const missing = group.filter((scope) => !coveredAllowedScopes.has(scope));
+    if (missing.length === 0) {
+      return [];
+    }
+    if (!closest || missing.length < closest.length) {
+      closest = missing;
+    }
+  }
+  return closest ?? [];
 }
 function collapseRedundantScopes(scopes) {
   const scopesSet = new Set(scopes);
@@ -91,7 +125,7 @@ function buildScopesFromEndpoints(includeWorkAccountScopes = false, enabledTools
     if (!includeWorkAccountScopes && !endpoint.scopes && endpoint.workScopes) {
       return;
     }
-    getEndpointRequiredScopes(endpoint, includeWorkAccountScopes).forEach(
+    getEndpointLoginScopes(endpoint, includeWorkAccountScopes).forEach(
       (scope) => scopesSet.add(scope)
     );
   });
@@ -173,6 +207,7 @@ function buildAllowedScopeDiagnostics(options = {}) {
   }
   const normalToolScopes = /* @__PURE__ */ new Set();
   const effectiveToolScopes = /* @__PURE__ */ new Set();
+  const effectiveToolScopesAllGroups = /* @__PURE__ */ new Set();
   const disabledTools = [];
   for (const endpoint of endpoints.default) {
     if (!endpointMatchesNormalToolSurface(
@@ -183,18 +218,21 @@ function buildAllowedScopeDiagnostics(options = {}) {
     )) {
       continue;
     }
-    const requiredScopes = getEndpointRequiredScopes(endpoint, Boolean(options.orgMode));
-    requiredScopes.forEach((scope) => normalToolScopes.add(scope));
-    const missingScopes = getMissingAllowedScopes(requiredScopes, allowedScopes);
+    const scopeGroups = getEndpointScopeGroups(endpoint, Boolean(options.orgMode));
+    const loginScopes = getEndpointLoginScopes(endpoint, Boolean(options.orgMode));
+    const allScopes = getEndpointRequiredScopes(endpoint, Boolean(options.orgMode));
+    loginScopes.forEach((scope) => normalToolScopes.add(scope));
+    const missingScopes = getMissingAllowedScopesForGroups(scopeGroups, allowedScopes);
     if (missingScopes.length > 0) {
       disabledTools.push({
         toolName: endpoint.toolName,
-        requiredScopes: requiredScopes.sort((a, b) => a.localeCompare(b)),
+        requiredScopes: allScopes.sort((a, b) => a.localeCompare(b)),
         missingScopes: missingScopes.sort((a, b) => a.localeCompare(b))
       });
       continue;
     }
-    requiredScopes.forEach((scope) => effectiveToolScopes.add(scope));
+    loginScopes.forEach((scope) => effectiveToolScopes.add(scope));
+    allScopes.forEach((scope) => effectiveToolScopesAllGroups.add(scope));
   }
   const toolPermissions = collapseRedundantScopes(Array.from(normalToolScopes)).sort(
     (a, b) => a.localeCompare(b)
@@ -206,7 +244,8 @@ function buildAllowedScopeDiagnostics(options = {}) {
   const missingAllowedScopesForTools = Array.from(
     new Set(disabledTools.flatMap((tool) => tool.missingScopes))
   ).sort((a, b) => a.localeCompare(b));
-  const extraAllowedScopesNotUsedByTools = sortedAllowedScopes?.filter((scope) => !isScopeUsedByTools(scope, effectivePermissions)) ?? [];
+  const allEffectiveToolScopes = Array.from(effectiveToolScopesAllGroups);
+  const extraAllowedScopesNotUsedByTools = sortedAllowedScopes?.filter((scope) => !isScopeUsedByTools(scope, allEffectiveToolScopes)) ?? [];
   return {
     permissions: effectivePermissions,
     toolPermissions,
@@ -811,7 +850,9 @@ export {
   auth_default as default,
   describeAuthError,
   getEndpointRequiredScopes,
+  getEndpointScopeGroups,
   getMissingAllowedScopes,
+  getMissingAllowedScopesForGroups,
   getSelectedAccountPath,
   getTokenCachePath,
   parseAllowedScopes,

package/dist/endpoints.json

@@ -1742,6 +1742,48 @@
       "ChannelMessage.Read.All"
     ]
   },
+  {
+    "pathPattern": "/copilot/retrieval",
+    "method": "post",
+    "toolName": "copilot-retrieve",
+    "presets": ["search", "work"],
+    "readOnly": true,
+    "workScopes": [["Files.Read.All", "Sites.Read.All"], ["ExternalItem.Read.All"]],
+    "requestBodySchema": {
+      "type": "object",
+      "required": ["queryString", "dataSource"],
+      "properties": {
+        "queryString": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1500,
+          "pattern": "\\S",
+          "description": "Natural-language query (a single sentence works best; max 1500 characters; must contain a non-whitespace character). Avoid spelling errors in context-rich keywords."
+        },
+        "dataSource": {
+          "type": "string",
+          "enum": ["sharePoint", "oneDriveBusiness", "externalItem"],
+          "description": "Which source to retrieve from — one at a time (interleaved results are not supported). 'sharePoint', 'oneDriveBusiness', or 'externalItem' (Copilot connectors)."
+        },
+        "filterExpression": {
+          "type": "string",
+          "description": "Optional KQL expression to scope the retrieval before the query runs. Supported SharePoint/OneDrive properties: Author, FileExtension, Filename, FileType, InformationProtectionLabelId, LastModifiedTime, ModifiedBy, Path, SiteID, Title. Invalid KQL is ignored (query runs unscoped)."
+        },
+        "resourceMetadata": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Optional list of retrievable metadata fields to return per hit (e.g. ['title', 'author']). By default no metadata is returned."
+        },
+        "maximumNumberOfResults": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 25,
+          "description": "Optional cap on the number of results (1-25). Best practice: leave unset unless your LLM has strict token limits — results are unordered."
+        }
+      }
+    },
+    "llmTip": "Semantic/hybrid search over Microsoft 365 content via the Copilot Retrieval API. Grounds a natural-language query against the same hybrid index that powers Microsoft 365 Copilot and returns permission-trimmed text extracts with their source URLs — unlike search-query/search-onedrive-files/search-sharepoint-sites, which are lexical KQL. Prefer this for paraphrase/intent queries (e.g. resolving an informal project nickname, or matching 'packaging requirements' against text that never uses that phrase). Pass the request fields nested under a 'body' object: { queryString, dataSource, filterExpression?, resourceMetadata?, maximumNumberOfResults? }. Returns { retrievalHits: [{ webUrl, extracts: [{ text, relevanceScore }], resourceType, resourceMetadata, sensitivityLabel? }] }. Work/school accounts only (personal accounts are not supported). dataSource 'sharePoint'/'oneDriveBusiness' need delegated Files.Read.All + Sites.Read.All (requested by default); dataSource 'externalItem' (Copilot connectors) needs ExternalItem.Read.All, which is not requested by default - add it with --extra-scopes ExternalItem.Read.All."
+  },
   {
     "pathPattern": "/me/onlineMeetings",
     "method": "get",

package/dist/generated/client.js

@@ -547,6 +547,52 @@ const microsoft_graph_presence = z.object({
   statusMessage: microsoft_graph_presenceStatusMessage.optional(),
   workLocation: microsoft_graph_userWorkLocation.optional()
 }).passthrough();
+const copilot_retrieve_Body = z.object({
+  queryString: z.string().min(1).max(1500).regex(/\S/).describe(
+    "Natural-language query (a single sentence works best; max 1500 characters; must contain a non-whitespace character). Avoid spelling errors in context-rich keywords."
+  ),
+  dataSource: z.enum(["sharePoint", "oneDriveBusiness", "externalItem"]).describe(
+    "Which source to retrieve from \u2014 one at a time (interleaved results are not supported). 'sharePoint', 'oneDriveBusiness', or 'externalItem' (Copilot connectors)."
+  ),
+  filterExpression: z.string().describe(
+    "Optional KQL expression to scope the retrieval before the query runs. Supported SharePoint/OneDrive properties: Author, FileExtension, Filename, FileType, InformationProtectionLabelId, LastModifiedTime, ModifiedBy, Path, SiteID, Title. Invalid KQL is ignored (query runs unscoped)."
+  ).optional(),
+  resourceMetadata: z.array(z.string()).describe(
+    "Optional list of retrievable metadata fields to return per hit (e.g. ['title', 'author']). By default no metadata is returned."
+  ).optional(),
+  maximumNumberOfResults: z.number().int().gte(1).lte(25).describe(
+    "Optional cap on the number of results (1-25). Best practice: leave unset unless your LLM has strict token limits \u2014 results are unordered."
+  ).optional()
+}).passthrough();
+const microsoft_graph_retrievalExtract = z.object({
+  relevanceScore: z.number().describe("[Simplified from 3 options]").nullish(),
+  text: z.string().nullish()
+}).passthrough();
+const microsoft_graph_searchResourceMetadataDictionary = z.object({}).passthrough();
+const microsoft_graph_retrievalEntityType = z.enum([
+  "site",
+  "list",
+  "listItem",
+  "drive",
+  "driveItem",
+  "externalItem",
+  "unknownFutureValue"
+]);
+const microsoft_graph_sensitivityLabelInfo = z.object({
+  color: z.string().nullish(),
+  displayName: z.string().nullish(),
+  priority: z.number().gte(-2147483648).lte(2147483647).nullish(),
+  sensitivityLabelId: z.string().nullish(),
+  tooltip: z.string().nullish()
+}).passthrough();
+const microsoft_graph_retrievalHit = z.object({
+  extracts: z.array(microsoft_graph_retrievalExtract).optional(),
+  resourceMetadata: microsoft_graph_searchResourceMetadataDictionary.optional(),
+  resourceType: microsoft_graph_retrievalEntityType.optional(),
+  sensitivityLabel: microsoft_graph_sensitivityLabelInfo.optional(),
+  webUrl: z.string().nullish()
+}).passthrough();
+const microsoft_graph_retrievalResponse = z.object({ retrievalHits: z.array(microsoft_graph_retrievalHit).optional() }).passthrough();
 const microsoft_graph_geoCoordinates = z.object({
   altitude: z.number().describe(
     "Optional. The altitude (height), in feet,  above sea level for the item. Read-only. [Simplified from 3 options]"
@@ -4818,6 +4864,13 @@ const schemas = {
   microsoft_graph_workLocationType,
   microsoft_graph_userWorkLocation,
   microsoft_graph_presence,
+  copilot_retrieve_Body,
+  microsoft_graph_retrievalExtract,
+  microsoft_graph_searchResourceMetadataDictionary,
+  microsoft_graph_retrievalEntityType,
+  microsoft_graph_sensitivityLabelInfo,
+  microsoft_graph_retrievalHit,
+  microsoft_graph_retrievalResponse,
   microsoft_graph_geoCoordinates,
   microsoft_graph_sharepointIds,
   microsoft_graph_itemReference,
@@ -5683,6 +5736,22 @@ const endpoints = makeApi([
     ],
     response: z.void()
   },
+  {
+    method: "post",
+    path: "/copilot/retrieval",
+    alias: "copilot-retrieve",
+    description: `Invoke action retrieval`,
+    requestFormat: "json",
+    parameters: [
+      {
+        name: "body",
+        description: `Action parameters`,
+        type: "Body",
+        schema: copilot_retrieve_Body
+      }
+    ],
+    response: z.void()
+  },
   {
     method: "get",
     path: "/drives/:driveId/items/:driveItemId",

package/dist/graph-tools.js

@@ -2,8 +2,8 @@ import { randomUUID } from "crypto";
 import logger from "./logger.js";
 import { auditLog, getUserIdentityForAudit } from "./audit-log.js";
 import {
-  getEndpointRequiredScopes,
-  getMissingAllowedScopes,
+  getEndpointScopeGroups,
+  getMissingAllowedScopesForGroups,
   parseAllowedScopes
 } from "./auth.js";
 import { api } from "./generated/client.js";
@@ -169,93 +169,6 @@ const UTILITY_TOOLS = [
         };
       }
     }
-  },
-  {
-    name: "copilot-retrieve",
-    method: "POST",
-    path: "tool:copilot-retrieve",
-    description: 'Semantic search over Microsoft 365 content via the Copilot Retrieval API (POST /copilot/retrieval). Grounds a natural-language query against the same hybrid index that powers Microsoft 365 Copilot and returns relevant, permission-trimmed text extracts with their source URLs \u2014 unlike search-query/search-onedrive-files/search-sharepoint-sites, which are lexical KQL. Prefer this for paraphrase/intent queries (e.g. resolving an informal project nickname, or matching "packaging requirements" against text that never uses that phrase). Returns { retrievalHits: [{ webUrl, extracts: [{ text, relevanceScore }], resourceType, resourceMetadata, sensitivityLabel? }] }. Read-only. Requires delegated Files.Read.All + Sites.Read.All (SharePoint/OneDrive) or ExternalItem.Read.All (Copilot connectors); application-only auth is not supported.',
-    readOnlyHint: true,
-    openWorldHint: true,
-    buildSchema: (ctx) => {
-      const schema = {
-        queryString: z.string().min(1).max(1500).describe(
-          "Natural-language query (a single sentence works best; max 1500 characters). Avoid spelling errors in context-rich keywords."
-        ),
-        dataSource: z.enum(["sharePoint", "oneDriveBusiness", "externalItem"]).describe(
-          'Which source to retrieve from \u2014 one at a time (interleaved results are not supported). "sharePoint", "oneDriveBusiness", or "externalItem" (Copilot connectors).'
-        ),
-        filterExpression: z.string().optional().describe(
-          'Optional KQL expression to scope the retrieval before the query runs. Supported SharePoint/OneDrive properties: Author, FileExtension, Filename, FileType, InformationProtectionLabelId, LastModifiedTime, ModifiedBy, Path, SiteID, Title. Example: Author:"Megan Bowen" OR Path:"https://contoso.sharepoint.com/sites/HR/". Invalid KQL is ignored (query runs unscoped).'
-        ),
-        resourceMetadata: z.array(z.string()).optional().describe(
-          'Optional list of retrievable metadata fields to return per hit (e.g. ["title", "author"]). By default no metadata is returned.'
-        ),
-        maximumNumberOfResults: z.number().int().min(1).max(25).optional().describe(
-          "Optional cap on the number of results (1-25). Best practice: leave unset unless your LLM has strict token limits \u2014 results are unordered."
-        )
-      };
-      if (ctx.multiAccount) {
-        schema["account"] = z.string().optional().describe(
-          "Account to use when multiple Microsoft accounts are configured. Required when multiple accounts exist (see list-accounts)."
-        );
-      }
-      return schema;
-    },
-    execute: async (params, { graphClient, authManager }) => {
-      const err = (message) => ({
-        content: [{ type: "text", text: JSON.stringify({ error: message }) }],
-        isError: true
-      });
-      const queryString = typeof params.queryString === "string" ? params.queryString : "";
-      if (queryString.trim().length === 0) {
-        return err("queryString is required and must be a non-empty string.");
-      }
-      if (queryString.length > 1500) {
-        return err("queryString must be 1500 characters or fewer.");
-      }
-      const dataSource = params.dataSource;
-      const allowedSources = ["sharePoint", "oneDriveBusiness", "externalItem"];
-      if (typeof dataSource !== "string" || !allowedSources.includes(dataSource)) {
-        return err(`dataSource is required and must be one of: ${allowedSources.join(", ")}.`);
-      }
-      const body = { queryString, dataSource };
-      if (params.filterExpression !== void 0) {
-        if (typeof params.filterExpression !== "string") {
-          return err("filterExpression must be a string (KQL expression).");
-        }
-        body.filterExpression = params.filterExpression;
-      }
-      if (params.resourceMetadata !== void 0) {
-        const rm = params.resourceMetadata;
-        if (!Array.isArray(rm) || rm.some((x) => typeof x !== "string")) {
-          return err("resourceMetadata must be an array of strings.");
-        }
-        body.resourceMetadata = rm;
-      }
-      if (params.maximumNumberOfResults !== void 0) {
-        const n = params.maximumNumberOfResults;
-        if (typeof n !== "number" || !Number.isInteger(n) || n < 1 || n > 25) {
-          return err("maximumNumberOfResults must be an integer between 1 and 25.");
-        }
-        body.maximumNumberOfResults = n;
-      }
-      try {
-        let accountAccessToken;
-        if (authManager && !authManager.isOAuthModeEnabled() && !getRequestTokens()) {
-          accountAccessToken = await authManager.getTokenForAccount(
-            params.account
-          );
-        }
-        return await graphClient.graphRequest("/copilot/retrieval", {
-          method: "POST",
-          body: JSON.stringify(body),
-          accessToken: accountAccessToken
-        });
-      } catch (error) {
-        return err(error.message);
-      }
-    }
   }
 ];
 function registerUtilityToolWithMcp(server, utility, ctx) {
@@ -609,8 +522,10 @@ function registerGraphTools(server, graphClient, readOnly = false, enabledToolsP
       skippedCount++;
       continue;
     }
-    const requiredScopes = getEndpointRequiredScopes(endpointConfig, orgMode);
-    const missingScopes = allowedScopes !== void 0 && !endpointConfig ? ["endpoint scope metadata"] : getMissingAllowedScopes(requiredScopes, allowedScopes);
+    const missingScopes = allowedScopes !== void 0 && !endpointConfig ? ["endpoint scope metadata"] : getMissingAllowedScopesForGroups(
+      getEndpointScopeGroups(endpointConfig, orgMode),
+      allowedScopes
+    );
     if (missingScopes.length > 0) {
       disabledByAllowedScopes.push({ toolName: tool.alias, missingScopes });
       skippedCount++;
@@ -693,6 +608,7 @@ function registerGraphTools(server, graphClient, readOnly = false, enabledToolsP
 
 \u{1F4A1} TIP: ${endpointConfig.llmTip}`;
     }
+    const isReadOnlyTool = tool.method.toUpperCase() === "GET" || endpointConfig?.readOnly === true;
     try {
       server.tool(
         tool.alias,
@@ -700,8 +616,8 @@ function registerGraphTools(server, graphClient, readOnly = false, enabledToolsP
         paramSchema,
         {
           title: tool.alias,
-          readOnlyHint: tool.method.toUpperCase() === "GET",
-          destructiveHint: ["POST", "PATCH", "DELETE"].includes(tool.method.toUpperCase()),
+          readOnlyHint: isReadOnlyTool,
+          destructiveHint: !isReadOnlyTool && ["POST", "PATCH", "DELETE"].includes(tool.method.toUpperCase()),
           openWorldHint: true
           // All tools call Microsoft Graph API
         },
@@ -760,8 +676,8 @@ function buildToolsRegistry(readOnly, orgMode, enabledToolsRegex, allowedScopesV
     if (enabledToolsRegex && !enabledToolsRegex.test(tool.alias)) {
       continue;
     }
-    const missingScopes = allowedScopes !== void 0 && !endpointConfig ? ["endpoint scope metadata"] : getMissingAllowedScopes(
-      getEndpointRequiredScopes(endpointConfig, orgMode),
+    const missingScopes = allowedScopes !== void 0 && !endpointConfig ? ["endpoint scope metadata"] : getMissingAllowedScopesForGroups(
+      getEndpointScopeGroups(endpointConfig, orgMode),
       allowedScopes
     );
     if (missingScopes.length > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softeria/ms-365-mcp-server",
-  "version": "0.122.0",
+  "version": "0.124.0",
   "description": " A Model Context Protocol (MCP) server for interacting with Microsoft 365 and Office services through the Graph API",
   "type": "module",
   "main": "dist/index.js",

package/src/endpoints.json

@@ -1742,6 +1742,48 @@
       "ChannelMessage.Read.All"
     ]
   },
+  {
+    "pathPattern": "/copilot/retrieval",
+    "method": "post",
+    "toolName": "copilot-retrieve",
+    "presets": ["search", "work"],
+    "readOnly": true,
+    "workScopes": [["Files.Read.All", "Sites.Read.All"], ["ExternalItem.Read.All"]],
+    "requestBodySchema": {
+      "type": "object",
+      "required": ["queryString", "dataSource"],
+      "properties": {
+        "queryString": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1500,
+          "pattern": "\\S",
+          "description": "Natural-language query (a single sentence works best; max 1500 characters; must contain a non-whitespace character). Avoid spelling errors in context-rich keywords."
+        },
+        "dataSource": {
+          "type": "string",
+          "enum": ["sharePoint", "oneDriveBusiness", "externalItem"],
+          "description": "Which source to retrieve from — one at a time (interleaved results are not supported). 'sharePoint', 'oneDriveBusiness', or 'externalItem' (Copilot connectors)."
+        },
+        "filterExpression": {
+          "type": "string",
+          "description": "Optional KQL expression to scope the retrieval before the query runs. Supported SharePoint/OneDrive properties: Author, FileExtension, Filename, FileType, InformationProtectionLabelId, LastModifiedTime, ModifiedBy, Path, SiteID, Title. Invalid KQL is ignored (query runs unscoped)."
+        },
+        "resourceMetadata": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Optional list of retrievable metadata fields to return per hit (e.g. ['title', 'author']). By default no metadata is returned."
+        },
+        "maximumNumberOfResults": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 25,
+          "description": "Optional cap on the number of results (1-25). Best practice: leave unset unless your LLM has strict token limits — results are unordered."
+        }
+      }
+    },
+    "llmTip": "Semantic/hybrid search over Microsoft 365 content via the Copilot Retrieval API. Grounds a natural-language query against the same hybrid index that powers Microsoft 365 Copilot and returns permission-trimmed text extracts with their source URLs — unlike search-query/search-onedrive-files/search-sharepoint-sites, which are lexical KQL. Prefer this for paraphrase/intent queries (e.g. resolving an informal project nickname, or matching 'packaging requirements' against text that never uses that phrase). Pass the request fields nested under a 'body' object: { queryString, dataSource, filterExpression?, resourceMetadata?, maximumNumberOfResults? }. Returns { retrievalHits: [{ webUrl, extracts: [{ text, relevanceScore }], resourceType, resourceMetadata, sensitivityLabel? }] }. Work/school accounts only (personal accounts are not supported). dataSource 'sharePoint'/'oneDriveBusiness' need delegated Files.Read.All + Sites.Read.All (requested by default); dataSource 'externalItem' (Copilot connectors) needs ExternalItem.Read.All, which is not requested by default - add it with --extra-scopes ExternalItem.Read.All."
+  },
   {
     "pathPattern": "/me/onlineMeetings",
     "method": "get",