outlook-file-attach-mcp 1.0.2

package/README.md

@@ -0,0 +1,66 @@
+# Outlook File Attach MCP Server
+
+A lightweight MCP server that attaches local files to Outlook draft emails via the Microsoft Graph API.
+
+## Why this exists
+
+MCP-based email tools like `@softeria/ms-365-mcp-server` require file content to be passed as base64 through tool parameters. For files larger than ~50KB, this exceeds what an LLM can output in a single tool call. This server solves the problem by accepting a **local file path** instead — it reads the file from disk, encodes it, and uploads it directly to the Graph API.
+
+## Requirements
+
+- **Node.js 18+**
+- **An Azure App Registration** with Application-level `Mail.ReadWrite` permission (with admin consent). This server uses client credentials flow, not delegated auth.
+- **Local filesystem access** — the MCP host (e.g. Claude Desktop, Claude Cowork) needs read access to the folder containing the files you want to attach. In Claude Cowork, this means selecting a workspace folder. In Claude Desktop, the file paths must be accessible from the machine running the MCP server.
+
+## Setup
+
+Add the following to your MCP config (e.g. `claude_desktop_config.json`) under `mcpServers`:
+
+```json
+"outlook-file-attach": {
+  "command": "npx",
+  "args": ["-y", "outlook-file-attach-mcp"],
+  "env": {
+    "MS365_MCP_CLIENT_ID": "your-client-id",
+    "MS365_MCP_CLIENT_SECRET": "your-client-secret",
+    "MS365_MCP_TENANT_ID": "your-tenant-id"
+  }
+}
+```
+
+Then restart your MCP host to load the server.
+
+## Usage
+
+The server provides one tool: **`attach-file-to-email`**
+
+Parameters:
+
+- `userEmail` — The mailbox owner's email address (e.g. `user@example.com`)
+- `messageId` — The Outlook message ID of the draft to attach the file to
+- `filePath` — Absolute path to the local file (e.g. `C:/Users/me/Documents/report.pdf`)
+- `fileName` (optional) — Custom filename for the attachment. Defaults to the original filename.
+
+Supported file types include PDF, DOCX, XLSX, PPTX, PNG, JPG, CSV, TXT, ZIP, and more. Unrecognized extensions are sent as `application/octet-stream`.
+
+## How it works
+
+1. The LLM calls `attach-file-to-email` with a local file path and a draft message ID
+2. The server reads the file from disk and base64-encodes it
+3. It authenticates using client credentials flow (no user interaction needed)
+4. It POSTs the encoded file to the Microsoft Graph API as an attachment
+5. The file appears on the draft email, ready to send
+
+## Typical workflow
+
+This server is designed to work alongside an MS365 MCP server that handles email composition. A typical flow looks like:
+
+1. Create a draft email (using your MS365 MCP server)
+2. Generate or locate a file locally (e.g. a report, spreadsheet, or PDF)
+3. Attach the file to the draft using this server
+4. Send the draft (using your MS365 MCP server)
+
+## Limitations
+
+- Maximum attachment size is 4MB per file (Microsoft Graph API limit for single-request uploads). For larger files, the resumable upload API would be needed.
+- Requires Application-level permissions, not delegated. This means the Azure app can access any mailbox in the tenant — scope access appropriately.

