@softeria/ms-365-mcp-server 0.119.0 → 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/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/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.119.0",
+  "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",