@softeria/ms-365-mcp-server 0.121.0 → 0.123.0

package/README.md

@@ -150,6 +150,18 @@ Scope coverage is hierarchy-aware: for example, `Mail.ReadWrite` covers tools th
 
 In HTTP mode, OAuth discovery advertises the effective filtered permissions so clients request the same consent surface. On-Behalf-Of mode (`--obo`) still advertises `api://<clientId>/access_as_user` for protected-resource metadata; `--allowed-scopes` does not override OBO.
 
+### Requesting extra scopes
+
+`--allowed-scopes` only ever _narrows_ the token request. To request a Graph scope that no bundled tool needs — for example to drive an endpoint via `graph-batch` — use `--extra-scopes` (or `MS365_MCP_EXTRA_SCOPES`). These scopes are appended verbatim to the token request, on top of the tool-derived scopes.
+
+```bash
+npx @softeria/ms-365-mcp-server \
+  --org-mode \
+  --extra-scopes 'CopilotPackages.ReadWrite.All'
+```
+
+This is for use with your own Azure app registration (`MS365_MCP_CLIENT_ID` / `MS365_MCP_CLIENT_SECRET`): the default Softeria app only declares a lean, fixed permission set, so request additional scopes against an app you control (your tenant admin consents to them there). CLI value takes precedence over the env var; an empty value fails at startup.
+
 ## Organization/Work Mode
 
 To access work/school features (Teams, SharePoint, etc.), enable organization mode using any of these flags:
@@ -542,6 +554,7 @@ The following options can be used when running ms-365-mcp-server directly from t
 --force-work-scopes Backwards compatibility alias for --org-mode (deprecated)
 --cloud <type>    Microsoft cloud environment: global (default) or china (21Vianet)
 --allowed-scopes <scopes> Limit exposed tools to Graph scopes covered by this allowlist
+--extra-scopes <scopes> Append additional Graph scopes to the token request (for use with your own app registration + graph-batch)
 --expected-username <username> Require local MSAL auth to use this account username
 --expected-home-account-id <id> Require local MSAL auth to use this exact homeAccountId
 ```

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

@@ -218,7 +218,12 @@ function buildAllowedScopeDiagnostics(options = {}) {
   };
 }
 function resolveAuthScopes(options = {}) {
-  return buildAllowedScopeDiagnostics(options).effectivePermissions;
+  const toolScopes = buildAllowedScopeDiagnostics(options).effectivePermissions;
+  const extraScopes = parseAllowedScopes(options.extraScopes);
+  if (!extraScopes || extraScopes.length === 0) {
+    return toolScopes;
+  }
+  return Array.from(/* @__PURE__ */ new Set([...toolScopes, ...extraScopes]));
 }
 function buildScopeDiagnostics(toolScopes, allowedScopesInput) {
   const toolPermissions = [...toolScopes].sort((a, b) => a.localeCompare(b));

package/dist/cli.js

@@ -26,6 +26,9 @@ program.name("ms-365-mcp-server").description("Microsoft 365 MCP Server").versio
 ).option(
   "--allowed-scopes <scopes>",
   "Limit exposed tools to Graph scopes covered by this whitespace-separated allowlist"
+).option(
+  "--extra-scopes <scopes>",
+  "Append additional Graph scopes (whitespace-separated) to the token request, beyond those derived from enabled tools. Use with your own app registration (MS365_MCP_CLIENT_ID/SECRET) to request scopes the default app does not declare, then call the endpoints via graph-batch."
 ).option(
   "--preset <names>",
   "Use preset tool categories (comma-separated). Available: mail, calendar, files, personal, work, excel, contacts, tasks, onenote, search, users, all"
@@ -97,6 +100,15 @@ function parseArgs() {
     );
     process.exit(1);
   }
+  if (options.extraScopes === void 0 && process.env.MS365_MCP_EXTRA_SCOPES !== void 0) {
+    options.extraScopes = process.env.MS365_MCP_EXTRA_SCOPES;
+  }
+  if (options.extraScopes !== void 0 && options.extraScopes.trim() === "") {
+    console.error(
+      "Error: --extra-scopes / MS365_MCP_EXTRA_SCOPES was provided but is empty. Provide one or more whitespace-separated scopes, or omit it."
+    );
+    process.exit(1);
+  }
   if (options.expectedUsername === void 0 && process.env.MS365_MCP_EXPECTED_USERNAME !== void 0) {
     options.expectedUsername = process.env.MS365_MCP_EXPECTED_USERNAME;
   }

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); needs delegated Files.Read.All + Sites.Read.All (SharePoint/OneDrive) or ExternalItem.Read.All (Copilot connectors)."
+  },
   {
     "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

@@ -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) {
@@ -693,6 +606,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 +614,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
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softeria/ms-365-mcp-server",
-  "version": "0.121.0",
+  "version": "0.123.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); needs delegated Files.Read.All + Sites.Read.All (SharePoint/OneDrive) or ExternalItem.Read.All (Copilot connectors)."
+  },
   {
     "pathPattern": "/me/onlineMeetings",
     "method": "get",