package/index.js

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+
+/**
+ * Outlook File Attach MCP Server
+ *
+ * A minimal MCP server that attaches local files to Outlook draft emails
+ * via the Microsoft Graph API. This solves the problem where Claude cannot
+ * pass large base64-encoded file content through tool parameters.
+ *
+ * The server reads the file from the local filesystem, base64-encodes it,
+ * and POSTs it to the Graph API using client credentials flow.
+ *
+ * Required environment variables:
+ *   MS365_MCP_CLIENT_ID     - Azure App Registration client ID
+ *   MS365_MCP_CLIENT_SECRET - Azure App Registration client secret
+ *   MS365_MCP_TENANT_ID     - Azure tenant ID
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { readFileSync } from "fs";
+import { basename } from "path";
+import https from "https";
+
+// --- Configuration from environment variables ---
+const CLIENT_ID = process.env.MS365_MCP_CLIENT_ID;
+const CLIENT_SECRET = process.env.MS365_MCP_CLIENT_SECRET;
+const TENANT_ID = process.env.MS365_MCP_TENANT_ID;
+
+// --- Helper: HTTPS request as a promise ---
+function httpsRequest(url, options, body = null) {
+  return new Promise((resolve, reject) => {
+    const req = https.request(url, options, (res) => {
+      let data = "";
+      res.on("data", (chunk) => (data += chunk));
+      res.on("end", () => {
+        resolve({ statusCode: res.statusCode, headers: res.headers, body: data });
+      });
+    });
+    req.on("error", reject);
+    if (body) req.write(body);
+    req.end();
+  });
+}
+
+// --- Get access token using client credentials flow ---
+async function getAccessToken() {
+  const tokenUrl = `https://login.microsoftonline.com/${TENANT_ID}/oauth2/v2.0/token`;
+  const params = new URLSearchParams({
+    client_id: CLIENT_ID,
+    client_secret: CLIENT_SECRET,
+    scope: "https://graph.microsoft.com/.default",
+    grant_type: "client_credentials",
+  });
+
+  const urlObj = new URL(tokenUrl);
+  const body = params.toString();
+
+  const response = await httpsRequest(tokenUrl, {
+    hostname: urlObj.hostname,
+    path: urlObj.pathname,
+    method: "POST",
+    headers: {
+      "Content-Type": "application/x-www-form-urlencoded",
+      "Content-Length": Buffer.byteLength(body),
+    },
+  }, body);
+
+  if (response.statusCode !== 200) {
+    throw new Error(`Token request failed (${response.statusCode}): ${response.body}`);
+  }
+
+  const tokenData = JSON.parse(response.body);
+  if (!tokenData.access_token) {
+    throw new Error(`No access token in response: ${response.body}`);
+  }
+
+  return tokenData.access_token;
+}
+
+// --- Attach file to a message via Graph API ---
+async function attachFileToMessage(token, userEmail, messageId, filePath, fileName) {
+  // Read the file and base64-encode it
+  const fileBuffer = readFileSync(filePath);
+  const base64Content = fileBuffer.toString("base64");
+
+  // Determine file name from path if not provided
+  const attachmentName = fileName || basename(filePath);
+
+  // Determine content type based on extension
+  const ext = attachmentName.split(".").pop().toLowerCase();
+  const contentTypes = {
+    pdf: "application/pdf",
+    doc: "application/msword",
+    docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    xls: "application/vnd.ms-excel",
+    xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    ppt: "application/vnd.ms-powerpoint",
+    pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+    png: "image/png",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    gif: "image/gif",
+    txt: "text/plain",
+    csv: "text/csv",
+    zip: "application/zip",
+  };
+  const contentType = contentTypes[ext] || "application/octet-stream";
+
+  // Build the attachment payload
+  const payload = JSON.stringify({
+    "@odata.type": "#microsoft.graph.fileAttachment",
+    name: attachmentName,
+    contentType: contentType,
+    contentBytes: base64Content,
+  });
+
+  // POST to Graph API
+  const graphUrl = `https://graph.microsoft.com/v1.0/users/${encodeURIComponent(userEmail)}/messages/${encodeURIComponent(messageId)}/attachments`;
+  const urlObj = new URL(graphUrl);
+
+  const response = await httpsRequest(graphUrl, {
+    hostname: urlObj.hostname,
+    path: urlObj.pathname,
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "Content-Type": "application/json",
+      "Content-Length": Buffer.byteLength(payload),
+    },
+  }, payload);
+
+  if (response.statusCode !== 200 && response.statusCode !== 201) {
+    throw new Error(`Attachment upload failed (${response.statusCode}): ${response.body}`);
+  }
+
+  return JSON.parse(response.body);
+}
+
+// --- Main: Create and start MCP server ---
+const server = new McpServer({
+  name: "outlook-file-attach",
+  version: "1.0.0",
+});
+
+server.tool(
+  "attach-file-to-email",
+  "Attach a local file to an existing Outlook draft email. Reads the file from the local filesystem, " +
+  "base64-encodes it, and uploads it to the specified draft message via Microsoft Graph API. " +
+  "This tool solves the problem of attaching files that are too large to pass as base64 through tool parameters.",
+  {
+    userEmail: z.string().describe("Email address of the mailbox owner (e.g. 'user@company.com')"),
+    messageId: z.string().describe("The Outlook message ID of the draft email to attach the file to"),
+    filePath: z.string().describe("Absolute path to the local file to attach (e.g. 'C:/Users/user/Documents/file.pdf')"),
+    fileName: z.string().optional().describe("Optional custom filename for the attachment. If omitted, uses the original filename from the path."),
+  },
+  async ({ userEmail, messageId, filePath, fileName }) => {
+    // Validate environment
+    if (!CLIENT_ID || !CLIENT_SECRET || !TENANT_ID) {
+      return {
+        content: [{
+          type: "text",
+          text: "Error: Missing required environment variables. Ensure MS365_MCP_CLIENT_ID, MS365_MCP_CLIENT_SECRET, and MS365_MCP_TENANT_ID are set.",
+        }],
+        isError: true,
+      };
+    }
+
+    try {
+      // Step 1: Get access token
+      const token = await getAccessToken();
+
+      // Step 2: Attach the file
+      const result = await attachFileToMessage(token, userEmail, messageId, filePath, fileName);
+
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            success: true,
+            message: `File "${result.name}" attached successfully.`,
+            attachment: {
+              id: result.id,
+              name: result.name,
+              size: result.size,
+              contentType: result.contentType,
+            },
+          }, null, 2),
+        }],
+      };
+    } catch (error) {
+      return {
+        content: [{
+          type: "text",
+          text: `Error attaching file: ${error.message}`,
+        }],
+        isError: true,
+      };
+    }
+  }
+);
+
+// Start the server
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "outlook-file-attach-mcp",
+  "version": "1.0.2",
+  "description": "MCP server that attaches local files to Outlook draft emails via Microsoft Graph API",
+  "main": "index.js",
+  "type": "module",
+  "bin": {
+    "outlook-file-attach-mcp": "index.js"
+  },
+  "keywords": [
+    "mcp",
+    "outlook",
+    "email",
+    "attachment",
+    "microsoft-graph"
+  ],
+  "license": "MIT",
+  "files": [
+    "index.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.25.0"
+  }
+}