@piotr-agier/google-drive-mcp 2.1.0 → 2.2.0

package/README.md

@@ -292,6 +292,16 @@ Notes:
   `drive`, `drive.file`, `drive.readonly`, `documents`, `spreadsheets`, `presentations`, `calendar`, `calendar.events`.
 - Changing scopes usually requires re-authentication.
 
+### Auth Server Port Configuration
+
+During OAuth authentication, a local HTTP server is started to receive the callback. By default it tries ports 3000–3004. If those conflict with other services (e.g., a dev server), you can change the starting port:
+
+```bash
+export GOOGLE_DRIVE_MCP_AUTH_PORT=3100
+```
+
+The server will try 5 consecutive ports starting from the configured value (e.g., 3100–3104).
+
 ### Token Storage
 
 Authentication tokens are stored securely following the XDG Base Directory specification:
@@ -1104,7 +1114,7 @@ OAuth credentials not found. Please provide credentials using one of these metho
 #### "Authentication failed" or Browser doesn't open
 **Possible causes:**
 1. **Wrong credential type**: Must be "Desktop app", not "Web application"
-2. **Port blocked**: Ports 3000-3004 must be available
+2. **Port blocked**: Ports 3000-3004 must be available (or custom range if `GOOGLE_DRIVE_MCP_AUTH_PORT` is set)
 3. **Test user not added**: Add your email in OAuth consent screen
 
 **Solution:**
@@ -1112,9 +1122,12 @@ OAuth credentials not found. Please provide credentials using one of these metho
 # Check if ports are in use
 lsof -i :3000-3004
 
-# Kill processes if needed
+# Option 1: Kill processes if needed
 kill -9 <PID>
 
+# Option 2: Use a different port range
+export GOOGLE_DRIVE_MCP_AUTH_PORT=3100
+
 # Re-run authentication
 npx @piotr-agier/google-drive-mcp auth
 ```
@@ -1309,6 +1322,7 @@ npm run typecheck # Type checking without compilation
 | Variable | Description | Default | Example |
 |----------|-------------|---------|---------|
 | `GOOGLE_DRIVE_MCP_TOKEN_PATH` | Override token storage location | `~/.config/google-drive-mcp/tokens.json` | `/custom/path/tokens.json` |
+| `GOOGLE_DRIVE_MCP_AUTH_PORT` | Starting port for OAuth callback server (uses 5 consecutive ports) | `3000` | `3100` |
 | `DEBUG` | Enable debug logging | (disabled) | `google-drive-mcp:*` |
 
 **External Authentication** (alternative to local OAuth flow):

package/dist/index.js

@@ -427,7 +427,14 @@ var AuthServer = class {
     this.baseOAuth2Client = oauth2Client;
     this.tokenManager = new TokenManager(oauth2Client);
     this.app = express();
-    this.portRange = { start: 3e3, end: 3004 };
+    const raw = process.env.GOOGLE_DRIVE_MCP_AUTH_PORT;
+    const portStart = raw ? Number(raw) : 3e3;
+    if (!Number.isInteger(portStart) || portStart < 1 || portStart > 65531) {
+      throw new Error(
+        `Invalid GOOGLE_DRIVE_MCP_AUTH_PORT: "${raw}". Must be an integer between 1 and 65531.`
+      );
+    }
+    this.portRange = { start: portStart, end: portStart + 4 };
     this.setupRoutes();
   }
   setupRoutes() {
@@ -1085,7 +1092,8 @@ var AddPermissionSchema = z.object({
   emailAddress: z.string().email("Valid email is required"),
   role: z.enum(["owner", "organizer", "fileOrganizer", "writer", "commenter", "reader"]).default("reader"),
   type: z.enum(["user", "group", "domain", "anyone"]).default("user"),
-  sendNotificationEmail: z.boolean().optional().default(false)
+  sendNotificationEmail: z.boolean().optional().default(false),
+  emailMessage: z.string().optional()
 });
 var UpdatePermissionSchema = z.object({
   fileId: z.string().min(1, "File ID is required"),
@@ -1105,7 +1113,8 @@ var ShareFileSchema = z.object({
   fileId: z.string().min(1, "File ID is required"),
   emailAddress: z.string().email("Valid email is required"),
   role: z.enum(["writer", "commenter", "reader"]).default("reader"),
-  sendNotificationEmail: z.boolean().optional().default(true)
+  sendNotificationEmail: z.boolean().optional().default(true),
+  emailMessage: z.string().optional()
 });
 var ConvertPdfToGoogleDocSchema = z.object({
   fileId: z.string().min(1, "File ID is required"),
@@ -1349,7 +1358,8 @@ var toolDefinitions = [
         emailAddress: { type: "string", description: "Target user/group email" },
         role: { type: "string", enum: ["owner", "organizer", "fileOrganizer", "writer", "commenter", "reader"], description: "Permission role" },
         type: { type: "string", enum: ["user", "group", "domain", "anyone"], description: "Principal type" },
-        sendNotificationEmail: { type: "boolean", description: "Send notification email" }
+        sendNotificationEmail: { type: "boolean", description: "Send notification email" },
+        emailMessage: { type: "string", description: "Custom message to include in the notification email. Ignored unless sendNotificationEmail is true." }
       },
       required: ["fileId", "emailAddress"]
     }
@@ -1389,7 +1399,8 @@ var toolDefinitions = [
         fileId: { type: "string", description: "Google Drive file ID" },
         emailAddress: { type: "string", description: "User email" },
         role: { type: "string", enum: ["writer", "commenter", "reader"], description: "Access role" },
-        sendNotificationEmail: { type: "boolean", description: "Send notification email" }
+        sendNotificationEmail: { type: "boolean", description: "Send notification email" },
+        emailMessage: { type: "string", description: "Custom message to include in the notification email. Ignored unless sendNotificationEmail is true." }
       },
       required: ["fileId", "emailAddress"]
     }
@@ -2139,6 +2150,7 @@ ${lines.join("\n")}` }], isError: false };
           emailAddress: data.emailAddress
         },
         sendNotificationEmail: data.sendNotificationEmail,
