@marlinjai/email-mcp 1.5.0 → 1.7.0

package/README.md

@@ -62,11 +62,19 @@ No configuration needed — the setup wizard handles everything using built-in O
 ```bash
 npx -y -p @marlinjai/email-mcp@latest email-mcp-setup
 # Select "Gmail" when prompted
+# Choose "Full" or "Restricted" permission scope when asked
 # A browser window opens for Google authorization
 # Grant the requested permissions and return to the terminal
 ```
 
-> **Note:** If you prefer to use your own OAuth app, create a Desktop OAuth 2.0 Client in the [Google Cloud Console](https://console.cloud.google.com/) with the Gmail API enabled.
+The wizard asks which Gmail permission scope to authorize:
+
+- **Full** (default) — everything below, plus immediate, Trash-bypassing permanent deletion (`https://mail.google.com/`, Gmail's maximum-permission scope).
+- **Restricted** — read, send, label, archive, and move-to-trash (`gmail.modify` + `gmail.settings.basic`), but no permanent deletion. Every tool in this server works identically under Restricted except an explicit `permanent: true` delete, which fails with a Gmail API error instead of succeeding.
+
+Pass `--scope full` or `--scope restricted` to skip the prompt, or set `EMAIL_MCP_GMAIL_SCOPE=restricted` in the environment the wizard runs in.
+
+> **Note:** If you prefer to use your own OAuth app instead of the shared one this package ships with, create a Desktop OAuth 2.0 Client in the [Google Cloud Console](https://console.cloud.google.com/) with the Gmail API enabled, then set `EMAIL_MCP_GMAIL_CLIENT_ID` and `EMAIL_MCP_GMAIL_CLIENT_SECRET` in the environment before running the setup wizard (and in the MCP server's environment, since re-authentication uses the same variables). This gives you your own token lifecycle, independent of the publisher's Cloud project, and sidesteps Google's unverified-app warning and 100-test-user cap for your own account(s) once you add yourself as a test user on your own app.
 
 ### Outlook
 
@@ -79,7 +87,7 @@ npx -y -p @marlinjai/email-mcp@latest email-mcp-setup
 # Sign in and grant the requested permissions
 ```
 
-> **Note:** If you prefer to use your own OAuth app, register one in the [Azure Portal](https://portal.azure.com/) with `Mail.ReadWrite`, `Mail.Send`, `MailboxSettings.ReadWrite` (needed for `email_create_block_rule`), and `offline_access` permissions.
+> **Note:** If you prefer to use your own OAuth app, register one in the [Azure Portal](https://portal.azure.com/) with `Mail.ReadWrite`, `Mail.Send`, `MailboxSettings.ReadWrite` (needed for `email_create_block_rule`), and `offline_access` permissions, then set `EMAIL_MCP_OUTLOOK_CLIENT_ID` in the environment before running the setup wizard.
 
 ### iCloud
 
@@ -105,7 +113,7 @@ npx -y -p @marlinjai/email-mcp@latest email-mcp-setup
 # Optionally enter SMTP host and port for sending
 ```
 
-## Available Tools (31)
+## Available Tools (32)
 
 ### Account Management (4)
 
@@ -127,7 +135,7 @@ npx -y -p @marlinjai/email-mcp@latest email-mcp-setup
 | `email_get_attachment` | Download a specific attachment by ID (returns base64 data) |
 | `email_save_attachment` | Download an attachment directly to disk, returning metadata only — avoids the token cost of round-tripping large files as base64. `outputPath` is relative to a fixed downloads directory (`~/.email-mcp/downloads`, override with `EMAIL_MCP_DOWNLOADS_DIR`) and cannot escape it |
 
-### Sending & Drafts (5)
+### Sending & Drafts (6)
 
 | Tool | Description |
 |------|-------------|
@@ -135,6 +143,7 @@ npx -y -p @marlinjai/email-mcp@latest email-mcp-setup
 | `email_reply` | Reply to an email (supports reply-all, preserves threading) |
 | `email_forward` | Forward an email to new recipients |
 | `email_draft_create` | Save a draft without sending |
+| `email_draft_update` | Update an existing draft in place. On Gmail/Outlook the draft id is unchanged; on iCloud/generic IMAP there's no in-place update (IMAP messages are immutable), so the old draft is deleted and a new one appended — the returned id is a **new** id, always use it going forward |
 | `email_draft_list` | List all drafts |
 
 ### Organization (8)

package/dist/index.js

@@ -7182,11 +7182,12 @@ var init_adapter = __esm({
         const labels = res.data.labels || [];
         return labels.map(mapGmailLabel);
       }
-      async createFolder(name) {
+      async createFolder(name, parentPath) {
         const gmail = this.ensureConnected();
+        const fullName = parentPath ? `${parentPath}/${name}` : name;
         const res = await gmail.users.labels.create({
           userId: "me",
-          requestBody: { name }
+          requestBody: { name: fullName }
         });
         return mapGmailLabel(res.data);
       }
@@ -7303,6 +7304,18 @@ var init_adapter = __esm({
         });
         return { id: res.data.id || "" };
       }
+      async updateDraft(draftId, params) {
+        const gmail = this.ensureConnected();
+        const raw = this.buildRfc2822(params);
+        const res = await gmail.users.drafts.update({
+          userId: "me",
+          id: draftId,
+          requestBody: {
+            message: { raw }
+          }
+        });
+        return { id: res.data.id || draftId };
+      }
       async listDrafts(limit, _offset) {
         const gmail = this.ensureConnected();
         const res = await gmail.users.drafts.list({
@@ -7466,6 +7479,34 @@ var init_adapter = __esm({
         }
         return result;
       }
+      async batchLabel(emailIds, addLabels, removeLabels) {
+        const gmail = this.ensureConnected();
+        const result = { succeeded: [], failed: [] };
+        const addLabelIds = addLabels ?? [];
+        const removeLabelIds = removeLabels ?? [];
+        if (addLabelIds.length === 0 && removeLabelIds.length === 0) {
+          result.succeeded = [...emailIds];
+          return result;
+        }
+        try {
+          await gmail.users.messages.batchModify({
+            userId: "me",
+            requestBody: { ids: emailIds, addLabelIds, removeLabelIds }
+          });
+          result.succeeded = [...emailIds];
+        } catch (error48) {
+          for (const id of emailIds) {
+            try {
+              if (addLabelIds.length > 0) await this.addLabels(id, addLabelIds);
+              if (removeLabelIds.length > 0) await this.removeLabels(id, removeLabelIds);
+              result.succeeded.push(id);
+            } catch (e) {
+              result.failed.push({ id, error: e.message });
+            }
+          }
+        }
+        return result;
+      }
       async getRawMessage(emailId, _sourceFolder) {
         const gmail = this.ensureConnected();
         const res = await gmail.users.messages.get({
@@ -7626,18 +7667,37 @@ var init_adapter = __esm({
 // src/providers/gmail/auth.ts
 import { OAuth2Client as OAuth2Client2 } from "google-auth-library";
 import crypto2 from "node:crypto";
+function resolveScopeMode(explicit) {
+  if (explicit) return explicit;
+  return process.env.EMAIL_MCP_GMAIL_SCOPE?.toLowerCase() === "restricted" ? "restricted" : "full";
+}
 var GMAIL_SCOPES, GmailAuth;
 var init_auth = __esm({
   "src/providers/gmail/auth.ts"() {
     "use strict";
-    GMAIL_SCOPES = [
-      "https://mail.google.com/",
-      "https://www.googleapis.com/auth/gmail.modify",
-      // Mailbox content access (above) does NOT cover the Settings API —
-      // Google treats them as separate permission domains. Needed for
-      // users.settings.filters.* (email_create_block_rule/list/delete).
-      "https://www.googleapis.com/auth/gmail.settings.basic"
-    ];
+    GMAIL_SCOPES = {
+      full: [
+        // Gmail's maximum-permission scope. Superset of gmail.modify below;
+        // the only capability it adds is immediate, trash-bypassing permanent
+        // deletion (messages.delete / batchDelete with permanent: true).
+        "https://mail.google.com/",
+        "https://www.googleapis.com/auth/gmail.modify",
+        // Mailbox content access (above) does NOT cover the Settings API —
+        // Google treats them as separate permission domains. Needed for
+        // users.settings.filters.* (email_create_block_rule/list/delete).
+        "https://www.googleapis.com/auth/gmail.settings.basic"
+      ],
+      // Drops https://mail.google.com/ so an AI-triggered permanent delete
+      // can't happen: gmail.modify already covers every other read/write
+      // operation this server performs (read, send, label, archive, trash,
+      // drafts, filters). Choosing this mode means deleteEmail(..., permanent:
+      // true) and batchDelete(..., permanent: true) will fail with a Gmail API
+      // 403 instead of succeeding — everything else behaves identically.
+      restricted: [
+        "https://www.googleapis.com/auth/gmail.modify",
+        "https://www.googleapis.com/auth/gmail.settings.basic"
+      ]
+    };
     GmailAuth = class {
       clientId;
       clientSecret;
@@ -7647,13 +7707,13 @@ var init_auth = __esm({
         this.clientSecret = clientSecret;
         this.oauth2Client = new OAuth2Client2(clientId, clientSecret, redirectUri);
       }
-      getAuthUrl(redirectUri) {
+      getAuthUrl(redirectUri, scopeMode) {
         const codeVerifier = crypto2.randomBytes(32).toString("base64url");
         const codeChallenge = crypto2.createHash("sha256").update(codeVerifier).digest("base64url");
         this.oauth2Client = new OAuth2Client2(this.clientId, this.clientSecret, redirectUri);
         const url2 = this.oauth2Client.generateAuthUrl({
           access_type: "offline",
-          scope: GMAIL_SCOPES,
+          scope: GMAIL_SCOPES[resolveScopeMode(scopeMode)],
           prompt: "consent",
           code_challenge: codeChallenge,
           code_challenge_method: "S256"
@@ -8010,6 +8070,12 @@ var init_adapter2 = __esm({
         const result = await client.api("/me/messages").post(message);
         return { id: result.id };
       }
+      async updateDraft(draftId, params) {
+        const client = this.ensureClient();
+        const message = this.buildGraphMessage(params);
+        await client.api(`/me/messages/${encodeURIComponent(draftId)}`).patch(message);
+        return { id: draftId };
+      }
       async listDrafts(limit, offset) {
         const client = this.ensureClient();
         let request = client.api("/me/mailFolders/drafts/messages");
@@ -8992,8 +9058,7 @@ var init_adapter3 = __esm({
         const messageId = await sendViaSmtp(transport, this.email, params);
         return { id: messageId };
       }
-      async createDraft(params) {
-        const client = await this.ensureConnected();
+      buildDraftRfc2822(params) {
         const lines = [];
         lines.push(`From: ${this.email}`);
         lines.push(`To: ${params.to.map((c) => c.name ? `"${c.name}" <${c.email}>` : c.email).join(", ")}`);
@@ -9008,12 +9073,41 @@ var init_adapter3 = __esm({
         lines.push("Content-Type: text/plain; charset=utf-8");
         lines.push("");
         lines.push(params.body.text || "");
-        const rawMessage = lines.join("\r\n");
+        return lines.join("\r\n");
+      }
+      async createDraft(params) {
+        const client = await this.ensureConnected();
+        const rawMessage = this.buildDraftRfc2822(params);
         const draftsFolder = await this.resolveFolder("Drafts");
         const result = await client.append(draftsFolder, rawMessage, ["\\Draft", "\\Seen"]);
         if (!result) throw new Error("Failed to append draft");
         return { id: String(result.uid || result) };
       }
+      /**
+       * IMAP has no in-place message update — a draft is just a message in the
+       * Drafts folder, and IMAP messages are immutable once appended. This
+       * deletes the old revision and appends a new one, so the returned `id`
+       * is a NEW uid; the old id no longer resolves after this call.
+       */
+      async updateDraft(draftId, params, sourceFolder) {
+        const client = await this.ensureConnected();
+        const draftsFolder = sourceFolder ? await this.resolveFolder(sourceFolder) : await this.resolveFolder("Drafts");
+        let lock;
+        try {
+          lock = await client.getMailboxLock(draftsFolder);
+        } catch (error48) {
+          throw formatImapError(error48, `Failed to open folder "${draftsFolder}"`);
+        }
+        try {
+          await client.messageDelete(draftId, { uid: true });
+        } finally {
+          lock.release();
+        }
+        const rawMessage = this.buildDraftRfc2822(params);
+        const result = await client.append(draftsFolder, rawMessage, ["\\Draft", "\\Seen"]);
+        if (!result) throw new Error("Failed to append updated draft");
+        return { id: String(result.uid || result) };
+      }
       async listDrafts(limit, offset) {
         return this.search({
           folder: "Drafts",
@@ -9269,9 +9363,9 @@ var GMAIL_CLIENT_ID, GMAIL_CLIENT_SECRET, OUTLOOK_CLIENT_ID;
 var init_oauth_config = __esm({
   "src/oauth-config.ts"() {
     "use strict";
-    GMAIL_CLIENT_ID = "1062266096576-lu2ukplhc3lcm0bvheml5i18urptdp4t.apps.googleusercontent.com";
-    GMAIL_CLIENT_SECRET = "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";
-    OUTLOOK_CLIENT_ID = "76d32225-ef10-4b49-951c-c80ae906595d";
+    GMAIL_CLIENT_ID = process.env.EMAIL_MCP_GMAIL_CLIENT_ID || "1062266096576-lu2ukplhc3lcm0bvheml5i18urptdp4t.apps.googleusercontent.com";
+    GMAIL_CLIENT_SECRET = process.env.EMAIL_MCP_GMAIL_CLIENT_SECRET || "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";
+    OUTLOOK_CLIENT_ID = process.env.EMAIL_MCP_OUTLOOK_CLIENT_ID || "76d32225-ef10-4b49-951c-c80ae906595d";
   }
 });
 
@@ -9677,14 +9771,30 @@ async function testAndSave(creds) {
 async function promptAccountName(defaultName) {
   return askText("Account name:", defaultName);
 }
-async function setupGmail() {
+async function setupGmail(scopeModeFlag) {
   console.log("\n--- Gmail Setup ---");
+  if (process.env.EMAIL_MCP_GMAIL_CLIENT_ID) {
+    console.log("Using your own Google OAuth Client ID (EMAIL_MCP_GMAIL_CLIENT_ID).");
+  }
   console.log("A browser window will open for Google authorization.\n");
+  let scopeMode = scopeModeFlag;
+  if (!scopeMode) {
+    scopeMode = await askChoice("Gmail permission scope:", [
+      {
+        name: "Full (default) \u2014 includes permanent delete, bypassing Trash",
+        value: "full"
+      },
+      {
+        name: "Restricted \u2014 read/send/label/archive/trash only, no permanent delete",
+        value: "restricted"
+      }
+    ]);
+  }
   const server = new OAuthCallbackServer();
   const port = await server.start();
   const redirectUri = `http://localhost:${port}/callback`;
   const gmailAuth = new GmailAuth(GMAIL_CLIENT_ID, GMAIL_CLIENT_SECRET, redirectUri);
-  const { url: url2, codeVerifier } = gmailAuth.getAuthUrl(redirectUri);
+  const { url: url2, codeVerifier } = gmailAuth.getAuthUrl(redirectUri, scopeMode);
   console.log("\nOpening browser for Google authorization...");
   console.log(`If the browser does not open, visit:
 ${url2}
@@ -9883,6 +9993,17 @@ async function main() {
     await removeAccount(id);
     return;
   }
+  const scopeIdx = args.indexOf("--scope");
+  let scopeModeFlag;
+  if (scopeIdx !== -1) {
+    const value = args[scopeIdx + 1];
+    if (value === "full" || value === "restricted") {
+      scopeModeFlag = value;
+    } else {
+      console.error("Usage: --scope <full|restricted>");
+      process.exit(1);
+    }
+  }
   console.log("@marlinjai/email-mcp Account Setup\n");
   let addMore = true;
   while (addMore) {
@@ -9894,7 +10015,7 @@ async function main() {
     ]);
     switch (provider) {
       case ProviderType.Gmail:
-        await setupGmail();
+        await setupGmail(scopeModeFlag);
         break;
       case ProviderType.Outlook:
         await setupOutlook();
@@ -33538,6 +33659,32 @@ function registerSendingTools(server, accountManager) {
       }
     }
   );
+  server.tool(
+    "email_draft_update",
+    "Update an existing email draft in place (to/subject/body). On Gmail and Outlook the draft id is unchanged. On iCloud/generic IMAP there is no in-place update \u2014 the old draft is deleted and a new one appended \u2014 so the returned id is a NEW id and the old one no longer resolves; always use the id this call returns, not the one you passed in.",
+    {
+      accountId: external_exports3.string(),
+      draftId: external_exports3.string(),
+      to: external_exports3.array(ContactSchema),
+      subject: external_exports3.string(),
+      body: BodySchema,
+      sourceFolder: external_exports3.string().optional().describe("Source folder (required for IMAP/iCloud when the draft is not in the default Drafts folder)")
+    },
+    async (args) => {
+      try {
+        const provider = await accountManager.getProvider(args.accountId);
+        const params = {
+          to: args.to,
+          subject: args.subject,
+          body: args.body
+        };
+        const result = await provider.updateDraft(args.draftId, params, args.sourceFolder);
+        return jsonResult3(result);
+      } catch (error48) {
+        return jsonResult3({ error: error48.message });
+      }
+    }
+  );
   server.tool(
     "email_draft_list",
     "List email drafts",
@@ -33725,6 +33872,45 @@ function registerOrganizingTools(server, accountManager) {
       }
     }
   );
+  server.tool(
+    "email_batch_label",
+    "Add or remove labels on multiple emails at once (Gmail only). Much faster than individual email_label calls.",
+    {
+      accountId: external_exports3.string(),
+      emailIds: external_exports3.array(external_exports3.string()).min(1).describe("Array of email IDs to label"),
+      addLabels: external_exports3.array(external_exports3.string()).optional(),
+      removeLabels: external_exports3.array(external_exports3.string()).optional()
+    },
+    async (args) => {
+      try {
+        const provider = await accountManager.getProvider(args.accountId);
+        if (!provider.addLabels || !provider.removeLabels) {
+          return jsonResult4({
+            success: false,
+            error: "email_batch_label is only supported on Gmail accounts",
+            supportedProviders: ["gmail"]
+          });
+        }
+        if (provider.batchLabel) {
+          const result2 = await provider.batchLabel(args.emailIds, args.addLabels, args.removeLabels);
+          return jsonResult4({ success: true, ...result2 });
+        }
+        const result = { succeeded: [], failed: [] };
+        for (const id of args.emailIds) {
+          try {
+            if (args.addLabels && args.addLabels.length > 0) await provider.addLabels(id, args.addLabels);
+            if (args.removeLabels && args.removeLabels.length > 0) await provider.removeLabels(id, args.removeLabels);
+            result.succeeded.push(id);
+          } catch (e) {
+            result.failed.push({ id, error: e.message });
+          }
+        }
+        return jsonResult4({ success: true, ...result });
+      } catch (error48) {
+        return jsonResult4({ success: false, error: error48.message });
+      }
+    }
+  );
   server.tool(
     "email_transfer",
     "Move or copy emails BETWEEN accounts, preserving the original message intact (sender, date, threading) by transferring the raw MIME. Fetches each message from the source account and imports it into the target account. With deleteAfter=true the source copy is sent to trash only after a confirmed import, making this a safe cross-account move.",