@softeria/ms-365-mcp-server 0.107.2 → 0.109.0

package/README.md

@@ -121,6 +121,35 @@ npx @softeria/ms-365-mcp-server --preset mail --list-permissions
 
 This is useful for enterprise environments where Graph API permissions must be pre-approved and admin-consented before deploying a new version.
 
+The `--list-permissions` JSON includes:
+
+- `toolPermissions`: permissions implied by the tool surface before `--allowed-scopes` filtering
+- `effectivePermissions`: permissions implied by the tools that remain enabled after `--allowed-scopes`
+- `permissions`: legacy alias for `effectivePermissions`, kept for compatibility with existing scripts
+- `allowedScopes`: the configured scope allowlist, when provided
+- `disabledTools`: tools hidden because their required Graph scopes are not covered by `allowedScopes`
+- `missingAllowedScopesForTools`: unique missing scopes across disabled tools
+- `extraAllowedScopesNotUsedByTools`: allowed scopes that are not used by the current tool surface
+
+### Allowed Scopes
+
+By default, MSAL requests the scopes implied by the enabled tools, and the tool surface is controlled by `--enabled-tools`, `--preset`, `--org-mode`, and `--read-only`.
+
+Enterprise and headless deployments can add a scope boundary with `--allowed-scopes` or `MS365_MCP_ALLOWED_SCOPES`. When configured, the server first computes the normal tool surface, then hides Graph tools whose required scopes are not covered by the allowlist. OAuth metadata and login flows request only the effective permissions for the tools that remain enabled.
+
+```bash
+npx @softeria/ms-365-mcp-server \
+  --org-mode \
+  --enabled-tools '^(list-mail-messages|get-mail-message|list-drives|get-drive-item|download-bytes)$' \
+  --allowed-scopes 'User.Read Mail.Read Files.Read'
+```
+
+CLI value takes precedence over `MS365_MCP_ALLOWED_SCOPES`; if neither is set, the default tool-derived scope behavior is unchanged. Supplying an empty value fails at startup so deployments do not accidentally fall back to a wider tool surface.
+
+Scope coverage is hierarchy-aware: for example, `Mail.ReadWrite` covers tools that require `Mail.Read`, and `Files.ReadWrite.All` covers tools that require `Files.Read`.
+
+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.
+
 ## Organization/Work Mode
 
 To access work/school features (Teams, SharePoint, etc.), enable organization mode using any of these flags:
@@ -469,11 +498,12 @@ The following options can be used when running ms-365-mcp-server directly from t
 --login           Login using device code flow
 --logout          Log out and clear saved credentials
 --verify-login    Verify login without starting the server
