@softeria/ms-365-mcp-server 0.95.0 → 0.97.0

package/bin/modules/generate-mcp-tools.mjs

@@ -51,6 +51,13 @@ export function generateMcpTools(openApiSpec, outputDir) {
     // Replace with: path: `/...range(param=':value')...`,
     clientCode = clientCode.replace(/(path:\s*)'(\/[^']*\([^)]*=':[\w]+'\)[^']*)'/g, '$1`$2`');
 
+    // openapi-zod-client emits z.instanceof(File) for `format: binary` bodies; MCP
+    // transports JSON so no caller produces File. Body marshaller decodes the string.
+    clientCode = clientCode.replace(
+      /z\.instanceof\(File\)/g,
+      "z.string().describe('Base64-encoded file content. The server decodes it and PUTs the raw bytes to Microsoft Graph.')"
+    );
+
     fs.writeFileSync(clientFilePath, clientCode);
 
     return true;

package/bin/modules/simplified-openapi.mjs

@@ -8,24 +8,34 @@ export function createAndSaveSimplifiedOpenAPI(endpointsFile, openapiFile, opena
   const spec = fs.readFileSync(openapiFile, 'utf8');
   const openApiSpec = yaml.load(spec);
 
+  // Synthesize paths that the Graph REST API supports but are missing from
+  // Microsoft's published OpenAPI metadata (e.g. range(address='{address}')/format
+  // — documented in Excel API but not in the OpenAPI spec).
   for (const endpoint of endpoints) {
     if (!openApiSpec.paths[endpoint.pathPattern]) {
-      throw new Error(`Path "${endpoint.pathPattern}" not found in OpenAPI spec.`);
+      openApiSpec.paths[endpoint.pathPattern] = {};
     }
   }
 
-  // Synthesize operations that the Graph REST API supports but are missing from
-  // Microsoft's published OpenAPI metadata (e.g. PATCH on range(address='{address}')
-  // for cell-value writes — documented in Excel API but not in the OpenAPI spec).
+  // Synthesize operations on existing paths when the method is missing.
   for (const endpoint of endpoints) {
     const pathSpec = openApiSpec.paths[endpoint.pathPattern];
     const methodLower = endpoint.method.toLowerCase();
     if (pathSpec && !pathSpec[methodLower]) {
+      const pathParamMatches = [...endpoint.pathPattern.matchAll(/\{([^}]+)\}/g)].map((m) => m[1]);
+      const synthesizedParameters = pathParamMatches.map((paramName) => ({
+        name: paramName,
+        in: 'path',
+        required: true,
+        description: `Path parameter: ${paramName}`,
+        schema: { type: 'string' },
+      }));
       pathSpec[methodLower] = {
         tags: ['drives.driveItem'],
         summary: endpoint.llmTip || `${endpoint.toolName} (synthesized)`,
         description: endpoint.llmTip || `${endpoint.toolName} (synthesized)`,
         operationId: endpoint.toolName,
+        parameters: synthesizedParameters,
         requestBody:
           methodLower === 'get' || methodLower === 'delete'
             ? undefined

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

@@ -441,4 +441,206 @@ describe("graph-tools", () => {
       expect(prefer === void 0 || !prefer.includes("outlook.body-content-type")).toBe(true);
     });
   });
+  describe("binary upload bodies", () => {
+    it("decodes base64 body to bytes and sets octet-stream Content-Type", async () => {
+      const endpoint = makeEndpoint({
+        alias: "upload-file-content",
+        method: "put",
+        path: "/drives/:driveId/items/:driveItemId/content",
+        requestFormat: "binary",
+        parameters: [
+          { name: "driveId", type: "Path", schema: z.string() },
+          { name: "driveItemId", type: "Path", schema: z.string() },
+          {
+            name: "body",
+            type: "Body",
+            schema: z.string().describe("Base64-encoded file content")
+          }
+        ]
+      });
+      const config = makeConfig({
+        toolName: "upload-file-content",
+        method: "put",
+        pathPattern: "/drives/{drive-id}/items/{driveItem-id}/content",
+        scopes: ["Files.ReadWrite"]
+      });
+      mockEndpoints.push(endpoint);
+      mockEndpointsJson = [config];
+      const graphClient = createMockGraphClient([{ content: [{ type: "text", text: "{}" }] }]);
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, graphClient);
+      const original = "Hello, world!";
+      const base64 = Buffer.from(original, "utf-8").toString("base64");
+      await server.tools.get("upload-file-content").handler({
+        driveId: "drive123",
+        driveItemId: "item456",
+        body: base64
+      });
+      const [path, options] = graphClient.graphRequest.mock.calls[0];
+      expect(path).toBe("/drives/drive123/items/item456/content");
+      expect(options.headers["Content-Type"]).toBe("application/octet-stream");
+      expect(Buffer.isBuffer(options.body) || options.body instanceof Uint8Array).toBe(true);
+      expect(Buffer.from(options.body).toString("utf-8")).toBe(original);
+    });
+    it("honors endpoints.json contentType override on binary uploads", async () => {
+      const endpoint = makeEndpoint({
+        alias: "upload-file-content",
+        method: "put",
+        path: "/drives/:driveId/items/:driveItemId/content",
+        requestFormat: "binary",
+        parameters: [
+          { name: "driveId", type: "Path", schema: z.string() },
+          { name: "driveItemId", type: "Path", schema: z.string() },
+          { name: "body", type: "Body", schema: z.string() }
+        ]
+      });
+      const config = makeConfig({
+        toolName: "upload-file-content",
+        method: "put",
+        pathPattern: "/drives/{drive-id}/items/{driveItem-id}/content",
+        scopes: ["Files.ReadWrite"],
+        contentType: "application/pdf"
+      });
+      mockEndpoints.push(endpoint);
+      mockEndpointsJson = [config];
+      const graphClient = createMockGraphClient([{ content: [{ type: "text", text: "{}" }] }]);
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, graphClient);
+      await server.tools.get("upload-file-content").handler({
+        driveId: "d",
+        driveItemId: "i",
+        body: Buffer.from("%PDF-1.4").toString("base64")
+      });
+      const [, options] = graphClient.graphRequest.mock.calls[0];
+      expect(options.headers["Content-Type"]).toBe("application/pdf");
+    });
+  });
+  describe("download-bytes", () => {
+    it("routes a relative Graph path through graphRequest", async () => {
+      mockEndpoints.length = 0;
+      mockEndpointsJson = [];
+      const graphClient = {
+        graphRequest: vi.fn().mockResolvedValue({
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                contentType: "image/jpeg",
+                encoding: "base64",
+                contentBytes: "aGk="
+              })
+            }
+          ]
+        })
+      };
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, graphClient);
+      const tool = server.tools.get("download-bytes");
+      expect(tool).toBeDefined();
+      await tool.handler({ target: "/me/photo/$value" });
+      expect(graphClient.graphRequest).toHaveBeenCalledTimes(1);
+      const [path, options] = graphClient.graphRequest.mock.calls[0];
+      expect(path).toBe("/me/photo/$value");
+      expect(options.accessToken).toBeUndefined();
+    });
+    it("rejects absolute URLs (Graph paths only)", async () => {
+      mockEndpoints.length = 0;
+      mockEndpointsJson = [];
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, {});
+      const tool = server.tools.get("download-bytes");
+      const result = await tool.handler({
+        target: "https://example.sharepoint.com/d/abc?temp=signed"
+      });
+      expect(result.isError).toBe(true);
+      const payload = JSON.parse(result.content[0].text);
+      expect(payload.error).toMatch(/relative Microsoft Graph path/);
+    });
+    it("rejects targets that do not start with /", async () => {
+      mockEndpoints.length = 0;
+      mockEndpointsJson = [];
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, {});
+      const tool = server.tools.get("download-bytes");
+      const result = await tool.handler({ target: "ftp://example.com/x" });
+      expect(result.isError).toBe(true);
+      const payload = JSON.parse(result.content[0].text);
+      expect(payload.error).toMatch(/relative Microsoft Graph path/);
+    });
+  });
+  describe("discovery mode: utility tools", () => {
+    it('search-tools surfaces download-bytes for "download" queries', async () => {
+      mockEndpoints.length = 0;
+      mockEndpointsJson = [];
+      const server = createMockServer();
+      const { registerDiscoveryTools } = await loadModule();
+      registerDiscoveryTools(server, {});
+      const result = await server.tools.get("search-tools").handler({ query: "download" });
+      const payload = JSON.parse(result.content[0].text);
+      const names = payload.tools.map((t) => t.name);
+      expect(names).toContain("download-bytes");
+    });
+    it("get-tool-schema returns the download-bytes parameter schema", async () => {
+      mockEndpoints.length = 0;
+      mockEndpointsJson = [];
+      const server = createMockServer();
+      const { registerDiscoveryTools } = await loadModule();
+      registerDiscoveryTools(server, {});
+      const result = await server.tools.get("get-tool-schema").handler({ tool_name: "download-bytes" });
+      const schema = JSON.parse(result.content[0].text);
+      expect(schema.name).toBe("download-bytes");
+      expect(schema.path).toBe("tool:download-bytes");
+      const targetParam = schema.parameters.find((p) => p.name === "target");
+      expect(targetParam).toBeDefined();
+      expect(targetParam.required).toBe(true);
+    });
+    it("execute-tool dispatches to download-bytes for a Graph path", async () => {
+      mockEndpoints.length = 0;
+      mockEndpointsJson = [];
+      const graphClient = {
+        graphRequest: vi.fn().mockResolvedValue({
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                contentType: "image/png",
+                encoding: "base64",
+                contentBytes: "iVBORw0K"
+              })
+            }
+          ]
+        })
+      };
+      const server = createMockServer();
+      const { registerDiscoveryTools } = await loadModule();
+      registerDiscoveryTools(server, graphClient);
+      const result = await server.tools.get("execute-tool").handler({
+        tool_name: "download-bytes",
+        parameters: { target: "/me/photo/$value" }
+      });
+      expect(result.isError).toBeFalsy();
+      expect(graphClient.graphRequest).toHaveBeenCalledTimes(1);
+      const [path] = graphClient.graphRequest.mock.calls[0];
+      expect(path).toBe("/me/photo/$value");
+    });
+    it("execute-tool reports unknown tool when name matches neither registry", async () => {
+      mockEndpoints.length = 0;
+      mockEndpointsJson = [];
+      const server = createMockServer();
+      const { registerDiscoveryTools } = await loadModule();
+      registerDiscoveryTools(server, {});
+      const result = await server.tools.get("execute-tool").handler({
+        tool_name: "no-such-tool",
+        parameters: {}
+      });
+      expect(result.isError).toBe(true);
+      const payload = JSON.parse(result.content[0].text);
+      expect(payload.error).toMatch(/not found/i);
+    });
+  });
 });

