@bold-tech-npm/graph-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bold Tech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,61 @@
+# @bold-tech-npm/graph-mcp
+
+A small [MCP](https://modelcontextprotocol.io) server that exposes **Microsoft Graph** (Outlook)
+to an AI client, with two things most Graph connectors get wrong:
+
+- **Device-code auth** — no client secret, no redirect URI. The signed-in user consents in a
+  browser; the server acts *as that user* (delegated, security-trimmed), so it only ever sees what
+  they're permitted to see.
+- **Smart inbox reads** — an overnight burst of long, multi-message threads is collapsed to **one
+  item per thread** (by `conversationId` *or* normalized subject), with unread and date-window
+  filters, so the model gets a clean list instead of a confusing pile.
+
+Configuration is entirely via environment variables, so one published package serves many
+tenants/clients.
+
+## Configure
+
+| Env var | Required | Default | Notes |
+|---|---|---|---|
+| `GRAPH_CLIENT_ID` | ✅ | — | Entra app registration (public client, device-code enabled) |
+| `GRAPH_TENANT_ID` | ✅ | — | The tenant that owns the mailbox |
+| `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)
+
+```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.
+
+## Use from an MCP client / plugin
+
+```json
+{
+  "mcpServers": {
+    "graph": {
+      "command": "npx",
+      "args": ["-y", "@bold-tech-npm/graph-mcp"],
+      "env": {
+        "GRAPH_CLIENT_ID": "…",
+        "GRAPH_TENANT_ID": "…",
+        "GRAPH_SCOPES": "User.Read,Mail.ReadWrite"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Scope | Description |
+|---|---|---|
+| `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) |
+| `create_reply_draft` | `Mail.ReadWrite` | Reply-draft into an existing thread (never sends) |
+
+Draft tools require `Mail.ReadWrite` in `GRAPH_SCOPES`; with a read-only token they return a clear
+permission error rather than failing silently.

package/dist/auth.js

@@ -0,0 +1,50 @@
+import { PublicClientApplication } from "@azure/msal-node";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { getConfig } from "./config.js";
+function cachePlugin(file) {
+    return {
+        beforeCacheAccess: async (ctx) => {
+            if (existsSync(file))
+                ctx.tokenCache.deserialize(readFileSync(file, "utf8"));
+        },
+        afterCacheAccess: async (ctx) => {
+            if (ctx.cacheHasChanged) {
+                mkdirSync(dirname(file), { recursive: true });
+                writeFileSync(file, ctx.tokenCache.serialize(), { mode: 0o600 });
+            }
+        },
+    };
+}
+function client() {
+    const { clientId, tenantId, cacheFile } = getConfig();
+    return new PublicClientApplication({
+        auth: { clientId, authority: `https://login.microsoftonline.com/${tenantId}` },
+        cache: { cachePlugin: cachePlugin(cacheFile) },
+    });
+}
+/** Interactive device-code sign-in. Caches tokens for later silent use. */
+export async function deviceLogin(onMessage) {
+    const { scopes } = getConfig();
+    const result = await client().acquireTokenByDeviceCode({
+        scopes,
+        deviceCodeCallback: (r) => onMessage(r.message),
+    });
+    if (!result?.account)
+        throw new Error("Device-code login returned no account.");
+    return result.account.username;
+}
+/** Silent token for tool calls. Throws a clear instruction if not signed in. */
+export async function getToken() {
+    const { scopes } = getConfig();
+    const pca = client();
+    const accounts = await pca.getTokenCache().getAllAccounts();
+    if (accounts.length === 0) {
+        throw new Error("Not signed in. Run:  npx -y @bold-tech-npm/graph-mcp login  (with GRAPH_CLIENT_ID and GRAPH_TENANT_ID set).");
+    }
+    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.");
+    }
+    return result.accessToken;
+}

package/dist/cli.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/**
+ * @bold-tech/graph-mcp entry point.
+ *
+ *   graph-mcp          → run the MCP server over stdio
+ *   graph-mcp login    → interactive device-code sign-in (once per tenant)
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerTools } from "./tools.js";
+import { deviceLogin } from "./auth.js";
+async function main() {
+    if (process.argv[2] === "login") {
+        const user = await deviceLogin((message) => console.log(message));
+        console.log(`\n✓ Signed in as ${user}. Token cached — the MCP server can now run silently.`);
+        return;
+    }
+    const server = new McpServer({ name: "bold-tech-graph", version: "0.1.0" });
+    registerTools(server);
+    await server.connect(new StdioServerTransport());
+    // stderr only — stdout is the MCP channel.
+    console.error("[graph-mcp] running on stdio");
+}
+main().catch((err) => {
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(1);
+});

package/dist/config.js

@@ -0,0 +1,18 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+/** Read configuration from the environment. Everything is per-invocation so one
+ * published package can serve many tenants. */
+export function getConfig() {
+    const clientId = process.env.GRAPH_CLIENT_ID;
+    const tenantId = process.env.GRAPH_TENANT_ID;
+    if (!clientId || !tenantId) {
+        throw new Error("Missing GRAPH_CLIENT_ID and/or GRAPH_TENANT_ID. Set them in the MCP server's env (see README).");
+    }
+    const scopes = (process.env.GRAPH_SCOPES ?? "User.Read,Mail.Read")
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    const cacheFile = process.env.GRAPH_TOKEN_CACHE ??
+        join(homedir(), ".bold-tech", "graph-mcp", tenantId, "tokens.json");
+    return { clientId, tenantId, scopes, cacheFile };
+}

package/dist/graph.js

@@ -0,0 +1,19 @@
+import { getToken } 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 res = await fetch(`${BASE}${path}`, {
+        ...init,
+        headers: {
+            Authorization: `Bearer ${token}`,
+            "Content-Type": "application/json",
+            ...(init?.headers ?? {}),
+        },
+    });
+    if (!res.ok) {
+        const body = (await res.text()).slice(0, 400);
+        throw new Error(`Graph ${init?.method ?? "GET"} ${path} -> ${res.status} ${body}`);
+    }
+    return res.status === 204 ? null : res.json();
+}

package/dist/tools.js

@@ -0,0 +1,82 @@
+import { z } from "zod";
+import { graph } from "./graph.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) }],
+});
+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("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
+            .number()
+            .optional()
+            .describe("Only messages received within the last N hours (e.g. 16 for an overnight window)."),
+        collapseThreads: z
+            .boolean()
+            .optional()
+            .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);
+        }
+        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 });
+    });
+    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 });
+    });
+    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 });
+    });
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@bold-tech-npm/graph-mcp",
+  "version": "0.1.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": {
+    "graph-mcp": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "login": "node dist/cli.js login"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "microsoft-graph",
+    "outlook",
+    "m365",
+    "office365",
+    "email"
+  ],
+  "license": "MIT",
+  "author": "Bold Tech",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@azure/msal-node": "^2.16.2",
+    "@modelcontextprotocol/sdk": "^1.11.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.9.0",
+    "typescript": "^5.6.3"
+  }
+}