mcp-google-multi 4.2.0 → 4.3.0-alpha.2

package/README.md

@@ -2,6 +2,8 @@
 
 A local [MCP](https://modelcontextprotocol.io) server that gives Claude Code (and any MCP client) access to **Gmail**, **Google Drive**, **Google Calendar**, **Google Sheets**, **Google Docs**, **Google Contacts**, **Google Search Console**, **Google Tasks**, **Google Meet**, and optionally **Google Forms**, **Google Chat**, and **Google Workspace Admin** APIs across multiple Google accounts simultaneously.
 
+[![npm](https://img.shields.io/npm/v/mcp-google-multi?label=npm&color=cb3837)](https://www.npmjs.com/package/mcp-google-multi)
+
 ## Features
 
 - **Multi-account** — manage any number of Google accounts from a single server
@@ -249,14 +251,25 @@ Enable with `GOOGLE_OPTIONAL_SCOPES=alertcenter` in `.env`.
 
 ### 2. Install & Configure
 
+**Option A — from npm (no clone):**
+
+```bash
+npm install -g mcp-google-multi    # installs the `mcp-google-multi` CLI
+# …or run on demand without installing: npx mcp-google-multi
+```
+
+Published with channel dist-tags — `@latest` (stable), `@dev` (alpha), `@staging` (beta); e.g. `npm i -g mcp-google-multi@dev` for the latest alpha.
+
+**Option B — from source:**
+
 ```bash
 git clone https://github.com/bakissation/mcp-google-multi.git
 cd mcp-google-multi
-npm install
+npm install && npm run build
 cp .env.example .env
 ```
 
-Edit `.env`:
+Create a `.env` (from source, `.env.example` is the template; from npm, make one in the directory you'll run the server from) with:
 
 ```env
 GOOGLE_CLIENT_ID=your_client_id_here
@@ -310,6 +323,24 @@ Or add it manually to your Claude Code MCP config:
 }
 ```
 
+If you installed from npm, point at the package instead and pass config via `env` (authenticate first with `mcp-google-multi auth --account <alias>`):
+
+```json
+{
+  "mcpServers": {
+    "google-multi": {
+      "command": "npx",
+      "args": ["-y", "mcp-google-multi"],
+      "env": {
+        "GOOGLE_CLIENT_ID": "your_client_id_here",
+        "GOOGLE_CLIENT_SECRET": "your_client_secret_here",
+        "GOOGLE_ACCOUNTS": "work:you@company.com,personal:you@gmail.com"
+      }
+    }
+  }
+}
+```
+
 ## Migrating from v3
 
 v4.0.0 grows the base OAuth scope set (Tasks and Meet are now included by default). Existing v3 tokens lack those scopes and the corresponding tools will 403.

package/dist/tools/drive.js

@@ -311,8 +311,14 @@ export function registerDriveTools(server) {
             newParentFolderId: z.string().optional().describe('Move to this folder'),
             localPath: z.string().optional().describe('Replace file content with this local file'),
             mimeType: z.string().optional().describe('MIME type of the replacement file (required if localPath is provided)'),
+            convertTo: z.enum([
+                'application/vnd.google-apps.document',
+                'application/vnd.google-apps.spreadsheet',
+                'application/vnd.google-apps.presentation',
+                'application/vnd.google-apps.drawing',
+            ]).optional().describe('When replacing content via localPath, convert the new content into this native Google Workspace type on import (e.g. replace a Google Doc body from a local .docx). Source must be an importable format.'),
         },
-    }, async ({ account, fileId, newName, newParentFolderId, localPath: localPathArg, mimeType: mimeTypeArg }) => {
+    }, async ({ account, fileId, newName, newParentFolderId, localPath: localPathArg, mimeType: mimeTypeArg, convertTo }) => {
         try {
             const auth = await getClient(account);
             const drive = google.drive({ version: 'v3', auth });
@@ -335,6 +341,8 @@ export function registerDriveTools(server) {
                     mimeType: mimeTypeArg ?? (mime.lookup(localPathArg) || 'application/octet-stream'),
                     body: fs.createReadStream(localPathArg),
                 };
+                if (convertTo)
+                    requestBody.mimeType = convertTo;
             }
             const res = await drive.files.update(params);
             return {

package/dist/tools/gmail-mime.d.ts

@@ -14,3 +14,12 @@ export declare function encodeAddressHeader(value: string): string;
  * Normalize bare `\n` or `\r` to CRLF.
  */
 export declare function normalizeBodyLineEndings(body: string): string;
+/**
+ * Build a multipart/alternative body so HTML-capable clients render the rich
+ * version and plain clients fall back. Returns the header value AND the body.
+ * Caller composes the full message: headers (including this Content-Type) + CRLF + body.
+ */
+export declare function buildMultipartAlternative(plainBody: string, htmlBody: string): {
+    contentType: string;
+    body: string;
+};

package/dist/tools/gmail-mime.js

@@ -1,3 +1,4 @@
+import { randomBytes } from 'node:crypto';
 /**
  * RFC 2047 encoded-word (`=?utf-8?B?...?=`) for non-ASCII header text.
  * Long values are split into multiple <=75-char encoded-words separated
@@ -62,3 +63,37 @@ export function encodeAddressHeader(value) {
 export function normalizeBodyLineEndings(body) {
     return body.replace(/\r\n|\r|\n/g, '\r\n');
 }
+/**
+ * RFC 2046 §5.1.1 boundary token: 1-70 chars from a restricted set, no trailing space.
+ * randomBytes hex output is only [0-9a-f], all of which are bcharsnospace.
+ */
+function generateMimeBoundary() {
+    // 5-char prefix + 32 hex chars = 37 chars, well under the 70-char limit.
+    return `=_gm_${randomBytes(16).toString('hex')}`;
+}
+/**
+ * Build a multipart/alternative body so HTML-capable clients render the rich
+ * version and plain clients fall back. Returns the header value AND the body.
+ * Caller composes the full message: headers (including this Content-Type) + CRLF + body.
+ */
+export function buildMultipartAlternative(plainBody, htmlBody) {
+    const boundary = generateMimeBoundary();
+    const parts = [
+        `--${boundary}`,
+        'Content-Type: text/plain; charset="UTF-8"',
+        'Content-Transfer-Encoding: 8bit',
+        '',
+        normalizeBodyLineEndings(plainBody),
+        `--${boundary}`,
+        'Content-Type: text/html; charset="UTF-8"',
+        'Content-Transfer-Encoding: 8bit',
+        '',
+        normalizeBodyLineEndings(htmlBody),
+        `--${boundary}--`,
+        '',
+    ];
+    return {
+        contentType: `multipart/alternative; boundary="${boundary}"`,
+        body: parts.join('\r\n'),
+    };
+}

package/dist/tools/gmail.js

@@ -3,7 +3,7 @@ import { google } from 'googleapis';
 import { ACCOUNTS } from '../accounts.js';
 import { getClient } from '../client.js';
 import { handleGoogleApiError } from './_errors.js';
-import { encodeAddressHeader, encodeHeaderValue, normalizeBodyLineEndings } from './gmail-mime.js';
+import { buildMultipartAlternative, encodeAddressHeader, encodeHeaderValue, normalizeBodyLineEndings } from './gmail-mime.js';
 import * as path from 'path';
 import * as fs from 'fs';
 const accountEnum = z.enum(ACCOUNTS);
@@ -163,14 +163,16 @@ export function registerGmailTools(server) {
             account: accountEnum.describe('Google account alias'),
             to: z.string().describe('Recipient(s), comma-separated'),
             subject: z.string().describe('Email subject'),
-            body: z.string().describe('Plain text body'),
+            body: z.string().describe('Plain text body (always required; also used as fallback when htmlBody is set)'),
+            htmlBody: z.string().optional()
+                .describe('Optional HTML body. When set, sends multipart/alternative so HTML-capable clients render the rich version. Use bare tags only: <p>, <a>, <br>, <strong>, <em>, <ul><li>.'),
             cc: z.string().optional().describe('CC recipients, comma-separated'),
             replyToMessageId: z.string().optional()
                 .describe('Message ID to reply to (sets In-Reply-To and References headers)'),
             replyToThreadId: z.string().optional()
                 .describe('Thread ID to send the message in'),
         },
-    }, async ({ account, to, subject, body, cc, replyToMessageId, replyToThreadId }) => {
+    }, async ({ account, to, subject, body, htmlBody, cc, replyToMessageId, replyToThreadId }) => {
         try {
             const auth = await getClient(account);
             const gmail = google.gmail({ version: 'v1', auth });
@@ -180,16 +182,25 @@ export function registerGmailTools(server) {
                 `To: ${encodeAddressHeader(to)}`,
                 `Subject: ${encodeHeaderValue(subject)}`,
                 'MIME-Version: 1.0',
-                'Content-Type: text/plain; charset="UTF-8"',
-                'Content-Transfer-Encoding: 8bit',
             ];
+            let bodyText;
+            if (htmlBody) {
+                const { contentType, body: mp } = buildMultipartAlternative(body, htmlBody);
+                headers.push(`Content-Type: ${contentType}`);
+                bodyText = mp;
+            }
+            else {
+                headers.push('Content-Type: text/plain; charset="UTF-8"');
+                headers.push('Content-Transfer-Encoding: 8bit');
+                bodyText = normalizeBodyLineEndings(body);
+            }
             if (cc)
                 headers.push(`Cc: ${encodeAddressHeader(cc)}`);
             if (replyToMessageId) {
                 headers.push(`In-Reply-To: ${replyToMessageId}`);
                 headers.push(`References: ${replyToMessageId}`);
             }
-            const rawMessage = [...headers, '', normalizeBodyLineEndings(body)].join('\r\n');
+            const rawMessage = [...headers, '', bodyText].join('\r\n');
             const encoded = Buffer.from(rawMessage, 'utf-8').toString('base64url');
             const sendParams = {
                 userId: 'me',
@@ -249,12 +260,14 @@ export function registerGmailTools(server) {
             account: accountEnum.describe('Google account alias'),
             to: z.string().describe('Recipient(s), comma-separated'),
             subject: z.string().describe('Email subject'),
-            body: z.string().describe('Plain text body'),
+            body: z.string().describe('Plain text body (always required; also used as fallback when htmlBody is set)'),
+            htmlBody: z.string().optional()
+                .describe('Optional HTML body. When set, drafts as multipart/alternative so HTML-capable clients render the rich version. Use bare tags only: <p>, <a>, <br>, <strong>, <em>, <ul><li>.'),
             cc: z.string().optional().describe('CC recipients, comma-separated'),
             replyToThreadId: z.string().optional()
                 .describe('Thread ID to associate the draft with'),
         },
-    }, async ({ account, to, subject, body, cc, replyToThreadId }) => {
+    }, async ({ account, to, subject, body, htmlBody, cc, replyToThreadId }) => {
         try {
             const auth = await getClient(account);
             const gmail = google.gmail({ version: 'v1', auth });
@@ -264,12 +277,21 @@ export function registerGmailTools(server) {
                 `To: ${encodeAddressHeader(to)}`,
                 `Subject: ${encodeHeaderValue(subject)}`,
                 'MIME-Version: 1.0',
-                'Content-Type: text/plain; charset="UTF-8"',
-                'Content-Transfer-Encoding: 8bit',
             ];
+            let bodyText;
+            if (htmlBody) {
+                const { contentType, body: mp } = buildMultipartAlternative(body, htmlBody);
+                headers.push(`Content-Type: ${contentType}`);
+                bodyText = mp;
+            }
+            else {
+                headers.push('Content-Type: text/plain; charset="UTF-8"');
+                headers.push('Content-Transfer-Encoding: 8bit');
+                bodyText = normalizeBodyLineEndings(body);
+            }
             if (cc)
                 headers.push(`Cc: ${encodeAddressHeader(cc)}`);
-            const rawMessage = [...headers, '', normalizeBodyLineEndings(body)].join('\r\n');
+            const rawMessage = [...headers, '', bodyText].join('\r\n');
             const encoded = Buffer.from(rawMessage, 'utf-8').toString('base64url');
             const draftParams = {
                 userId: 'me',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-google-multi",
-  "version": "4.2.0",
+  "version": "4.3.0-alpha.2",
   "description": "MCP server for Gmail, Google Drive, Calendar, Sheets, Docs, and Contacts with multi-account support",
   "type": "module",
   "license": "MIT",
@@ -67,6 +67,6 @@
     "semantic-release": "^25.0.3",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.59.1",
-    "vitest": "^4.1.5"
+    "vitest": "^3.2.4"
   }
 }