@frustrated/ms-graph-mcp 0.1.7 → 0.1.10

package/docs/tools/calendar.md

@@ -1,31 +1,31 @@
-# Calendar Tools
-
-This document details the sub-tools available under the `calendar` top-level tool. These tools allow interaction with the user's Microsoft 365 calendar.
-
-## `calendar.create_event`
-
-Creates a new event in the user's calendar.
-
-### Parameters
-
-*   `subject` (string, required): The subject of the event.
-*   `start` (object, required): The start date and time of the event.
-    *   `dateTime` (string, required): The date and time in ISO 8601 format (e.g., `2026-03-20T09:00:00`).
-    *   `timeZone` (string, required): The time zone of the start time (e.g., `America/Los_Angeles`).
-*   `end` (object, required): The end date and time of the event.
-    *   `dateTime` (string, required): The date and time in ISO 8601 format (e.g., `2026-03-20T10:00:00`).
-    *   `timeZone` (string, required): The time zone of the end time (e.g., `America/Los_Angeles`).
-*   `content` (string, optional): The body content of the event, in HTML format.
-*   `attendees` (array of objects, optional): A list of attendees for the event.
-    *   Each object contains:
-        *   `emailAddress` (string, required): The email address of the attendee.
-        *   `type` (string, required): The attendee type, either `required` or `optional`.
-*   `location` (string, optional): The display name of the event location.
-
-### Returns
-
-An object containing:
-*   `id` (string): The unique identifier of the created event.
-*   `webLink` (string): A URL to open the event in Outlook Web App.
-*   `status` (string): The status of the event creation, either `created` or `failed`.
-*   `errorMessage` (string, optional): An error message if the event creation failed.
+# Calendar Tools
+
+This document details the sub-tools available under the `calendar` top-level tool. These tools allow interaction with the user's Microsoft 365 calendar.
+
+## `calendar.create_event`
+
+Creates a new event in the user's calendar.
+
+### Parameters
+
+*   `subject` (string, required): The subject of the event.
+*   `start` (object, required): The start date and time of the event.
+    *   `dateTime` (string, required): The date and time in ISO 8601 format (e.g., `2026-03-20T09:00:00`).
+    *   `timeZone` (string, required): The time zone of the start time (e.g., `America/Los_Angeles`).
+*   `end` (object, required): The end date and time of the event.
+    *   `dateTime` (string, required): The date and time in ISO 8601 format (e.g., `2026-03-20T10:00:00`).
+    *   `timeZone` (string, required): The time zone of the end time (e.g., `America/Los_Angeles`).
+*   `content` (string, optional): The body content of the event, in HTML format.
+*   `attendees` (array of objects, optional): A list of attendees for the event.
+    *   Each object contains:
+        *   `emailAddress` (string, required): The email address of the attendee.
+        *   `type` (string, required): The attendee type, either `required` or `optional`.
+*   `location` (string, optional): The display name of the event location.
+
+### Returns
+
+An object containing:
+*   `id` (string): The unique identifier of the created event.
+*   `webLink` (string): A URL to open the event in Outlook Web App.
+*   `status` (string): The status of the event creation, either `created` or `failed`.
+*   `errorMessage` (string, optional): An error message if the event creation failed.

package/docs/tools/mail.md