+        ...data.emailMessage && { emailMessage: data.emailMessage },
         fields: "id,type,role,emailAddress",
         supportsAllDrives: true
       });
@@ -2225,6 +2237,7 @@ ${lines.join("\n")}` }], isError: false };
           emailAddress: data.emailAddress
         },
         sendNotificationEmail: data.sendNotificationEmail,
+        ...data.emailMessage && { emailMessage: data.emailMessage },
         fields: "id,type,role,emailAddress",
         supportsAllDrives: true
       });
@@ -3143,7 +3156,8 @@ var CreateGoogleDocSchema = z2.object({
 });
 var UpdateGoogleDocSchema = z2.object({
   documentId: z2.string().min(1, "Document ID is required"),
-  content: z2.string()
+  content: z2.string(),
+  tabId: z2.string().optional()
 });
 var GetGoogleDocContentSchema = z2.object({
   documentId: z2.string().min(1, "Document ID is required"),
@@ -3152,12 +3166,14 @@ var GetGoogleDocContentSchema = z2.object({
 var InsertTextSchema = z2.object({
   documentId: z2.string().min(1, "Document ID is required"),
   text: z2.string().min(1, "Text to insert is required"),
-  index: z2.number().int().min(1, "Index must be at least 1 (1-based)")
+  index: z2.number().int().min(1, "Index must be at least 1 (1-based)"),
+  tabId: z2.string().optional()
 });
 var DeleteRangeSchema = z2.object({
   documentId: z2.string().min(1, "Document ID is required"),
   startIndex: z2.number().int().min(1, "Start index must be at least 1"),
-  endIndex: z2.number().int().min(1, "End index must be at least 1")
+  endIndex: z2.number().int().min(1, "End index must be at least 1"),
+  tabId: z2.string().optional()
 }).refine((data) => data.endIndex > data.startIndex, {
   message: "End index must be greater than start index",
   path: ["endIndex"]
@@ -3298,7 +3314,8 @@ var FindAndReplaceInDocSchema = z2.object({
   findText: z2.string().min(1, "findText is required"),
   replaceText: z2.string(),
   matchCase: z2.boolean().optional().default(false),
-  dryRun: z2.boolean().optional().default(false)
+  dryRun: z2.boolean().optional().default(false),
+  tabId: z2.string().optional()
 });
 var AddDocumentTabSchema = z2.object({
   documentId: z2.string().min(1, "Document ID is required"),
@@ -3342,38 +3359,41 @@ var toolDefinitions2 = [
   },
   {
     name: "updateGoogleDoc",
-    description: "Update an existing Google Doc",
+    description: "Update an existing Google Doc (replaces all content). For multi-tab docs, specify tabId to replace a single tab's content atomically; leaves other tabs untouched.",
     inputSchema: {
       type: "object",
       properties: {
         documentId: { type: "string", description: "Doc ID" },
-        content: { type: "string", description: "New content" }
+        content: { type: "string", description: "New content" },
+        tabId: { type: "string", description: "Optional. Tab ID to replace (from listDocumentTabs). If set, delete+insert run in a single atomic batchUpdate scoped to that tab." }
       },
       required: ["documentId", "content"]
     }
   },
   {
     name: "insertText",
-    description: "Insert text at a specific index in a Google Doc (surgical edit, doesn't replace entire doc)",
+    description: "Insert text at a specific index in a Google Doc (surgical edit, doesn't replace entire doc). For multi-tab docs, specify tabId to target a specific tab.",
     inputSchema: {
       type: "object",
       properties: {
         documentId: { type: "string", description: "The document ID" },
         text: { type: "string", description: "Text to insert" },
-        index: { type: "number", description: "Position to insert at (1-based)" }
+        index: { type: "number", description: "Position to insert at (1-based)" },
+        tabId: { type: "string", description: "Optional. Tab ID to insert into (from listDocumentTabs). If omitted, inserts into the first/default tab." }
       },
       required: ["documentId", "text", "index"]
     }
   },
   {
     name: "deleteRange",
-    description: "Delete content between start and end indices in a Google Doc",
+    description: "Delete content between start and end indices in a Google Doc. For multi-tab docs, specify tabId to target a specific tab.",
     inputSchema: {
       type: "object",
       properties: {
         documentId: { type: "string", description: "The document ID" },
         startIndex: { type: "number", description: "Start index (1-based, inclusive)" },
-        endIndex: { type: "number", description: "End index (exclusive)" }
+        endIndex: { type: "number", description: "End index (exclusive)" },
+        tabId: { type: "string", description: "Optional. Tab ID to delete from (from listDocumentTabs). If omitted, deletes from the first/default tab." }
       },
       required: ["documentId", "startIndex", "endIndex"]
     }
@@ -3516,7 +3536,7 @@ var toolDefinitions2 = [
   },
   {
     name: "findAndReplaceInDoc",
-    description: "Find and replace text across a Google Document. Dry-run mode counts matches from paragraph text only (may differ from actual replacements which cover tables, headers, footers, etc.)",
+    description: "Find and replace text across a Google Document. Dry-run mode counts matches from paragraph text only (may differ from actual replacements which cover tables, headers, footers, etc.). For multi-tab docs, specify tabId to scope replacements to a single tab.",
     inputSchema: {
       type: "object",
       properties: {
@@ -3524,7 +3544,8 @@ var toolDefinitions2 = [
         findText: { type: "string", description: "Text to find" },
         replaceText: { type: "string", description: "Replacement text" },
         matchCase: { type: "boolean", description: "Case-sensitive match (default: false)" },
-        dryRun: { type: "boolean", description: "Only count approximate matches from paragraph text, do not modify document (default: false)" }
+        dryRun: { type: "boolean", description: "Only count approximate matches from paragraph text, do not modify document (default: false). Ignores tabId \u2014 always scans the full document body." },
+        tabId: { type: "string", description: "Optional. Tab ID to scope replacements to (from listDocumentTabs). If omitted, replaces across all tabs." }
       },
       required: ["documentId", "findText", "replaceText"]
     }
@@ -3838,6 +3859,43 @@ Link: ${doc.webViewLink}` }],
       }
       const a = validation.data;
       const docs = ctx.google.docs({ version: "v1", auth: ctx.authClient });
