@softeria/ms-365-mcp-server 0.150.2 → 0.150.3

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

@@ -1219,6 +1219,198 @@ describe("graph-tools", () => {
       expect(schema["messageId"].description).toContain("not as 'id'");
     });
   });
+  describe("$search quote normalization", () => {
+    async function callSearch(search, path = "/me/messages") {
+      const endpoint = makeEndpoint({ path });
+      const config = makeConfig();
+      mockEndpoints.push(endpoint);
+      mockEndpointsJson = [config];
+      const graphClient = createMockGraphClient([
+        { content: [{ type: "text", text: JSON.stringify({ value: [] }) }] }
+      ]);
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, graphClient);
+      const result = await server.tools.get("test-tool").handler({ search });
+      return { result, graphClient };
+    }
+    async function callWithSearch(search, path = "/me/messages") {
+      const { graphClient } = await callSearch(search, path);
+      return graphClient.graphRequest.mock.calls[0][0];
+    }
+    it("wraps a bare KQL expression in one pair of double quotes", async () => {
+      const url = await callWithSearch("from:john AND subject:meeting");
+      expect(url).toContain(`$search=${encodeURIComponent('"from:john AND subject:meeting"')}`);
+    });
+    it("collapses per-term quoting into a single enclosing pair", async () => {
+      const url = await callWithSearch('"from:john" AND subject:meeting');
+      expect(url).toContain(`$search=${encodeURIComponent('"from:john AND subject:meeting"')}`);
+    });
+    it("leaves an already correctly quoted expression untouched", async () => {
+      const url = await callWithSearch('"from:john AND subject:meeting"');
+      expect(url).toContain(`$search=${encodeURIComponent('"from:john AND subject:meeting"')}`);
+    });
+    it("adds the enclosing pair around a property phrase", async () => {
+      const url = await callWithSearch('subject:"quarterly report"');
+      expect(url).toContain(`$search=${encodeURIComponent('"subject:\\"quarterly report\\""')}`);
+    });
+    it("keeps a standalone phrase grouped", async () => {
+      const url = await callWithSearch('"quarterly report" AND from:john');
+      expect(url).toContain(
+        `$search=${encodeURIComponent('"\\"quarterly report\\" AND from:john"')}`
+      );
+    });
+    it("leaves an already escaped phrase untouched", async () => {
+      const query = '"subject:\\"quarterly report\\""';
+      const url = await callWithSearch(query);
+      expect(url).toContain(`$search=${encodeURIComponent(query)}`);
+    });
+    it("leaves already-wrapped free text as a multi-term search", async () => {
+      const query = '"quarterly report"';
+      const url = await callWithSearch(query);
+      expect(url).toContain(`$search=${encodeURIComponent(query)}`);
+    });
+    it.each([
+      ['"received>=2024-01-01" AND from:john', '"received>=2024-01-01 AND from:john"'],
+      ['"size>1000" AND subject:meeting', '"size>1000 AND subject:meeting"'],
+      ['"received<2024-01-01"', '"received<2024-01-01"']
+    ])("undoes per-clause quoting on a comparison clause (%s)", async (query, expected) => {
+      const url = await callWithSearch(query);
+      expect(url).toContain(`$search=${encodeURIComponent(expected)}`);
+    });
+    it.each([
+      ['"RE: quarterly report" AND from:john', '"\\"RE: quarterly report\\" AND from:john"'],
+      ['"Q3: plan.pdf" AND subject:budget', '"\\"Q3: plan.pdf\\" AND subject:budget"']
+    ])("keeps phrase quotes on a clause-shaped phrase (%s)", async (query, expected) => {
+      const url = await callWithSearch(query);
+      expect(url).toContain(`$search=${encodeURIComponent(expected)}`);
+    });
+    it.each([
+      ['subject:"RE: quarterly report"', '"subject:\\"RE: quarterly report\\""'],
+      ['attachment:"Q3: plan.pdf"', '"attachment:\\"Q3: plan.pdf\\""']
+    ])("keeps phrase quotes when the phrase contains a colon (%s)", async (query, expected) => {
+      const url = await callWithSearch(query);
+      expect(url).toContain(`$search=${encodeURIComponent(expected)}`);
+    });
+    it.each([
+      [
+        '"from: the desk of the CEO" AND subject:report',
+        '"\\"from: the desk of the CEO\\" AND subject:report"'
+      ],
+      [
+        '"subject: quarterly report" AND from:john',
+        '"\\"subject: quarterly report\\" AND from:john"'
+      ]
+    ])("keeps phrase quotes when a space follows the property (%s)", async (query, expected) => {
+      const url = await callWithSearch(query);
+      expect(url).toContain(`$search=${encodeURIComponent(expected)}`);
+    });
+    it("balances a trailing backslash so it cannot escape the closing quote", async () => {
+      const url = await callWithSearch("from:john\\");
+      expect(url).toContain(`$search=${encodeURIComponent('"from:john\\\\"')}`);
+    });
+    it.each([
+      ['from:"john', '"from:\\"john\\""'],
+      ['subject:"quarterly report', '"subject:\\"quarterly report\\""']
+    ])("closes an unterminated quote rather than dropping it (%s)", async (query, expected) => {
+      const url = await callWithSearch(query);
+      expect(url).toContain(`$search=${encodeURIComponent(expected)}`);
+    });
+    it.each([
+      [
+        '"subject:quarterly report" AND from:john',
+        '"subject:\\"quarterly report\\" AND from:john"'
+      ],
+      ['"from:john" AND "subject:the big report"', '"from:john AND subject:\\"the big report\\""']
+    ])("moves quotes past the operator on a multi-word value (%s)", async (query, expected) => {
+      const url = await callWithSearch(query);
+      expect(url).toContain(`$search=${encodeURIComponent(expected)}`);
+    });
+    it.each([
+      [
+        '"from:john AND subject:meeting" OR from:jane',
+        '"from:john AND subject:meeting OR from:jane"'
+      ],
+      [
+        '"from:john OR from:jane" AND hasAttachments:true',
+        '"from:john OR from:jane AND hasAttachments:true"'
+      ]
+    ])("unwraps a quoted group of clauses (%s)", async (query, expected) => {
+      const url = await callWithSearch(query);
+      expect(url).toContain(`$search=${encodeURIComponent(expected)}`);
+    });
+    it("recovers a dropped closing quote on the enclosing pair", async () => {
+      const url = await callWithSearch('"from:john AND subject:meeting');
+      expect(url).toContain(`$search=${encodeURIComponent('"from:john AND subject:meeting"')}`);
+    });
+    it("reads an escaped backslash before a closing quote", async () => {
+      const url = await callWithSearch('from:"a\\\\"');
+      expect(url).toContain(`$search=${encodeURIComponent('"from:\\"a\\\\\\""')}`);
+    });
+    const CORPUS = [
+      "from:john AND subject:meeting",
+      '"from:john" AND subject:meeting',
+      'subject:"quarterly report',
+      '"subject:quarterly report" AND from:john',
+      '"from:john AND subject:meeting" OR from:jane',
+      '"from:john AND subject:meeting',
+      "from:john\\",
+      'from:"a\\\\"',
+      'subject:"abc\\',
+      '"quarterly report"'
+    ];
+    it.each(CORPUS)("emits a balanced escaped string (%s)", async (query) => {
+      const url = await callWithSearch(query);
+      const value = new URL(url, "https://graph.microsoft.com").searchParams.get("$search");
+      expect(value.startsWith('"') && value.endsWith('"')).toBe(true);
+      let unescaped = 0;
+      for (let i = 0; i < value.length; i++) {
+        if (value[i] === "\\") {
+          i++;
+          continue;
+        }
+        if (value[i] === '"') unescaped++;
+      }
+      expect(unescaped).toBe(2);
+    });
+    it.each(CORPUS)("normalizing twice is a no-op (%s)", async (query) => {
+      const once = await callWithSearch(query);
+      const search = new URL(once, "https://graph.microsoft.com").searchParams.get("$search");
+      const twice = await callWithSearch(search);
+      expect(twice).toContain(`$search=${encodeURIComponent(search)}`);
+    });
+    it.each([" ", "   ", '"', '""""'])(
+      "refuses an unsearchable $search value %j",
+      async (query) => {
+        const { result, graphClient } = await callSearch(query);
+        expect(result.isError).toBe(true);
+        expect(JSON.parse(result.content[0].text).error).toBe("invalid_search");
+        expect(graphClient.graphRequest).not.toHaveBeenCalled();
+      }
+    );
+    it.each([
+      ["/users", '"displayName:john" OR "displayName:jane"'],
+      // Mail-adjacent, but none of these take message KQL.
+      ["/me/mailFolders", "foo OR bar"],
+      ["/me/mailFolders/:mailFolderId/childFolders", "foo OR bar"],
+      ["/me/mailFolders/:mailFolderId/messageRules", "foo OR bar"],
+      ["/me/messages/:messageId/attachments", "foo OR bar"],
+      ["/planner/tasks/:plannerTaskId/messages", "foo OR bar"],
+      ["/chats/:chatId/messages", "foo OR bar"],
+      ["/teams/:teamId/channels/:channelId/messages", "foo OR bar"]
+    ])("does not touch $search on %s", async (path, query) => {
+      const url = await callWithSearch(query, path);
+      expect(url).toContain(`$search=${encodeURIComponent(query)}`);
+    });
+    it.each([
+      "/me/mailFolders/:mailFolderId/messages",
+      "/users/:userId/messages",
+      "/me/mailFolders/:mailFolderId/childFolders/:childFolderId/messages"
+    ])("still normalizes on %s", async (path) => {
+      const url = await callWithSearch('"from:john" AND subject:meeting', path);
+      expect(url).toContain(`$search=${encodeURIComponent('"from:john AND subject:meeting"')}`);
+    });
+  });
   describe("MS365_MCP_MAX_TOP", () => {
     const prevMaxTop = process.env.MS365_MCP_MAX_TOP;
     afterEach(() => {

package/dist/graph-tools.js

@@ -80,6 +80,142 @@ function clampTopQueryParam(queryParams) {
   logger.info(`Clamping $top from ${requested} to ${cap} (MS365_MCP_MAX_TOP)`);
   queryParams["$top"] = String(cap);
 }
+const OUTLOOK_MAIL_PATH = /^\/(?:me|users\/[^/]+)(?:\/(?:mailFolders|childFolders)\/[^/]+)*\/messages(?:\/delta\(\))?$/i;
+function isOutlookMailPath(path2) {
+  return OUTLOOK_MAIL_PATH.test(path2);
+}
+function readQuotedSegment(expr, start) {
+  let j = start + 1;
+  let segment = "";
+  while (j < expr.length) {
+    if (expr[j] === "\\" && expr[j + 1] === "\\") {
+      segment += "\\\\";
+      j += 2;
+      continue;
+    }
+    if (expr[j] === "\\" && expr[j + 1] === '"') {
+      segment += '\\"';
+      j += 2;
+      continue;
+    }
+    if (expr[j] === '"') return { segment, end: j };
+    segment += expr[j];
+    j += 1;
+  }
+  return void 0;
+}
+const MAIL_SEARCH_PROPERTIES = /* @__PURE__ */ new Set([
+  "attachment",
+  "bcc",
+  "body",
+  "category",
+  "cc",
+  "from",
+  "hasattachment",
+  "hasattachments",
+  "importance",
+  "kind",
+  "participants",
+  "received",
+  "recipients",
+  "sent",
+  "size",
+  "subject",
+  "to"
+]);
+const CLAUSE_HEAD = /^([A-Za-z]+)(?::|<=|>=|<>|=|<|>)\S/;
+const BOOLEAN_JOIN = /\s(?:AND|OR|NOT)\s/;
+function clauseHead(segment) {
+  const head = CLAUSE_HEAD.exec(segment);
+  return head && MAIL_SEARCH_PROPERTIES.has(head[1].toLowerCase()) ? head : null;
+}
+function balanceTrailingSlashes(text) {
+  const slashes = text.length - text.replace(/\\+$/, "").length;
+  return slashes % 2 === 1 ? `${text}\\` : text;
+}
+function classifyRun(segment, introducedByProperty) {
+  if (introducedByProperty) return "phrase";
+  const head = clauseHead(segment);
+  if (!head) return "phrase";
+  if (BOOLEAN_JOIN.test(segment) || !/\s/.test(segment)) return "clause";
+  return "restriction-value";
+}
+function rewriteMailSearchQuotes(expr) {
+  let out = "";
+  let i = 0;
+  while (i < expr.length) {
+    if (expr[i] === "\\" && expr[i + 1] === "\\") {
+      out += "\\\\";
+      i += 2;
+      continue;
+    }
+    if (expr[i] === "\\" && expr[i + 1] === '"') {
+      out += '\\"';
+      i += 2;
+      continue;
+    }
+    if (expr[i] !== '"') {
+      out += expr[i];
+      i += 1;
+      continue;
+    }
+    const run = readQuotedSegment(expr, i);
+    const segment = run ? run.segment : balanceTrailingSlashes(expr.slice(i + 1));
+    const introducedByProperty = i > 0 && expr[i - 1] === ":";
+    switch (classifyRun(segment, introducedByProperty)) {
+      case "clause":
+        out += segment;
+        break;
+      case "restriction-value": {
+        const head = clauseHead(segment);
+        const valueAt = head[0].length - 1;
+        out += `${segment.slice(0, valueAt)}\\"${segment.slice(valueAt)}\\"`;
+        break;
+      }
+      default:
+        out += `\\"${segment}\\"`;
+    }
+    if (!run) break;
+    i = run.end + 1;
+  }
+  return balanceTrailingSlashes(out.trim());
+}
+function normalizeSearchQueryParam(queryParams, path2, toolAlias) {
+  if (!isOutlookMailPath(path2)) return;
+  const raw = queryParams["$search"];
+  if (raw === void 0) return;
+  const trimmed = raw.trim();
+  const noSearchableText = () => {
+    logger.warn(`Refusing ${toolAlias}: '$search' has no searchable text`);
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error: "invalid_search",
+            tool: toolAlias,
+            message: 'The $search parameter has no searchable text. Supply a KQL expression such as "from:john" or "subject:budget", or omit $search to list messages unfiltered.'
+          })
+        }
+      ],
+      isError: true
+    };
+  };
+  if (trimmed === "" || /^["'\s]+$/.test(trimmed)) return noSearchableText();
+  let expr = trimmed;
+  if (expr.startsWith('"')) {
+    const whole = readQuotedSegment(expr, 0);
+    if (!whole) expr = expr.slice(1);
+    else if (whole.end === expr.length - 1) expr = whole.segment;
+  }
+  const inner = rewriteMailSearchQuotes(expr);
+  if (inner === "") return noSearchableText();
+  const normalized = `"${inner}"`;
+  if (normalized !== raw) {
+    logger.info(`Auto-corrected parameter '$search': normalized KQL quoting to ${normalized}`);
+    queryParams["$search"] = normalized;
+  }
+}
 const DEFAULT_MAX_ITEMS = 1e4;
 function isConfirmGateEnabled() {
   return process.env.MS365_MCP_REQUIRE_CONFIRM === "true";
@@ -1037,6 +1173,8 @@ async function executeGraphTool(tool, config, graphClient, params, authManager)
       delete queryParams["$top"];
     }
     clampTopQueryParam(queryParams);
+    const searchError = normalizeSearchQueryParam(queryParams, tool.path, tool.alias);
+    if (searchError) return searchError;
     const preferValues = [];
     if (config?.supportsTimezone && params.timezone) {
       preferValues.push(`outlook.timezone="${params.timezone}"`);

package/dist/lib/param-descriptions.js

@@ -29,7 +29,7 @@ function isFetchAllPagesApplicable(tool) {
   return tool.method.toUpperCase() === "GET" && tool.path.includes("/") && paginationAllowed();
 }
 const FILTER_PARAM_DESCRIPTION = "OData filter expression. Add $count=true for advanced filters (flag/flagStatus, contains()). Cannot combine with $search.";
-const SEARCH_PARAM_DESCRIPTION = "KQL search query \u2014 wrap value in double quotes. Cannot combine with $filter.";
+const SEARCH_PARAM_DESCRIPTION = "KQL search query in one pair of double quotes; directory (users/groups) instead quotes each clause with no outer pair. Cannot combine with $filter.";
 const SELECT_PARAM_DESCRIPTION = "Comma-separated fields to return, e.g. id,subject,from,receivedDateTime";
 const EXPAND_PARAM_DESCRIPTION = 'Navigation properties to inline, e.g. attachments on a message or event. Only navigation properties can be expanded: expanding a non-navigation property such as a message body fails with "Parsing OData Select and Expand failed", and an unsupported value may be ignored rather than reported. Request ordinary fields with $select instead.';
 const ORDERBY_PARAM_DESCRIPTION = "Sort expression, e.g. receivedDateTime desc";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@softeria/ms-365-mcp-server",
   "mcpName": "io.github.Softeria/ms-365-mcp-server",
-  "version": "0.150.2",
+  "version": "0.150.3",
   "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",