@bold-tech-npm/graph-mcp 0.1.0 → 0.2.0

package/README.md

@@ -22,13 +22,18 @@ tenants/clients.
 | `GRAPH_SCOPES` | | `User.Read,Mail.Read` | Add `Mail.ReadWrite` to enable draft tools |
 | `GRAPH_TOKEN_CACHE` | | `~/.bold-tech/graph-mcp/<tenant>/tokens.json` | Per-tenant token cache |
 
-## Sign in (once per tenant)
+## Sign in
 
+**Preferred — in-conversation (no terminal):** the AI client calls the **`connect`** tool, which
+returns a verification URL + code; the user opens it, signs in, and **`auth_status`** confirms.
+Nothing to run in a shell. This is the flow to use inside a plugin.
+
+**Alternative — CLI (for scripts/CI):**
 ```bash
 GRAPH_CLIENT_ID=… GRAPH_TENANT_ID=… npx -y @bold-tech-npm/graph-mcp login
 ```
 
-Follow the printed URL + code. Tokens cache per-tenant, so multiple clients coexist on one machine.
+Either way, tokens cache per-tenant, so multiple clients coexist on one machine.
 
 ## Use from an MCP client / plugin
 
@@ -52,6 +57,8 @@ Follow the printed URL + code. Tokens cache per-tenant, so multiple clients coex
 
 | Tool | Scope | Description |
 |---|---|---|
+| `connect` | — | Start/confirm sign-in; returns a verification URL + code (or "connected") |
+| `auth_status` | — | Sign-in status: connected / pending (URL + code) / not_connected |
 | `whoami` | `User.Read` | The signed-in user (proves the auth chain) |
 | `inbox_list` | `Mail.Read` | Inbox messages with unread/date filters and thread collapse |
 | `create_draft` | `Mail.ReadWrite` | Create an email draft (never sends) |

package/dist/auth.js

@@ -1,6 +1,7 @@
 import { PublicClientApplication } from "@azure/msal-node";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
