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

package/dist/graph-tools.js

@@ -8,7 +8,7 @@ import { TOOL_CATEGORIES } from "./tool-categories.js";
 import { getRequestTokens } from "./request-context.js";
 import { parseTeamsUrl } from "./lib/teams-url-parser.js";
 import { buildBM25Index, scoreQuery, tokenize } from "./lib/bm25.js";
-import { describeToolSchema } from "./lib/tool-schema.js";
+import { describeToolSchema, describeUtilityToolSchema } from "./lib/tool-schema.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const endpointsData = JSON.parse(
@@ -34,6 +34,111 @@ function clampTopQueryParam(queryParams) {
   logger.info(`Clamping $top from ${requested} to ${cap} (MS365_MCP_MAX_TOP)`);
   queryParams["$top"] = String(cap);
 }
+const UTILITY_TOOLS = [
+  {
+    name: "parse-teams-url",
+    method: "POST",
+    path: "tool:parse-teams-url",
+    description: "Converts any Teams meeting URL format (short /meet/, full /meetup-join/, or recap ?threadId=) into a standard joinWebUrl. Use this before list-online-meetings when the user provides a recap or short URL.",
+    readOnlyHint: true,
+    openWorldHint: false,
+    buildSchema: () => ({
+      url: z.string().describe("Teams meeting URL in any format")
+    }),
+    execute: async (params) => {
+      const url = params.url;
+      if (typeof url !== "string") {
+        return {
+          content: [{ type: "text", text: JSON.stringify({ error: "url is required." }) }],
+          isError: true
+        };
+      }
+      try {
+        const joinWebUrl = parseTeamsUrl(url);
+        return { content: [{ type: "text", text: joinWebUrl }] };
+      } catch (error) {
+        return {
+          content: [{ type: "text", text: JSON.stringify({ error: error.message }) }],
+          isError: true
+        };
+      }
+    }
+  },
+  {
+    name: "download-bytes",
+    method: "GET",
+    path: "tool:download-bytes",
+    description: 'Download binary content from Microsoft Graph and return it as base64. Single tool for any binary read: drive file content, mail attachment, profile photo, Teams hosted content, meeting recording. Returns { contentType, encoding: "base64", contentLength, contentBytes }.',
+    readOnlyHint: true,
+    openWorldHint: true,
+    buildSchema: (ctx) => {
+      const schema = {
+        target: z.string().describe(
+          'Relative Microsoft Graph path starting with "/". Common paths: /drives/{drive-id}/items/{driveItem-id}/content (drive file content); /me/messages/{message-id}/attachments/{attachment-id}/$value (mail attachment, list-mail-attachments returns the IDs); /me/photo/$value or /users/{user-id}/photo/$value (profile photo); /chats/{chat-id}/messages/{chatMessage-id}/hostedContents/{chatMessageHostedContent-id}/$value (Teams chat hosted content, list-chat-message-hosted-contents returns the IDs); /teams/{team-id}/channels/{channel-id}/messages/{chatMessage-id}/hostedContents/{chatMessageHostedContent-id}/$value (Teams channel hosted content). For meeting recordings (often large), use get-meeting-recording-content which returns a URL for out-of-band download by the client.'
+        )
+      };
+      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 target = params.target;
+      const accountParam = params.account;
+      if (typeof target !== "string" || target.length === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ error: "target is required and must be a non-empty string." })
+            }
+          ],
+          isError: true
+        };
+      }
+      if (!target.startsWith("/")) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                error: 'target must be a relative Microsoft Graph path starting with "/", e.g. /me/photo/$value or /drives/{drive-id}/items/{driveItem-id}/content. Absolute URLs are not accepted; if you have an @microsoft.graph.downloadUrl, use the equivalent /content or /$value path instead (Graph 302-redirects to the same bytes).'
+              })
+            }
+          ],
+          isError: true
+        };
+      }
+      try {
+        let accountAccessToken;
+        if (authManager && !authManager.isOAuthModeEnabled() && !getRequestTokens()) {
+          accountAccessToken = await authManager.getTokenForAccount(accountParam);
+        }
+        return await graphClient.graphRequest(target, { accessToken: accountAccessToken });
+      } catch (error) {
+        return {
+          content: [{ type: "text", text: JSON.stringify({ error: error.message }) }],
+          isError: true
+        };
+      }
+    }
+  }
+];
+function registerUtilityToolWithMcp(server, utility, ctx) {
+  server.tool(
+    utility.name,
+    utility.description,
+    utility.buildSchema(ctx),
+    {
+      title: utility.name,
+      readOnlyHint: utility.readOnlyHint ?? true,
+      openWorldHint: utility.openWorldHint ?? true
+    },
+    async (params) => utility.execute(params, ctx)
+  );
+}
 async function executeGraphTool(tool, config, graphClient, params, authManager) {
   logger.info(`Tool ${tool.alias} called with params: ${JSON.stringify(params)}`);
   try {
@@ -174,7 +279,12 @@ async function executeGraphTool(tool, config, graphClient, params, authManager)
       headers
     };
     if (options.method !== "GET" && body) {
-      if (config?.contentType === "text/html") {
+      if (tool.requestFormat === "binary" && typeof body === "string") {
+        options.body = Buffer.from(body, "base64");
+        if (!config?.contentType) {
+          headers["Content-Type"] = "application/octet-stream";
+        }
+      } else if (config?.contentType === "text/html") {
         if (typeof body === "string") {
           options.body = body;
         } else if (typeof body === "object" && "content" in body) {
@@ -426,36 +536,19 @@ function registerGraphTools(server, graphClient, readOnly = false, enabledToolsP
   if (multiAccount) {
     logger.info('Multi-account mode: "account" parameter injected into all tool schemas');
   }
-  if (!enabledToolsRegex || enabledToolsRegex.test("parse-teams-url")) {
+  const utilityCtx = {
+    graphClient,
+    authManager,
+    multiAccount,
+    accountNames
+  };
+  for (const utility of UTILITY_TOOLS) {
+    if (enabledToolsRegex && !enabledToolsRegex.test(utility.name)) continue;
     try {
-      server.tool(
-        "parse-teams-url",
-        "Converts any Teams meeting URL format (short /meet/, full /meetup-join/, or recap ?threadId=) into a standard joinWebUrl. Use this before list-online-meetings when the user provides a recap or short URL.",
-        {
-          url: z.string().describe("Teams meeting URL in any format")
-        },
-        {
-          title: "parse-teams-url",
-          readOnlyHint: true,
-          openWorldHint: false
-        },
-        async ({ url }) => {
-          try {
-            const joinWebUrl = parseTeamsUrl(url);
-            return { content: [{ type: "text", text: joinWebUrl }] };
-          } catch (error) {
-            return {
-              content: [
-                { type: "text", text: JSON.stringify({ error: error.message }) }
-              ],
-              isError: true
-            };
-          }
-        }
-      );
+      registerUtilityToolWithMcp(server, utility, utilityCtx);
       registeredCount++;
     } catch (error) {
-      logger.error(`Failed to register tool parse-teams-url: ${error.message}`);
+      logger.error(`Failed to register tool ${utility.name}: ${error.message}`);
       failedCount++;
     }
   }
@@ -481,7 +574,7 @@ function buildToolsRegistry(readOnly, orgMode) {
   }
   return toolsMap;
 }
-function buildDiscoverySearchIndex(toolsRegistry) {
+function buildDiscoverySearchIndex(toolsRegistry, utilityTools = []) {
   const TIP_EXCERPT_TOKENS = 12;
   const DESC_CAP_TOKENS = 40;
   const docs = [];
@@ -505,6 +598,14 @@ function buildDiscoverySearchIndex(toolsRegistry) {
     ];
     docs.push({ id: name, tokens });
   }
+  for (const utility of utilityTools) {
+    const nt = tokenize(utility.name);
+    nameTokens.set(utility.name, new Set(nt));
+    const pathTokens = tokenize(utility.path);
+    const descTokens = tokenize(utility.description).slice(0, DESC_CAP_TOKENS);
+    const tokens = [...nt, ...nt, ...nt, ...nt, ...nt, ...pathTokens, ...pathTokens, ...descTokens];
+    docs.push({ id: utility.name, tokens });
+  }
   return { bm25: buildBM25Index(docs), nameTokens };
 }
 function scoreDiscoveryQuery(query, index) {
@@ -530,29 +631,51 @@ 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) {
+function registerDiscoveryTools(server, graphClient, readOnly = false, orgMode = false, authManager, multiAccount = false, accountNames = []) {
   const toolsRegistry = buildToolsRegistry(readOnly, orgMode);
-  const searchIndex = buildDiscoverySearchIndex(toolsRegistry);
-  logger.info(`Discovery mode: ${toolsRegistry.size} tools available in registry`);
+  const utilityTools = UTILITY_TOOLS;
+  const searchIndex = buildDiscoverySearchIndex(toolsRegistry, utilityTools);
+  const totalCount = toolsRegistry.size + utilityTools.length;
+  logger.info(
+    `Discovery mode: ${totalCount} tools (${toolsRegistry.size} Graph + ${utilityTools.length} utility)`
+  );
+  const utilityCtx = {
+    graphClient,
+    authManager,
+    multiAccount,
+    accountNames
+  };
+  const utilityByName = new Map(utilityTools.map((u) => [u.name, u]));
   const categoryNames = Object.keys(TOOL_CATEGORIES).join(", ");
   const toResultEntry = (name) => {
     const entry = toolsRegistry.get(name);
-    if (!entry) return null;
-    const { tool, config } = entry;
-    return {
-      name,
-      method: tool.method.toUpperCase(),
-      path: tool.path,
-      description: tool.description || `${tool.method.toUpperCase()} ${tool.path}`,
-      ...config?.llmTip ? { llmTip: config.llmTip } : {}
-    };
+    if (entry) {
+      const { tool, config } = entry;
+      return {
+        name,
+        method: tool.method.toUpperCase(),
+        path: tool.path,
+        description: tool.description || `${tool.method.toUpperCase()} ${tool.path}`,
+        ...config?.llmTip ? { llmTip: config.llmTip } : {}
+      };
+    }
+    const utility = utilityByName.get(name);
+    if (utility) {
+      return {
+        name: utility.name,
+        method: utility.method,
+        path: utility.path,
+        description: utility.description
+      };
+    }
+    return null;
   };
   server.tool(
     "search-tools",
-    `Search through ${toolsRegistry.size} Microsoft Graph API tools. Ranks results by BM25 over tool name, llmTip, description, and path (tokenized on hyphens, camelCase, and whitespace). After picking a tool, call get-tool-schema to see its parameters, then execute-tool to invoke it.`,
+    `Search through ${totalCount} tools (${toolsRegistry.size} Microsoft Graph API operations + ${utilityTools.length} server utilities like download-bytes). Ranks results by BM25 over tool name, llmTip, description, and path. After picking a tool, call get-tool-schema for parameters, then execute-tool.`,
     {
       query: z.string().describe(
-        'Natural-language query. Tokenized and BM25-ranked. E.g. "send email", "create calendar event", "list unread messages".'
+        'Natural-language query. Tokenized and BM25-ranked. E.g. "send email", "download photo", "list unread messages".'
       ).optional(),
       category: z.string().describe(`Optional pre-filter by category: ${categoryNames}`).optional(),
       limit: z.number().describe("Maximum results (default: 10, max: 50)").optional()
@@ -571,7 +694,9 @@ function registerDiscoveryTools(server, graphClient, readOnly = false, orgMode =
         const ranked = scoreDiscoveryQuery(query, searchIndex);
         orderedNames = ranked.map((r) => r.id).filter(categoryFilter);
       } else {
-        orderedNames = [...toolsRegistry.keys()].filter(categoryFilter);
+        orderedNames = [...toolsRegistry.keys(), ...utilityTools.map((u) => u.name)].filter(
+          categoryFilter
+        );
       }
       const tools = orderedNames.slice(0, maxLimit).map(toResultEntry).filter(Boolean);
       return {
@@ -581,7 +706,7 @@ function registerDiscoveryTools(server, graphClient, readOnly = false, orgMode =
             text: JSON.stringify(
               {
                 found: tools.length,
-                total: toolsRegistry.size,
+                total: totalCount,
                 tools,
                 tip: "Call get-tool-schema(tool_name) to see parameters before invoking execute-tool."
               },
@@ -606,23 +731,30 @@ function registerDiscoveryTools(server, graphClient, readOnly = false, orgMode =
     },
     async ({ tool_name }) => {
       const entry = toolsRegistry.get(tool_name);
-      if (!entry) {
+      if (entry) {
+        const schema = describeToolSchema(entry.tool, entry.config?.llmTip);
         return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify({
-                error: `Tool not found: ${tool_name}`,
-                tip: "Use search-tools to find available tools."
-              })
-            }
-          ],
-          isError: true
+          content: [{ type: "text", text: JSON.stringify(schema, null, 2) }]
+        };
+      }
+      const utility = utilityByName.get(tool_name);
+      if (utility) {
+        const schema = describeUtilityToolSchema(utility, utilityCtx);
+        return {
+          content: [{ type: "text", text: JSON.stringify(schema, null, 2) }]
         };
       }
-      const schema = describeToolSchema(entry.tool, entry.config?.llmTip);
       return {
-        content: [{ type: "text", text: JSON.stringify(schema, null, 2) }]
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              error: `Tool not found: ${tool_name}`,
+              tip: "Use search-tools to find available tools."
+            })
+          }
+        ],
+        isError: true
       };
     }
   );
@@ -643,25 +775,36 @@ function registerDiscoveryTools(server, graphClient, readOnly = false, orgMode =
     },
     async ({ tool_name, parameters = {} }) => {
       const toolData = toolsRegistry.get(tool_name);
-      if (!toolData) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify({
-                error: `Tool not found: ${tool_name}`,
-                tip: "Use search-tools to find available tools."
-              })
-            }
-          ],
-          isError: true
-        };
+      if (toolData) {
+        return executeGraphTool(
+          toolData.tool,
+          toolData.config,
+          graphClient,
+          parameters,
+          authManager
+        );
+      }
+      const utility = utilityByName.get(tool_name);
+      if (utility) {
+        return utility.execute(parameters, utilityCtx);
       }
-      return executeGraphTool(toolData.tool, toolData.config, graphClient, parameters, authManager);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              error: `Tool not found: ${tool_name}`,
+              tip: "Use search-tools to find available tools."
+            })
+          }
+        ],
+        isError: true
+      };
     }
   );
 }
 export {
+  UTILITY_TOOLS,
   buildDiscoverySearchIndex,
   buildToolsRegistry,
   registerDiscoveryTools,

package/dist/lib/tool-schema.js

@@ -30,6 +30,29 @@ function describeToolSchema(tool, llmTip) {
     parameters: params
   };
 }
