outlook-reader-mcp 1.0.0

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

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

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

@@ -0,0 +1,20 @@
+"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'),
+    attachmentIds: zod_1.z
+        .array(zod_1.z.string())
+        .optional()
+        .describe('Specific attachment IDs to download (from list_attachments). Omit to download ALL file attachments of the message.'),
+    saveTo: zod_1.z
+        .string()
+        .optional()
+        .describe('Directory path to save the files. Defaults to user Downloads folder (e.g. C:\\Users\\username\\Downloads)'),
+    includeInline: zod_1.z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe('When downloading all attachments, also include inline ones (embedded images, signatures). Default false.'),
+});

package/dist/tools/get-email/definition.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.description = void 0;
+exports.handler = handler;
+const mail_js_1 = require("../../mail.js");
+exports.description = 'Get the full content of a specific email by its ID, including the complete body. To fetch several emails at once, use get_emails instead.';
+async function handler({ id }) {
+    const m = await (0, mail_js_1.getEmail)(id);
+    const from = m.from?.emailAddress;
+    const to = (m.toRecipients ?? [])
+        .map((r) => `${r.emailAddress?.name ?? ''} <${r.emailAddress?.address ?? ''}>`)
+        .join(', ');
+    // Graph returns plain text thanks to the Prefer header; the regex strip is
+    // only a fallback in case the header is ignored.
+    const body = m.body?.content ?? '';
+    const plainBody = m.body?.contentType === 'html'
+        ? body
+            .replace(/<[^>]+>/g, ' ')
+            .replace(/\s+/g, ' ')
+            .trim()
+        : body;
+    const text = [
+        `ID: ${m.id}`,
+        `Subject: ${m.subject ?? '(no subject)'}`,
+        `From: ${from?.name ?? ''} <${from?.address ?? ''}>`,
+        `To: ${to}`,
+        `Date: ${m.receivedDateTime ?? ''}`,
+        `Attachments: ${m.hasAttachments ?? false}`,
+        `---`,
+        plainBody,
+    ].join('\n');
+    return { content: [{ type: 'text', text }] };
+}

package/dist/tools/get-email/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/get-email/key.js

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

package/dist/tools/get-email/schema.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.schema = void 0;
+const zod_1 = require("zod");
+exports.schema = zod_1.z.object({
+    id: zod_1.z
+        .string()
+        .describe('The email message ID (obtained from list_emails or search_emails)'),
+});

package/dist/tools/get-emails/definition.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.description = void 0;
+exports.handler = handler;
+const mail_js_1 = require("../../mail.js");
+exports.description = 'Get the full content of multiple emails by their IDs in a single batched request. Much faster than calling get_email repeatedly. Returns subject, sender, recipients, and complete body for each.';
+function formatMessage(m) {
+    const from = m.from?.emailAddress;
+    const to = (m.toRecipients ?? [])
+        .map((r) => `${r.emailAddress?.name ?? ''} <${r.emailAddress?.address ?? ''}>`)
+        .join(', ');
+    return [
+        `ID: ${m.id}`,
+        `Subject: ${m.subject ?? '(no subject)'}`,
+        `From: ${from?.name ?? ''} <${from?.address ?? ''}>`,
+        `To: ${to}`,
+        `Date: ${m.receivedDateTime ?? ''}`,
+        `Attachments: ${m.hasAttachments ?? false}`,
+        `---`,
+        m.body?.content ?? '',
+    ].join('\n');
+}
+async function handler({ ids }) {
+    const results = await (0, mail_js_1.getEmails)(ids);
+    const text = results
+        .map((r, i) => r.ok
+        ? `===== [${i + 1}/${results.length}] =====\n${formatMessage(r.message)}`
+        : `===== [${i + 1}/${results.length}] =====\nFailed to fetch ${r.id}: ${r.error}`)
+        .join('\n\n');
+    return { content: [{ type: 'text', text }] };
+}

package/dist/tools/get-emails/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/get-emails/key.js

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

package/dist/tools/get-emails/schema.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.schema = void 0;
+const zod_1 = require("zod");
+exports.schema = zod_1.z.object({
+    ids: zod_1.z
+        .array(zod_1.z.string())
+        .min(1)
+        .max(50)
+        .describe('Email message IDs to fetch (from list_emails or search_emails). Max 50.'),
+});