package/dist/endpoints.json

@@ -1,4 +1,11 @@
 [
+  {
+    "pathPattern": "/$batch",
+    "method": "post",
+    "toolName": "graph-batch",
+    "scopes": [],
+    "llmTip": "Combine up to 20 Graph requests into a single HTTP call. Body: { requests: [{ id: '1', method: 'GET'|'POST'|'PATCH'|'DELETE', url: '/me/messages?$top=5', headers?: {...}, body?: {...}, dependsOn?: ['1'] }, ...] }. Returns { responses: [{ id, status, body, headers }] } in arbitrary order — match by id. Use cases: (1) parallelize many small reads (e.g. fetch 15 mail messages by id in one round-trip); (2) sequence dependent writes via dependsOn; (3) batch many Excel range writes into one call to dramatically reduce latency on large workbook builds. Note: each sub-request URL is relative to the Graph version root (/me/..., /drives/..., NOT https://graph.microsoft.com/v1.0/...)."
+  },
   {
     "pathPattern": "/me/messages",
     "method": "get",
@@ -144,13 +151,8 @@
     "pathPattern": "/me/messages/{message-id}/attachments",
     "method": "get",
     "toolName": "list-mail-attachments",
-    "scopes": ["Mail.Read"]
-  },
-  {
-    "pathPattern": "/me/messages/{message-id}/attachments/{attachment-id}",
-    "method": "get",
-    "toolName": "get-mail-attachment",
-    "scopes": ["Mail.Read"]
+    "scopes": ["Mail.Read"],
+    "llmTip": "Lists attachments on a message: id, name, contentType, size, isInline. To download the bytes, call download-bytes with target=/me/messages/{message-id}/attachments/{attachment-id}/$value (the /$value suffix returns raw bytes; the bare attachment URL embeds contentBytes in JSON which can truncate large files)."
   },
   {
     "pathPattern": "/me/messages/{message-id}/attachments/{attachment-id}",
@@ -472,14 +474,6 @@
     "toolName": "list-folder-files",
     "scopes": ["Files.Read"]
   },
-  {
-    "pathPattern": "/drives/{drive-id}/items/{driveItem-id}/content",
-    "method": "get",
-    "toolName": "download-onedrive-file-content",
-    "scopes": ["Files.Read"],
-    "returnDownloadUrl": true,
-    "llmTip": "Returns a temporary download URL, NOT the file content directly."
-  },
   {
     "pathPattern": "/drives/{drive-id}/items/{driveItem-id}",
     "method": "delete",
@@ -491,7 +485,7 @@
     "method": "put",
     "toolName": "upload-file-content",
     "scopes": ["Files.ReadWrite"],
-    "llmTip": "Max 4MB. For new files use path format: /items/root:/path/to/file.txt:/content. Overwrites existing files without warning."
+    "llmTip": "Body is a base64-encoded string of the file bytes; the server decodes it before PUT. Max 4MB inline (use create-upload-session above 4MB). For new files use path format: /items/root:/path/to/file.txt:/content. Overwrites existing files without warning."
   },
   {
     "pathPattern": "/drives/{drive-id}/items/{driveItem-id}/createUploadSession",
@@ -505,7 +499,7 @@
     "method": "get",
     "toolName": "get-drive-item",
     "scopes": ["Files.Read"],
-    "llmTip": "Gets metadata for a file or folder: name, size, lastModifiedDateTime, createdBy, webUrl, file (mimeType, hashes), folder (childCount), parentReference. Does not return content — use download-onedrive-file-content for that."
+    "llmTip": "Gets metadata for a file or folder: name, size, lastModifiedDateTime, createdBy, webUrl, file (mimeType, hashes), folder (childCount), parentReference, and @microsoft.graph.downloadUrl. For the bytes, call download-bytes with target=/drives/{drive-id}/items/{driveItem-id}/content (Graph redirects to the same downloadUrl)."
   },
   {
     "pathPattern": "/drives/{drive-id}/items/{driveItem-id}",
@@ -593,11 +587,13 @@
     "scopes": ["Files.ReadWrite"]
   },
   {
-    "pathPattern": "/drives/{drive-id}/items/{driveItem-id}/workbook/worksheets/{workbookWorksheet-id}/range()/format",
+    "pathPattern": "/drives/{drive-id}/items/{driveItem-id}/workbook/worksheets/{workbookWorksheet-id}/range(address='{address}')/format",
     "method": "patch",
     "toolName": "format-excel-range",
     "isExcelOp": true,
-    "scopes": ["Files.ReadWrite"]
+    "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 }."
   },
   {
     "pathPattern": "/drives/{drive-id}/items/{driveItem-id}/workbook/worksheets/{workbookWorksheet-id}/range()/sort",
@@ -614,6 +610,14 @@
     "scopes": ["Files.Read"],
     "skipEncoding": ["address"]
   },
+  {
+    "pathPattern": "/me/messages/{message-id}/$value",
+    "method": "get",
+    "toolName": "get-mail-message-mime",
+    "scopes": ["Mail.Read"],
+    "acceptType": "text/plain",
+    "llmTip": "Download an email message as raw RFC 5322 MIME content (.eml format). Use this when archiving an email to disk preserving all original headers, body, and inline-encoded attachments. Returns the MIME stream as text. Find the message id with list-mail-messages first."
+  },
   {
     "pathPattern": "/drives/{drive-id}/items/{driveItem-id}/workbook/worksheets/{workbookWorksheet-id}/range(address='{address}')",
     "method": "patch",
@@ -641,6 +645,41 @@
     "skipEncoding": ["address"],
     "llmTip": "Delete cells at the given range, shifting remaining content. Body: { shift: 'Up' } or { shift: 'Left' }. Use 'Up' to delete entire rows."
   },
+  {
+    "pathPattern": "/drives/{drive-id}/items/{driveItem-id}/workbook/worksheets/{workbookWorksheet-id}/range(address='{address}')/merge",
+    "method": "post",
+    "toolName": "merge-excel-range",
+    "isExcelOp": true,
+    "scopes": ["Files.ReadWrite"],
+    "skipEncoding": ["address"],
+    "llmTip": "Merge the cells in the given range into a single cell. Body: { across: false } merges the entire range into one cell; { across: true } merges each row separately. Useful for building styled headers, banner rows, and report layouts."
+  },
+  {
+    "pathPattern": "/drives/{drive-id}/items/{driveItem-id}/workbook/worksheets/{workbookWorksheet-id}/range(address='{address}')/unmerge",
+    "method": "post",
+    "toolName": "unmerge-excel-range",
+    "isExcelOp": true,
+    "scopes": ["Files.ReadWrite"],
+    "skipEncoding": ["address"],
+    "llmTip": "Unmerge any merged cells within the given range back into individual cells. No request body. Inverse of merge-excel-range."
+  },
+  {
+    "pathPattern": "/drives/{drive-id}/items/{driveItem-id}/workbook/worksheets/{workbookWorksheet-id}/range(address='{address}')/clear",
+    "method": "post",
+    "toolName": "clear-excel-range",
+    "isExcelOp": true,
+    "scopes": ["Files.ReadWrite"],
+    "skipEncoding": ["address"],
+    "llmTip": "Clear cell contents and/or formatting on the given range. Body: { applyTo: 'All' | 'Formats' | 'Contents' }. 'Contents' wipes values but keeps formatting; 'Formats' resets styling but keeps values; 'All' wipes both. Use this to reset a worksheet section before a fresh write rather than overwriting cell-by-cell."
+  },
+  {
+    "pathPattern": "/drives/{drive-id}/items/{driveItem-id}/workbook/worksheets/{workbookWorksheet-id}/usedRange()",
+    "method": "get",
+    "toolName": "get-excel-used-range",
+    "isExcelOp": true,
+    "scopes": ["Files.Read"],
+    "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."
+  },
   {
     "pathPattern": "/drives/{drive-id}/items/{driveItem-id}/workbook/tables/{workbookTable-id}/rows/itemAt(index={index})",
     "method": "patch",
@@ -1025,22 +1064,6 @@
     "workScopes": ["User.Read.All"],
     "llmTip": "Lists users who report directly to a specific user. Use with get-user-manager to traverse the org hierarchy."
   },
-  {
-    "pathPattern": "/me/photo/$value",
-    "method": "get",
-    "toolName": "get-my-profile-photo",
-    "scopes": ["User.Read"],
-    "returnDownloadUrl": true,
-    "llmTip": "Returns the current user's profile photo as binary image data. The photo is typically in JPEG format."
-  },
-  {
-    "pathPattern": "/users/{user-id}/photo/$value",
-    "method": "get",
-    "toolName": "get-user-profile-photo",
-    "workScopes": ["User.Read.All"],
-    "returnDownloadUrl": true,
-    "llmTip": "Returns a specific user's profile photo as binary image data. Use the user ID or UPN (email)."
-  },
   {
     "pathPattern": "/me/people",
     "method": "get",
@@ -1133,15 +1156,7 @@
     "method": "get",
     "toolName": "list-chat-message-hosted-contents",
     "workScopes": ["ChatMessage.Read"],
-    "llmTip": "Lists hosted-content references (inline images, code snippets) attached to a Teams chat message. Returns an array of { id, contentType }. Use get-chat-message-hosted-content with the id to download the bytes. Hosted content IDs can also be parsed from the <img src> URL in the message body between /hostedContents/ and /$value."
-  },
-  {
-    "pathPattern": "/chats/{chat-id}/messages/{chatMessage-id}/hostedContents/{chatMessageHostedContent-id}/$value",
-    "method": "get",
-    "toolName": "get-chat-message-hosted-content",
-    "workScopes": ["ChatMessage.Read"],
-    "returnDownloadUrl": true,
-    "llmTip": "Returns raw bytes of a hosted content item (typically image/png or image/jpeg) attached to a Teams 1:1 or group chat message. Use list-chat-message-hosted-contents to discover IDs, or extract the ID from the <img src> URL in the message body."
+    "llmTip": "Lists hosted-content references (inline images, code snippets) attached to a Teams chat message. Returns { id, contentType } per item. To download bytes, call download-bytes with target=/chats/{chat-id}/messages/{chatMessage-id}/hostedContents/{id}/$value. IDs can also be extracted from the <img src> URL in the message body between /hostedContents/ and /$value."
   },
   {
     "pathPattern": "/chats/{chat-id}/messages",
@@ -1209,15 +1224,7 @@
     "method": "get",
     "toolName": "list-channel-message-hosted-contents",
     "workScopes": ["ChannelMessage.Read.All"],
-    "llmTip": "Lists hosted-content references (inline images, code snippets) attached to a Teams channel message. Returns an array of { id, contentType }. Use get-channel-message-hosted-content with the id to download bytes."
-  },
-  {
-    "pathPattern": "/teams/{team-id}/channels/{channel-id}/messages/{chatMessage-id}/hostedContents/{chatMessageHostedContent-id}/$value",
-    "method": "get",
-    "toolName": "get-channel-message-hosted-content",
-    "workScopes": ["ChannelMessage.Read.All"],
-    "returnDownloadUrl": true,
-    "llmTip": "Returns raw bytes of a hosted content item attached to a Teams channel message. Use list-channel-message-hosted-contents to discover IDs."
+    "llmTip": "Lists hosted-content references (inline images, code snippets) attached to a Teams channel message. Returns { id, contentType } per item. To download bytes, call download-bytes with target=/teams/{team-id}/channels/{channel-id}/messages/{chatMessage-id}/hostedContents/{id}/$value."
   },
   {
     "pathPattern": "/teams/{team-id}/channels/{channel-id}/messages",