+import { spawn } from "node:child_process";
 import { getConfig } from "./config.js";
 function cachePlugin(file) {
     return {
@@ -44,7 +45,125 @@ export async function getToken() {
     }
     const result = await pca.acquireTokenSilent({ account: accounts[0], scopes });
     if (!result?.accessToken) {
-        throw new Error("Could not acquire a token silently — sign in again with the `login` command.");
+        throw new Error("Could not acquire a token silently — sign in again (call `connect`).");
     }
     return result.accessToken;
 }
+/** Username if a valid cached session exists, else null. */
+export async function currentUser() {
+    const { scopes } = getConfig();
+    const pca = client();
+    const accounts = await pca.getTokenCache().getAllAccounts();
+    if (accounts.length === 0)
+        return null;
+    try {
+        const result = await pca.acquireTokenSilent({ account: accounts[0], scopes });
+        return result?.account?.username ?? accounts[0].username;
+    }
+    catch {
+        return null;
+    }
+}
+let pending = null;
+/** The in-flight device-code login, if any (cleared once expired). */
+export function getPending() {
+    if (pending && !pending.done && !pending.error && Date.now() > pending.expiresAt)
+        pending = null;
+    return pending;
+}
+/**
+ * Begin a device-code sign-in WITHOUT blocking. Returns as soon as the code is
+ * issued; the login then completes in the background (this process stays alive as
+ * an MCP server) and caches the token. Poll `currentUser()` / `getPending()` after.
+ */
+export async function beginDeviceLogin() {
+    const { scopes } = getConfig();
+    const pca = client();
+    pending = null;
+    const promise = pca.acquireTokenByDeviceCode({
+        scopes,
+        deviceCodeCallback: (r) => {
+            pending = {
+                verificationUri: r.verificationUri,
+                userCode: r.userCode,
+                expiresAt: Date.now() + r.expiresIn * 1000,
+                done: false,
+            };
+        },
+    });
+    promise
+        .then(() => {
+        if (pending)
+            pending.done = true;
+    })
+        .catch((e) => {
+        if (pending)
+            pending.error = e instanceof Error ? e.message : String(e);
+    });
+    const start = Date.now();
+    while (!getPending() && Date.now() - start < 15000) {
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    const issued = getPending();
+    if (!issued)
+        throw new Error("Device code was not issued (network or config problem).");
+    openBrowser(issued.verificationUri);
+    return issued;
+}
+/** Best-effort open of a URL in the user's default browser. No-op in headless envs. */
+export function openBrowser(url) {
+    try {
+        if (process.platform === "win32") {
+            spawn("cmd", ["/c", "start", "", url], { detached: true, stdio: "ignore" }).unref();
+        }
+        else {
+            const opener = process.platform === "darwin" ? "open" : "xdg-open";
+            spawn(opener, [url], { detached: true, stdio: "ignore" }).unref();
+        }
+    }
+    catch {
+        /* headless / no browser — the caller still returns the URL + code */
+    }
+}
+/** Thrown when there's no session; carries the device-code prompt for the caller. */
+export class AuthRequiredError extends Error {
+    verificationUri;
+    userCode;
+    constructor(verificationUri, userCode) {
+        super(`Not signed in. Open ${verificationUri} and enter code ${userCode}.`);
+        this.verificationUri = verificationUri;
+        this.userCode = userCode;
+        this.name = "AuthRequiredError";
+    }
+}
+/** Silent token if a session exists, else null (no throw). */
+async function trySilentToken() {
+    const { scopes } = getConfig();
+    const pca = client();
+    const accounts = await pca.getTokenCache().getAllAccounts();
+    if (accounts.length === 0)
+        return null;
+    try {
+        const result = await pca.acquireTokenSilent({ account: accounts[0], scopes });
+        return result?.accessToken ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Token for a tool call — or auto-start sign-in. If there's no session, begin the
+ * device-code flow (auto-opening the browser) and throw AuthRequiredError with the
+ * code so the tool can tell the user how to finish. Reuses an in-flight login.
+ */
+export async function getTokenOrBegin() {
+    const token = await trySilentToken();
+    if (token)
+        return token;
+    const existing = getPending();
+    if (existing && !existing.done && !existing.error) {
+        throw new AuthRequiredError(existing.verificationUri, existing.userCode);
+    }
+    const p = await beginDeviceLogin();
+    throw new AuthRequiredError(p.verificationUri, p.userCode);
+}

package/dist/graph.js

@@ -1,8 +1,8 @@
-import { getToken } from "./auth.js";
+import { getTokenOrBegin } from "./auth.js";
 const BASE = "https://graph.microsoft.com/v1.0";
 /** Thin authenticated Graph fetch. Returns parsed JSON, or null for 204. */
 export async function graph(path, init) {
-    const token = await getToken();
+    const token = await getTokenOrBegin();
     const res = await fetch(`${BASE}${path}`, {
         ...init,
         headers: {

package/dist/tools.js

@@ -1,12 +1,56 @@
 import { z } from "zod";
 import { graph } from "./graph.js";
+import { AuthRequiredError, beginDeviceLogin, currentUser, getPending } from "./auth.js";
 /** Strip leading Re:/Fw:/Fwd: (and I:/R:/Aw: variants) so replies group with their thread. */
 const normSubject = (s) => (s || "").replace(/^((re|fw|fwd|r|i|aw)\s*:\s*)+/i, "").trim().toLowerCase();
 const text = (value) => ({
     content: [{ type: "text", text: JSON.stringify(value) }],
 });
+/** In a graph tool's catch: turn a missing session into a friendly auth prompt; rethrow the rest. */
+const authText = (e) => {
+    if (e instanceof AuthRequiredError) {
+        return text({
+            status: "auth_required",
+            verificationUri: e.verificationUri,
+            userCode: e.userCode,
+            message: `Not signed in — I've opened the Microsoft sign-in page. Enter code ${e.userCode} and approve, then retry.`,
+        });
+    }
+    throw e;
+};
 export function registerTools(server) {
-    server.tool("whoami", "Return the signed-in Microsoft 365 user. Proves the auth chain.", {}, async () => text(await graph("/me?$select=displayName,userPrincipalName,mail")));
+    server.tool("connect", "Start (or confirm) Microsoft 365 sign-in for this mailbox. If already signed in, returns the user. Otherwise opens the sign-in page in the browser and returns the verification URL + code; call `auth_status` afterward to confirm. This is the entire connect flow — no terminal command needed.", {}, async () => {
+        const user = await currentUser();
+        if (user)
+            return text({ status: "connected", user });
+        const p = await beginDeviceLogin();
+        return text({
+            status: "pending",
+            verificationUri: p.verificationUri,
+            userCode: p.userCode,
+            instructions: `A browser should have opened. Enter code ${p.userCode} at ${p.verificationUri} and sign in, then call auth_status.`,
+        });
+    });
+    server.tool("auth_status", "Report Microsoft 365 sign-in status: connected (with the user), pending (with the URL + code still to enter), or not_connected.", {}, async () => {
+        const user = await currentUser();
+        if (user)
+            return text({ status: "connected", user });
+        const p = getPending();
+        if (p?.error)
+            return text({ status: "error", error: p.error });
+        if (p && !p.done) {
+            return text({ status: "pending", verificationUri: p.verificationUri, userCode: p.userCode });
+        }
+        return text({ status: "not_connected", hint: "Call connect to start sign-in." });
+    });
+    server.tool("whoami", "Return the signed-in Microsoft 365 user. Proves the auth chain.", {}, async () => {
+        try {
+            return text(await graph("/me?$select=displayName,userPrincipalName,mail"));
+        }
+        catch (e) {
+            return authText(e);
+        }
+    });
     server.tool("inbox_list", "List Inbox messages, newest first, with optional unread and date-window filters. When collapseThreads is true (default) it returns ONE item per thread — grouping by conversationId OR normalized subject and keeping the latest message — so an overnight burst of long threads becomes a clean, deal-mappable list instead of a confusing pile.", {
         unreadOnly: z.boolean().optional().describe("Only messages the user has not read yet."),
         sinceHours: z
@@ -19,64 +63,79 @@ export function registerTools(server) {
             .describe("Collapse each thread to its latest message. Default true."),
         top: z.number().optional().describe("Max messages to fetch before filtering. Default 60."),
     }, async ({ unreadOnly, sinceHours, collapseThreads, top }) => {
-        const data = await graph(`/me/mailFolders/inbox/messages?$top=${top ?? 60}&$select=subject,from,receivedDateTime,isRead,conversationId,bodyPreview`);
-        let msgs = data.value ?? [];
-        if (unreadOnly)
-            msgs = msgs.filter((m) => m.isRead === false);
-        if (sinceHours) {
-            const cutoff = Date.now() - sinceHours * 3600_000;
-            msgs = msgs.filter((m) => Date.parse(m.receivedDateTime) >= cutoff);
+        try {
+            const data = await graph(`/me/mailFolders/inbox/messages?$top=${top ?? 60}&$select=subject,from,receivedDateTime,isRead,conversationId,bodyPreview`);
+            let msgs = data.value ?? [];
+            if (unreadOnly)
+                msgs = msgs.filter((m) => m.isRead === false);
+            if (sinceHours) {
+                const cutoff = Date.now() - sinceHours * 3600_000;
+                msgs = msgs.filter((m) => Date.parse(m.receivedDateTime) >= cutoff);
+            }
+            msgs.sort((a, b) => (a.receivedDateTime < b.receivedDateTime ? 1 : -1));
+            if (collapseThreads === false) {
+                return text({ total: msgs.length, messages: msgs });
+            }
+            const byThread = new Map();
+            for (const m of msgs) {
+                const key = normSubject(m.subject) || m.conversationId || m.id;
+                const group = byThread.get(key);
+                if (group)
+                    group.push(m);
+                else
+                    byThread.set(key, [m]);
+            }
+            const threads = [...byThread.values()].map((group) => {
+                group.sort((a, b) => (a.receivedDateTime < b.receivedDateTime ? 1 : -1));
+                const latest = group[0];
+                return {
+                    count: group.length,
+                    from: latest.from?.emailAddress?.address ?? null,
+                    subject: latest.subject,
+                    receivedDateTime: latest.receivedDateTime,
+                    preview: latest.bodyPreview,
+                    messageId: latest.id,
+                };
+            });
+            return text({ totalMessages: msgs.length, threads: threads.length, items: threads });
         }
-        msgs.sort((a, b) => (a.receivedDateTime < b.receivedDateTime ? 1 : -1));
-        if (collapseThreads === false) {
-            return text({ total: msgs.length, messages: msgs });
+        catch (e) {
+            return authText(e);
         }
-        const byThread = new Map();
-        for (const m of msgs) {
-            const key = normSubject(m.subject) || m.conversationId || m.id;
-            const group = byThread.get(key);
-            if (group)
-                group.push(m);
-            else
-                byThread.set(key, [m]);
-        }
-        const threads = [...byThread.values()].map((group) => {
-            group.sort((a, b) => (a.receivedDateTime < b.receivedDateTime ? 1 : -1));
-            const latest = group[0];
-            return {
-                count: group.length,
-                from: latest.from?.emailAddress?.address ?? null,
-                subject: latest.subject,
-                receivedDateTime: latest.receivedDateTime,
-                preview: latest.bodyPreview,
-                messageId: latest.id,
-            };
-        });
-        return text({ totalMessages: msgs.length, threads: threads.length, items: threads });
     });
     server.tool("create_draft", "Create a new email draft in the signed-in mailbox. Requires Mail.ReadWrite. NEVER sends.", {
         to: z.array(z.string()).describe("Recipient email addresses."),
         subject: z.string(),
         body: z.string().describe("HTML or plain-text body."),
     }, async ({ to, subject, body }) => {
-        const draft = await graph("/me/messages", {
-            method: "POST",
-            body: JSON.stringify({
-                subject,
-                body: { contentType: "HTML", content: body },
-                toRecipients: to.map((address) => ({ emailAddress: { address } })),
-            }),
-        });
-        return text({ id: draft.id, webLink: draft.webLink });
+        try {
+            const draft = await graph("/me/messages", {
+                method: "POST",
+                body: JSON.stringify({
+                    subject,
+                    body: { contentType: "HTML", content: body },
+                    toRecipients: to.map((address) => ({ emailAddress: { address } })),
+                }),
+            });
+            return text({ id: draft.id, webLink: draft.webLink });
+        }
+        catch (e) {
+            return authText(e);
+        }
     });
     server.tool("create_reply_draft", "Create a reply DRAFT to an existing message (keeps the thread). Requires Mail.ReadWrite. NEVER sends.", {
         messageId: z.string().describe("The id of the message to reply to (from inbox_list)."),
         comment: z.string().describe("The reply body to prepend above the quoted thread."),
     }, async ({ messageId, comment }) => {
-        const draft = await graph(`/me/messages/${messageId}/createReply`, {
-            method: "POST",
-            body: JSON.stringify({ comment }),
-        });
-        return text({ id: draft.id, webLink: draft.webLink });
+        try {
+            const draft = await graph(`/me/messages/${messageId}/createReply`, {
+                method: "POST",
+                body: JSON.stringify({ comment }),
+            });
+            return text({ id: draft.id, webLink: draft.webLink });
+        }
+        catch (e) {
+            return authText(e);
+        }
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bold-tech-npm/graph-mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Microsoft Graph MCP server with device-code auth and smart inbox reads (unread + date filter, thread collapse by conversation or normalized subject). By Bold Tech.",
   "type": "module",
   "bin": {
@@ -27,6 +27,14 @@
   ],
   "license": "MIT",
   "author": "Bold Tech",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Mitchel-BT/graph-mcp.git"
+  },
+  "homepage": "https://github.com/Mitchel-BT/graph-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/Mitchel-BT/graph-mcp/issues"
+  },
   "publishConfig": {
     "access": "public"
   },