package/dist/tools/index.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerAllTools = registerAllTools;
+const index_js_1 = require("./authenticate/index.js");
+const index_js_2 = require("./download-attachment/index.js");
+const index_js_3 = require("./download-attachments/index.js");
+const index_js_4 = require("./get-email/index.js");
+const index_js_5 = require("./get-emails/index.js");
+const index_js_6 = require("./list-attachments/index.js");
+const index_js_7 = require("./list-emails/index.js");
+const index_js_8 = require("./list-folders/index.js");
+const index_js_9 = require("./search-emails/index.js");
+const index_js_10 = require("./sign-out/index.js");
+function registerAllTools(server) {
+    (0, index_js_1.register)(server);
+    (0, index_js_10.register)(server);
+    (0, index_js_7.register)(server);
+    (0, index_js_4.register)(server);
+    (0, index_js_5.register)(server);
+    (0, index_js_9.register)(server);
+    (0, index_js_8.register)(server);
+    (0, index_js_6.register)(server);
+    (0, index_js_2.register)(server);
+    (0, index_js_3.register)(server);
+}

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

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.description = void 0;
+exports.handler = handler;
+const mail_js_1 = require("../../mail.js");
+exports.description = 'List all attachments for a specific email. Returns attachment IDs, names, sizes, and content types. Use download_attachment for one file, or download_attachments to save several (or all) in a single call.';
+async function handler({ messageId }) {
+    const attachments = await (0, mail_js_1.listAttachments)(messageId);
+    if (attachments.length === 0) {
+        return {
+            content: [{ type: 'text', text: 'No attachments found.' }],
+        };
+    }
+    const text = attachments
+        .map((a, i) => [
+        `[${i + 1}] ID: ${a.id}`,
+        `    Name: ${a.name}`,
+        `    Size: ${(a.size / 1024).toFixed(1)} KB`,
+        `    Type: ${a.contentType}`,
+        `    Inline: ${a.isInline}`,
+    ].join('\n'))
+        .join('\n\n');
+    return { content: [{ type: 'text', text }] };
+}

package/dist/tools/list-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));
+}

package/dist/tools/list-attachments/key.js

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

package/dist/tools/list-attachments/schema.js

@@ -0,0 +1,9 @@
+"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 (from list_emails or search_emails)'),
+});

package/dist/tools/list-emails/definition.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.description = void 0;
+exports.handler = handler;
+const mail_js_1 = require("../../mail.js");
+exports.description = 'List emails from an Outlook mailbox folder. Supports filtering by read status, sender, date range, and more using OData filter syntax. Use skip to page through results.';
+async function handler({ folder, top, skip, filter, orderby }) {
+    const emails = await (0, mail_js_1.listEmails)({ folder, top, skip, filter, orderby });
+    const text = emails
+        .map((m, i) => {
+        const from = m.from?.emailAddress;
+        return [
+            `[${(skip ?? 0) + i + 1}] ID: ${m.id}`,
+            `    Subject: ${m.subject ?? '(no subject)'}`,
+            `    From: ${from?.name ?? ''} <${from?.address ?? ''}>`,
+            `    Date: ${m.receivedDateTime ?? ''}`,
+            `    Read: ${m.isRead} | Attachments: ${m.hasAttachments ?? false}`,
+            `    Preview: ${(m.bodyPreview ?? '').slice(0, 150)}`,
+        ].join('\n');
+    })
+        .join('\n\n');
+    const footer = emails.length === top
+        ? `\n\n(Showing ${emails.length} results — more may exist. Use skip=${(skip ?? 0) + top} for the next page.)`
+        : '';
+    return {
+        content: [
+            {
+                type: 'text',
+                text: text ? text + footer : 'No emails found.',
+            },
+        ],
+    };
+}

package/dist/tools/list-emails/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/list-emails/key.js

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

package/dist/tools/list-emails/schema.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.schema = void 0;
+const zod_1 = require("zod");
+exports.schema = zod_1.z.object({
+    folder: zod_1.z
+        .string()
+        .optional()
+        .default('inbox')
+        .describe('Folder name or well-known folder: inbox, sentitems, drafts, deleteditems'),
+    top: zod_1.z
+        .number()
+        .int()
+        .min(1)
+        .max(50)
+        .optional()
+        .default(10)
+        .describe('Number of emails to return (max 50)'),
+    skip: zod_1.z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .describe('Number of emails to skip, for paging through results (e.g. skip=50 for page 2 with top=50)'),
+    filter: zod_1.z
+        .string()
+        .optional()
+        .describe('OData filter expression. Examples: "isRead eq false", "from/emailAddress/address eq \'someone@example.com\'", "receivedDateTime ge 2024-01-01T00:00:00Z"'),
+    orderby: zod_1.z
+        .string()
+        .optional()
+        .default('receivedDateTime desc')
+        .describe('OData orderBy clause. Default: receivedDateTime desc'),
+});

package/dist/tools/list-folders/definition.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.description = void 0;
+exports.handler = handler;
+const mail_js_1 = require("../../mail.js");
+exports.description = 'List all mail folders in the mailbox, including custom folders.';
+async function handler(_input) {
+    const folders = await (0, mail_js_1.listFolders)();
+    const text = folders
+        .map((f) => `${f.displayName} (id: ${f.id}, unread: ${f.unreadItemCount ?? 0}, total: ${f.totalItemCount ?? 0})`)
+        .join('\n');
+    return {
+        content: [{ type: 'text', text: text || 'No folders found.' }],
+    };
+}

package/dist/tools/list-folders/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/list-folders/key.js

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

