@softeria/ms-365-mcp-server 0.118.2 → 0.120.0

package/README.md

@@ -285,7 +285,7 @@ Open WebUI supports MCP servers via HTTP transport with OAuth 2.1.
 
 3. Click **Register Client**.
 
-> **Note**: Dynamic client registration is enabled by default in HTTP mode. Use `--no-dynamic-registration` to disable it. If using a custom Azure Entra app, add your redirect URI under "Mobile and desktop applications" platform (not "Single-page application").
+> **Note**: Dynamic client registration is enabled by default in HTTP mode. Use `--no-dynamic-registration` to disable it. If using a custom Azure Entra app, the platform type for your redirect URI depends on whether the app has a client secret: with a secret use "Web", without one use "Mobile and desktop applications" (never "Single-page application").
 
 **Quick test setup** using the default Azure app (ID `ms-365` and `localhost:8080` are pre-configured):
 

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

@@ -914,4 +914,118 @@ 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/cli.js

@@ -50,6 +50,9 @@ program.name("ms-365-mcp-server").description("Microsoft 365 MCP Server").versio
 ).option(
   "--trust-proxy-auth",
   "In HTTP mode, skip the built-in Bearer-token check on /mcp and ignore any forwarded Authorization header. All callers share the locally cached MSAL identity (same path stdio mode uses). Use only when an upstream reverse proxy has already authenticated the caller."
+).option(
+  "--allow-unauthenticated-discovery",
+  "In HTTP mode, allow MCP discovery requests (initialize, tools/list, prompts/list, resources/list, ping) without a bearer token, so a gateway can enumerate the tool catalog before any user has authenticated. Non-discovery requests (e.g. tools/call) still require a token. Off by default."
 ).addOption(
   // DEPRECATED: kept only so existing deployments that set --base-url or
   // MS365_MCP_BASE_URL do not crash at startup. Use --public-url /
@@ -155,6 +158,9 @@ function parseArgs() {
   if (process.env.MS365_MCP_TRUST_PROXY_AUTH === "true" || process.env.MS365_MCP_TRUST_PROXY_AUTH === "1") {
     options.trustProxyAuth = true;
   }
+  if (process.env.MS365_MCP_ALLOW_UNAUTHENTICATED_DISCOVERY === "true" || process.env.MS365_MCP_ALLOW_UNAUTHENTICATED_DISCOVERY === "1") {
+    options.allowUnauthenticatedDiscovery = true;
+  }
   if (options.cloud) {
     process.env.MS365_MCP_CLOUD_TYPE = options.cloud;
   }

package/dist/graph-tools.js

@@ -169,6 +169,93 @@ 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) {

package/dist/lib/microsoft-auth.js

@@ -17,6 +17,22 @@ function isJwtExpired(token) {
     return false;
   }
 }
+const DISCOVERY_METHODS = /* @__PURE__ */ new Set([
+  "initialize",
+  "notifications/initialized",
+  "tools/list",
+  "prompts/list",
+  "resources/list",
+  "ping"
+]);
+function isDiscoveryRequest(req) {
+  if (req.method !== "POST" || !req.body) return false;
+  const body = req.body;
+  if (Array.isArray(body)) {
+    return body.every((item) => DISCOVERY_METHODS.has(item?.method));
+  }
+  return DISCOVERY_METHODS.has(body?.method);
+}
 const microsoftBearerTokenAuthMiddleware = (opts = {}) => (req, res, next) => {
   if (opts.trustProxyAuth) {
     next();
@@ -24,6 +40,10 @@ const microsoftBearerTokenAuthMiddleware = (opts = {}) => (req, res, next) => {
   }
   const authHeader = req.headers.authorization;
   if (!authHeader || !authHeader.startsWith("Bearer ")) {
+    if (opts.allowUnauthenticatedDiscovery && isDiscoveryRequest(req)) {
+      next();
+      return;
+    }
     res.status(401).set(
       "WWW-Authenticate",
       buildWwwAuthenticate(req, "invalid_token", "Missing or malformed Authorization header")

package/dist/server.js

@@ -469,7 +469,8 @@ class MicrosoftGraphServer {
         })
       );
       const mcpAuth = microsoftBearerTokenAuthMiddleware({
-        trustProxyAuth: this.options.trustProxyAuth
+        trustProxyAuth: this.options.trustProxyAuth,
+        allowUnauthenticatedDiscovery: this.options.allowUnauthenticatedDiscovery
       });
       app.get(
         "/mcp",

package/docs/deployment.md

@@ -127,7 +127,7 @@ When deploying for an organization, create a dedicated app registration instead
      - Claude (claude.ai, Desktop, Cowork): `https://claude.ai/api/mcp/auth_callback`
      - Other clients: check the `redirect_uri` query parameter your client sends to the server's `/authorize` endpoint (visible in the server logs)
 
-   > **Common pitfall**: registering `https://your-server-domain/callback` here breaks sign-in with `AADSTS50011` (redirect URI mismatch) after the user authenticates. The server has no callback endpoint of its own; the authorization code always goes to the MCP client.
+   > **Common pitfall**: registering `https://your-server-domain/callback` here breaks sign-in with `AADSTS50011` (redirect URI mismatch) after the user authenticates. The server has no callback endpoint of its own; the authorization code always goes to the MCP client. Note that platform type **Web** applies because this setup uses a client secret; an app without a secret must register the redirect URI under "Mobile and desktop applications" instead.
 
 2. **Add API permissions** > Microsoft Graph > Delegated permissions
    Run `npx @softeria/ms-365-mcp-server --org-mode --list-permissions` to print the exact list of permissions required for your enabled tools.

package/package.json

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