+function describeUtilityToolSchema(utility, ctx) {
+  const schemaMap = utility.buildSchema(ctx);
+  const params = Object.entries(schemaMap).map(([name, zodSchema]) => {
+    const { inner, optional } = unwrapOptional(zodSchema);
+    const jsonSchema = zodToJsonSchema(inner, { target: "jsonSchema7", $refStrategy: "none" });
+    const { $schema: _s, ...schema } = jsonSchema;
+    return {
+      name,
+      in: "Query",
+      required: !optional,
+      description: zodSchema.description,
+      schema
+    };
+  });
+  return {
+    name: utility.name,
+    method: utility.method,
+    path: utility.path,
+    description: utility.description,
+    parameters: params
+  };
+}
 export {
-  describeToolSchema
+  describeToolSchema,
+  describeUtilityToolSchema
 };

package/dist/mcp-instructions.js

@@ -5,7 +5,8 @@ function buildGeneralMcpInstructions(opts) {
     "Mail and message $search uses KQL; the $search query parameter value must be double-quoted per Graph (see search-query-parameter in Microsoft Graph docs).",
     "When you need an organizational user or recipient address, resolve it with list-users (or another directory tool); do not invent SMTP addresses.",
     "Directory $search on collections such as /users or /groups requires ConsistencyLevel: eventual when the tool exposes that header.",
-    "Teams chat and channel messages: prefer HTML contentType in the body; plain text is often mangled by Graph."
+    "Teams chat and channel messages: prefer HTML contentType in the body; plain text is often mangled by Graph.",
+    "Files / binary content: use download-bytes for any binary read (drive file content, mail attachments, profile photos, Teams hosted content, meeting recordings); pass it a Graph path or an absolute @microsoft.graph.downloadUrl from a metadata response. For uploads, upload-file-content takes a base64 string body up to 4MB; use create-upload-session above that."
   ];
   if (opts.readOnly) parts.push("This server is read-only; write operations are disabled.");
   if (opts.multiAccount)