package/dist/tools/list-folders/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/search-emails/definition.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.description = void 0;
+exports.handler = handler;
+const mail_js_1 = require("../../mail.js");
+exports.description = 'Search emails using a keyword query. Searches across subject, body, sender, and recipients.';
+async function handler({ query, top }) {
+    const emails = await (0, mail_js_1.searchEmails)(query, top);
+    const text = emails
+        .map((m, i) => {
+        const from = m.from?.emailAddress;
+        return [
+            `[${i + 1}] ID: ${m.id}`,
+            `    Subject: ${m.subject ?? '(no subject)'}`,
+            `    From: ${from?.name ?? ''} <${from?.address ?? ''}>`,
+            `    Date: ${m.receivedDateTime ?? ''}`,
+            `    Preview: ${(m.bodyPreview ?? '').slice(0, 150)}`,
+        ].join('\n');
+    })
+        .join('\n\n');
+    return {
+        content: [{ type: 'text', text: text || 'No results found.' }],
+    };
+}

package/dist/tools/search-emails/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/search-emails/key.js

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

package/dist/tools/search-emails/schema.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.schema = void 0;
+const zod_1 = require("zod");
+exports.schema = zod_1.z.object({
+    query: zod_1.z
+        .string()
+        .describe("Search terms, e.g. 'invoice from acme', 'meeting next week'"),
+    top: zod_1.z
+        .number()
+        .int()
+        .min(1)
+        .max(25)
+        .optional()
+        .default(10)
+        .describe('Number of results to return (max 25)'),
+});

package/dist/tools/sign-out/definition.js

@@ -0,0 +1,13 @@
+"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 out of the Microsoft account: removes the cached session from this machine and cancels any pending sign-in. After this, the authenticate tool must be run again before other tools work. Note: this clears the local token cache but does not revoke app consent in the Microsoft account.';
+async function handler(_input) {
+    const removed = await (0, auth_js_1.clearAuth)();
+    const text = removed.length > 0
+        ? `Signed out: ${removed.join(', ')}. Run the authenticate tool to sign in again.`
+        : 'No cached session found — already signed out.';
+    return { content: [{ type: 'text', text }] };
+}

package/dist/tools/sign-out/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/sign-out/key.js

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

package/dist/tools/sign-out/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/wrap.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wrapHandler = wrapHandler;
+const auth_js_1 = require("../auth.js");
+/**
+ * Wraps a tool handler so Graph/network errors come back as readable tool
+ * output instead of a raw stack trace.
+ */
+function wrapHandler(fn) {
+    return async (input) => {
+        try {
+            return await fn(input);
+        }
+        catch (err) {
+            return {
+                content: [{ type: 'text', text: friendlyError(err) }],
+                isError: true,
+            };
+        }
+    };
+}
+function friendlyError(err) {
+    if (err instanceof auth_js_1.AuthRequiredError)
+        return err.message;
+    const e = err;
+    // statusCode -1 = client-side failure: the Graph middleware wraps errors
+    // thrown by the auth provider (e.g. AuthRequiredError), losing the class
+    // but keeping the message — pass it through untouched.
+    if (e?.statusCode === -1 && e?.message)
+        return e.message;
+    switch (e?.statusCode) {
+        case 400:
+            return `Bad request — likely invalid OData filter/orderby syntax. Details: ${e.message ?? ''}`;
+        case 401:
+            return 'Authentication failed or token expired. Restart the server to re-authenticate.';
+        case 403:
+            return 'Permission denied. The app registration may be missing the Mail.Read scope.';
+        case 404:
+            return 'Not found. The message or attachment ID may be stale — re-run list_emails or list_attachments to get fresh IDs.';
+        case 429:
+            return 'Microsoft Graph throttled the request (429). Wait a moment and retry.';
+        default:
+            return `Request failed${e?.statusCode ? ` (HTTP ${e.statusCode})` : ''}: ${e?.message ?? String(err)}`;
+    }
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "outlook-reader-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for reading Outlook mail via Microsoft Graph: list, search, and fetch emails (batched), and download attachments.",
+  "bin": {
+    "outlook-reader-mcp": "dist/mcp-server.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "mcp": "tsx src/mcp-server.ts",
+    "build": "tsc",
+    "prepublishOnly": "npm run format:check && npm run build",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "outlook",
+    "microsoft-graph",
+    "email"
+  ],
+  "author": "Jesús Imitola",
+  "license": "GPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jgimitola/outlook-reader-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jgimitola/outlook-reader-mcp/issues"
+  },
+  "homepage": "https://github.com/jgimitola/outlook-reader-mcp#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "type": "commonjs",
+  "dependencies": {
+    "@azure/msal-node": "^5.2.3",
+    "@azure/msal-node-extensions": "^5.2.4",
+    "@microsoft/microsoft-graph-client": "^3.0.7",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "dotenv": "^17.4.2",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@microsoft/microsoft-graph-types": "^2.43.1",
+    "@trivago/prettier-plugin-sort-imports": "^6.0.2",
+    "@types/node": "^25.9.2",
+    "prettier": "^3.8.4",
+    "tsx": "^4.22.4",
+    "typescript": "^6.0.3"
+  }
+}