m365connector 0.3.8 → 0.3.9

package/README.md

@@ -56,6 +56,8 @@ Then add to your MCP client config:
 | `M365C_EDGE_PATH` | auto-detected | Microsoft Edge executable path |
 | `M365C_EDGE_USER_DATA_DIR` | phantomwright `ud-m365` profile when present, else `~/.m365connector/edge-profile` | Persistent Edge user data directory |
 | `M365C_EDGE_PROFILE_DIRECTORY` | `Default` | Edge profile directory inside the user data dir |
+| `M365C_ALLOW_BROWSER_FOCUS` | unset | Set to `1` to allow MCP-driven Edge tabs to come to the foreground for any active-tab request. By default Edge stays in the background unless Microsoft 365 requires user login, MFA, or consent. |
+| `M365C_NEVER_FOCUS_BROWSER` | unset | Set to `1` to prevent MCP-driven Edge tabs from ever coming to the foreground. When user interaction is required, the operation will wait/fail instead of stealing focus. |
 | `M365C_TOKEN_CACHE_PATH` | `~/.m365connector/token-cache.json` | Local token cache path; stores only current unexpired captured tokens |
 
 ## Tools

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "m365connector",
-  "version": "0.3.8",
+  "version": "0.3.9",
   "description": "MCP server for Microsoft 365 data via Edge CDP",
   "type": "module",
   "main": "src/index.js",

package/src/browser-session.js

@@ -3,11 +3,14 @@ import fs from "node:fs";
 import http from "node:http";
 import os from "node:os";
 import path from "node:path";
-import { spawn } from "node:child_process";
+import { execFile, spawn } from "node:child_process";
+import { promisify } from "node:util";
 import { WebSocket } from "ws";
 
 const DEFAULT_EDGE_PORT = 52367;
 const DEFAULT_NAVIGATION_TIMEOUT_MS = 30000;
+const USER_INTERACTION_FOCUS_REASON = "user-interaction";
+const execFileAsync = promisify(execFile);
 
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
@@ -70,6 +73,79 @@ function requestText(url, options = {}) {
   });
 }
 
