@softeria/ms-365-mcp-server 0.119.0 → 0.120.1

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/bin/modules/simplified-openapi.mjs

@@ -508,6 +508,14 @@ function findUsedSchemas(openApiSpec) {
             );
             schemasToProcess.push(schemaName);
           }
+          // Trace refs nested anywhere in an inline request body (e.g. a property's
+          // anyOf: [{$ref}, {nullable object}]). Without this they're pruned as unused,
+          // then stripped as a "broken reference", degrading the body to a bare object.
+          if (content.schema) {
+            findRefsInObject(content.schema, (ref) =>
+              schemasToProcess.push(ref.replace('#/components/schemas/', ''))
+            );
+          }
         });
       }
 
@@ -547,6 +555,12 @@ function findUsedSchemas(openApiSpec) {
                   }
                 });
               }
+              // Trace refs nested anywhere in an inline response schema.
+              if (content.schema) {
+                findRefsInObject(content.schema, (ref) =>
+                  schemasToProcess.push(ref.replace('#/components/schemas/', ''))
+                );
+              }
             });
           }
         });

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/generated/client.js

@@ -825,6 +825,15 @@ const copy_drive_item_Body = z.object({
   childrenOnly: z.boolean().nullable().default(false),
   includeAllVersionHistory: z.boolean().nullable().default(false)
 }).partial().passthrough();
+const microsoft_graph_driveRecipient = z.object({
+  alias: z.string().describe(
+    "The alias of the domain object, for cases where an email address is unavailable (for example, security groups)."
+  ).nullish(),
+  email: z.string().describe(
+    "The email address for the recipient, if the recipient has an associated email address."
+  ).nullish(),
+  objectId: z.string().describe("The unique identifier for the recipient in the directory.").nullish()
+}).passthrough();
 const create_drive_item_share_link_Body = z.object({
   type: z.string().nullable(),
   scope: z.string().nullable(),
@@ -833,7 +842,7 @@ const create_drive_item_share_link_Body = z.object({
   ).datetime({ offset: true }).nullable(),
   password: z.string().nullable(),
   message: z.string().nullable(),
-  recipients: z.array(z.object({}).partial().passthrough()),
+  recipients: z.array(microsoft_graph_driveRecipient),
   retainInheritedPermissions: z.boolean().nullable().default(false),
   sendNotification: z.boolean().nullable().default(false)
 }).partial().passthrough();
@@ -917,7 +926,51 @@ const microsoft_graph_permission = z.object({
     "A unique token that can be used to access this shared item via the shares API. Read-only."
   ).nullish()
 }).passthrough();