+      if (a.tabId) {
+        const document2 = await docs.documents.get({ documentId: a.documentId, includeTabsContent: true });
+        const tabs = document2.data.tabs;
+        const tab = tabs ? findTabById(tabs, a.tabId) : null;
+        if (!tab) {
+          return errorResponse(`Tab with ID "${a.tabId}" not found. Use listDocumentTabs to see available tabs.`);
+        }
+        const bodyContent = tab.documentTab?.body?.content;
+        const lastEndIndex = bodyContent?.[bodyContent.length - 1]?.endIndex ?? 1;
+        const deleteEndIndex2 = Math.max(1, lastEndIndex - 1);
+        const requests = [];
+        if (deleteEndIndex2 > 1) {
+          requests.push({
+            deleteContentRange: {
+              range: { startIndex: 1, endIndex: deleteEndIndex2, tabId: a.tabId }
+            }
+          });
+        }
+        requests.push({
+          insertText: { location: { index: 1, tabId: a.tabId }, text: a.content }
+        });
+        requests.push({
+          updateParagraphStyle: {
+            range: { startIndex: 1, endIndex: a.content.length + 1, tabId: a.tabId },
+            paragraphStyle: { namedStyleType: "NORMAL_TEXT" },
+            fields: "namedStyleType"
+          }
+        });
+        await docs.documents.batchUpdate({
+          documentId: a.documentId,
+          requestBody: { requests }
+        });
+        return {
+          content: [{ type: "text", text: `Updated Google Doc: ${document2.data.title} (tab: ${a.tabId})` }],
+          isError: false
+        };
+      }
       const document = await docs.documents.get({ documentId: a.documentId });
       const endIndex = document.data.body?.content?.[document.data.body.content.length - 1]?.endIndex || 1;
       const deleteEndIndex = Math.max(1, endIndex - 1);
