@alfe.ai/microsoft-mcp 0.1.0

package/README.md

@@ -0,0 +1,16 @@
+# @alfe.ai/microsoft-mcp
+
+Microsoft 365 MCP server — multi-account Microsoft Graph access using Alfe OAuth credentials with server-mediated token refresh
+
+Part of [**Alfe**](https://alfe.ai) — the operating system for AI agents: build, deploy, and run agents with persistent memory, identity, integrations, and channels. See the [documentation](https://docs.alfe.ai) to get started.
+
+## Install
+
+```bash
+npm install @alfe.ai/microsoft-mcp
+```
+
+## Links
+
+- 🌐 Website: <https://alfe.ai>
+- 📚 Docs: <https://docs.alfe.ai>

package/dist/server.d.ts

@@ -0,0 +1,54 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+//#region src/server.d.ts
+
+interface MicrosoftAccountInfo {
+  connectionId: string;
+  accountIdentifier: string;
+  email: string;
+  displayName?: string;
+  connectedAt?: string;
+  microsoftTenantId?: string;
+  accessToken: string;
+  accessTokenExpiresAt: string;
+}
+declare function tokenIsExpired(account: MicrosoftAccountInfo): boolean;
+interface GraphRequestSpec {
+  method: string;
+  path: string;
+  body?: unknown;
+}
+/**
+ * Parse the `command` string into a Graph request. Accepts a compact
+ * "METHOD /path" line (optionally followed by a JSON body), so the LLM can
+ * express any Graph operation the way it would a curl call:
+ *   - "GET /me/messages?$top=5"
+ *   - "GET /me"
+ *   - "POST /me/sendMail {\"message\":{...}}"
+ * A bare "/path" (or "me/messages") is treated as a GET.
+ */
+declare function parseCommand(command: string): GraphRequestSpec;
+/**
+ * Resolve a relative Graph path to an absolute graph.microsoft.com URL and
+ * assert the host cannot have been escaped. Defense-in-depth alongside
+ * parseCommand's absolute/protocol-relative rejection — the bearer token must
+ * never be sent anywhere but graph.microsoft.com.
+ */
+declare function resolveGraphUrl(path: string): string;
+declare function createServer(): McpServer;
+/**
+ * True when this module is the process entrypoint — i.e. `process.argv[1]`
+ * resolves to the same real file as `import.meta.url`. Used to start the stdio
+ * server only when spawned via `npx -y @alfe.ai/microsoft-mcp` / the `bin`, and
+ * to stay quiet (importable) under a test runner.
+ *
+ * CRITICAL: both sides MUST be realpath-resolved before comparing. npm/pnpm/npx
+ * install a package `bin` as a SYMLINK in a `.bin` dir, so when spawned via
+ * `npx`, `process.argv[1]` is that symlink (…/.bin/microsoft-mcp-proxy) while
+ * `import.meta.url` is the realpath target (…/dist/server.js). A plain `===` /
+ * `endsWith` check fails on that mismatch → main() never runs → the server
+ * starts and exits without connecting its transport (green-but-dead).
+ */
+declare function isProcessEntrypoint(argvPath: string | undefined, metaUrl: string): boolean;
+//#endregion
+export { MicrosoftAccountInfo, createServer, isProcessEntrypoint, parseCommand, resolveGraphUrl, tokenIsExpired };

package/dist/server.js

@@ -0,0 +1,299 @@
+#!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { resolveConfig } from "@alfe.ai/config";
+import { AgentApiClient } from "@alfe.ai/agent-api-client";
+//#region src/server.ts
+/**
+* @alfe.ai/microsoft-mcp — self-contained Microsoft 365 MCP server
+*
+* A runtime-agnostic stdio MCP server (works on OpenClaw AND Hermes) that gives
+* an agent multi-account Microsoft 365 access. Declared via the manifest's
+* top-level `mcp_servers:` block (`command: npx, args: [-y, @alfe.ai/microsoft-mcp@x]`,
+* `requires_credentials: microsoft`), like every other OAuth provider
+* (Notion / Xero / GitHub / Atlassian / MYOB).
+*
+* Tools (multi-account by design — every credential-touching tool requires an
+* explicit `email` so the LLM picks the target account per call):
+*   - microsoft_list_accounts        — list connected Microsoft 365 accounts
+*   - microsoft_run_command          — run a Microsoft Graph request (requires email)
+*   - microsoft_disconnect_account   — disconnect an account (requires email)
+*
+* ── Why self-contained (not a proxy around an upstream MCP) ────────────────
+* Notion/Xero/etc. WRAP an official upstream MCP server that accepts an
+* injected credential. Microsoft has NO suitable upstream MCP that accepts an
+* injected DELEGATED access token — the community M365 MCP servers do their
+* own device/browser OAuth. So this server exposes its own tools and calls
+* `graph.microsoft.com` REST directly.
+*
+* ── Why direct Graph REST, not the `mgc` CLI ───────────────────────────────
+* The Google Workspace sibling shells out to `gws` because `gws` accepts a
+* hand-written `authorized_user` refresh-token file and self-refreshes
+* non-interactively. `mgc` (Microsoft Graph CLI) does NOT: its auth strategies
+* are DeviceCode / InteractiveBrowser (both need a human at a browser —
+* impossible on a headless agent VM) and ClientCertificate / Environment /
+* ManagedIdentity (all APP-ONLY client-credentials, which need admin-consented
+* *application* permissions, not the DELEGATED authorization-code refresh token
+* our connect flow produces). mgc persists tokens in a proprietary MSAL binary
+* cache (needs a keyring on headless Linux) with no hand-writable credentials
+* file and no config-dir override env var — so per-account isolation via config
+* dirs (the gws pattern) is impossible.
+*
+* Token refresh is server-mediated: the connect backend owns token refresh
+* (`refreshMicrosoftAccountToken`) so the client secret never leaves the server
+* and per-(tenant,user) refresh-token rotation stays server-side.
+*/
+const GRAPH_BASE = "https://graph.microsoft.com/v1.0";
+const TOKEN_SKEW_MS = 120 * 1e3;
+let client = null;
+let cachedAccounts = [];
+function log(msg) {
+	process.stderr.write(`[microsoft-mcp] ${msg}\n`);
+}
+function getClient() {
+	if (!client) {
+		const config = resolveConfig();
+		client = new AgentApiClient({
+			apiKey: config.apiKey,
+			apiUrl: config.apiUrl
+		});
+	}
+	return client;
+}
+async function refreshAccountCache() {
+	cachedAccounts = (await getClient().getMicrosoftAccounts()).accounts.map((a) => ({
+		connectionId: a.connectionId,
+		accountIdentifier: a.accountIdentifier,
+		email: a.email,
+		displayName: a.displayName ?? void 0,
+		connectedAt: a.connectedAt,
+		microsoftTenantId: a.microsoftTenantId || void 0,
+		accessToken: a.accessToken,
+		accessTokenExpiresAt: a.accessTokenExpiresAt
+	}));
+	return cachedAccounts;
+}
+function findAccount(email) {
+	const account = cachedAccounts.find((a) => a.email === email || a.accountIdentifier === email);
+	if (!account) throw new Error(`Microsoft account "${email}" not found. Available: ${cachedAccounts.map((a) => a.email).join(", ")}`);
+	return account;
+}
+/**
+* Resolve an account by email (or accountIdentifier), refreshing the cache once
+* if it's not already there. This server is long-lived, so an account connected
+* AFTER the last cache fill would otherwise be invisible until a
+* microsoft_list_accounts call — this closes that stale window. Throws
+* findAccount's descriptive error if the account still isn't found after a refresh.
+*/
+async function resolveAccount(email) {
+	const hit = cachedAccounts.find((a) => a.email === email || a.accountIdentifier === email);
+	if (hit) return hit;
+	await refreshAccountCache();
+	return findAccount(email);
+}
+function tokenIsExpired(account) {
+	if (!account.accessToken) return true;
+	if (!account.accessTokenExpiresAt) return false;
+	const expiresAt = Date.parse(account.accessTokenExpiresAt);
+	if (Number.isNaN(expiresAt)) return false;
+	return expiresAt - Date.now() <= TOKEN_SKEW_MS;
+}
+/**
+* Returns a currently-valid access token for the account, refreshing it via the
+* connect service (which owns the client secret + refresh-token rotation) when
+* the cached token is missing or near expiry. Setting `force` bypasses the
+* expiry check — used to recover from a 401 on a token we believed was valid.
+*/
+async function ensureAccessToken(account, force = false) {
+	if (!force && !tokenIsExpired(account)) return account.accessToken;
+	const refreshed = await getClient().refreshMicrosoftAccountToken(account.accountIdentifier);
+	account.accessToken = refreshed.accessToken;
+	account.accessTokenExpiresAt = refreshed.accessTokenExpiresAt;
+	return account.accessToken;
+}
+/**
+* Parse the `command` string into a Graph request. Accepts a compact
+* "METHOD /path" line (optionally followed by a JSON body), so the LLM can
+* express any Graph operation the way it would a curl call:
+*   - "GET /me/messages?$top=5"
+*   - "GET /me"
+*   - "POST /me/sendMail {\"message\":{...}}"
+* A bare "/path" (or "me/messages") is treated as a GET.
+*/
+function parseCommand(command) {
+	const trimmed = command.trim();
+	if (!trimmed) throw new Error("Command cannot be empty");
+	const methodMatch = /^(GET|POST|PATCH|PUT|DELETE)\s+(.*)$/is.exec(trimmed);
+	let method = "GET";
+	let rest = trimmed;
+	if (methodMatch) {
+		method = methodMatch[1].toUpperCase();
+		rest = methodMatch[2].trim();
+	}
+	let path = rest;
+	let body;
+	const bodyStart = rest.search(/[{[]/);
+	if (bodyStart > 0) {
+		path = rest.slice(0, bodyStart).trim();
+		const rawBody = rest.slice(bodyStart).trim();
+		try {
+			body = JSON.parse(rawBody);
+		} catch {
+			throw new Error(`Invalid JSON body in command: ${rawBody.slice(0, 120)}`);
+		}
+	}
+	path = path.trim();
+	if (!path) throw new Error("Command must include a Graph path (e.g. 'GET /me/messages')");
+	if (/^[a-z][a-z0-9+.-]*:/i.test(path) || path.startsWith("//")) throw new Error("Graph path must be a relative path (e.g. '/me/messages'), not an absolute or protocol-relative URL");
+	if (!path.startsWith("/")) path = `/${path}`;
+	return {
+		method,
+		path,
+		body
+	};
+}
+/**
+* Resolve a relative Graph path to an absolute graph.microsoft.com URL and
+* assert the host cannot have been escaped. Defense-in-depth alongside
+* parseCommand's absolute/protocol-relative rejection — the bearer token must
+* never be sent anywhere but graph.microsoft.com.
+*/
+function resolveGraphUrl(path) {
+	const url = `${GRAPH_BASE}${path.startsWith("/") ? path : `/${path}`}`;
+	let hostname;
+	try {
+		hostname = new URL(url).hostname;
+	} catch {
+		throw new Error(`Invalid Graph path: ${path.slice(0, 120)}`);
+	}
+	if (hostname.toLowerCase() !== "graph.microsoft.com") throw new Error(`Refusing to send a Microsoft token to non-Graph host: ${hostname}`);
+	return url;
+}
+async function graphRequest(account, spec) {
+	const url = resolveGraphUrl(spec.path);
+	const doFetch = async (token) => fetch(url, {
+		method: spec.method,
+		headers: {
+			Authorization: `Bearer ${token}`,
+			...spec.body !== void 0 ? { "Content-Type": "application/json" } : {}
+		},
+		...spec.body !== void 0 ? { body: JSON.stringify(spec.body) } : {}
+	});
+	let token = await ensureAccessToken(account);
+	let response = await doFetch(token);
+	if (response.status === 401) {
+		token = await ensureAccessToken(account, true);
+		response = await doFetch(token);
+	}
+	const text = await response.text();
+	let data = text;
+	if (text) try {
+		data = JSON.parse(text);
+	} catch {}
+	else data = null;
+	return {
+		status: response.status,
+		ok: response.ok,
+		data
+	};
+}
+function jsonResult(data) {
+	return { content: [{
+		type: "text",
+		text: JSON.stringify(data)
+	}] };
+}
+function createServer() {
+	const server = new McpServer({
+		name: "microsoft-mcp",
+		version: "0.0.1"
+	});
+	const registerTool = server.registerTool.bind(server);
+	registerTool("microsoft_list_accounts", {
+		description: "List all connected Microsoft 365 accounts. Shows email, display name, and when each account was connected. Use this to resolve which account to target (e.g., 'Kevin's mail' → kevin@contoso.com) before calling microsoft_run_command.",
+		inputSchema: {}
+	}, async () => {
+		const accounts = await refreshAccountCache();
+		return jsonResult({
+			accounts: accounts.map((a) => ({
+				email: a.email,
+				displayName: a.displayName,
+				connectedAt: a.connectedAt
+			})),
+			count: accounts.length
+		});
+	});
+	registerTool("microsoft_run_command", {
+		description: "Call the Microsoft Graph API for a specific Microsoft 365 account. The `command` is a Graph REST request line — an optional HTTP method, a Graph path (relative to https://graph.microsoft.com/v1.0), and an optional JSON body. Email is required — call microsoft_list_accounts first if you don't know which account to use. Examples: microsoft_run_command({ command: 'GET /me/messages?$top=5&$select=subject,from,receivedDateTime', email: 'kevin@contoso.com' }); microsoft_run_command({ command: 'GET /me/calendarView?startDateTime=2026-07-08T00:00:00Z&endDateTime=2026-07-09T00:00:00Z', email: 'kevin@contoso.com' }); microsoft_run_command({ command: 'POST /me/sendMail {\"message\":{\"subject\":\"Hi\",\"body\":{\"contentType\":\"Text\",\"content\":\"Hello\"},\"toRecipients\":[{\"emailAddress\":{\"address\":\"a@b.com\"}}]}}', email: 'kevin@contoso.com' }). A bare path with no method is treated as GET.",
+		inputSchema: {
+			command: z.string().describe("The Graph request: '[METHOD] /path [json-body]'. Method defaults to GET. Path is relative to https://graph.microsoft.com/v1.0 (e.g. '/me/messages')."),
+			email: z.string().describe("Email of the Microsoft 365 account to use. Required — there is no implicit default.")
+		}
+	}, async ({ command, email }) => {
+		const account = await resolveAccount(email);
+		const spec = parseCommand(command);
+		const result = await graphRequest(account, spec);
+		return jsonResult({
+			account: account.email,
+			request: `${spec.method} ${spec.path}`,
+			status: result.status,
+			ok: result.ok,
+			data: result.data
+		});
+	});
+	registerTool("microsoft_disconnect_account", {
+		description: "Disconnect a specific Microsoft 365 account from this agent. Revokes the connection and removes the account.",
+		inputSchema: { email: z.string().describe("Email of the Microsoft 365 account to disconnect") }
+	}, async ({ email }) => {
+		const account = await resolveAccount(email);
+		const result = await getClient().disconnectMicrosoftAccount(account.accountIdentifier);
+		await refreshAccountCache();
+		return jsonResult({
+			message: `${account.email} has been disconnected`,
+			remainingAccounts: result.accounts
+		});
+	});
+	return server;
+}
+async function main() {
+	const server = createServer();
+	try {
+		const accounts = await refreshAccountCache();
+		log(`Cached ${String(accounts.length)} Microsoft account(s): ${accounts.map((a) => a.email).join(", ")}`);
+	} catch (err) {
+		log(`Failed to pre-cache Microsoft accounts (will fetch on demand): ${err instanceof Error ? err.message : String(err)}`);
+	}
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+	log("Microsoft 365 MCP server running (multi-account, direct Graph REST)");
+}
+/**
+* True when this module is the process entrypoint — i.e. `process.argv[1]`
+* resolves to the same real file as `import.meta.url`. Used to start the stdio
+* server only when spawned via `npx -y @alfe.ai/microsoft-mcp` / the `bin`, and
+* to stay quiet (importable) under a test runner.
+*
+* CRITICAL: both sides MUST be realpath-resolved before comparing. npm/pnpm/npx
+* install a package `bin` as a SYMLINK in a `.bin` dir, so when spawned via
+* `npx`, `process.argv[1]` is that symlink (…/.bin/microsoft-mcp-proxy) while
+* `import.meta.url` is the realpath target (…/dist/server.js). A plain `===` /
+* `endsWith` check fails on that mismatch → main() never runs → the server
+* starts and exits without connecting its transport (green-but-dead).
+*/
+function isProcessEntrypoint(argvPath, metaUrl) {
+	try {
+		if (!argvPath) return false;
+		return pathToFileURL(realpathSync(argvPath)).href === pathToFileURL(realpathSync(fileURLToPath(metaUrl))).href;
+	} catch {
+		return false;
+	}
+}
+if (isProcessEntrypoint(process.argv[1], import.meta.url)) main().catch((err) => {
+	log(`Fatal: ${err instanceof Error ? err.message : String(err)}`);
+	process.exit(1);
+});
+//#endregion
+export { createServer, isProcessEntrypoint, parseCommand, resolveGraphUrl, tokenIsExpired };

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@alfe.ai/microsoft-mcp",
+  "version": "0.1.0",
+  "description": "Microsoft 365 MCP server — multi-account Microsoft Graph access using Alfe OAuth credentials with server-mediated token refresh",
+  "type": "module",
+  "main": "./dist/server.js",
+  "bin": {
+    "microsoft-mcp-proxy": "./dist/server.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": ">=1.24.0",
+    "zod": "^4.0.5",
+    "@alfe.ai/config": "0.3.0",
+    "@alfe.ai/agent-api-client": "0.9.0"
+  },
+  "license": "UNLICENSED",
+  "homepage": "https://alfe.ai",
+  "author": "Alfe (https://alfe.ai)",
+  "keywords": [
+    "alfe",
+    "ai-agents",
+    "agent",
+    "llm",
+    "mcp",
+    "model-context-protocol"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run"
+  }
+}