@@ -1,26 +1,26 @@
-# Mail Tools
-
-This document details the sub-tools available under the `mail` top-level tool. These tools allow interaction with the user's Microsoft 365 mailbox.
-
-## `mail.list_messages`
-
-Lists messages from the user's mailbox.
-
-### Parameters
-
-*   `folderId` (string, optional): The ID of the mail folder to retrieve messages from. If not provided, defaults to the inbox (`/me/messages`).
-*   `top` (number, optional): The maximum number of messages to return in the response.
-*   `filter` (string, optional): An OData filter query to apply to the messages (e.g., `isRead eq false`).
-
-### Returns
-
-An object containing:
-*   `messages` (array): A list of message objects, each containing:
-    *   `id` (string): The unique identifier of the message.
-    *   `subject` (string): The subject of the message.
-    *   `from` (object): Information about the sender.
-    *   `receivedDateTime` (string): The date and time the message was received.
-    *   `isRead` (boolean): Indicates whether the message has been read.
-    *   `bodyPreview` (string): A short preview of the message body.
-    *   `webLink` (string): A URL to open the message in Outlook Web App.
-*   `nextLink` (string, optional): A URL to retrieve the next page of messages, if available.
+# Mail Tools
+
+This document details the sub-tools available under the `mail` top-level tool. These tools allow interaction with the user's Microsoft 365 mailbox.
+
+## `mail.list_messages`
+
+Lists messages from the user's mailbox.
+
+### Parameters
+
+*   `folderId` (string, optional): The ID of the mail folder to retrieve messages from. If not provided, defaults to the inbox (`/me/messages`).
+*   `top` (number, optional): The maximum number of messages to return in the response.
+*   `filter` (string, optional): An OData filter query to apply to the messages (e.g., `isRead eq false`).
+
+### Returns
+
+An object containing:
+*   `messages` (array): A list of message objects, each containing:
+    *   `id` (string): The unique identifier of the message.
+    *   `subject` (string): The subject of the message.
+    *   `from` (object): Information about the sender.
+    *   `receivedDateTime` (string): The date and time the message was received.
+    *   `isRead` (boolean): Indicates whether the message has been read.
+    *   `bodyPreview` (string): A short preview of the message body.
+    *   `webLink` (string): A URL to open the message in Outlook Web App.
+*   `nextLink` (string, optional): A URL to retrieve the next page of messages, if available.

package/package.json