package/dist/server.js

@@ -74,7 +74,8 @@ class MicrosoftGraphServer {
         this.options.readOnly,
         this.options.orgMode,
         this.authManager,
-        this.multiAccount
+        this.multiAccount,
+        this.accountNames
       );
     } else {
       registerGraphTools(

package/dist/tool-categories.js

@@ -1,7 +1,7 @@
 const TOOL_CATEGORIES = {
   mail: {
     name: "mail",
-    pattern: /mail|attachment|draft/i,
+    pattern: /mail|attachment|draft|download-bytes/i,
     description: "Email operations (read, send, manage folders, attachments)"
   },
   calendar: {
@@ -16,12 +16,12 @@ const TOOL_CATEGORIES = {
   },
   personal: {
     name: "personal",
-    pattern: /mail|calendar|drive|contact|todo|onenote|attachment|draft|event|file|folder|search|query/i,
+    pattern: /mail|calendar|drive|contact|todo|onenote|attachment|draft|event|file|folder|search|query|download-bytes|parse-teams-url/i,
     description: "Personal productivity tools (mail, calendar, files, contacts, tasks, notes, search)"
   },
   work: {
     name: "work",
-    pattern: /team|channel|chat|sharepoint|planner|site|list|shared|search|query/i,
+    pattern: /team|channel|chat|sharepoint|planner|site|list|shared|search|query|download-bytes/i,
     description: "Organization/work tools (Teams, SharePoint, shared mailboxes, search)",
     requiresOrgMode: true
   },
@@ -52,7 +52,7 @@ const TOOL_CATEGORIES = {
   },
   users: {
     name: "users",
-    pattern: /user|list-users/i,
+    pattern: /user|list-users|download-bytes/i,
     description: "User directory access",
     requiresOrgMode: true
   },

package/package.json

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