---list-permissions List all required Graph API permissions and exit (respects --org-mode, --preset, --enabled-tools)
+--list-permissions List required Graph API permissions and exit (respects --org-mode, --preset, --enabled-tools, --allowed-scopes)
 --org-mode        Enable organization/work mode from start (includes Teams, SharePoint, etc.)
 --work-mode       Alias for --org-mode
 --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
 ```
 
 ### Server Options

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

@@ -573,6 +573,104 @@ describe("graph-tools", () => {
       expect(payload.error).toMatch(/relative Microsoft Graph path/);
     });
   });
+  describe("allowed scopes filtering", () => {
+    it("registerGraphTools hides Graph tools outside the allowed scopes", async () => {
+      mockEndpoints.push(
+        {
+          alias: "list-mail-messages",
+          method: "get",
+          path: "/me/messages",
+          description: "List mail",
+          parameters: []
+        },
+        {
+          alias: "list-calendar-events",
+          method: "get",
+          path: "/me/events",
+          description: "List events",
+          parameters: []
+        }
+      );
+      mockEndpointsJson = [
+        {
+          toolName: "list-mail-messages",
+          method: "get",
+          pathPattern: "/me/messages",
+          scopes: ["Mail.Read"]
+        },
+        {
+          toolName: "list-calendar-events",
+          method: "get",
+          pathPattern: "/me/events",
+          scopes: ["Calendars.Read"]
+        }
+      ];
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(
+        server,
+        createMockGraphClient(),
+        false,
+        void 0,
+        false,
+        void 0,
+        false,
+        [],
+        "Mail.Read"
+      );
+      expect(server.tools.has("list-mail-messages")).toBe(true);
+      expect(server.tools.has("list-calendar-events")).toBe(false);
+    });
+    it("discovery hides Graph tools outside the allowed scopes", async () => {
+      mockEndpoints.push(
+        {
+          alias: "list-mail-messages",
+          method: "get",
+          path: "/me/messages",
+          description: "List mail",
+          parameters: []
+        },
+        {
+          alias: "list-calendar-events",
+          method: "get",
+          path: "/me/events",
+          description: "List events",
+          parameters: []
+        }
+      );
+      mockEndpointsJson = [
+        {
+          toolName: "list-mail-messages",
+          method: "get",
+          pathPattern: "/me/messages",
+          scopes: ["Mail.Read"]
+        },
+        {
+          toolName: "list-calendar-events",
+          method: "get",
+          pathPattern: "/me/events",
+          scopes: ["Calendars.Read"]
+        }
+      ];
+      const server = createMockServer();
+      const { registerDiscoveryTools } = await loadModule();
+      registerDiscoveryTools(
+        server,
+        {},
+        false,
+        false,
+        void 0,
+        false,
+        [],
+        void 0,
+        "Mail.Read"
+      );
+      const result = await server.tools.get("search-tools").handler({ limit: 50 });
+      const found = JSON.parse(result.content[0].text).tools.map((t) => t.name);
+      expect(found).toContain("list-mail-messages");
+      expect(found).not.toContain("list-calendar-events");
+    });
+  });
   describe("discovery mode: utility tools", () => {
     it('search-tools surfaces download-bytes for "download" queries', async () => {
       mockEndpoints.length = 0;

package/dist/auth.js

@@ -89,6 +89,34 @@ const SCOPE_HIERARCHY = {
   "Tasks.ReadWrite": ["Tasks.Read"],
   "Contacts.ReadWrite": ["Contacts.Read"]
 };
+function parseAllowedScopes(value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  return Array.from(new Set(value.trim().split(/\s+/).filter(Boolean)));
+}
+function getEndpointRequiredScopes(endpoint, includeWorkAccountScopes = false) {
+  if (!endpoint) {
+    return [];
+  }
+  const scopes = /* @__PURE__ */ new Set();
+  if (endpoint.scopes && Array.isArray(endpoint.scopes)) {
+    endpoint.scopes.forEach((scope) => scopes.add(scope));
+  }
+  if (includeWorkAccountScopes && endpoint.workScopes && Array.isArray(endpoint.workScopes)) {
+    endpoint.workScopes.forEach((scope) => scopes.add(scope));
+  }
+  return Array.from(scopes);
+}
+function collapseRedundantScopes(scopes) {
+  const scopesSet = new Set(scopes);
+  Object.entries(SCOPE_HIERARCHY).forEach(([higherScope, lowerScopes]) => {
+    if (scopesSet.has(higherScope) && lowerScopes.every((scope) => scopesSet.has(scope))) {
+      lowerScopes.forEach((scope) => scopesSet.delete(scope));
+    }
+  });
+  return Array.from(scopesSet);
+}
 function buildScopesFromEndpoints(includeWorkAccountScopes = false, enabledToolsPattern, readOnly = false) {
   const scopesSet = /* @__PURE__ */ new Set();
   let enabledToolsRegex;
@@ -104,7 +132,9 @@ function buildScopesFromEndpoints(includeWorkAccountScopes = false, enabledTools
   }
   endpoints.default.forEach((endpoint) => {
     if (readOnly && endpoint.method.toUpperCase() !== "GET") {
-      return;
+      if (!(endpoint.method.toUpperCase() === "POST" && endpoint.readOnly)) {
+        return;
+      }
     }
     if (enabledToolsRegex && !enabledToolsRegex.test(endpoint.toolName)) {
       return;
@@ -112,26 +142,153 @@ function buildScopesFromEndpoints(includeWorkAccountScopes = false, enabledTools
     if (!includeWorkAccountScopes && !endpoint.scopes && endpoint.workScopes) {
       return;
     }
-    if (endpoint.scopes && Array.isArray(endpoint.scopes)) {
-      endpoint.scopes.forEach((scope) => scopesSet.add(scope));
-    }
-    if (includeWorkAccountScopes && endpoint.workScopes && Array.isArray(endpoint.workScopes)) {
-      endpoint.workScopes.forEach((scope) => scopesSet.add(scope));
-    }
-  });
-  Object.entries(SCOPE_HIERARCHY).forEach(([higherScope, lowerScopes]) => {
-    if (scopesSet.has(higherScope) && lowerScopes.every((scope) => scopesSet.has(scope))) {
-      lowerScopes.forEach((scope) => scopesSet.delete(scope));
-    }
+    getEndpointRequiredScopes(endpoint, includeWorkAccountScopes).forEach(
+      (scope) => scopesSet.add(scope)
+    );
   });
-  const scopes = Array.from(scopesSet);
+  const scopes = collapseRedundantScopes(Array.from(scopesSet));
   if (enabledToolsPattern) {
     logger.info(`Built ${scopes.length} scopes for filtered tools: ${scopes.join(", ")}`);
   }
   return scopes;
 }
+function lowerScopesFor(scope) {
+  const lowerScopes = new Set(SCOPE_HIERARCHY[scope] ?? []);
+  if (scope.endsWith(".ReadWrite.All")) {
+    const readAllScope = scope.replace(/\.ReadWrite\.All$/, ".Read.All");
+    const readWriteScope = scope.replace(/\.ReadWrite\.All$/, ".ReadWrite");
+    const readScope = scope.replace(/\.ReadWrite\.All$/, ".Read");
+    lowerScopes.add(readAllScope);
+    lowerScopes.add(readWriteScope);
+    lowerScopes.add(readScope);
+  } else if (scope.endsWith(".ReadWrite.Shared")) {
+    lowerScopes.add(scope.replace(/\.ReadWrite\.Shared$/, ".Read.Shared"));
+  } else if (scope.endsWith(".ReadWrite")) {
+    lowerScopes.add(scope.replace(/\.ReadWrite$/, ".Read"));
+  } else if (scope.endsWith(".Read.All")) {
+    lowerScopes.add(scope.replace(/\.Read\.All$/, ".Read"));
+  }
+  return Array.from(lowerScopes);
+}
+function addImpliedScopes(scope, scopesSet) {
+  for (const lowerScope of lowerScopesFor(scope)) {
+    if (!scopesSet.has(lowerScope)) {
+      scopesSet.add(lowerScope);
+      addImpliedScopes(lowerScope, scopesSet);
+    }
+  }
+}
+function collapseScopeHierarchy(scopes) {
+  const scopesSet = new Set(scopes);
+  for (const scope of scopes) {
+    addImpliedScopes(scope, scopesSet);
+  }
+  return Array.from(scopesSet);
+}
+function getMissingAllowedScopes(requiredScopes, allowedScopes) {
+  if (allowedScopes === void 0) {
+    return [];
+  }
+  const coveredAllowedScopes = new Set(collapseScopeHierarchy(allowedScopes));
+  return requiredScopes.filter((scope) => !coveredAllowedScopes.has(scope));
+}
+function isScopeUsedByTools(allowedScope, toolScopes) {
+  const coveredByAllowedScope = new Set(collapseScopeHierarchy([allowedScope]));
+  return toolScopes.some((scope) => coveredByAllowedScope.has(scope));
+}
+function endpointMatchesNormalToolSurface(endpoint, includeWorkAccountScopes, enabledToolsRegex, readOnly = false) {
+  if (readOnly && endpoint.method.toUpperCase() !== "GET") {
+    if (!(endpoint.method.toUpperCase() === "POST" && endpoint.readOnly)) {
+      return false;
+    }
+  }
+  if (enabledToolsRegex && !enabledToolsRegex.test(endpoint.toolName)) {
+    return false;
+  }
+  if (!includeWorkAccountScopes && !endpoint.scopes && endpoint.workScopes) {
+    return false;
+  }
+  return true;
+}
+function buildAllowedScopeDiagnostics(options = {}) {
+  const allowedScopes = parseAllowedScopes(options.allowedScopes);
+  let enabledToolsRegex;
+  if (options.enabledTools) {
+    try {
+      enabledToolsRegex = new RegExp(options.enabledTools, "i");
+    } catch {
+      logger.error(
+        `Invalid tool filter regex pattern: ${options.enabledTools}. Building diagnostics without filter.`
+      );
+    }
+  }
+  const normalToolScopes = /* @__PURE__ */ new Set();
+  const effectiveToolScopes = /* @__PURE__ */ new Set();
+  const disabledTools = [];
+  for (const endpoint of endpoints.default) {
+    if (!endpointMatchesNormalToolSurface(
+      endpoint,
+      Boolean(options.orgMode),
+      enabledToolsRegex,
+      Boolean(options.readOnly)
+    )) {
+      continue;
+    }
+    const requiredScopes = getEndpointRequiredScopes(endpoint, Boolean(options.orgMode));
+    requiredScopes.forEach((scope) => normalToolScopes.add(scope));
+    const missingScopes = getMissingAllowedScopes(requiredScopes, allowedScopes);
+    if (missingScopes.length > 0) {
+      disabledTools.push({
+        toolName: endpoint.toolName,
+        requiredScopes: requiredScopes.sort((a, b) => a.localeCompare(b)),
+        missingScopes: missingScopes.sort((a, b) => a.localeCompare(b))
+      });
+      continue;
+    }
+    requiredScopes.forEach((scope) => effectiveToolScopes.add(scope));
+  }
+  const toolPermissions = collapseRedundantScopes(Array.from(normalToolScopes)).sort(
+    (a, b) => a.localeCompare(b)
+  );
+  const effectivePermissions = collapseRedundantScopes(Array.from(effectiveToolScopes)).sort(
+    (a, b) => a.localeCompare(b)
+  );
+  const sortedAllowedScopes = allowedScopes ? [...allowedScopes].sort((a, b) => a.localeCompare(b)) : void 0;
+  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)) ?? [];
+  return {
+    permissions: effectivePermissions,
+    toolPermissions,
+    effectivePermissions,
+    ...sortedAllowedScopes ? { allowedScopes: sortedAllowedScopes } : {},
+    disabledTools,
+    missingAllowedScopesForTools,
+    extraAllowedScopesNotUsedByTools
+  };
+}
+function resolveAuthScopes(options = {}) {
+  return buildAllowedScopeDiagnostics(options).effectivePermissions;
+}
+function buildScopeDiagnostics(toolScopes, allowedScopesInput) {
+  const toolPermissions = [...toolScopes].sort((a, b) => a.localeCompare(b));
+  const coveredAllowedScopes = new Set(collapseScopeHierarchy(allowedScopesInput));
+  const missingAllowedScopesForTools = toolPermissions.filter(
+    (scope) => !coveredAllowedScopes.has(scope)
+  );
+  return {
+    permissions: toolPermissions.filter((scope) => coveredAllowedScopes.has(scope)),
+    toolPermissions,
+    effectivePermissions: toolPermissions.filter((scope) => coveredAllowedScopes.has(scope)),
+    allowedScopes: [...allowedScopesInput].sort((a, b) => a.localeCompare(b)),
+    disabledTools: [],
+    missingAllowedScopesForTools,
+    extraAllowedScopesNotUsedByTools: [...allowedScopesInput].sort((a, b) => a.localeCompare(b)).filter((scope) => !isScopeUsedByTools(scope, toolPermissions))
+  };
+}
 class AuthManager {
-  constructor(config, scopes = buildScopesFromEndpoints()) {
+  constructor(config, scopes = []) {
     logger.info(`And scopes are ${scopes.join(", ")}`, scopes);
     this.config = config;
     this.scopes = scopes;
@@ -148,7 +305,7 @@ class AuthManager {
    * Creates an AuthManager instance with secrets loaded from the configured provider.
    * Uses Key Vault if MS365_MCP_KEYVAULT_URL is set, otherwise environment variables.
    */
-  static async create(scopes = buildScopesFromEndpoints()) {
+  static async create(scopes = []) {
     const secrets = await getSecrets();
     const config = createMsalConfig(secrets);
     return new AuthManager(config, scopes);
@@ -587,11 +744,18 @@ class AuthManager {
 }
 var auth_default = AuthManager;
 export {
+  buildAllowedScopeDiagnostics,
+  buildScopeDiagnostics,
   buildScopesFromEndpoints,
+  collapseScopeHierarchy,
   auth_default as default,
+  getEndpointRequiredScopes,
+  getMissingAllowedScopes,
   getSelectedAccountPath,
   getTokenCachePath,
+  parseAllowedScopes,
   pickNewest,
+  resolveAuthScopes,
   unwrapCache,
   wrapCache
 };

package/dist/cli.js

@@ -17,6 +17,9 @@ program.name("ms-365-mcp-server").description("Microsoft 365 MCP Server").versio
 ).option(
   "--enabled-tools <pattern>",
   'Filter tools using regex pattern (e.g., "excel|contact" to enable Excel and Contact tools)'
+).option(
+  "--allowed-scopes <scopes>",
+  "Limit exposed tools to Graph scopes covered by this whitespace-separated allowlist"
 ).option(
   "--preset <names>",
   "Use preset tool categories (comma-separated). Available: mail, calendar, files, personal, work, excel, contacts, tasks, onenote, search, users, all"
@@ -73,6 +76,15 @@ function parseArgs() {
   if (process.env.ENABLED_TOOLS) {
     options.enabledTools = process.env.ENABLED_TOOLS;
   }
+  if (options.allowedScopes === void 0 && process.env.MS365_MCP_ALLOWED_SCOPES !== void 0) {
+    options.allowedScopes = process.env.MS365_MCP_ALLOWED_SCOPES;
+  }
+  if (options.allowedScopes !== void 0 && options.allowedScopes.trim() === "") {
+    console.error(
+      "Error: --allowed-scopes / MS365_MCP_ALLOWED_SCOPES was provided but is empty. Provide one or more whitespace-separated scopes, or omit it to use tool-derived scopes."
+    );
+    process.exit(1);
+  }
   if (options.enabledTools) {
     try {
       new RegExp(options.enabledTools, "i");

package/dist/endpoints.json

@@ -620,7 +620,7 @@
     "isExcelOp": true,
     "scopes": ["Files.ReadWrite"],
     "skipEncoding": ["address"],
-    "llmTip": "Apply font/fill/borders/alignment/wrapText/columnWidth/rowHeight to a specific range. Required path param 'address' (e.g. 'A1:E5' or 'Sheet1!A1:E5'). Body: { font: {bold,color,size,italic,name,underline}, fill: {color}, borders: [{sideIndex,style,color,weight}], horizontalAlignment, verticalAlignment, wrapText, columnWidth, rowHeight }."
+    "llmTip": "Apply rangeFormat properties to a specific range. Required path param 'address' (e.g. 'A1:E5' or 'Sheet1!A1:E5'). Body: { horizontalAlignment, verticalAlignment, wrapText, columnWidth, rowHeight }. Note: font, fill, and borders are sub-resources on rangeFormat — set them via /format/font, /format/fill, and /format/borders/{sideIndex} respectively, not on this endpoint."
   },
   {
     "pathPattern": "/drives/{drive-id}/items/{driveItem-id}/workbook/worksheets/{workbookWorksheet-id}/range()/sort",
@@ -704,7 +704,7 @@
     "method": "get",
     "toolName": "get-excel-used-range",
     "isExcelOp": true,
-    "scopes": ["Files.Read"],
+    "scopes": ["Files.ReadWrite"],
     "llmTip": "Get the smallest range that encompasses any cells with values or formatting on the worksheet. Returns address, values, formulas, numberFormat, rowCount, columnCount. Use this to discover the populated bounds of a sheet before reading or appending — avoids guessing how far data extends. Optional $select to trim the response."
   },
   {

package/dist/graph-tools.js

@@ -1,4 +1,9 @@
 import logger from "./logger.js";
+import {
+  getEndpointRequiredScopes,
+  getMissingAllowedScopes,
+  parseAllowedScopes
+} from "./auth.js";
 import { api } from "./generated/client.js";
 import { z } from "zod";
 import { readFileSync } from "fs";
@@ -34,6 +39,11 @@ function clampTopQueryParam(queryParams) {
   logger.info(`Clamping $top from ${requested} to ${cap} (MS365_MCP_MAX_TOP)`);
   queryParams["$top"] = String(cap);
 }
+function formatDisabledToolsForLog(disabledTools) {
+  const shown = disabledTools.slice(0, 20).map((tool) => `${tool.toolName} (missing: ${tool.missingScopes.join(", ")})`);
+  const suffix = disabledTools.length > shown.length ? `, ... +${disabledTools.length - shown.length} more` : "";
+  return `${shown.join("; ")}${suffix}`;
+}
 const UTILITY_TOOLS = [
   {
     name: "parse-teams-url",
@@ -404,7 +414,7 @@ async function executeGraphTool(tool, config, graphClient, params, authManager)
     };
   }
 }
-function registerGraphTools(server, graphClient, readOnly = false, enabledToolsPattern, orgMode = false, authManager, multiAccount = false, accountNames = []) {
+function registerGraphTools(server, graphClient, readOnly = false, enabledToolsPattern, orgMode = false, authManager, multiAccount = false, accountNames = [], allowedScopesValue) {
   let enabledToolsRegex;
   if (enabledToolsPattern) {
     try {
@@ -417,6 +427,8 @@ function registerGraphTools(server, graphClient, readOnly = false, enabledToolsP
   let registeredCount = 0;
   let skippedCount = 0;
   let failedCount = 0;
+  const allowedScopes = parseAllowedScopes(allowedScopesValue);
+  const disabledByAllowedScopes = [];
   for (const tool of api.endpoints) {
     const endpointConfig = endpointsData.find((e) => e.toolName === tool.alias);
     if (!orgMode && endpointConfig && !endpointConfig.scopes && endpointConfig.workScopes) {
@@ -437,6 +449,13 @@ 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);
+    if (missingScopes.length > 0) {
+      disabledByAllowedScopes.push({ toolName: tool.alias, missingScopes });
+      skippedCount++;
+      continue;
+    }
     const paramSchema = {};
     if (tool.parameters && tool.parameters.length > 0) {
       for (const param of tool.parameters) {
@@ -536,6 +555,11 @@ function registerGraphTools(server, graphClient, readOnly = false, enabledToolsP
   if (multiAccount) {
     logger.info('Multi-account mode: "account" parameter injected into all tool schemas');
   }
+  if (disabledByAllowedScopes.length > 0) {
+    logger.info(
+      `Allowed scopes disabled ${disabledByAllowedScopes.length} Graph tools: ${formatDisabledToolsForLog(disabledByAllowedScopes)}`
+    );
+  }
   const utilityCtx = {
     graphClient,
     authManager,
@@ -558,8 +582,9 @@ function registerGraphTools(server, graphClient, readOnly = false, enabledToolsP
   );
   return registeredCount;
 }
-function buildToolsRegistry(readOnly, orgMode, enabledToolsRegex) {
+function buildToolsRegistry(readOnly, orgMode, enabledToolsRegex, allowedScopesValue, disabledByAllowedScopes = []) {
   const toolsMap = /* @__PURE__ */ new Map();
+  const allowedScopes = parseAllowedScopes(allowedScopesValue);
   for (const tool of api.endpoints) {
     const endpointConfig = endpointsData.find((e) => e.toolName === tool.alias);
     if (!orgMode && endpointConfig && !endpointConfig.scopes && endpointConfig.workScopes) {
@@ -574,6 +599,14 @@ function buildToolsRegistry(readOnly, orgMode, enabledToolsRegex) {
     if (enabledToolsRegex && !enabledToolsRegex.test(tool.alias)) {
       continue;
     }
+    const missingScopes = allowedScopes !== void 0 && !endpointConfig ? ["endpoint scope metadata"] : getMissingAllowedScopes(
+      getEndpointRequiredScopes(endpointConfig, orgMode),
+      allowedScopes
+    );
+    if (missingScopes.length > 0) {
+      disabledByAllowedScopes.push({ toolName: tool.alias, missingScopes });
+      continue;
+    }
     toolsMap.set(tool.alias, { tool, config: endpointConfig });
   }
   return toolsMap;
@@ -635,7 +668,7 @@ function scoreDiscoveryQuery(query, index) {
   ranked.sort((a, b) => b.score - a.score);
   return ranked;
 }
-function registerDiscoveryTools(server, graphClient, readOnly = false, orgMode = false, authManager, multiAccount = false, accountNames = [], enabledTools) {
+function registerDiscoveryTools(server, graphClient, readOnly = false, orgMode = false, authManager, multiAccount = false, accountNames = [], enabledTools, allowedScopesValue) {
   let enabledToolsRegex;
   if (enabledTools) {
     try {
@@ -647,7 +680,19 @@ function registerDiscoveryTools(server, graphClient, readOnly = false, orgMode =
       );
     }
   }
-  const toolsRegistry = buildToolsRegistry(readOnly, orgMode, enabledToolsRegex);
+  const disabledByAllowedScopes = [];
+  const toolsRegistry = buildToolsRegistry(
+    readOnly,
+    orgMode,
+    enabledToolsRegex,
+    allowedScopesValue,
+    disabledByAllowedScopes
+  );
+  if (disabledByAllowedScopes.length > 0) {
+    logger.info(
+      `Discovery mode: allowed scopes disabled ${disabledByAllowedScopes.length} Graph tools: ${formatDisabledToolsForLog(disabledByAllowedScopes)}`
+    );
+  }
   const utilityTools = UTILITY_TOOLS.filter((u) => {
     if (readOnly && !u.readOnlyHint) return false;
     if (enabledToolsRegex && !enabledToolsRegex.test(u.name)) return false;

package/dist/index.js

@@ -2,7 +2,7 @@
 import "dotenv/config";
 import { parseArgs } from "./cli.js";
 import logger from "./logger.js";
-import AuthManager, { buildScopesFromEndpoints } from "./auth.js";
+import AuthManager, { buildAllowedScopeDiagnostics, resolveAuthScopes } from "./auth.js";
 import MicrosoftGraphServer from "./server.js";
 import { version } from "./version.js";
 async function main() {
@@ -13,15 +13,31 @@ async function main() {
       logger.info("Organization mode enabled - including work account scopes");
     }
     const readOnly = args.readOnly || false;
-    const scopes = buildScopesFromEndpoints(includeWorkScopes, args.enabledTools, readOnly);
+    const effectiveScopes = resolveAuthScopes(args);
     if (args.listPermissions) {
-      const sorted = [...scopes].sort((a, b) => a.localeCompare(b));
+      const diagnostics = buildAllowedScopeDiagnostics(args);
       const mode = includeWorkScopes ? "org" : "personal";
       const filter = args.enabledTools ? args.enabledTools : void 0;
-      console.log(JSON.stringify({ mode, readOnly, filter, permissions: sorted }, null, 2));
+      if (diagnostics.disabledTools.length > 0) {
+        console.error(
+          `Warning: allowed scopes disabled ${diagnostics.disabledTools.length} tools. Missing scopes: ${diagnostics.missingAllowedScopesForTools.join(", ")}`
+        );
+      }
+      console.log(
+        JSON.stringify(
+          {
+            mode,
+            readOnly,
+            filter,
+            ...diagnostics
+          },
+          null,
+          2
+        )
+      );
       process.exit(0);
     }
-    const authManager = await AuthManager.create(scopes);
+    const authManager = await AuthManager.create(effectiveScopes);
     await authManager.loadTokenCache();
     if (args.authBrowser) {
       authManager.setUseInteractiveAuth(true);

package/dist/server.js

@@ -8,7 +8,11 @@ import { registerAuthTools } from "./auth-tools.js";
 import { registerGraphTools, registerDiscoveryTools } from "./graph-tools.js";
 import { buildMcpServerInstructions } from "./mcp-instructions.js";
 import GraphClient from "./graph-client.js";
-import { buildScopesFromEndpoints } from "./auth.js";
+import {
+  buildScopesFromEndpoints,
+  parseAllowedScopes,
+  resolveAuthScopes
+} from "./auth.js";
 import { MicrosoftOAuthProvider } from "./oauth-provider.js";
 import {
   exchangeCodeForToken,
@@ -77,7 +81,8 @@ class MicrosoftGraphServer {
         this.authManager,
         this.multiAccount,
         this.accountNames,
-        this.options.enabledTools
+        this.options.enabledTools,
+        this.options.allowedScopes
       );
     } else {
       registerGraphTools(
@@ -88,7 +93,8 @@ class MicrosoftGraphServer {
         this.options.orgMode,
         this.authManager,
         this.multiAccount,
-        this.accountNames
+        this.accountNames,
+        this.options.allowedScopes
       );
     }
     return server;
@@ -170,11 +176,7 @@ class MicrosoftGraphServer {
         const protocol = req.secure ? "https" : "http";
         const requestOrigin = `${protocol}://${req.get("host")}`;
         const browserBase = publicBase ?? requestOrigin;