@@ -4118,20 +4176,22 @@ Total length: ${totalLength} characters`
         return errorResponse(validation.error.errors[0].message);
       }
       const a = validation.data;
+      const location = { index: a.index };
+      if (a.tabId) location.tabId = a.tabId;
       const docs = ctx.google.docs({ version: "v1", auth: ctx.authClient });
       await docs.documents.batchUpdate({
         documentId: a.documentId,
         requestBody: {
           requests: [{
             insertText: {
-              location: { index: a.index },
+              location,
               text: a.text
             }
           }]
         }
       });
       return {
-        content: [{ type: "text", text: `Successfully inserted ${a.text.length} characters at index ${a.index}` }],
+        content: [{ type: "text", text: `Successfully inserted ${a.text.length} characters at index ${a.index}${a.tabId ? ` in tab ${a.tabId}` : ""}` }],
         isError: false
       };
     }
@@ -4144,22 +4204,22 @@ Total length: ${totalLength} characters`
       if (a.endIndex <= a.startIndex) {
         return errorResponse("endIndex must be greater than startIndex");
       }
+      const range = {
+        startIndex: a.startIndex,
+        endIndex: a.endIndex
+      };
+      if (a.tabId) range.tabId = a.tabId;
       const docs = ctx.google.docs({ version: "v1", auth: ctx.authClient });
       await docs.documents.batchUpdate({
         documentId: a.documentId,
         requestBody: {
           requests: [{
-            deleteContentRange: {
-              range: {
-                startIndex: a.startIndex,
-                endIndex: a.endIndex
-              }
-            }
+            deleteContentRange: { range }
           }]
         }
       });
       return {
-        content: [{ type: "text", text: `Successfully deleted content from index ${a.startIndex} to ${a.endIndex}` }],
+        content: [{ type: "text", text: `Successfully deleted content from index ${a.startIndex} to ${a.endIndex}${a.tabId ? ` in tab ${a.tabId}` : ""}` }],
         isError: false
       };
     }
