@triffon/google-docs-mcp 1.11.3-triffon

package/dist/tools/drive/listGoogleDocs.js

@@ -0,0 +1,70 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDriveClient } from '../../clients.js';
+import { escapeDriveQuery } from '../../driveQueryUtils.js';
+export function register(server) {
+    server.addTool({
+        name: 'listDocuments',
+        description: 'Lists Google Documents in your Drive, optionally filtered by name or content. Use modifiedAfter to find recently changed documents.',
+        parameters: z.strictObject({
+            maxResults: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .optional()
+                .default(20)
+                .describe('Maximum number of documents to return (1-100).'),
+            query: z.string().optional().describe('Search query to filter documents by name or content.'),
+            orderBy: z
+                .enum(['name', 'modifiedTime', 'createdTime'])
+                .optional()
+                .default('modifiedTime')
+                .describe('Sort order for results.'),
+            modifiedAfter: z
+                .string()
+                .optional()
+                .describe('Only return documents modified after this date (ISO 8601 format, e.g., "2024-01-01").'),
+        }),
+        execute: async (args, { log }) => {
+            const drive = await getDriveClient();
+            log.info(`Listing Google Docs. Query: ${args.query || 'none'}, Max: ${args.maxResults}, Order: ${args.orderBy}`);
+            try {
+                // Build the query string for Google Drive API
+                let queryString = "mimeType='application/vnd.google-apps.document' and trashed=false";
+                if (args.query) {
+                    queryString += ` and (name contains '${escapeDriveQuery(args.query)}' or fullText contains '${escapeDriveQuery(args.query)}')`;
+                }
+                if (args.modifiedAfter) {
+                    const cutoffDate = new Date(args.modifiedAfter).toISOString();
+                    queryString += ` and modifiedTime > '${escapeDriveQuery(cutoffDate)}'`;
+                }
+                const response = await drive.files.list({
+                    q: queryString,
+                    pageSize: args.maxResults,
+                    // Drive rejects `orderBy` when `q` contains a `fullText` clause
+                    // ("Sorting is not supported for queries with fullText terms").
+                    ...(args.query ? {} : { orderBy: args.orderBy === 'name' ? 'name' : args.orderBy }),
+                    fields: 'files(id,name,modifiedTime,createdTime,size,webViewLink,owners(displayName,emailAddress))',
+                    supportsAllDrives: true,
+                    includeItemsFromAllDrives: true,
+                });
+                const files = response.data.files || [];
+                const documents = files.map((file) => ({
+                    id: file.id,
+                    name: file.name,
+                    modifiedTime: file.modifiedTime,
+                    owner: file.owners?.[0]?.displayName || null,
+                    url: file.webViewLink,
+                }));
+                return JSON.stringify({ documents }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error listing Google Docs: ${error.message || error}`);
+                if (error.code === 403)
+                    throw new UserError('Permission denied. Make sure you have granted Google Drive access to the application.');
+                throw new UserError(`Failed to list documents: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/drive/moveFile.js

@@ -0,0 +1,54 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDriveClient } from '../../clients.js';
+export function register(server) {
+    server.addTool({
+        name: 'moveFile',
+        description: 'Moves a file or folder to a different Drive folder. By default adds the new parent while keeping existing parents; set removeFromAllParents=true for a true move.',
+        parameters: z.strictObject({
+            fileId: z
+                .string()
+                .describe('The file or folder ID from a Google Drive URL or a previous tool result.'),
+            newParentId: z.string().describe('ID of the destination folder. Use "root" for Drive root.'),
+            removeFromAllParents: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe('If true, removes from all current parents. If false, adds to new parent while keeping existing parents.'),
+        }),
+        execute: async (args, { log }) => {
+            const drive = await getDriveClient();
+            log.info(`Moving file ${args.fileId} to folder ${args.newParentId}`);
+            try {
+                // First get the current parents
+                const fileInfo = await drive.files.get({
+                    fileId: args.fileId,
+                    fields: 'name,parents',
+                    supportsAllDrives: true,
+                });
+                const fileName = fileInfo.data.name;
+                const currentParents = fileInfo.data.parents || [];
+                let updateParams = {
+                    fileId: args.fileId,
+                    addParents: args.newParentId,
+                    fields: 'id,name,parents',
+                    supportsAllDrives: true,
+                };
+                if (args.removeFromAllParents && currentParents.length > 0) {
+                    updateParams.removeParents = currentParents.join(',');
+                }
+                const response = await drive.files.update(updateParams);
+                const action = args.removeFromAllParents ? 'moved' : 'copied';
+                return `Successfully ${action} "${fileName}" to new location.\nFile ID: ${response.data.id}`;
+            }
+            catch (error) {
+                log.error(`Error moving file: ${error.message || error}`);
+                if (error.code === 404)
+                    throw new UserError('File or destination folder not found. Check the IDs.');
+                if (error.code === 403)
+                    throw new UserError('Permission denied. Make sure you have write access to both source and destination.');
+                throw new UserError(`Failed to move file: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/drive/renameFile.js

@@ -0,0 +1,39 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDriveClient } from '../../clients.js';
+export function register(server) {
+    server.addTool({
+        name: 'renameFile',
+        description: 'Renames a file or folder in Google Drive. Returns the updated file info.',
+        parameters: z.strictObject({
+            fileId: z
+                .string()
+                .describe('The file or folder ID from a Google Drive URL or a previous tool result.'),
+            newName: z.string().min(1).describe('New name for the file or folder.'),
+        }),
+        execute: async (args, { log }) => {
+            const drive = await getDriveClient();
+            log.info(`Renaming file ${args.fileId} to "${args.newName}"`);
+            try {
+                const response = await drive.files.update({
+                    fileId: args.fileId,
+                    requestBody: {
+                        name: args.newName,
+                    },
+                    fields: 'id,name,webViewLink',
+                    supportsAllDrives: true,
+                });
+                const file = response.data;
+                return `Successfully renamed to "${file.name}" (ID: ${file.id})\nLink: ${file.webViewLink}`;
+            }
+            catch (error) {
+                log.error(`Error renaming file: ${error.message || error}`);
+                if (error.code === 404)
+                    throw new UserError('File not found. Check the file ID.');
+                if (error.code === 403)
+                    throw new UserError('Permission denied. Make sure you have write access to this file.');
+                throw new UserError(`Failed to rename file: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/drive/savePathGuard.js

@@ -0,0 +1,86 @@
+// Path boundary for downloadFile's `savePath`.
+//
+// downloadFile runs on behalf of an AI agent that routinely reads untrusted
+// content (Drive documents, exported text). Both `fileId` and `savePath` are
+// therefore attacker-influenceable through indirect prompt injection, and in
+// stdio mode `savePath` reaches fs.createWriteStream() directly — an arbitrary
+// file write primitive (CWE-22 / CWE-73) if it is not constrained.
+//
+// v1.10.0 confined writes to the working directory with ensureWithinCwd();
+// v1.11.0 dropped it. This restores the boundary, resolves symlinks so a
+// symlinked directory cannot be used to escape, and makes the allowed roots
+// configurable for people who legitimately save outside the working directory.
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * Parses GOOGLE_DOCS_MCP_DOWNLOAD_ROOTS: a platform-delimited list of
+ * directories that downloadFile may write to. Defaults to the working
+ * directory, which is the v1.10.0 behavior.
+ */
+export function parseDownloadRoots(value, cwd = process.cwd()) {
+    const raw = value ?? process.env.GOOGLE_DOCS_MCP_DOWNLOAD_ROOTS ?? '';
+    const entries = raw
+        .split(path.delimiter)
+        .map((entry) => entry.trim())
+        .filter(Boolean)
+        .map((entry) => path.resolve(cwd, entry));
+    return entries.length > 0 ? entries : [path.resolve(cwd)];
+}
+function isInside(child, parent) {
+    if (child === parent)
+        return true;
+    return child.startsWith(parent.endsWith(path.sep) ? parent : parent + path.sep);
+}
+/** Deepest ancestor of `target` that exists on disk, as a literal path. */
+function nearestExistingAncestor(target) {
+    let current = target;
+    for (;;) {
+        if (fs.existsSync(current))
+            return current;
+        const parent = path.dirname(current);
+        if (parent === current)
+            return current;
+        current = parent;
+    }
+}
+/**
+ * Canonicalizes a path that may not exist yet: resolves symlinks as far as the
+ * filesystem allows, then re-appends the portion that has still to be created.
+ *
+ * Both the destination and the allowed roots go through this, so a root behind
+ * a symlink (on macOS `/tmp` is a link to `/private/tmp`) compares correctly,
+ * and a symlinked directory inside a root cannot redirect a write out of it.
+ */
+function canonicalize(target) {
+    const absolute = path.resolve(target);
+    const ancestor = nearestExistingAncestor(absolute);
+    let realAncestor;
+    try {
+        realAncestor = fs.realpathSync(ancestor);
+    }
+    catch {
+        return absolute;
+    }
+    return path.resolve(realAncestor, path.relative(ancestor, absolute));
+}
+/**
+ * Resolves `savePath` and throws if it would write outside the allowed roots.
+ *
+ * Comparison happens after symlinks are resolved on both sides, which rejects
+ * `../` traversal and symlinked-directory escapes alike.
+ *
+ * @throws Error when the destination escapes every allowed root.
+ */
+export function ensureWithinDownloadRoots(savePath, roots) {
+    const resolved = path.resolve(savePath);
+    const realTarget = canonicalize(resolved);
+    const realRoots = roots.map((root) => canonicalize(root));
+    if (!realRoots.some((root) => isInside(realTarget, root))) {
+        throw new Error(`savePath must stay inside the allowed download directory. ` +
+            `"${savePath}" resolves to "${realTarget}", which is outside ${realRoots
+                .map((root) => `"${root}"`)
+                .join(', ')}. ` +
+            `Pass a path inside that directory, or set GOOGLE_DOCS_MCP_DOWNLOAD_ROOTS to allow another one.`);
+    }
+    return resolved;
+}

package/dist/tools/drive/searchDriveFiles.js

@@ -0,0 +1,148 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDriveClient } from '../../clients.js';
+import { escapeDriveQuery } from '../../driveQueryUtils.js';
+/**
+ * Convenience shortcuts for common MIME types.
+ * Users can also pass any full MIME type string directly.
+ */
+const MIME_TYPE_SHORTCUTS = {
+    document: 'application/vnd.google-apps.document',
+    spreadsheet: 'application/vnd.google-apps.spreadsheet',
+    presentation: 'application/vnd.google-apps.presentation',
+    folder: 'application/vnd.google-apps.folder',
+    form: 'application/vnd.google-apps.form',
+    pdf: 'application/pdf',
+    zip: 'application/zip',
+};
+export function register(server) {
+    server.addTool({
+        name: 'searchDriveFiles',
+        description: 'Searches across all file types in Google Drive by name or content. ' +
+            'Unlike searchDocuments (which only searches Google Docs), this tool finds Sheets, PDFs, ' +
+            'presentations, folders, and any other Drive file. Supports filtering by MIME type, ' +
+            'scoping to a specific folder subtree, controllable sort order, and pagination via pageToken.',
+        parameters: z.strictObject({
+            query: z.string().min(1).describe('Search term to find in file names or content.'),
+            searchIn: z
+                .enum(['name', 'content', 'both'])
+                .optional()
+                .default('both')
+                .describe('Where to search: "name" matches file titles only, "content" searches inside files, ' +
+                '"both" searches names and content (default).'),
+            mimeType: z
+                .string()
+                .optional()
+                .describe('Restrict search to a specific file type. ' +
+                'Shortcuts: "document", "spreadsheet", "presentation", "folder", "form", "pdf", "zip". ' +
+                'Or pass a full MIME type string.'),
+            folderId: z
+                .string()
+                .optional()
+                .describe('Restrict search to files inside this folder (and its subfolders). ' +
+                'Use "root" for the top-level Drive. Omit to search all of Drive.'),
+            orderBy: z
+                .enum(['name', 'modifiedTime', 'createdTime'])
+                .optional()
+                .default('modifiedTime')
+                .describe('Field to sort results by.'),
+            sortDirection: z
+                .enum(['asc', 'desc'])
+                .optional()
+                .default('desc')
+                .describe('Sort direction: "asc" for oldest first, "desc" for newest first (default).'),
+            maxResults: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .optional()
+                .default(10)
+                .describe('Maximum number of results to return per page (1-100).'),
+            modifiedAfter: z
+                .string()
+                .optional()
+                .describe('Only return files modified after this date (ISO 8601 format, e.g. "2024-01-01").'),
+            pageToken: z
+                .string()
+                .optional()
+                .describe('Pagination token from a previous searchDriveFiles response. ' +
+                'Pass this to retrieve the next page of results.'),
+        }),
+        execute: async (args, { log }) => {
+            const drive = await getDriveClient();
+            log.info(`Searching Drive files for: "${args.query}" in ${args.searchIn}, ` +
+                `mimeType=${args.mimeType || 'any'}, folder=${args.folderId || 'all'}, ` +
+                `orderBy=${args.orderBy} ${args.sortDirection}`);
+            try {
+                const conditions = ['trashed=false'];
+                // Search term
+                if (args.searchIn === 'name') {
+                    conditions.push(`name contains '${escapeDriveQuery(args.query)}'`);
+                }
+                else if (args.searchIn === 'content') {
+                    conditions.push(`fullText contains '${escapeDriveQuery(args.query)}'`);
+                }
+                else {
+                    conditions.push(`(name contains '${escapeDriveQuery(args.query)}' or fullText contains '${escapeDriveQuery(args.query)}')`);
+                }
+                // Resolve MIME type shortcut or use value as-is
+                if (args.mimeType) {
+                    const resolved = MIME_TYPE_SHORTCUTS[args.mimeType] ?? args.mimeType;
+                    conditions.push(`mimeType='${escapeDriveQuery(resolved)}'`);
+                }
+                // Scope to a specific folder (searches within the folder subtree via fullText,
+                // but Drive API does not support recursive parent filtering natively — using
+                // ancestor query instead which covers all descendants)
+                if (args.folderId) {
+                    conditions.push(`'${escapeDriveQuery(args.folderId)}' in ancestors`);
+                }
+                // Date filter
+                if (args.modifiedAfter) {
+                    const cutoff = new Date(args.modifiedAfter).toISOString();
+                    conditions.push(`modifiedTime > '${escapeDriveQuery(cutoff)}'`);
+                }
+                const queryString = conditions.join(' and ');
+                const orderByParam = args.sortDirection === 'desc' ? `${args.orderBy} desc` : args.orderBy;
+                // Drive rejects `orderBy` when `q` contains a `fullText` clause
+                // ("Sorting is not supported for queries with fullText terms") —
+                // only the "name" search mode avoids fullText.
+                const includesFullText = args.searchIn !== 'name';
+                const response = await drive.files.list({
+                    q: queryString,
+                    pageSize: args.maxResults,
+                    ...(includesFullText ? {} : { orderBy: orderByParam }),
+                    pageToken: args.pageToken,
+                    fields: 'nextPageToken,files(id,name,mimeType,size,modifiedTime,createdTime,webViewLink,owners(displayName,emailAddress),parents)',
+                    supportsAllDrives: true,
+                    includeItemsFromAllDrives: true,
+                });
+                const files = (response.data.files || []).map((file) => ({
+                    id: file.id,
+                    name: file.name,
+                    mimeType: file.mimeType,
+                    size: file.size != null ? Number(file.size) : null,
+                    modifiedTime: file.modifiedTime,
+                    createdTime: file.createdTime,
+                    owner: file.owners?.[0]?.displayName || null,
+                    url: file.webViewLink,
+                }));
+                const result = { files, total: files.length };
+                if (response.data.nextPageToken) {
+                    result.nextPageToken = response.data.nextPageToken;
+                    result.hasMore = true;
+                }
+                else {
+                    result.hasMore = false;
+                }
+                return JSON.stringify(result, null, 2);
+            }
+            catch (error) {
+                log.error(`Error searching Drive files: ${error.message || error}`);
+                if (error.code === 403)
+                    throw new UserError('Permission denied. Make sure you have granted Google Drive access to the application.');
+                throw new UserError(`Failed to search files: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/drive/searchGoogleDocs.js

@@ -0,0 +1,77 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDriveClient } from '../../clients.js';
+import { escapeDriveQuery } from '../../driveQueryUtils.js';
+export function register(server) {
+    server.addTool({
+        name: 'searchDocuments',
+        description: 'Searches for documents by name, content, or both. Use listDocuments for browsing and this tool for targeted queries.',
+        parameters: z.strictObject({
+            query: z.string().min(1).describe('Search term to find in document names or content.'),
+            searchIn: z
+                .enum(['name', 'content', 'both'])
+                .optional()
+                .default('both')
+                .describe('Where to search: document names, content, or both.'),
+            maxResults: z
+                .number()
+                .int()
+                .min(1)
+                .max(50)
+                .optional()
+                .default(10)
+                .describe('Maximum number of results to return.'),
+            modifiedAfter: z
+                .string()
+                .optional()
+                .describe('Only return documents modified after this date (ISO 8601 format, e.g., "2024-01-01").'),
+        }),
+        execute: async (args, { log }) => {
+            const drive = await getDriveClient();
+            log.info(`Searching Google Docs for: "${args.query}" in ${args.searchIn}`);
+            try {
+                let queryString = "mimeType='application/vnd.google-apps.document' and trashed=false";
+                // Add search criteria
+                if (args.searchIn === 'name') {
+                    queryString += ` and name contains '${escapeDriveQuery(args.query)}'`;
+                }
+                else if (args.searchIn === 'content') {
+                    queryString += ` and fullText contains '${escapeDriveQuery(args.query)}'`;
+                }
+                else {
+                    queryString += ` and (name contains '${escapeDriveQuery(args.query)}' or fullText contains '${escapeDriveQuery(args.query)}')`;
+                }
+                // Add date filter if provided
+                if (args.modifiedAfter) {
+                    queryString += ` and modifiedTime > '${escapeDriveQuery(args.modifiedAfter)}'`;
+                }
+                const response = await drive.files.list({
+                    q: queryString,
+                    pageSize: args.maxResults,
+                    // Drive rejects `orderBy` when `q` contains a `fullText` clause
+                    // ("Sorting is not supported for queries with fullText terms") —
+                    // only the "name" search mode avoids fullText.
+                    ...(args.searchIn === 'name' ? { orderBy: 'modifiedTime desc' } : {}),
+                    fields: 'files(id,name,modifiedTime,createdTime,webViewLink,owners(displayName),parents)',
+                    supportsAllDrives: true,
+                    includeItemsFromAllDrives: true,
+                });
+                const files = response.data.files || [];
+                const documents = files.map((file) => ({
+                    id: file.id,
+                    name: file.name,
+                    modifiedTime: file.modifiedTime,
+                    owner: file.owners?.[0]?.displayName || null,
+                    url: file.webViewLink,
+                }));
+                return JSON.stringify({ documents }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error searching Google Docs: ${error.message || error}`);
+                if (error.code === 403)
+                    throw new UserError('Permission denied. Make sure you have granted Google Drive access to the application.');
+                throw new UserError(`Failed to search documents: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/drive/setFilePermission.js

@@ -0,0 +1,68 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDriveClient } from '../../clients.js';
+export function register(server) {
+    server.addTool({
+        name: 'setFilePermission',
+        description: "Sets a sharing permission on a Drive file or folder. Common case: type='anyone' with role='reader' enables 'anyone with the link can view'. Use type='user' with emailAddress to grant a specific person access. Returns the created permission record.",
+        parameters: z.strictObject({
+            fileId: z
+                .string()
+                .describe('The file or folder ID from a Drive URL or a previous tool result.'),
+            role: z
+                .enum(['reader', 'commenter', 'writer'])
+                .describe('Access level granted. "reader" = view only, "commenter" = view + comment, "writer" = full edit.'),
+            type: z
+                .enum(['user', 'group', 'domain', 'anyone'])
+                .describe('Who this permission applies to. "anyone" means anyone with the link (combine with allowFileDiscovery=false to keep it unlisted).'),
+            emailAddress: z.string().optional().describe("Required when type is 'user' or 'group'."),
+            domain: z.string().optional().describe("Required when type is 'domain'."),
+            sendNotificationEmail: z
+                .boolean()
+                .optional()
+                .describe('If true, Google sends a notification email when granting access to a user or group. Defaults to false.'),
+            allowFileDiscovery: z
+                .boolean()
+                .optional()
+                .describe("Only relevant for type='anyone' or 'domain'. If true, the file is discoverable via search; if false (default), only people with the direct link can find it."),
+        }),
+        execute: async (args, { log }) => {
+            const drive = await getDriveClient();
+            log.info(`Setting ${args.type}/${args.role} permission on file ${args.fileId}`);
+            if ((args.type === 'user' || args.type === 'group') && !args.emailAddress) {
+                throw new UserError(`emailAddress is required when type is "${args.type}".`);
+            }
+            if (args.type === 'domain' && !args.domain) {
+                throw new UserError('domain is required when type is "domain".');
+            }
+            const requestBody = {
+                role: args.role,
+                type: args.type,
+            };
+            if (args.emailAddress)
+                requestBody.emailAddress = args.emailAddress;
+            if (args.domain)
+                requestBody.domain = args.domain;
+            if (typeof args.allowFileDiscovery === 'boolean')
+                requestBody.allowFileDiscovery = args.allowFileDiscovery;
+            try {
+                const response = await drive.permissions.create({
+                    fileId: args.fileId,
+                    requestBody,
+                    sendNotificationEmail: args.sendNotificationEmail ?? false,
+                    supportsAllDrives: true,
+                    fields: 'id,type,role,emailAddress,domain,allowFileDiscovery',
+                });
+                return JSON.stringify(response.data, null, 2);
+            }
+            catch (error) {
+                log.error(`Error setting permission: ${error.message || error}`);
+                if (error.code === 404)
+                    throw new UserError('File not found. Check the file ID.');
+                if (error.code === 403)
+                    throw new UserError('Permission denied. You may not have rights to share this file, or the requested permission conflicts with org policy.');
+                throw new UserError(`Failed to set permission: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/gmail/createDraft.js

@@ -0,0 +1,58 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getGmailClient } from '../../clients.js';
+import { prepareMimeRequest } from './helpers.js';
+export function register(server) {
+    server.addTool({
+        name: 'createDraft',
+        description: 'Creates a Gmail draft (does NOT send). Use this for AI-composed emails that the user should review before sending. The draft appears in the Gmail Drafts folder and can be sent later with sendDraft, edited with updateDraft, or deleted with deleteDraft. Supports threading via replyToMessageId.',
+        parameters: z.strictObject({
+            to: z
+                .union([z.string(), z.array(z.string()).min(1)])
+                .describe('Recipient email address, or an array of recipient email addresses.'),
+            subject: z.string().describe('Email subject line.'),
+            body: z.string().describe('Plain-text body of the draft.'),
+            cc: z.array(z.string()).optional().describe('Optional list of Cc recipients.'),
+            bcc: z.array(z.string()).optional().describe('Optional list of Bcc recipients.'),
+            replyToMessageId: z
+                .string()
+                .optional()
+                .describe('Optional Gmail message ID to draft a reply to. The draft is threaded with the original.'),
+        }),
+        execute: async (args, { log }) => {
+            const gmail = await getGmailClient();
+            try {
+                const { raw, threadId, toList } = await prepareMimeRequest(gmail, args);
+                log.info(`Creating Gmail draft to ${toList.join(', ')}${args.replyToMessageId ? ` (reply to ${args.replyToMessageId})` : ''}`);
+                const response = await gmail.users.drafts.create({
+                    userId: 'me',
+                    requestBody: {
+                        message: {
+                            raw,
+                            ...(threadId ? { threadId } : {}),
+                        },
+                    },
+                });
+                return JSON.stringify({
+                    success: true,
+                    draftId: response.data.id,
+                    messageId: response.data.message?.id,
+                    threadId: response.data.message?.threadId,
+                    to: toList,
+                    subject: args.subject,
+                    message: `Draft created. Use sendDraft with draftId="${response.data.id}" to send it, or updateDraft to edit it first.`,
+                }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error creating draft: ${error.message || error}`);
+                if (error.code === 401)
+                    throw new UserError('Gmail authorization failed. Re-authorize to grant the gmail.modify scope.');
+                if (error.code === 403)
+                    throw new UserError('Permission denied. Confirm the gmail.modify scope was granted.');
+                if (error.code === 400)
+                    throw new UserError(`Gmail rejected the draft: ${error.message || 'Bad request'}`);
+                throw new UserError(`Failed to create draft: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/gmail/deleteDraft.js

@@ -0,0 +1,37 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getGmailClient } from '../../clients.js';
+export function register(server) {
+    server.addTool({
+        name: 'deleteDraft',
+        description: 'Permanently deletes a Gmail draft. This is irreversible — the draft is removed entirely, not moved to Trash. Use when an AI-composed draft was rejected or replaced.',
+        parameters: z.strictObject({
+            draftId: z
+                .string()
+                .describe('The Gmail draft ID to delete (from createDraft or listDrafts).'),
+        }),
+        execute: async (args, { log }) => {
+            const gmail = await getGmailClient();
+            log.info(`Deleting Gmail draft ${args.draftId}`);
+            try {
+                await gmail.users.drafts.delete({
+                    userId: 'me',
+                    id: args.draftId,
+                });
+                return JSON.stringify({
+                    success: true,
+                    draftId: args.draftId,
+                    message: `Draft ${args.draftId} permanently deleted.`,
+                }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error deleting draft: ${error.message || error}`);
+                if (error.code === 404)
+                    throw new UserError(`Draft not found (ID: ${args.draftId}).`);
+                if (error.code === 403)
+                    throw new UserError('Permission denied. Confirm the gmail.modify scope was granted.');
+                throw new UserError(`Failed to delete draft: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}