outlook-reader-mcp 1.0.0

package/README.md

@@ -0,0 +1,74 @@
+# outlook-reader-mcp
+
+MCP (Model Context Protocol) server for reading Outlook / Microsoft 365 mail through Microsoft Graph. Read-only by design: list, search, and fetch emails — single or batched — and download attachments safely to disk.
+
+## Tools
+
+| Tool                   | Description                                                                         |
+| ---------------------- | ----------------------------------------------------------------------------------- |
+| `authenticate`         | Sign in with a device code shown directly in the chat; reports current account      |
+| `sign_out`             | Remove the cached session from this machine; cancels any pending sign-in            |
+| `list_emails`          | List emails from any folder with OData filters, ordering, and paging (`top`/`skip`) |
+| `search_emails`        | Keyword search across subject, body, sender, and recipients                         |
+| `get_email`            | Full content of one email (plain-text body)                                         |
+| `get_emails`           | Full content of up to 50 emails in one batched Graph request                        |
+| `list_folders`         | Mail folders with unread/total counts                                               |
+| `list_attachments`     | Attachment IDs, names, sizes, and types for an email                                |
+| `download_attachment`  | Save one attachment to disk                                                         |
+| `download_attachments` | Save several (or all) attachments of an email in one call                           |
+
+## Setup
+
+### 1. Create an Azure app registration
+
+1. Go to [Azure Portal → App registrations](https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade) → **New registration**.
+2. Supported account types: pick what fits — "Personal Microsoft accounts only" for outlook.com/hotmail mailboxes, or an org option for Microsoft 365.
+3. No redirect URI needed. After creating, under **Authentication** enable **Allow public client flows**.
+4. Under **API permissions** add delegated Microsoft Graph permissions: `Mail.Read`, `User.Read`.
+5. Copy the **Application (client) ID**.
+
+### 2. Configure your MCP client
+
+```json
+{
+  "mcpServers": {
+    "outlook-reader": {
+      "command": "npx",
+      "args": ["-y", "outlook-reader-mcp"],
+      "env": {
+        "CLIENT_ID": "your-application-client-id",
+        "TENANT_ID": "consumers"
+      }
+    }
+  }
+}
+```
+
+`TENANT_ID`: `consumers` for personal accounts, `organizations` or your tenant GUID for work accounts, `common` (default) for both.
+
+Optional: `OUTLOOK_ACCOUNT=you@example.com` pins which cached account to use if several have signed in.
+
+### 3. First run
+
+Ask your assistant to run the `authenticate` tool (or just ask it to read your mail — any tool that needs auth will tell it to). The chat shows a URL and a one-time code: open the URL, enter the code, sign in. Sessions are cached, so this only happens once per machine.
+
+## Token cache & security
+
+- Tokens are cached per user in the OS application-data directory (`%LOCALAPPDATA%\outlook-reader-mcp` on Windows, `~/Library/Application Support/outlook-reader-mcp` on macOS, `$XDG_CONFIG_HOME/outlook-reader-mcp` on Linux).
+- The cache is encrypted at rest with the OS credential store (DPAPI / Keychain / libsecret). If no store is available it falls back to a permission-restricted plaintext file and warns on stderr.
+- Scopes are read-only (`Mail.Read`); this server cannot send, modify, or delete mail.
+- Attachment filenames are sanitized (path traversal, reserved characters) before writing to disk, and existing files are never overwritten.
+- To revoke access: remove the app under [account.live.com/consent/Manage](https://account.live.com/consent/Manage) (personal) or have your admin revoke sessions, then delete the cache directory.
+
+## Development
+
+```bash
+npm install
+npm run mcp      # run from source (tsx)
+npm run build    # compile to dist/
+npm run format   # prettier
+```
+
+## License
+
+GPL-3.0

package/dist/auth.js

@@ -0,0 +1,219 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthRequiredError = void 0;
+exports.getConfig = getConfig;
+exports.startDeviceCodeAuth = startDeviceCodeAuth;
+exports.clearAuth = clearAuth;
+exports.getSignedInAccount = getSignedInAccount;
+exports.getAccessToken = getAccessToken;
+const fs_1 = __importDefault(require("fs"));
+const os_1 = require("os");
+const path_1 = __importDefault(require("path"));
+const msal_node_1 = require("@azure/msal-node");
+const msal_node_extensions_1 = require("@azure/msal-node-extensions");
+const SCOPES = ['Mail.Read', 'User.Read'];
+const APP_DIR_NAME = 'outlook-reader-mcp';
+function getConfig() {
+    const clientId = process.env.CLIENT_ID;
+    if (!clientId) {
+        throw new Error('CLIENT_ID environment variable is required. Create an Azure app registration ' +
+            '(public client, device code flow, Mail.Read + User.Read delegated permissions) ' +
+            'and set CLIENT_ID to its application ID.');
+    }
+    return { clientId, tenantId: process.env.TENANT_ID ?? 'common' };
+}
+/**
+ * Per-user OS data directory. The token cache must never live inside the
+ * package or a project folder: it would be world-shared on global installs
+ * and one `git add -f` away from being published.
+ */
+function cacheDir() {
+    if (process.platform === 'win32') {
+        return path_1.default.join(process.env.LOCALAPPDATA ?? path_1.default.join((0, os_1.homedir)(), 'AppData', 'Local'), APP_DIR_NAME);
+    }
+    if (process.platform === 'darwin') {
+        return path_1.default.join((0, os_1.homedir)(), 'Library', 'Application Support', APP_DIR_NAME);
+    }
+    return path_1.default.join(process.env.XDG_CONFIG_HOME ?? path_1.default.join((0, os_1.homedir)(), '.config'), APP_DIR_NAME);
+}
+/**
+ * Encrypted-at-rest persistence: DPAPI on Windows, Keychain on macOS,
+ * libsecret on Linux. Falls back to a plaintext file (chmod 600 where
+ * supported) only if the platform store is unavailable.
+ */
+async function createPersistence(cachePath) {
+    try {
+        return await msal_node_extensions_1.PersistenceCreator.createPersistence({
+            cachePath,
+            dataProtectionScope: msal_node_extensions_1.DataProtectionScope.CurrentUser,
+            serviceName: APP_DIR_NAME,
+            accountName: 'msal-token-cache',
+            usePlaintextFileOnLinux: false,
+        });
+    }
+    catch (err) {
+        console.error(`Warning: OS-level token encryption unavailable (${err instanceof Error ? err.message : err}). ` +
+            `Falling back to a plaintext token cache at ${cachePath} — protect this file.`);
+        const persistence = await msal_node_extensions_1.FilePersistence.create(cachePath);
+        if (process.platform !== 'win32') {
+            fs_1.default.chmodSync(cachePath, 0o600);
+        }
+        return persistence;
+    }
+}
+let msalAppPromise = null;
+let cachedToken = null;
+function buildMsalApp() {
+    if (msalAppPromise)
+        return msalAppPromise;
+    msalAppPromise = (async () => {
+        const { clientId, tenantId } = getConfig();
+        const dir = cacheDir();
+        fs_1.default.mkdirSync(dir, { recursive: true });
+        const persistence = await createPersistence(path_1.default.join(dir, 'token_cache.bin'));
+        return new msal_node_1.PublicClientApplication({
+            auth: {
+                clientId,
+                authority: `https://login.microsoftonline.com/${tenantId}`,
+            },
+            cache: { cachePlugin: new msal_node_extensions_1.PersistenceCachePlugin(persistence) },
+        });
+    })();
+    return msalAppPromise;
+}
+function pickAccount(accounts) {
+    const hint = process.env.OUTLOOK_ACCOUNT?.toLowerCase();
+    const account = hint
+        ? (accounts.find((a) => a.username.toLowerCase() === hint) ?? accounts[0])
+        : accounts[0];
+    if (accounts.length > 1 ||
+        (hint && account.username.toLowerCase() !== hint)) {
+        console.error(`Using cached account: ${account.username}`);
+    }
+    return account;
+}
+/**
+ * Thrown when a request needs the user to sign in. Tool handlers surface the
+ * message as tool output so the model can tell the user exactly what to do —
+ * auth must never silently block inside a tool call.
+ */
+class AuthRequiredError extends Error {
+}
+exports.AuthRequiredError = AuthRequiredError;
+let pendingAuth = null;
+// Held so sign_out can abort an in-flight device code flow: MSAL checks
+// request.cancel between polls.
+let pendingRequest = null;
+function rememberToken(result) {
+    cachedToken = {
+        token: result.accessToken,
+        expiresOn: result.expiresOn?.getTime() ?? Date.now() + 5 * 60_000,
+    };
+}
+/**
+ * Kicks off the device code flow and resolves as soon as the verification
+ * URL + code are available, while MSAL keeps polling in the background.
+ * Calling again while a code is still valid returns the same code.
+ */
+async function startDeviceCodeAuth() {
+    if (pendingAuth && Date.now() < pendingAuth.expiresAt) {
+        return pendingAuth.verification;
+    }
+    const app = await buildMsalApp();
+    return new Promise((resolve, reject) => {
+        const request = {
+            scopes: SCOPES,
+            deviceCodeCallback: (response) => {
+                pendingAuth = {
+                    verification: response.message,
+                    expiresAt: Date.now() + response.expiresIn * 1000,
+                };
+                // Also mirror to the server log.
+                console.error(response.message);
+                resolve(response.message);
+            },
+        };
+        pendingRequest = request;
+        app
+            .acquireTokenByDeviceCode(request)
+            .then((result) => {
+            if (result) {
+                rememberToken(result);
+                console.error(`Signed in as ${result.account?.username ?? 'unknown account'}.`);
+            }
+        })
+            .catch((err) => {
+            // Reaches the tool only if the flow failed before the code was
+            // issued; after resolve() this is a no-op and the error is logged.
+            reject(err);
+            console.error(`Device code sign-in did not complete: ${err instanceof Error ? err.message : err}`);
+        })
+            .finally(() => {
+            pendingAuth = null;
+            pendingRequest = null;
+        });
+    });
+}
+/**
+ * Signs out: cancels any in-flight device code flow, drops the in-memory
+ * token, and removes all accounts from the persistent cache. Returns the
+ * usernames that were removed.
+ */
+async function clearAuth() {
+    cachedToken = null;
+    if (pendingRequest) {
+        pendingRequest.cancel = true;
+        pendingRequest = null;
+    }
+    pendingAuth = null;
+    const app = await buildMsalApp();
+    const cache = app.getTokenCache();
+    const accounts = await cache.getAllAccounts();
+    for (const account of accounts) {
+        await cache.removeAccount(account);
+    }
+    return accounts.map((a) => a.username);
+}
+/** Username of the signed-in account, or null when not authenticated. */
+async function getSignedInAccount() {
+    const app = await buildMsalApp();
+    const accounts = await app.getTokenCache().getAllAccounts();
+    return accounts.length > 0 ? pickAccount(accounts).username : null;
+}
+async function getAccessToken() {
+    // Reuse the in-memory token until shortly before expiry to avoid
+    // hitting the MSAL cache (and the OS credential store) on every request.
+    if (cachedToken && Date.now() < cachedToken.expiresOn - 60_000) {
+        return cachedToken.token;
+    }
+    const app = await buildMsalApp();
+    const accounts = await app.getTokenCache().getAllAccounts();
+    if (accounts.length === 0) {
+        if (pendingAuth && Date.now() < pendingAuth.expiresAt) {
+            throw new AuthRequiredError(`Sign-in is still pending. ${pendingAuth.verification} Retry this request after signing in.`);
+        }
+        throw new AuthRequiredError('Not signed in to a Microsoft account. Run the authenticate tool first, ' +
+            'then retry this request.');
+    }
+    const account = pickAccount(accounts);
+    let result;
+    try {
+        result = await app.acquireTokenSilent({ account, scopes: SCOPES });
+    }
+    catch (err) {
+        if (!(err instanceof msal_node_1.InteractionRequiredAuthError))
+            throw err;
+        // Refresh token expired or revoked: drop the stale account so the next
+        // authenticate run starts clean instead of looping on silent failures.
+        await app.getTokenCache().removeAccount(account);
+        throw new AuthRequiredError(`The cached session for ${account.username} has expired or was revoked. ` +
+            'Run the authenticate tool to sign in again, then retry this request.');
+    }
+    if (!result)
+        throw new Error('Token acquisition returned no result.');
+    rememberToken(result);
+    return cachedToken.token;
+}

package/dist/files.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sanitizeFilename = sanitizeFilename;
+exports.uniquePath = uniquePath;
+const fs_1 = require("fs");
+const path_1 = require("path");
+/**
+ * Attachment names come from the email sender, so they must be treated as
+ * untrusted input: strip any path components (prevents `..\` traversal),
+ * control characters, and characters Windows rejects in filenames.
+ */
+function sanitizeFilename(name) {
+    const base = Array.from((0, path_1.basename)(name ?? ''))
+        .filter((c) => c.charCodeAt(0) >= 32)
+        .join('')
+        .replace(/[<>:"/\\|?*]/g, '_')
+        .replace(/^[. ]+|[. ]+$/g, '');
+    return base || 'attachment';
+}
+/** Returns a path in `dir` that doesn't collide with an existing file. */
+function uniquePath(dir, filename) {
+    let candidate = (0, path_1.join)(dir, filename);
+    if (!(0, fs_1.existsSync)(candidate))
+        return candidate;
+    const ext = (0, path_1.extname)(filename);
+    const stem = filename.slice(0, filename.length - ext.length);
+    for (let i = 1;; i++) {
+        candidate = (0, path_1.join)(dir, `${stem} (${i})${ext}`);
+        if (!(0, fs_1.existsSync)(candidate))
+            return candidate;
+    }
+}

package/dist/mail.js

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listEmails = listEmails;
+exports.listFolders = listFolders;
+exports.getEmail = getEmail;
+exports.getEmails = getEmails;
+exports.searchEmails = searchEmails;
+exports.listAttachments = listAttachments;
+exports.downloadAttachment = downloadAttachment;
+const microsoft_graph_client_1 = require("@microsoft/microsoft-graph-client");
+const auth_1 = require("./auth");
+let client = null;
+function buildClient() {
+    if (client)
+        return client;
+    client = microsoft_graph_client_1.Client.initWithMiddleware({
+        authProvider: { getAccessToken: auth_1.getAccessToken },
+    });
+    return client;
+}
+const LIST_FIELDS = 'id,subject,from,receivedDateTime,isRead,hasAttachments,bodyPreview';
+const DETAIL_FIELDS = 'id,subject,from,toRecipients,receivedDateTime,hasAttachments,body';
+const PREFER_TEXT_BODY = 'outlook.body-content-type="text"';
+async function listEmails(options = {}) {
+    const { top = 10, skip, filter, folder = 'inbox', orderby = 'receivedDateTime desc', } = options;
+    const client = buildClient();
+    let req = client
+        .api(`/me/mailFolders/${encodeURIComponent(folder)}/messages`)
+        .top(top)
+        .orderby(orderby)
+        .select(LIST_FIELDS);
+    if (skip)
+        req = req.skip(skip);
+    if (filter)
+        req = req.filter(filter);
+    const res = await req.get();
+    return res.value;
+}
+async function listFolders() {
+    const client = buildClient();
+    const res = await client
+        .api('/me/mailFolders')
+        .select('id,displayName,unreadItemCount,totalItemCount')
+        .top(50)
+        .get();
+    return res.value;
+}
+async function getEmail(id) {
+    const client = buildClient();
+    return client
+        .api(`/me/messages/${encodeURIComponent(id)}`)
+        .header('Prefer', PREFER_TEXT_BODY)
+        .select(DETAIL_FIELDS)
+        .get();
+}
+async function getEmails(ids) {
+    const client = buildClient();
+    const results = [];
+    // Graph JSON batching allows max 20 sub-requests per call.
+    for (let i = 0; i < ids.length; i += 20) {
+        const chunk = ids.slice(i, i + 20);
+        const batch = {
+            requests: chunk.map((id, idx) => ({
+                id: String(idx),
+                method: 'GET',
+                url: `/me/messages/${encodeURIComponent(id)}?$select=${DETAIL_FIELDS}`,
+                headers: { Prefer: PREFER_TEXT_BODY },
+            })),
+        };
+        const res = await client.api('/$batch').post(batch);
+        // Responses come back in arbitrary order; re-align to input order via id.
+        const byId = new Map(res.responses.map((r) => [r.id, r]));
+        chunk.forEach((id, idx) => {
+            const r = byId.get(String(idx));
+            if (r && r.status >= 200 && r.status < 300) {
+                results.push({ ok: true, message: r.body });
+            }
+            else {
+                const errBody = r?.body;
+                results.push({
+                    ok: false,
+                    id,
+                    error: `HTTP ${r?.status ?? '?'}: ${errBody?.error?.message ?? 'request failed'}`,
+                });
+            }
+        });
+    }
+    return results;
+}
+async function searchEmails(query, top = 10) {
+    const client = buildClient();
+    // Escape embedded quotes so user input can't break the $search phrase syntax.
+    const safeQuery = query.replace(/"/g, '\\"');
+    const res = await client
+        .api('/me/messages')
+        .search(`"${safeQuery}"`)
+        .top(top)
+        .select(LIST_FIELDS)
+        .get();
+    return res.value;
+}
+async function listAttachments(messageId) {
+    const client = buildClient();
+    const res = await client
+        .api(`/me/messages/${encodeURIComponent(messageId)}/attachments`)
+        .select('id,name,size,contentType,isInline')
+        .get();
+    return res.value;
+}
+async function downloadAttachment(messageId, attachmentId) {
+    const client = buildClient();
+    const att = await client
+        .api(`/me/messages/${encodeURIComponent(messageId)}/attachments/${encodeURIComponent(attachmentId)}`)
+        .get();
+    return {
+        name: att.name,
+        contentBytes: att.contentBytes,
+        contentType: att.contentType,
+    };
+}

package/dist/mcp-server.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+require("dotenv/config");
+const auth_js_1 = require("./auth.js");
+const index_js_1 = require("./tools/index.js");
+async function main() {
+    // Fail fast with a readable message instead of a confusing MSAL error on
+    // the first tool call.
+    (0, auth_js_1.getConfig)();
+    const server = new mcp_js_1.McpServer({
+        name: 'outlook-reader',
+        version: '1.0.0',
+    });
+    (0, index_js_1.registerAllTools)(server);
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    // When the client disconnects, stdin ends — but background MSAL device-code
+    // polling can keep the event loop alive for up to 15 minutes, leaving an
+    // orphaned process. Give in-flight responses a moment to flush, then exit.
+    // unref() lets the process exit sooner naturally if the loop drains.
+    process.stdin.on('end', () => {
+        setTimeout(() => process.exit(0), 5_000).unref();
+    });
+}
+main().catch((err) => {
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(1);
+});

package/dist/tools/authenticate/definition.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.description = void 0;
+exports.handler = handler;
+const auth_js_1 = require("../../auth.js");
+exports.description = 'Sign in to the Microsoft account used by the other tools. Returns a URL and a one-time code: show both to the user and tell them to complete the sign-in in their browser. Run this when other tools report that authentication is required. Safe to call anytime — reports the current account if already signed in.';
+async function handler(_input) {
+    const account = await (0, auth_js_1.getSignedInAccount)();
+    if (account) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Already signed in as ${account}. Other tools are ready to use.`,
+                },
+            ],
+        };
+    }
+    const verification = await (0, auth_js_1.startDeviceCodeAuth)();
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `${verification}\n\n` +
+                    'Show the URL and code to the user and ask them to complete the sign-in ' +
+                    'in their browser. Once done, retry the original request — no need to ' +
+                    'run this tool again.',
+            },
+        ],
+    };
+}

package/dist/tools/authenticate/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.register = register;
+const wrap_js_1 = require("../wrap.js");
+const definition_js_1 = require("./definition.js");
+const key_js_1 = require("./key.js");
+const schema_js_1 = require("./schema.js");
+function register(server) {
+    server.registerTool(key_js_1.KEY, { description: definition_js_1.description, inputSchema: schema_js_1.schema }, (0, wrap_js_1.wrapHandler)(definition_js_1.handler));
+}

package/dist/tools/authenticate/key.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KEY = void 0;
+exports.KEY = 'authenticate';

package/dist/tools/authenticate/schema.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.schema = void 0;
+const zod_1 = require("zod");
+exports.schema = zod_1.z.object({});

package/dist/tools/download-attachment/definition.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.description = void 0;
+exports.handler = handler;
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+const files_js_1 = require("../../files.js");
+const mail_js_1 = require("../../mail.js");
+exports.description = 'Download a specific email attachment and save it to disk. Use list_attachments first to get the attachment ID. To save several (or all) attachments from an email in one call, use download_attachments instead. Returns the full path where the file was saved.';
+async function handler({ messageId, attachmentId, saveTo }) {
+    const att = await (0, mail_js_1.downloadAttachment)(messageId, attachmentId);
+    if (!att.contentBytes) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: 'Attachment has no downloadable content (may be an item attachment, not a file).',
+                },
+            ],
+        };
+    }
+    const dir = saveTo ?? (0, path_1.join)((0, os_1.homedir)(), 'Downloads');
+    (0, fs_1.mkdirSync)(dir, { recursive: true });
+    const buf = Buffer.from(att.contentBytes, 'base64');
+    const filePath = (0, files_js_1.uniquePath)(dir, (0, files_js_1.sanitizeFilename)(att.name));
+    (0, fs_1.writeFileSync)(filePath, buf);
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `Saved: ${filePath}\nSize: ${(buf.length / 1024).toFixed(1)} KB\nType: ${att.contentType}`,
+            },
+        ],
+    };
+}

package/dist/tools/download-attachment/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.register = register;
+const wrap_js_1 = require("../wrap.js");
+const definition_js_1 = require("./definition.js");
+const key_js_1 = require("./key.js");
+const schema_js_1 = require("./schema.js");
+function register(server) {
+    server.registerTool(key_js_1.KEY, { description: definition_js_1.description, inputSchema: schema_js_1.schema }, (0, wrap_js_1.wrapHandler)(definition_js_1.handler));
+}

package/dist/tools/download-attachment/key.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KEY = void 0;
+exports.KEY = 'download_attachment';

package/dist/tools/download-attachment/schema.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.schema = void 0;
+const zod_1 = require("zod");
+exports.schema = zod_1.z.object({
+    messageId: zod_1.z.string().describe('The email message ID'),
+    attachmentId: zod_1.z
+        .string()
+        .describe('The attachment ID (from list_attachments)'),
+    saveTo: zod_1.z
+        .string()
+        .optional()
+        .describe('Directory path to save the file. Defaults to user Downloads folder (e.g. C:\\Users\\username\\Downloads)'),
+});

package/dist/tools/download-attachments/definition.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.description = void 0;
+exports.handler = handler;
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+const files_js_1 = require("../../files.js");
+const mail_js_1 = require("../../mail.js");
+exports.description = 'Download multiple attachments from an email in a single call and save them to disk. Omit attachmentIds to download all file attachments. Returns the saved path for each file.';
+async function handler({ messageId, attachmentIds, saveTo, includeInline, }) {
+    const all = await (0, mail_js_1.listAttachments)(messageId);
+    const lines = [];
+    let targets;
+    if (attachmentIds?.length) {
+        const known = new Set(all.map((a) => a.id));
+        for (const id of attachmentIds) {
+            if (!known.has(id))
+                lines.push(`Not found: attachment ID ${id}`);
+        }
+        targets = all.filter((a) => attachmentIds.includes(a.id));
+    }
+    else {
+        targets = all.filter((a) => includeInline || !a.isInline);
+    }
+    if (targets.length === 0) {
+        lines.push('No attachments to download.');
+        return { content: [{ type: 'text', text: lines.join('\n') }] };
+    }
+    const dir = saveTo ?? (0, path_1.join)((0, os_1.homedir)(), 'Downloads');
+    (0, fs_1.mkdirSync)(dir, { recursive: true });
+    // Sequential on purpose: uniquePath checks disk, so parallel downloads of
+    // same-named attachments could race into the same target path.
+    for (const a of targets) {
+        try {
+            const att = await (0, mail_js_1.downloadAttachment)(messageId, a.id);
+            if (!att.contentBytes) {
+                lines.push(`Skipped: ${a.name} (no downloadable content — item attachment, not a file)`);
+                continue;
+            }
+            const buf = Buffer.from(att.contentBytes, 'base64');
+            const filePath = (0, files_js_1.uniquePath)(dir, (0, files_js_1.sanitizeFilename)(att.name ?? a.name));
+            (0, fs_1.writeFileSync)(filePath, buf);
+            lines.push(`Saved: ${filePath} (${(buf.length / 1024).toFixed(1)} KB)`);
+        }
+        catch (err) {
+            lines.push(`Failed: ${a.name} — ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return { content: [{ type: 'text', text: lines.join('\n') }] };
+}

package/dist/tools/download-attachments/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.register = register;
+const wrap_js_1 = require("../wrap.js");
+const definition_js_1 = require("./definition.js");
+const key_js_1 = require("./key.js");
+const schema_js_1 = require("./schema.js");
+function register(server) {
+    server.registerTool(key_js_1.KEY, { description: definition_js_1.description, inputSchema: schema_js_1.schema }, (0, wrap_js_1.wrapHandler)(definition_js_1.handler));
+}