@@ -1,45 +1,49 @@
-{
-  "name": "@frustrated/ms-graph-mcp",
-  "version": "0.1.7",
-  "description": "A JSR-based TypeScript MCP package for personal Microsoft Graph access via CLI",
-  "type": "module",
-  "main": "./src/index.ts",
-  "bin": {
-    "ms-graph-mcp": "./src/index.ts"
-  },
-  "exports": {
-    ".": "./src/index.ts"
-  },
-  "scripts": {
-    "dev": "bun run src/index.ts",
-    "test": "bun test",
-    "typecheck": "bun run tsc --noEmit"
-  },
-  "nodeModulesDir": "auto",
-  "imports": {
-    "@azure/msal-node": "npm:@azure/msal-node@^3.0.0",
-    "@microsoft/microsoft-graph-client": "npm:@microsoft/microsoft-graph-client@^3.0.0",
-    "@commander-js/extra-typings": "npm:@commander-js/extra-typings@^14.0.0"
-  },
-  "dependencies": {
-    "@azure/msal-node": "^3.0.0",
-    "@microsoft/microsoft-graph-client": "^3.0.0",
-    "@commander-js/extra-typings": "^14.0.0"
-  },
-  "publish": {
-    "include": [
-      "src/",
-      "README.md",
-      "LICENSE"
-    ]
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/usually-frustrated/ms-graph-mcp.git"
-  },
-  "devDependencies": {
-    "bun-types": "latest",
-    "typescript": "^5.3.0",
-    "@types/node": "^20.10.0"
-  }
-}
+{
+  "name": "@frustrated/ms-graph-mcp",
+  "version": "0.1.10",
+  "description": "A JSR-based TypeScript MCP package for personal Microsoft Graph access via CLI",
+  "type": "module",
+  "main": "./src/index.ts",
+  "bin": {
+    "ms-graph-mcp": "./src/index.ts"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "dev": "bun run src/index.ts",
+    "test": "bun test",
+    "typecheck": "bun run tsc --noEmit"
+  },
+  "nodeModulesDir": "auto",
+  "imports": {
+    "@azure/msal-node": "npm:@azure/msal-node@^3.0.0",
+    "@microsoft/microsoft-graph-client": "npm:@microsoft/microsoft-graph-client@^3.0.0",
+    "@commander-js/extra-typings": "npm:@commander-js/extra-typings@^14.0.0",
+    "@modelcontextprotocol/sdk": "npm:@modelcontextprotocol/sdk@^1.28.0",
+    "zod": "npm:zod@^3.24.2"
+  },
+  "dependencies": {
+    "@azure/msal-node": "^3.0.0",
+    "@microsoft/microsoft-graph-client": "^3.0.0",
+    "@commander-js/extra-typings": "^14.0.0",
+    "@modelcontextprotocol/sdk": "^1.28.0",
+    "zod": "^3.24.2"
+  },
+  "publish": {
+    "include": [
+      "src/",
+      "README.md",
+      "LICENSE"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/usually-frustrated/ms-graph-mcp.git"
+  },
+  "devDependencies": {
+    "bun-types": "latest",
+    "typescript": "^5.3.0",
+    "@types/node": "^20.10.0"
+  }
+}

package/src/auth.ts

@@ -1,199 +1,194 @@
-import {
-  PublicClientApplication,
-  Configuration,
-  LogLevel,
-  CryptoProvider,
-} from "@azure/msal-node";
-import { AddressInfo } from "node:net";
-import { promises as fs } from "node:fs";
-import * as path from "node:path";
-import * as os from "node:os";
-import { createServer } from "node:http";
-
-const MSAL_CONFIG: Configuration = {
-  auth: {
-    clientId: "0a74e52a-4d5b-4005-8dad-6b7cf45ec5fe", // Replace with actual Client ID
-    authority: "https://login.microsoftonline.com/common",
-  },
-  system: {
-    loggerOptions: {
-      loggerCallback(loglevel, message, containsPii) {
-        console.log(message);
-      },
-      piiLoggingEnabled: false,
-      logLevel: LogLevel.Verbose,
-    },
-  },
-};
-
-const REDIRECT_URI_PATH = "/auth-callback";
-const TOKEN_CACHE_FILE = path.join(
-  os.homedir(),
-  ".config",
-  "ms-graph-mcp",
-  "msal_cache.json",
-);
-const SCOPES = [
-  "User.Read",
-  "Mail.ReadWrite",
-  "Calendars.ReadWrite",
-  "Files.ReadWrite.All",
-  "offline_access",
-];
-
-const pca = new PublicClientApplication(MSAL_CONFIG);
-
-async function saveTokenCache() {
-  const serialized = pca.getTokenCache().serialize();
-  await fs.mkdir(path.dirname(TOKEN_CACHE_FILE), { recursive: true });
-  await fs.writeFile(TOKEN_CACHE_FILE, serialized, { mode: 0o600 });
-}
-
-async function loadTokenCache(): Promise<boolean> {
-  try {
-    const data = await fs.readFile(TOKEN_CACHE_FILE, "utf-8");
-    pca.getTokenCache().deserialize(data);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-export async function initAuth(): Promise<void> {
-  console.log("Initiating Microsoft Graph authentication...");
-  console.log(
-    "Please ensure you have registered a multi-tenant application in Azure AD with the following redirect URI: http://localhost:PORT/auth-callback",
-  );
-
-  const cryptoProvider = new CryptoProvider();
-  const pkceCodes = await cryptoProvider.generatePkceCodes();
-
-  const authCodeUrlParameters = {
-    scopes: SCOPES,
-    redirectUri: `http://localhost:0${REDIRECT_URI_PATH}`,
-    codeChallenge: pkceCodes.challenge,
-    codeChallengeMethod: "S256" as const,
-  };
-
-  const authCodeUrl = await pca.getAuthCodeUrl(authCodeUrlParameters);
-
-  return new Promise((resolve, reject) => {
-    const server = createServer(async (req, res) => {
-      if (req.url?.startsWith(REDIRECT_URI_PATH)) {
-        const url = new URL(`http://localhost${req.url}`);
-        const code = url.searchParams.get("code");
-
-        if (code) {
-          try {
-            const addr = server.address() as AddressInfo;
-            const tokenResult = await pca.acquireTokenByCode({
-              code,
-              scopes: SCOPES,
-              redirectUri: `http://localhost:${addr.port}${REDIRECT_URI_PATH}`,
-              codeVerifier: pkceCodes.verifier,
-            });
-
-            if (tokenResult) {
-              await saveTokenCache();
-              res.writeHead(200, { "Content-Type": "text/plain" });
-              res.end("Authentication successful! You can close this window.");
-              console.log("Authentication successful. Tokens saved securely.");
-              server.close(() => resolve());
-            } else {
-              throw new Error(
-                "Authentication failed: no token result received.",
-              );
-            }
-          } catch (error) {
-            console.error("Error acquiring token:", error);
-            res.writeHead(500, { "Content-Type": "text/plain" });
-            res.end("Authentication failed. Check console for details.");
-            server.close(() => reject(error));
-          }
-        } else {
-          res.writeHead(400, { "Content-Type": "text/plain" });
-          res.end("Authorization code not found in redirect.");
-          server.close(() =>
-            reject(new Error("Authorization code not found.")),
-          );
-        }
-      } else {
-        res.writeHead(404, { "Content-Type": "text/plain" });
-        res.end("Not Found");
-      }
-    });
-
-    server.listen(0, () => {
-      const addr = server.address() as AddressInfo;
-      const finalRedirectUri = `http://localhost:${addr.port}${REDIRECT_URI_PATH}`;
-      const finalAuthUrl = authCodeUrl.replace(
-        `http://localhost:0${REDIRECT_URI_PATH}`,
-        finalRedirectUri,
-      );
-      console.log(
-        `\nOpen this URL in your browser to authenticate:\n\n  ${finalAuthUrl}\n`,
-      );
-    });
-
-    server.on("error", (err) => {
-      console.error("Server error:", err);
-      reject(err);
-    });
-  });
-}
-
-export async function getAccessToken(): Promise<string> {
-  await loadTokenCache();
-
-  const accounts = await pca.getAllAccounts();
-  if (accounts.length === 0) {
-    throw new Error("No account found. Please run `ms-graph-mcp init` first.");
-  }
-
-  try {
-    const tokenResult = await pca.acquireTokenSilent({
-      account: accounts[0],
-      scopes: SCOPES,
-    });
-
-    if (!tokenResult) {
-      throw new Error("Failed to acquire access token silently.");
-    }
-
-    await saveTokenCache();
-    return tokenResult.accessToken;
-  } catch (error) {
-    console.error("Error refreshing token:", error);
-    await fs.unlink(TOKEN_CACHE_FILE).catch(() => {});
-    throw new Error(
-      "Failed to refresh access token. Please re-authenticate using `ms-graph-mcp init`.",
-    );
-  }
-}
-
-export async function revokeAuth(): Promise<void> {
-  try {
-    await fs.unlink(TOKEN_CACHE_FILE).catch(() => {});
-    console.log("Authentication revoked. All tokens cleared.");
-  } catch (error) {
-    console.error("Error revoking authentication:", error);
-    throw error;
-  }
-}
-
-export async function getAuthStatus(): Promise<{
-  clientId: string;
-  tenantId: string;
-  isAuthenticated: boolean;
-}> {
-  await loadTokenCache();
-  const accounts = await pca.getAllAccounts();
-  const isAuthenticated = accounts.length > 0;
-  const authority =
-    MSAL_CONFIG.auth.authority ?? "https://login.microsoftonline.com/common";
-  return {
-    clientId: MSAL_CONFIG.auth.clientId,
-    tenantId: authority.split("/").pop() || "common",
-    isAuthenticated,
-  };
-}
+import {
+  PublicClientApplication,
+  Configuration,
+  LogLevel,
+  CryptoProvider,
+} from "@azure/msal-node";
+import { AddressInfo } from "node:net";
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { createServer } from "node:http";
+
+const MSAL_CONFIG: Configuration = {
+  auth: {
+    clientId: "0a74e52a-4d5b-4005-8dad-6b7cf45ec5fe", // Replace with actual Client ID
+    authority: "https://login.microsoftonline.com/common",
+  },
+  system: {
+    loggerOptions: {
+      loggerCallback(loglevel, message, containsPii) {
+        console.log(message);
+      },
+      piiLoggingEnabled: false,
+      logLevel: LogLevel.Verbose,
+    },
+  },
+};
+
+const REDIRECT_URI_PATH = "/auth-callback";
+const TOKEN_CACHE_FILE = path.join(
+  os.homedir(),
+  ".config",
+  "ms-graph-mcp",
+  "msal_cache.json",
+);
+const SCOPES = [
+  "User.Read",
+  "Mail.ReadWrite",
+  "Calendars.ReadWrite",
+  "Files.ReadWrite.All",
+  "offline_access",
+];
+
+const pca = new PublicClientApplication(MSAL_CONFIG);
+
+async function saveTokenCache() {
+  const serialized = pca.getTokenCache().serialize();
+  await fs.mkdir(path.dirname(TOKEN_CACHE_FILE), { recursive: true });
+  await fs.writeFile(TOKEN_CACHE_FILE, serialized, { mode: 0o600 });
+}
+
+async function loadTokenCache(): Promise<boolean> {
+  try {
+    const data = await fs.readFile(TOKEN_CACHE_FILE, "utf-8");
+    pca.getTokenCache().deserialize(data);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function initAuth(): Promise<void> {
+  console.log("Initiating Microsoft Graph authentication...");
+
+  const cryptoProvider = new CryptoProvider();
+  const pkceCodes = await cryptoProvider.generatePkceCodes();
+
+  return new Promise((resolve, reject) => {
+    const server = createServer(async (req, res) => {
+      if (req.url?.startsWith(REDIRECT_URI_PATH)) {
+        const url = new URL(`http://localhost${req.url}`);
+        const code = url.searchParams.get("code");
+
+        if (code) {
+          try {
+            const addr = server.address() as AddressInfo;
+            const redirectUri = `http://localhost:${addr.port}${REDIRECT_URI_PATH}`;
+            const tokenResult = await pca.acquireTokenByCode({
+              code,
+              scopes: SCOPES,
+              redirectUri,
+              codeVerifier: pkceCodes.verifier,
+            });
+
+            if (tokenResult) {
+              await saveTokenCache();
+              res.writeHead(200, { "Content-Type": "text/plain" });
+              res.end("Authentication successful! You can close this window.");
+              console.log("Authentication successful. Tokens saved securely.");
+              server.close(() => resolve());
+            } else {
+              throw new Error(
+                "Authentication failed: no token result received.",
+              );
+            }
+          } catch (error) {
+            console.error("Error acquiring token:", error);
+            res.writeHead(500, { "Content-Type": "text/plain" });
+            res.end("Authentication failed. Check console for details.");
+            server.close(() => reject(error));
+          }
+        } else {
+          res.writeHead(400, { "Content-Type": "text/plain" });
+          res.end("Authorization code not found in redirect.");
+          server.close(() =>
+            reject(new Error("Authorization code not found.")),
+          );
+        }
+      } else {
+        res.writeHead(404, { "Content-Type": "text/plain" });
+        res.end("Not Found");
+      }
+    });
+
+    server.listen(0, async () => {
+      try {
+        const addr = server.address() as AddressInfo;
+        const redirectUri = `http://localhost:${addr.port}${REDIRECT_URI_PATH}`;
+        const authCodeUrl = await pca.getAuthCodeUrl({
+          scopes: SCOPES,
+          redirectUri,
+          codeChallenge: pkceCodes.challenge,
+          codeChallengeMethod: "S256" as const,
+        });
+        console.log(
+          `\nOpen this URL in your browser to authenticate:\n\n  ${authCodeUrl}\n`,
+        );
+      } catch (err) {
+        server.close(() => reject(err));
+      }
+    });
+
+    server.on("error", (err) => {
+      console.error("Server error:", err);
+      reject(err);
+    });
+  });
+}
+
+export async function getAccessToken(): Promise<string> {
+  await loadTokenCache();
+
+  const accounts = await pca.getAllAccounts();
+  if (accounts.length === 0) {
+    throw new Error("No account found. Please run `ms-graph-mcp init` first.");
+  }
+
+  try {
+    const tokenResult = await pca.acquireTokenSilent({
+      account: accounts[0],
+      scopes: SCOPES,
+    });
+
+    if (!tokenResult) {
+      throw new Error("Failed to acquire access token silently.");
+    }
+
+    await saveTokenCache();
+    return tokenResult.accessToken;
+  } catch (error) {
+    console.error("Error refreshing token:", error);
+    await fs.unlink(TOKEN_CACHE_FILE).catch(() => {});
+    throw new Error(
+      "Failed to refresh access token. Please re-authenticate using `ms-graph-mcp init`.",
+    );
+  }
+}
+
+export async function revokeAuth(): Promise<void> {
+  try {
+    await fs.unlink(TOKEN_CACHE_FILE).catch(() => {});
+    console.log("Authentication revoked. All tokens cleared.");
+  } catch (error) {
+    console.error("Error revoking authentication:", error);
+    throw error;
+  }
+}
+
+export async function getAuthStatus(): Promise<{
+  clientId: string;
+  tenantId: string;
+  isAuthenticated: boolean;
+}> {
+  await loadTokenCache();
+  const accounts = await pca.getAllAccounts();
+  const isAuthenticated = accounts.length > 0;
+  const authority =
+    MSAL_CONFIG.auth.authority ?? "https://login.microsoftonline.com/common";
+  return {
+    clientId: MSAL_CONFIG.auth.clientId,
+    tenantId: authority.split("/").pop() || "common",
+    isAuthenticated,
+  };
+}