+async function createBackgroundTarget(port, url) {
+  const version = await requestJson(`http://127.0.0.1:${port}/json/version`, { timeoutMs: 2000 });
+  const wsUrl = version?.webSocketDebuggerUrl;
+  if (!wsUrl) {
+    throw new Error("Browser CDP websocket URL unavailable");
+  }
+
+  const ws = new WebSocket(wsUrl);
+  await new Promise((resolve, reject) => {
+    ws.once("open", resolve);
+    ws.once("error", reject);
+  });
+
+  try {
+    const result = await new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        ws.off("message", onMessage);
+        reject(new Error("CDP timeout: Target.createTarget"));
+      }, 5000);
+      const onMessage = (raw) => {
+        try {
+          const message = JSON.parse(String(raw));
+          if (message.id !== 1) {
+            return;
+          }
+          clearTimeout(timeout);
+          ws.off("message", onMessage);
+          if (message.error) {
+            reject(new Error(message.error.message || JSON.stringify(message.error)));
+          } else {
+            resolve(message.result || {});
+          }
+        } catch (err) {
+          clearTimeout(timeout);
+          ws.off("message", onMessage);
+          reject(err);
+        }
+      };
+      ws.on("message", onMessage);
+      ws.send(JSON.stringify({
+        id: 1,
+        method: "Target.createTarget",
+        params: {
+          url,
+          background: true
+        }
+      }));
+    });
+
+    const targetId = result?.targetId;
+    if (!targetId) {
+      throw new Error("Target.createTarget did not return targetId");
+    }
+
+    const deadline = Date.now() + 5000;
+    while (Date.now() < deadline) {
+      const targets = await requestJson(`http://127.0.0.1:${port}/json/list`, { timeoutMs: 2000 });
+      const target = targets.find((row) => row.id === targetId);
+      if (target?.webSocketDebuggerUrl) {
+        return target;
+      }
+      await sleep(100);
+    }
+    throw new Error(`Target ${targetId} did not appear in /json/list`);
+  } finally {
+    try {
+      ws.close();
+    } catch {
+      // ignored
+    }
+  }
+}
+
 export function findEdgeExecutable() {
   if (process.env.M365C_EDGE_PATH) {
     return expandHome(process.env.M365C_EDGE_PATH);
@@ -122,6 +198,41 @@ function normalizeHeaderMap(headers = {}) {
   return out;
 }
 
+async function getFrontmostApplicationName() {
+  if (process.platform !== "darwin") {
+    return null;
+  }
+  try {
+    const { stdout } = await execFileAsync("osascript", [
+      "-e",
+      'tell application "System Events" to get name of first application process whose frontmost is true'
+    ]);
+    const name = stdout.trim();
+    return name || null;
+  } catch {
+    return null;
+  }
+}
+
+async function restoreFrontmostApplication(name, logger = console) {
+  if (process.platform !== "darwin" || !name || name === "Microsoft Edge") {
+    return;
+  }
+  const escapedName = name.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+  const script = [
+    'tell application "System Events"',
+    `  if exists process "${escapedName}" then`,
+    `    set frontmost of process "${escapedName}" to true`,
+    "  end if",
+    "end tell"
+  ].join("\n");
+  try {
+    await execFileAsync("osascript", ["-e", script], { timeout: 3000 });
+  } catch (err) {
+    logger.warn?.("[m365connector][browser] failed to restore frontmost application:", err.message);
+  }
+}
+
 export class CdpPage extends EventEmitter {
   constructor(session, target) {
     super();
@@ -290,12 +401,13 @@ export class CdpPage extends EventEmitter {
   }
 
   async bringToFront(options = {}) {
-    if (!this.session.allowBrowserFocus && !options.force) {
+    if (!this.session.shouldBringBrowserToFront(options)) {
       this.session.activePageId = this.id;
-      return;
+      return false;
     }
     await this.send("Page.bringToFront").catch(() => {});
     this.session.activePageId = this.id;
+    return true;
   }
 
   async clickAt(x, y) {
@@ -389,11 +501,40 @@ export class BrowserSession extends EventEmitter {
     this.edgePath = findEdgeExecutable();
     this.logger = options.logger || console;
     this.allowBrowserFocus = options.allowBrowserFocus ?? process.env.M365C_ALLOW_BROWSER_FOCUS === "1";
+    this.neverFocusBrowser = options.neverFocusBrowser ?? process.env.M365C_NEVER_FOCUS_BROWSER === "1";
     this.process = null;
     this.pages = new Map();
     this.activePageId = null;
   }
 
+  shouldBringBrowserToFront(options = {}) {
+    if (this.neverFocusBrowser) {
+      return false;
+    }
+    if (this.allowBrowserFocus) {
+      return true;
+    }
+    return options.force === true && options.reason === USER_INTERACTION_FOCUS_REASON;
+  }
+
+  shouldPreserveFrontmostApp() {
+    return process.platform === "darwin" && !this.allowBrowserFocus;
+  }
+
+  async captureFrontmostApp() {
+    if (!this.shouldPreserveFrontmostApp()) {
+      return null;
+    }
+    return getFrontmostApplicationName();
+  }
+
+  async restoreFrontmostApp(name) {
+    if (!this.shouldPreserveFrontmostApp()) {
+      return;
+    }
+    await restoreFrontmostApplication(name, this.logger);
+  }
+
   async start() {
     if (await this.#isDebugEndpointReady()) {
       return;
@@ -465,10 +606,23 @@ export class BrowserSession extends EventEmitter {
 
   async createPage(url = "about:blank", options = {}) {
     await this.start();
-    const target = await requestJson(
-      `http://127.0.0.1:${this.port}/json/new?${encodeURIComponent(url)}`,
-      { method: "PUT", timeoutMs: 3000 }
-    );
+    const previousFrontmostApp = await this.captureFrontmostApp();
+    let target = null;
+    if (!this.shouldBringBrowserToFront(options)) {
+      target = await createBackgroundTarget(this.port, url).catch((err) => {
+        this.logger.warn("[m365connector][browser] background target creation failed:", err.message);
+        return null;
+      });
+    }
+    if (!target) {
+      target = await requestJson(
+        `http://127.0.0.1:${this.port}/json/new?${encodeURIComponent(url)}`,
+        { method: "PUT", timeoutMs: 3000 }
+      );
+    }
+    if (!this.shouldBringBrowserToFront(options)) {
+      await this.restoreFrontmostApp(previousFrontmostApp);
+    }
     const page = new CdpPage(this, target);
     this.pages.set(page.id, page);
     await page.connect();
@@ -479,11 +633,33 @@ export class BrowserSession extends EventEmitter {
       this.emit("bearer", event);
     });
     if (options.active) {
-      await page.bringToFront({ force: true });
+      await page.bringToFront();
+    }
+    if (!this.shouldBringBrowserToFront(options)) {
+      await this.restoreFrontmostApp(previousFrontmostApp);
     }
     return page;
   }
 
+  async requestUserInteraction(page, reason = "Microsoft 365 requires user interaction") {
+    if (!page) {
+      return false;
+    }
+    const focused = await page.bringToFront({
+      force: true,
+      reason: USER_INTERACTION_FOCUS_REASON
+    });
+    if (focused) {
+      this.logger.warn("[m365connector][browser] brought Edge to foreground:", reason);
+    } else if (this.neverFocusBrowser) {
+      this.logger.warn(
+        "[m365connector][browser] user interaction required but browser focus is disabled:",
+        reason
+      );
+    }
+    return focused;
+  }
+
   async getPage(id) {
     if (this.pages.has(id)) {
       return this.pages.get(id);
@@ -571,11 +747,15 @@ export function installChromeShim(browserSession) {
         if (!page) {
           throw new Error(`Tab not found: ${tabId}`);
         }
+        const previousFrontmostApp = await browserSession.captureFrontmostApp();
         if (updateProperties.url) {
           await page.navigate(updateProperties.url);
         }
         if (updateProperties.active) {
-          await page.bringToFront({ force: true });
+          await page.bringToFront();
+        }
+        if (!updateProperties.active || !browserSession.shouldBringBrowserToFront()) {
+          await browserSession.restoreFrontmostApp(previousFrontmostApp);
         }
         return { id: page.id, url: page.url, status: page.loaded ? "complete" : "loading" };
       },
@@ -626,6 +806,12 @@ export function installChromeShim(browserSession) {
         }
         return results;
       }
+    },
+    m365connector: {
+      async requestUserInteraction(tabId, reason) {
+        const page = await browserSession.getPage(tabId);
+        return browserSession.requestUserInteraction(page, reason);
+      }
     }
   };
 }

package/src/lib/content-reader.js

@@ -1,3 +1,8 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
 let jsZipRef = globalThis.JSZip || null;
 let jsZipLoadPromise = null;
 let jsZipLoadFailed = false;
@@ -40,6 +45,45 @@ function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+function shouldPreserveFrontmostApp() {
+  return process.platform === "darwin" && process.env.M365C_ALLOW_BROWSER_FOCUS !== "1";
+}
+
+async function getFrontmostApplicationName() {
+  if (!shouldPreserveFrontmostApp()) {
+    return null;
+  }
+  try {
+    const { stdout } = await execFileAsync("osascript", [
+      "-e",
+      'tell application "System Events" to get name of first application process whose frontmost is true'
+    ]);
+    const name = stdout.trim();
+    return name || null;
+  } catch (_err) {
+    return null;
+  }
+}
+
+async function restoreFrontmostApplication(name, logger = console) {
+  if (!shouldPreserveFrontmostApp() || !name || name === "Microsoft Edge") {
+    return;
+  }
+  const escapedName = name.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+  const script = [
+    'tell application "System Events"',
+    `  if exists process "${escapedName}" then`,
+    `    set frontmost of process "${escapedName}" to true`,
+    "  end if",
+    "end tell"
+  ].join("\n");
+  try {
+    await execFileAsync("osascript", ["-e", script], { timeout: 3000 });
+  } catch (err) {
+    logger.warn?.("[m365connector] failed to restore frontmost application:", err.message);
+  }
+}
+
 function pickContext(params) {
   if (!params) {
     return null;
@@ -1214,6 +1258,7 @@ export class ContentReader {
 
   async waitForEditorInAnyFrame(tabId, deadline) {
     const pollEnd = Math.min(Date.now() + 60000, deadline);
+    let interactionRequested = false;
 
     while (Date.now() < pollEnd) {
       try {
@@ -1221,6 +1266,23 @@ export class ContentReader {
           target: { tabId, allFrames: true },
           func: () => {
             const host = location.hostname.toLowerCase();
+            const text = document.body?.innerText?.toLowerCase() || "";
+            const path = location.pathname.toLowerCase();
+            if (
+              host === "login.microsoftonline.com"
+              || host === "login.live.com"
+              || path.includes("/common/oauth2")
+              || text.includes("sign in to your account")
+              || text.includes("pick an account")
+              || text.includes("enter password")
+              || text.includes("stay signed in?")
+              || text.includes("verify your identity")
+              || text.includes("approve sign in request")
+              || text.includes("permission requested")
+              || text.includes("permissions requested")
+            ) {
+              return "interaction";
+            }
             if (!host.endsWith(".officeapps.live.com")) {
               return null;
             }
@@ -1239,6 +1301,10 @@ export class ContentReader {
         if (results && results.some((r) => r.result === "ready")) {
           return true;
         }
+        if (!interactionRequested && results && results.some((r) => r.result === "interaction")) {
+          interactionRequested = true;
+          await this.requestUserInteraction(tabId, "Office Online requires Microsoft 365 sign-in or consent");
+        }
       } catch (_err) {
         // Frames may not be ready yet; keep polling.
       }
@@ -1248,6 +1314,18 @@ export class ContentReader {
     return false;
   }
 
+  async requestUserInteraction(tabId, reason) {
+    try {
+      if (chrome.m365connector?.requestUserInteraction) {
+        return await chrome.m365connector.requestUserInteraction(tabId, reason);
+      }
+    } catch (err) {
+      this.logger.warn("[m365connector] failed to request browser user interaction:", err?.message || err);
+    }
+    this.logger.warn("[m365connector] browser user interaction required:", reason);
+    return false;
+  }
+
   /**
    * Scroll through the Word Online document inside the iframe so that all
    * virtually-rendered pages get materialised in the DOM.  Returns the number
@@ -1622,14 +1700,15 @@ export class ContentReader {
     const deadline = Date.now() + DEEP_LINK_BUDGET_MS;
     const editUrl = this.buildOfficeEditUrl(webUrl);
     let tabId = null;
+    const previousFrontmostApp = await getFrontmostApplicationName();
 
     this.#deepLinkActive = true;
     try {
-      const tab = await chrome.tabs.create({ url: editUrl, active: true });
+      const tab = await chrome.tabs.create({ url: editUrl, active: false });
       tabId = tab.id;
 
       await this.waitForTabLoad(tabId, Math.min(15000, deadline - Date.now()));
-      await chrome.tabs.update(tabId, { active: true }).catch(() => null);
+      await chrome.tabs.update(tabId, { active: false }).catch(() => null);
 
       // SharePoint auto-submits the WOPI form into a cross-origin iframe where
       // Word/PowerPoint Online renders.  Wait for the editor to become ready in
@@ -1674,6 +1753,7 @@ export class ContentReader {
           // Ignore if tab already closed.
         }
       }
+      await restoreFrontmostApplication(previousFrontmostApp, this.logger);
     }
   }
 
@@ -1686,6 +1766,7 @@ export class ContentReader {
     let tabId = null;
     let previousActiveTabId = null;
     let activatedForDecryption = false;
+    const previousFrontmostApp = await getFrontmostApplicationName();
     try {
       previousActiveTabId = await this.getActiveTabId();
       const tab = await chrome.tabs.create({ url: deepLink, active: false });
@@ -1707,6 +1788,7 @@ export class ContentReader {
       let sawEncryptedWrapper = false;
       let stableContent = null;
       let followedReadMessageUrl = false;
+      let interactionRequested = false;
       const startedAt = Date.now();
       const pollDeadline = () => sawEncryptedWrapper ? IRM_POLL_MS : BASE_POLL_MS;
 
@@ -1734,6 +1816,21 @@ export class ContentReader {
                 seen.add(bodyText);
                 candidates.push(bodyText);
               }
+              const lowerBodyText = (bodyText || "").toLowerCase();
+              const host = location.hostname.toLowerCase();
+              const userInteractionRequired = Boolean(
+                host === "login.microsoftonline.com"
+                || host === "login.live.com"
+                || location.pathname.toLowerCase().includes("/common/oauth2")
+                || lowerBodyText.includes("sign in to your account")
+                || lowerBodyText.includes("pick an account")
+                || lowerBodyText.includes("enter password")
+                || lowerBodyText.includes("stay signed in?")
+                || lowerBodyText.includes("verify your identity")
+                || lowerBodyText.includes("approve sign in request")
+                || lowerBodyText.includes("permission requested")
+                || lowerBodyText.includes("permissions requested")
+              );
               for (const link of document.querySelectorAll("a[href]")) {
                 const label = `${link.innerText || ""} ${link.getAttribute("aria-label") || ""}`.toLowerCase();
                 const href = String(link.href || "");
@@ -1741,11 +1838,19 @@ export class ContentReader {
                   readMessageUrls.push(href);
                 }
               }
-              return { candidates, readMessageUrls };
+              return { candidates, readMessageUrls, userInteractionRequired };
             },
             args: [EMAIL_SELECTORS]
           });
 
+          if (
+            !interactionRequested
+            && executions?.some((entry) => entry?.result?.userInteractionRequired)
+          ) {
+            interactionRequested = true;
+            await this.requestUserInteraction(tabId, "Outlook requires Microsoft 365 sign-in or consent");
+          }
+
           const extraction = this.selectEmailExtraction(executions);
           if (extraction.encrypted && extraction.readMessageUrl && !followedReadMessageUrl && tabId !== null) {
             followedReadMessageUrl = true;
@@ -1833,6 +1938,7 @@ export class ContentReader {
           // Best-effort; the original tab may have been closed.
         }
       }
+      await restoreFrontmostApplication(previousFrontmostApp, this.logger);
     }
   }
 
@@ -1917,7 +2023,7 @@ export class ContentReader {
 
       chrome.tabs.onUpdated.addListener(onUpdated);
       timeoutId = setTimeout(finish, timeoutMs);
-      Promise.resolve(chrome.tabs.update(tabId, { url, active: true })).catch(finish);
+      Promise.resolve(chrome.tabs.update(tabId, { url, active: false })).catch(finish);
     });
   }
 

package/src/token-providers.js

@@ -578,6 +578,7 @@ export class GraphTokenProvider {
       let lastInfo = null;
       let signInClicked = false;
       let signInDetectCount = 0;
+      let interactionRequested = false;
       while (Date.now() < deadline) {
         if (headerToken && this.#acceptToken(headerToken)) {
           return headerToken;
@@ -625,6 +626,13 @@ export class GraphTokenProvider {
               "[m365connector][graph] clicked Graph Explorer sign-in:",
               JSON.stringify(clickResult?.result || {})
             );
+            if (!clickResult?.result?.clicked && !interactionRequested) {
+              interactionRequested = true;
+              await this.browserSession.requestUserInteraction?.(
+                this.page,
+                "Graph Explorer sign-in is required"
+              );
+            }
             await this.#completeLoginPopup(deadline);
             await sleep(3000);
             continue;
@@ -647,6 +655,8 @@ export class GraphTokenProvider {
 
   async #completeLoginPopup(deadline) {
     let accountClicked = false;
+    let interactionRequested = false;
+    let noAutoResolveCount = 0;
     while (Date.now() < deadline) {
       const loginPage = await this.browserSession.findPage((target) => {
         try {
@@ -669,6 +679,7 @@ export class GraphTokenProvider {
       const info = result?.result || {};
       if (info.clicked) {
         accountClicked = true;
+        noAutoResolveCount = 0;
         const rect = info.rect;
         if (rect && rect.w > 0 && rect.h > 0) {
           await loginPage.clickAt(rect.x + rect.w / 2, rect.y + rect.h / 2).catch(() => {});
@@ -676,6 +687,16 @@ export class GraphTokenProvider {
         this.logger.warn("[m365connector][graph] clicked Microsoft login account:", JSON.stringify(info));
         await sleep(3000);
       } else {
+        noAutoResolveCount += 1;
+        if (!interactionRequested && noAutoResolveCount >= 2) {
+          interactionRequested = true;
+          await this.browserSession.requestUserInteraction?.(
+            loginPage,
+            accountClicked
+              ? "Microsoft login requires additional verification"
+              : "Microsoft login requires user interaction"
+          );
+        }
         await sleep(1000);
       }