-        const scopes = buildScopesFromEndpoints(
-          this.options.orgMode,
-          this.options.enabledTools,
-          this.options.readOnly
-        );
+        const scopes = resolveAuthScopes(this.options);
         const metadata = {
           issuer: browserBase,
           authorization_endpoint: `${browserBase}/authorize`,
@@ -195,11 +197,7 @@ class MicrosoftGraphServer {
         const protocol = req.secure ? "https" : "http";
         const requestOrigin = `${protocol}://${req.get("host")}`;
         const browserBase = publicBase ?? requestOrigin;
-        const scopes = this.options.obo ? [`api://${this.secrets.clientId}/access_as_user`] : buildScopesFromEndpoints(
-          this.options.orgMode,
-          this.options.enabledTools,
-          this.options.readOnly
-        );
+        const scopes = this.options.obo ? [`api://${this.secrets.clientId}/access_as_user`] : resolveAuthScopes(this.options);
         res.json({
           resource: `${requestOrigin}/mcp`,
           authorization_servers: [browserBase],
@@ -304,8 +302,9 @@ class MicrosoftGraphServer {
           }
         }
         microsoftAuthUrl.searchParams.set("client_id", clientId);
+        const explicitAllowedScopes = parseAllowedScopes(this.options.allowedScopes);
         const clientScope = microsoftAuthUrl.searchParams.get("scope");
-        const baseScopes = clientScope ? clientScope.split(/\s+/).filter(Boolean) : buildScopesFromEndpoints(
+        const baseScopes = explicitAllowedScopes !== void 0 ? resolveAuthScopes(this.options) : clientScope ? clientScope.split(/\s+/).filter(Boolean) : buildScopesFromEndpoints(
           this.options.orgMode,
           this.options.enabledTools,
           this.options.readOnly

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softeria/ms-365-mcp-server",
-  "version": "0.107.2",
+  "version": "0.109.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

@@ -620,7 +620,7 @@
     "isExcelOp": true,
     "scopes": ["Files.ReadWrite"],
     "skipEncoding": ["address"],
-    "llmTip": "Apply font/fill/borders/alignment/wrapText/columnWidth/rowHeight to a specific range. Required path param 'address' (e.g. 'A1:E5' or 'Sheet1!A1:E5'). Body: { font: {bold,color,size,italic,name,underline}, fill: {color}, borders: [{sideIndex,style,color,weight}], horizontalAlignment, verticalAlignment, wrapText, columnWidth, rowHeight }."
+    "llmTip": "Apply rangeFormat properties to a specific range. Required path param 'address' (e.g. 'A1:E5' or 'Sheet1!A1:E5'). Body: { horizontalAlignment, verticalAlignment, wrapText, columnWidth, rowHeight }. Note: font, fill, and borders are sub-resources on rangeFormat — set them via /format/font, /format/fill, and /format/borders/{sideIndex} respectively, not on this endpoint."
   },
   {
     "pathPattern": "/drives/{drive-id}/items/{driveItem-id}/workbook/worksheets/{workbookWorksheet-id}/range()/sort",
@@ -704,7 +704,7 @@
     "method": "get",
     "toolName": "get-excel-used-range",
     "isExcelOp": true,
-    "scopes": ["Files.Read"],
+    "scopes": ["Files.ReadWrite"],
     "llmTip": "Get the smallest range that encompasses any cells with values or formatting on the worksheet. Returns address, values, formulas, numberFormat, rowCount, columnCount. Use this to discover the populated bounds of a sheet before reading or appending — avoids guessing how far data extends. Optional $select to trim the response."
   },
   {