@@ -4541,25 +4601,20 @@ ${text}`;
           isError: false
         };
       }
+      const replaceAllText = {
+        containsText: { text: a.findText, matchCase: a.matchCase },
+        replaceText: a.replaceText
+      };
+      if (a.tabId) replaceAllText.tabsCriteria = { tabIds: [a.tabId] };
       const response = await docs.documents.batchUpdate({
         documentId: a.documentId,
         requestBody: {
-          requests: [
-            {
-              replaceAllText: {
-                containsText: {
-                  text: a.findText,
-                  matchCase: a.matchCase
-                },
-                replaceText: a.replaceText
-              }
-            }
-          ]
+          requests: [{ replaceAllText }]
         }
       });
       const occurrences = response.data.replies?.[0]?.replaceAllText?.occurrencesChanged ?? 0;
       return {
-        content: [{ type: "text", text: `Replaced ${occurrences} occurrence(s) of "${a.findText}".` }],
+        content: [{ type: "text", text: `Replaced ${occurrences} occurrence(s) of "${a.findText}"${a.tabId ? ` in tab ${a.tabId}` : ""}.` }],
         isError: false
       };
     }
@@ -5131,8 +5186,10 @@ Image URL: ${imageUrl}` }],
       const docs = ctx.google.docs({ version: "v1", auth: ctx.authClient });
       await docs.documents.batchUpdate({
         documentId: a.documentId,
-        // updateDocumentTabProperties is not yet in the googleapis TypeScript types — cast required
-        requestBody: { requests: [{ updateDocumentTabProperties: { tabId: a.tabId, tabProperties: { title: a.title }, fields: "title" } }] }
+        // updateDocumentTabProperties is not yet in the googleapis TypeScript types — cast required.
+        // Per Google Docs API spec: tabId lives INSIDE tabProperties (it's the tab identifier),
+        // and `fields` is a FieldMask for which properties to update (excludes tabId).
+        requestBody: { requests: [{ updateDocumentTabProperties: { tabProperties: { tabId: a.tabId, title: a.title }, fields: "title" } }] }
       });
       return { content: [{ type: "text", text: `Renamed tab ${a.tabId} to "${a.title}".` }], isError: false };
     }
@@ -8812,6 +8869,7 @@ Examples:
 Environment Variables:
   GOOGLE_DRIVE_OAUTH_CREDENTIALS        Path to OAuth credentials file
   GOOGLE_DRIVE_MCP_TOKEN_PATH           Path to store authentication tokens
+  GOOGLE_DRIVE_MCP_AUTH_PORT            Starting port for OAuth callback server (default: 3000, uses 5 consecutive ports)
 
   Transport Configuration:
   MCP_TRANSPORT                         Transport mode: stdio or http (default: stdio)
@@ -8837,8 +8895,9 @@ async function runAuthServer() {
     const authServerInstance = new AuthServer(oauth2Client);
     const success = await authServerInstance.start(true);
     if (!success && !authServerInstance.authCompletedSuccessfully) {
+      const { start, end } = authServerInstance.portRange;
       console.error(
-        "Authentication failed. Could not start server or validate existing tokens. Check port availability (3000-3004) and try again."
+        `Authentication failed. Could not start server or validate existing tokens. Check port availability (${start}-${end}) and try again.`
       );
       process.exit(1);
     } else if (authServerInstance.authCompletedSuccessfully) {