-const create_upload_session_Body = z.object({ item: z.object({}).partial().passthrough() }).partial().passthrough();
+const microsoft_graph_driveItemSourceApplication = z.enum([
+  "teams",
+  "yammer",
+  "sharePoint",
+  "oneDrive",
+  "stream",
+  "powerPoint",
+  "office",
+  "loki",
+  "loop",
+  "other",
+  "unknownFutureValue"
+]);
+const microsoft_graph_driveItemSource = z.object({
+  application: microsoft_graph_driveItemSourceApplication.optional(),
+  externalId: z.string().describe("The external identifier for the drive item from the source.").nullish()
+}).passthrough();
+const microsoft_graph_mediaSourceContentCategory = z.enum([
+  "meeting",
+  "liveStream",
+  "presentation",
+  "screenRecording",
+  "story",
+  "profile",
+  "chat",
+  "note",
+  "comment",
+  "unknownFutureValue"
+]);
+const microsoft_graph_mediaSource = z.object({ contentCategory: microsoft_graph_mediaSourceContentCategory.optional() }).passthrough();
+const microsoft_graph_driveItemUploadableProperties = z.object({
+  description: z.string().describe(
+    "Provides a user-visible description of the item. Read-write. Only on OneDrive Personal."
+  ).nullish(),
+  driveItemSource: microsoft_graph_driveItemSource.optional(),
+  fileSize: z.number().describe(
+    "Provides an expected file size to perform a quota check before uploading. Only on OneDrive Personal."
+  ).nullish(),
+  fileSystemInfo: microsoft_graph_fileSystemInfo.optional(),
+  mediaSource: microsoft_graph_mediaSource.optional(),
+  name: z.string().describe("The name of the item (filename and extension). Read-write.").nullish()
+}).passthrough();
+const create_upload_session_Body = z.object({
+  item: z.union([microsoft_graph_driveItemUploadableProperties, z.object({}).partial().passthrough()])
+}).partial().passthrough();
 const microsoft_graph_uploadSession = z.object({
   expirationDateTime: z.string().regex(
     /^[0-9]{4,}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?(Z|[+-][0-9][0-9]:[0-9][0-9])$/
@@ -951,7 +1004,7 @@ const share_drive_item_Body = z.object({
   roles: z.array(z.string().nullable()),
   sendInvitation: z.boolean().nullable().default(false),
   message: z.string().nullable(),
-  recipients: z.array(z.object({}).partial().passthrough()),
+  recipients: z.array(microsoft_graph_driveRecipient),
   retainInheritedPermissions: z.boolean().nullable().default(false),
   expirationDateTime: z.string().nullable(),
   password: z.string().nullable()
@@ -3182,6 +3235,20 @@ const microsoft_graph_attachmentCollectionResponse = z.object({
   "@odata.nextLink": z.string().nullable(),
   value: z.array(microsoft_graph_attachment)
 }).partial().passthrough();
+const microsoft_graph_attachmentType = z.enum(["file", "item", "reference"]);
+const microsoft_graph_attachmentItem = z.object({
+  attachmentType: microsoft_graph_attachmentType.optional(),
+  contentId: z.string().describe(
+    "The CID or Content-Id of the attachment for referencing for the in-line attachments using the <img src='cid:contentId'> tag in HTML messages. Optional."
+  ).nullish(),
+  contentType: z.string().describe("The nature of the data in the attachment. Optional.").nullish(),
+  isInline: z.boolean().describe("true if the attachment is an inline attachment; otherwise, false. Optional.").nullish(),
+  name: z.string().describe(
+    "The display name of the attachment. This can be a descriptive string and doesn't have to be the actual file name. Required."
+  ).nullish(),
+  size: z.number().describe("The length of the attachment in bytes. Required.").nullish()
+}).passthrough();
+const create_mail_attachment_upload_session_Body = z.object({ AttachmentItem: microsoft_graph_attachmentItem }).partial().passthrough();
 const create_forward_draft_Body = z.object({
   ToRecipients: z.array(microsoft_graph_recipient),
   Message: z.union([microsoft_graph_message, z.object({}).partial().passthrough()]),
@@ -3875,13 +3942,27 @@ const microsoft_graph_userScopeTeamsAppInstallationCollectionResponse = z.object
   "@odata.nextLink": z.string().nullable(),
   value: z.array(microsoft_graph_userScopeTeamsAppInstallation)
 }).partial().passthrough();
+const microsoft_graph_teamworkActivityTopicSource = z.enum(["entityUrl", "text"]);
+const microsoft_graph_teamworkActivityTopic = z.object({
+  source: microsoft_graph_teamworkActivityTopicSource.optional(),
+  value: z.string().describe(
+    "The topic value. If the value of the source property is entityUrl, this must be a Microsoft Graph URL. If the value is text, this must be a plain text value."
+  ).optional(),
+  webUrl: z.string().describe(
+    "The link the user clicks when they select the notification. Optional when source is entityUrl; required when source is text."
+  ).nullish()
+}).passthrough();
+const microsoft_graph_keyValuePair = z.object({
+  name: z.string().describe("Name for this key-value pair").optional(),
+  value: z.string().describe("Value for this key-value pair").nullish()
+}).passthrough();
 const send_my_activity_notification_Body = z.object({
-  topic: z.object({}).partial().passthrough(),
+  topic: z.union([microsoft_graph_teamworkActivityTopic, z.object({}).partial().passthrough()]),
   activityType: z.string().nullable(),
   chainId: z.number().nullable(),
   previewText: z.union([microsoft_graph_itemBody, z.object({}).partial().passthrough()]),
   teamsAppId: z.string().nullable(),
-  templateParameters: z.array(z.object({}).partial().passthrough()),
+  templateParameters: z.array(microsoft_graph_keyValuePair),
   iconId: z.string().nullable()
 }).partial().passthrough();
 const microsoft_graph_wellknownListName = z.enum([
@@ -4762,6 +4843,7 @@ const schemas = {
   microsoft_graph_driveItem,
   microsoft_graph_driveItemCollectionResponse,
   copy_drive_item_Body,
+  microsoft_graph_driveRecipient,
   create_drive_item_share_link_Body,
   microsoft_graph_sharePointGroupIdentity,
   microsoft_graph_sharePointIdentity,
@@ -4769,6 +4851,11 @@ const schemas = {
   microsoft_graph_sharingInvitation,
   microsoft_graph_sharingLink,
   microsoft_graph_permission,
+  microsoft_graph_driveItemSourceApplication,
+  microsoft_graph_driveItemSource,
+  microsoft_graph_mediaSourceContentCategory,
+  microsoft_graph_mediaSource,
+  microsoft_graph_driveItemUploadableProperties,
   create_upload_session_Body,
   microsoft_graph_uploadSession,
   BaseDeltaFunctionResponse,
@@ -4993,6 +5080,9 @@ const schemas = {
   microsoft_graph_messageRuleCollectionResponse,
   microsoft_graph_messageCollectionResponse,
   microsoft_graph_attachmentCollectionResponse,
+  microsoft_graph_attachmentType,
+  microsoft_graph_attachmentItem,
+  create_mail_attachment_upload_session_Body,
   create_forward_draft_Body,
   create_reply_draft_Body,
   microsoft_graph_attendeeBase,
@@ -5070,6 +5160,9 @@ const schemas = {
   microsoft_graph_associatedTeamInfoCollectionResponse,
   microsoft_graph_userScopeTeamsAppInstallation,
   microsoft_graph_userScopeTeamsAppInstallationCollectionResponse,
+  microsoft_graph_teamworkActivityTopicSource,
+  microsoft_graph_teamworkActivityTopic,
+  microsoft_graph_keyValuePair,
   send_my_activity_notification_Body,
   microsoft_graph_wellknownListName,
   microsoft_graph_taskStatus,
@@ -10176,7 +10269,7 @@ resource.`,
         name: "body",
         description: `Action parameters`,
         type: "Body",
-        schema: z.object({ AttachmentItem: z.object({}).partial().passthrough() }).partial().passthrough()
+        schema: create_mail_attachment_upload_session_Body
       }
     ],
     response: z.void()

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.1",
   "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",