@softeria/ms-365-mcp-server 0.25.0 → 0.27.0

package/dist/graph-tools.js

@@ -4,11 +4,194 @@ import { z } from "zod";
 import { readFileSync } from "fs";
 import path from "path";
 import { fileURLToPath } from "url";
+import { TOOL_CATEGORIES } from "./tool-categories.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const endpointsData = JSON.parse(
   readFileSync(path.join(__dirname, "endpoints.json"), "utf8")
 );
+async function executeGraphTool(tool, config, graphClient, params) {
+  logger.info(`Tool ${tool.alias} called with params: ${JSON.stringify(params)}`);
+  try {
+    const parameterDefinitions = tool.parameters || [];
+    let path2 = tool.path;
+    const queryParams = {};
+    const headers = {};
+    let body = null;
+    for (const [paramName, paramValue] of Object.entries(params)) {
+      if (["fetchAllPages", "includeHeaders", "excludeResponse", "timezone"].includes(paramName)) {
+        continue;
+      }
+      const odataParams = [
+        "filter",
+        "select",
+        "expand",
+        "orderby",
+        "skip",
+        "top",
+        "count",
+        "search",
+        "format"
+      ];
+      const normalizedParamName = paramName.startsWith("$") ? paramName.slice(1) : paramName;
+      const isOdataParam = odataParams.includes(normalizedParamName.toLowerCase());
+      const fixedParamName = isOdataParam ? `$${normalizedParamName.toLowerCase()}` : paramName;
+      const paramDef = parameterDefinitions.find(
+        (p) => p.name === paramName || isOdataParam && p.name === normalizedParamName
+      );
+      if (paramDef) {
+        switch (paramDef.type) {
+          case "Path":
+            path2 = path2.replace(`{${paramName}}`, encodeURIComponent(paramValue)).replace(`:${paramName}`, encodeURIComponent(paramValue));
+            break;
+          case "Query":
+            queryParams[fixedParamName] = `${paramValue}`;
+            break;
+          case "Body":
+            if (paramDef.schema) {
+              const parseResult = paramDef.schema.safeParse(paramValue);
+              if (!parseResult.success) {
+                const wrapped = { [paramName]: paramValue };
+                const wrappedResult = paramDef.schema.safeParse(wrapped);
+                if (wrappedResult.success) {
+                  logger.info(
+                    `Auto-corrected parameter '${paramName}': AI passed nested field directly, wrapped it as {${paramName}: ...}`
+                  );
+                  body = wrapped;
+                } else {
+                  body = paramValue;
+                }
+              } else {
+                body = paramValue;
+              }
+            } else {
+              body = paramValue;
+            }
+            break;
+          case "Header":
+            headers[fixedParamName] = `${paramValue}`;
+            break;
+        }
+      } else if (paramName === "body") {
+        body = paramValue;
+        logger.info(`Set body param: ${JSON.stringify(body)}`);
+      }
+    }
+    if (config?.supportsTimezone && params.timezone) {
+      headers["Prefer"] = `outlook.timezone="${params.timezone}"`;
+      logger.info(`Setting timezone header: Prefer: outlook.timezone="${params.timezone}"`);
+    }
+    if (Object.keys(queryParams).length > 0) {
+      const queryString = Object.entries(queryParams).map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`).join("&");
+      path2 = `${path2}${path2.includes("?") ? "&" : "?"}${queryString}`;
+    }
+    const options = {
+      method: tool.method.toUpperCase(),
+      headers
+    };
+    if (options.method !== "GET" && body) {
+      options.body = typeof body === "string" ? body : JSON.stringify(body);
+    }
+    const isProbablyMediaContent = tool.errors?.some((error) => error.description === "Retrieved media content") || path2.endsWith("/content");
+    if (config?.returnDownloadUrl && path2.endsWith("/content")) {
+      path2 = path2.replace(/\/content$/, "");
+      logger.info(
+        `Auto-returning download URL for ${tool.alias} (returnDownloadUrl=true in endpoints.json)`
+      );
+    } else if (isProbablyMediaContent) {
+      options.rawResponse = true;
+    }
+    if (params.includeHeaders === true) {
+      options.includeHeaders = true;
+    }
+    if (params.excludeResponse === true) {
+      options.excludeResponse = true;
+    }
+    logger.info(`Making graph request to ${path2} with options: ${JSON.stringify(options)}`);
+    let response = await graphClient.graphRequest(path2, options);
+    const fetchAllPages = params.fetchAllPages === true;
+    if (fetchAllPages && response?.content?.[0]?.text) {
+      try {
+        let combinedResponse = JSON.parse(response.content[0].text);
+        let allItems = combinedResponse.value || [];
+        let nextLink = combinedResponse["@odata.nextLink"];
+        let pageCount = 1;
+        while (nextLink && pageCount < 100) {
+          logger.info(`Fetching page ${pageCount + 1} from: ${nextLink}`);
+          const url = new URL(nextLink);
+          const nextPath = url.pathname.replace("/v1.0", "");
+          const nextOptions = { ...options };
+          const nextQueryParams = {};
+          for (const [key, value] of url.searchParams.entries()) {
+            nextQueryParams[key] = value;
+          }
+          nextOptions.queryParams = nextQueryParams;
+          const nextResponse = await graphClient.graphRequest(nextPath, nextOptions);
+          if (nextResponse?.content?.[0]?.text) {
+            const nextJsonResponse = JSON.parse(nextResponse.content[0].text);
+            if (nextJsonResponse.value && Array.isArray(nextJsonResponse.value)) {
+              allItems = allItems.concat(nextJsonResponse.value);
+            }
+            nextLink = nextJsonResponse["@odata.nextLink"];
+            pageCount++;
+          } else {
+            break;
+          }
+        }
+        if (pageCount >= 100) {
+          logger.warn(`Reached maximum page limit (100) for pagination`);
+        }
+        combinedResponse.value = allItems;
+        if (combinedResponse["@odata.count"]) {
+          combinedResponse["@odata.count"] = allItems.length;
+        }
+        delete combinedResponse["@odata.nextLink"];
+        response.content[0].text = JSON.stringify(combinedResponse);
+        logger.info(
+          `Pagination complete: collected ${allItems.length} items across ${pageCount} pages`
+        );
+      } catch (e) {
+        logger.error(`Error during pagination: ${e}`);
+      }
+    }
+    if (response?.content?.[0]?.text) {
+      const responseText = response.content[0].text;
+      logger.info(`Response size: ${responseText.length} characters`);
+      try {
+        const jsonResponse = JSON.parse(responseText);
+        if (jsonResponse.value && Array.isArray(jsonResponse.value)) {
+          logger.info(`Response contains ${jsonResponse.value.length} items`);
+        }
+        if (jsonResponse["@odata.nextLink"]) {
+          logger.info(`Response has pagination nextLink: ${jsonResponse["@odata.nextLink"]}`);
+        }
+      } catch {
+      }
+    }
+    const content = response.content.map((item) => ({
+      type: "text",
+      text: item.text
+    }));
+    return {
+      content,
+      _meta: response._meta,
+      isError: response.isError
+    };
+  } catch (error) {
+    logger.error(`Error in tool ${tool.alias}: ${error.message}`);
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error: `Error in tool ${tool.alias}: ${error.message}`
+          })
+        }
+      ],
+      isError: true
+    };
+  }
+}
 function registerGraphTools(server, graphClient, readOnly = false, enabledToolsPattern, orgMode = false) {
   let enabledToolsRegex;
   if (enabledToolsPattern) {
@@ -19,18 +202,24 @@ function registerGraphTools(server, graphClient, readOnly = false, enabledToolsP
       logger.error(`Invalid tool filter regex pattern: ${enabledToolsPattern}. Ignoring filter.`);
     }
   }
+  let registeredCount = 0;
+  let skippedCount = 0;
+  let failedCount = 0;
   for (const tool of api.endpoints) {
     const endpointConfig = endpointsData.find((e) => e.toolName === tool.alias);
     if (!orgMode && endpointConfig && !endpointConfig.scopes && endpointConfig.workScopes) {
       logger.info(`Skipping work account tool ${tool.alias} - not in org mode`);
+      skippedCount++;
       continue;
     }
     if (readOnly && tool.method.toUpperCase() !== "GET") {
       logger.info(`Skipping write operation ${tool.alias} in read-only mode`);
+      skippedCount++;
       continue;
     }
     if (enabledToolsRegex && !enabledToolsRegex.test(tool.alias)) {
       logger.info(`Skipping tool ${tool.alias} - doesn't match filter pattern`);
+      skippedCount++;
       continue;
     }
     const paramSchema = {};
@@ -44,220 +233,144 @@ function registerGraphTools(server, graphClient, readOnly = false, enabledToolsP
     }
     paramSchema["includeHeaders"] = z.boolean().describe("Include response headers (including ETag) in the response metadata").optional();
     paramSchema["excludeResponse"] = z.boolean().describe("Exclude the full response body and only return success or failure indication").optional();
+    if (endpointConfig?.supportsTimezone) {
+      paramSchema["timezone"] = z.string().describe(
+        'IANA timezone name (e.g., "America/New_York", "Europe/London", "Asia/Tokyo") for calendar event times. If not specified, times are returned in UTC.'
+      ).optional();
+    }
     let toolDescription = tool.description || `Execute ${tool.method.toUpperCase()} request to ${tool.path}`;
     if (endpointConfig?.llmTip) {
       toolDescription += `
 
 \u{1F4A1} TIP: ${endpointConfig.llmTip}`;
     }
-    server.tool(
-      tool.alias,
-      toolDescription,
-      paramSchema,
-      {
-        title: tool.alias,
-        readOnlyHint: tool.method.toUpperCase() === "GET"
-      },
-      async (params) => {
-        logger.info(`Tool ${tool.alias} called with params: ${JSON.stringify(params)}`);
-        try {
-          logger.info(`params: ${JSON.stringify(params)}`);
-          const parameterDefinitions = tool.parameters || [];
-          let path2 = tool.path;
-          const queryParams = {};
-          const headers = {};
-          let body = null;
-          for (let [paramName, paramValue] of Object.entries(params)) {
-            if (paramName === "fetchAllPages") {
-              continue;
-            }
-            if (paramName === "includeHeaders") {
-              continue;
-            }
-            if (paramName === "excludeResponse") {
-              continue;
-            }
-            const odataParams = [
-              "filter",
-              "select",
-              "expand",
-              "orderby",
-              "skip",
-              "top",
-              "count",
-              "search",
-              "format"
-            ];
-            const fixedParamName = odataParams.includes(paramName.toLowerCase()) ? `$${paramName.toLowerCase()}` : paramName;
-            const paramDef = parameterDefinitions.find((p) => p.name === paramName);
-            if (paramDef) {
-              switch (paramDef.type) {
-                case "Path":
-                  path2 = path2.replace(`{${paramName}}`, encodeURIComponent(paramValue)).replace(`:${paramName}`, encodeURIComponent(paramValue));
-                  break;
-                case "Query":
-                  queryParams[fixedParamName] = `${paramValue}`;
-                  break;
-                case "Body":
-                  if (paramDef.schema) {
-                    const parseResult = paramDef.schema.safeParse(paramValue);
-                    if (!parseResult.success) {
-                      const wrapped = { [paramName]: paramValue };
-                      const wrappedResult = paramDef.schema.safeParse(wrapped);
-                      if (wrappedResult.success) {
-                        logger.info(
-                          `Auto-corrected parameter '${paramName}': AI passed nested field directly, wrapped it as {${paramName}: ...}`
-                        );
-                        body = wrapped;
-                      } else {
-                        body = paramValue;
-                      }
-                    } else {
-                      body = paramValue;
-                    }
-                  } else {
-                    body = paramValue;
-                  }
-                  break;
-                case "Header":
-                  headers[fixedParamName] = `${paramValue}`;
-                  break;
-              }
-            } else if (paramName === "body") {
-              body = paramValue;
-              logger.info(`Set body param: ${JSON.stringify(body)}`);
-            }
-          }
-          if (Object.keys(queryParams).length > 0) {
-            const queryString = Object.entries(queryParams).map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`).join("&");
-            path2 = `${path2}${path2.includes("?") ? "&" : "?"}${queryString}`;
-          }
-          const options = {
-            method: tool.method.toUpperCase(),
-            headers
-          };
-          if (options.method !== "GET" && body) {
-            options.body = typeof body === "string" ? body : JSON.stringify(body);
-          }
-          const isProbablyMediaContent = tool.errors?.some((error) => error.description === "Retrieved media content") || path2.endsWith("/content");
-          if (endpointConfig?.returnDownloadUrl && path2.endsWith("/content")) {
-            path2 = path2.replace(/\/content$/, "");
-            logger.info(
-              `Auto-returning download URL for ${tool.alias} (returnDownloadUrl=true in endpoints.json)`
-            );
-          } else if (isProbablyMediaContent) {
-            options.rawResponse = true;
-          }
-          if (params.includeHeaders === true) {
-            options.includeHeaders = true;
-          }
-          if (params.excludeResponse === true) {
-            options.excludeResponse = true;
-          }
-          logger.info(`Making graph request to ${path2} with options: ${JSON.stringify(options)}`);
-          let response = await graphClient.graphRequest(path2, options);
-          const fetchAllPages = params.fetchAllPages === true;
-          if (fetchAllPages && response && response.content && response.content.length > 0) {
-            try {
-              let combinedResponse = JSON.parse(response.content[0].text);
-              let allItems = combinedResponse.value || [];
-              let nextLink = combinedResponse["@odata.nextLink"];
-              let pageCount = 1;
-              while (nextLink) {
-                logger.info(`Fetching page ${pageCount + 1} from: ${nextLink}`);
-                const url = new URL(nextLink);
-                const nextPath = url.pathname.replace("/v1.0", "");
-                const nextOptions = { ...options };
-                const nextQueryParams = {};
-                for (const [key, value] of url.searchParams.entries()) {
-                  nextQueryParams[key] = value;
-                }
-                nextOptions.queryParams = nextQueryParams;
-                const nextResponse = await graphClient.graphRequest(nextPath, nextOptions);
-                if (nextResponse && nextResponse.content && nextResponse.content.length > 0) {
-                  const nextJsonResponse = JSON.parse(nextResponse.content[0].text);
-                  if (nextJsonResponse.value && Array.isArray(nextJsonResponse.value)) {
-                    allItems = allItems.concat(nextJsonResponse.value);
-                  }
-                  nextLink = nextJsonResponse["@odata.nextLink"];
-                  pageCount++;
-                  if (pageCount > 100) {
-                    logger.warn(`Reached maximum page limit (100) for pagination`);
-                    break;
-                  }
-                } else {
-                  break;
-                }
-              }
-              combinedResponse.value = allItems;
-              if (combinedResponse["@odata.count"]) {
-                combinedResponse["@odata.count"] = allItems.length;
-              }
-              delete combinedResponse["@odata.nextLink"];
-              response.content[0].text = JSON.stringify(combinedResponse);
-              logger.info(
-                `Pagination complete: collected ${allItems.length} items across ${pageCount} pages`
-              );
-            } catch (e) {
-              logger.error(`Error during pagination: ${e}`);
-            }
+    try {
+      server.tool(
+        tool.alias,
+        toolDescription,
+        paramSchema,
+        {
+          title: tool.alias,
+          readOnlyHint: tool.method.toUpperCase() === "GET"
+        },
+        async (params) => executeGraphTool(tool, endpointConfig, graphClient, params)
+      );
+      registeredCount++;
+    } catch (error) {
+      logger.error(`Failed to register tool ${tool.alias}: ${error.message}`);
+      failedCount++;
+    }
+  }
+  logger.info(
+    `Tool registration complete: ${registeredCount} registered, ${skippedCount} skipped, ${failedCount} failed`
+  );
+  return registeredCount;
+}
+function buildToolsRegistry(readOnly, orgMode) {
+  const toolsMap = /* @__PURE__ */ new Map();
+  for (const tool of api.endpoints) {
+    const endpointConfig = endpointsData.find((e) => e.toolName === tool.alias);
+    if (!orgMode && endpointConfig && !endpointConfig.scopes && endpointConfig.workScopes) {
+      continue;
+    }
+    if (readOnly && tool.method.toUpperCase() !== "GET") {
+      continue;
+    }
+    toolsMap.set(tool.alias, { tool, config: endpointConfig });
+  }
+  return toolsMap;
+}
+function registerDiscoveryTools(server, graphClient, readOnly = false, orgMode = false) {
+  const toolsRegistry = buildToolsRegistry(readOnly, orgMode);
+  logger.info(`Discovery mode: ${toolsRegistry.size} tools available in registry`);
+  server.tool(
+    "search-tools",
+    `Search through ${toolsRegistry.size} available Microsoft Graph API tools. Use this to find tools by name, path, or description before executing them.`,
+    {
+      query: z.string().describe("Search query to filter tools (searches name, path, and description)").optional(),
+      category: z.string().describe(
+        "Filter by category: mail, calendar, files, contacts, tasks, onenote, search, users, excel"
+      ).optional(),
+      limit: z.number().describe("Maximum results to return (default: 20, max: 50)").optional()
+    },
+    {
+      title: "search-tools",
+      readOnlyHint: true
+    },
+    async ({ query, category, limit = 20 }) => {
+      const maxLimit = Math.min(limit, 50);
+      const results = [];
+      const queryLower = query?.toLowerCase();
+      const categoryDef = category ? TOOL_CATEGORIES[category] : void 0;
+      for (const [name, { tool, config }] of toolsRegistry) {
+        if (categoryDef && !categoryDef.pattern.test(name)) {
+          continue;
+        }
+        if (queryLower) {
+          const searchText = `${name} ${tool.path} ${tool.description || ""} ${config?.llmTip || ""}`.toLowerCase();
+          if (!searchText.includes(queryLower)) {
+            continue;
           }
-          if (response && response.content && response.content.length > 0) {
-            const responseText = response.content[0].text;
-            const responseSize = responseText.length;
-            logger.info(`Response size: ${responseSize} characters`);
-            try {
-              const jsonResponse = JSON.parse(responseText);
-              if (jsonResponse.value && Array.isArray(jsonResponse.value)) {
-                logger.info(`Response contains ${jsonResponse.value.length} items`);
-                if (jsonResponse.value.length > 0 && jsonResponse.value[0].body) {
-                  logger.info(
-                    `First item has body field with size: ${JSON.stringify(jsonResponse.value[0].body).length} characters`
-                  );
-                }
-              }
-              if (jsonResponse["@odata.nextLink"]) {
-                logger.info(`Response has pagination nextLink: ${jsonResponse["@odata.nextLink"]}`);
-              }
-              const preview = responseText.substring(0, 500);
-              logger.info(`Response preview: ${preview}${responseText.length > 500 ? "..." : ""}`);
-            } catch {
-              const preview = responseText.substring(0, 500);
-              logger.info(
-                `Response preview (non-JSON): ${preview}${responseText.length > 500 ? "..." : ""}`
-              );
-            }
+        }
+        results.push({
+          name,
+          method: tool.method.toUpperCase(),
+          path: tool.path,
+          description: tool.description || `${tool.method.toUpperCase()} ${tool.path}`
+        });
+        if (results.length >= maxLimit) break;
+      }
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                found: results.length,
+                total: toolsRegistry.size,
+                tools: results,
+                tip: "Use execute-tool with the tool name and required parameters to call any of these tools."
+              },
+              null,
+              2
+            )
           }
-          const content = response.content.map((item) => {
-            const textContent = {
+        ]
+      };
+    }
+  );
+  server.tool(
+    "execute-tool",
+    "Execute a Microsoft Graph API tool by name. Use search-tools first to find available tools and their parameters.",
+    {
+      tool_name: z.string().describe('Name of the tool to execute (e.g., "list-mail-messages")'),
+      parameters: z.record(z.any()).describe("Parameters to pass to the tool as key-value pairs").optional()
+    },
+    {
+      title: "execute-tool",
+      readOnlyHint: false
+    },
+    async ({ tool_name, parameters = {} }) => {
+      const toolData = toolsRegistry.get(tool_name);
+      if (!toolData) {
+        return {
+          content: [
+            {
               type: "text",
-              text: item.text
-            };
-            return textContent;
-          });
-          const result = {
-            content,
-            _meta: response._meta,
-            isError: response.isError
-          };
-          return result;
-        } catch (error) {
-          logger.error(`Error in tool ${tool.alias}: ${error.message}`);
-          const errorContent = {
-            type: "text",
-            text: JSON.stringify({
-              error: `Error in tool ${tool.alias}: ${error.message}`
-            })
-          };
-          return {
-            content: [errorContent],
-            isError: true
-          };
-        }
+              text: JSON.stringify({
+                error: `Tool not found: ${tool_name}`,
+                tip: "Use search-tools to find available tools."
+              })
+            }
+          ],
+          isError: true
+        };
       }
-    );
-  }
+      return executeGraphTool(toolData.tool, toolData.config, graphClient, parameters);
+    }
+  );
 }
 export {
+  registerDiscoveryTools,
   registerGraphTools
 };

package/dist/server.js

@@ -6,7 +6,7 @@ import express from "express";
 import crypto from "crypto";
 import logger, { enableConsoleLogging } from "./logger.js";
 import { registerAuthTools } from "./auth-tools.js";
-import { registerGraphTools } from "./graph-tools.js";
+import { registerGraphTools, registerDiscoveryTools } from "./graph-tools.js";
 import GraphClient from "./graph-client.js";
 import { buildScopesFromEndpoints } from "./auth.js";
 import { MicrosoftOAuthProvider } from "./oauth-provider.js";
@@ -33,13 +33,23 @@ class MicrosoftGraphServer {
     if (shouldRegisterAuthTools) {
       registerAuthTools(this.server, this.authManager);
     }
-    registerGraphTools(
-      this.server,
-      this.graphClient,
-      this.options.readOnly,
-      this.options.enabledTools,
-      this.options.orgMode
-    );
+    if (this.options.discovery) {
+      logger.info("Discovery mode enabled (experimental) - registering discovery tool only");
+      registerDiscoveryTools(
+        this.server,
+        this.graphClient,
+        this.options.readOnly,
+        this.options.orgMode
+      );
+    } else {
+      registerGraphTools(
+        this.server,
+        this.graphClient,
+        this.options.readOnly,
+        this.options.enabledTools,
+        this.options.orgMode
+      );
+    }
   }
   async start() {
     if (this.options.v) {