google-tools-mcp 1.0.0

package/dist/tools/docs/listDocumentTabs.js

@@ -0,0 +1,60 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDocsClient } from '../../clients.js';
+import { DocumentIdParameter } from '../../types.js';
+import * as GDocsHelpers from '../../googleDocsApiHelpers.js';
+export function register(server) {
+    server.addTool({
+        name: 'listTabs',
+        description: "Lists all tabs in a document with their IDs and hierarchy. Use the returned tab IDs with other tools' tabId parameter to target a specific tab.",
+        parameters: DocumentIdParameter.extend({
+            includeContent: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe('Whether to include a content summary for each tab (character count).'),
+        }),
+        execute: async (args, { log }) => {
+            const docs = await getDocsClient();
+            log.info(`Listing tabs for document: ${args.documentId}`);
+            try {
+                // Get document with tabs structure
+                const res = await docs.documents.get({
+                    documentId: args.documentId,
+                    includeTabsContent: true,
+                    // Only get essential fields for tab listing
+                    fields: args.includeContent
+                        ? 'title,tabs' // Get all tab data if we need content summary
+                        : 'title,tabs(tabProperties,childTabs)', // Otherwise just structure
+                });
+                const docTitle = res.data.title || 'Untitled Document';
+                // Get all tabs in a flat list with hierarchy info
+                const allTabs = GDocsHelpers.getAllTabs(res.data);
+                const tabs = allTabs.map((tab) => {
+                    const tabProperties = tab.tabProperties || {};
+                    const tabObj = {
+                        id: tabProperties.tabId || null,
+                        title: tabProperties.title || null,
+                        index: tabProperties.index ?? null,
+                    };
+                    if (tabProperties.parentTabId) {
+                        tabObj.parentTabId = tabProperties.parentTabId;
+                    }
+                    if (args.includeContent && tab.documentTab) {
+                        tabObj.characterCount = GDocsHelpers.getTabTextLength(tab.documentTab);
+                    }
+                    return tabObj;
+                });
+                return JSON.stringify({ documentTitle: docTitle, tabs }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error listing tabs for doc ${args.documentId}: ${error.message || error}`);
+                if (error.code === 404)
+                    throw new UserError(`Document not found (ID: ${args.documentId}).`);
+                if (error.code === 403)
+                    throw new UserError(`Permission denied for document (ID: ${args.documentId}).`);
+                throw new UserError(`Failed to list tabs: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/docs/modifyText.js

@@ -0,0 +1,158 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDocsClient } from '../../clients.js';
+import { DocumentIdParameter, TextFindParameter, TextStyleParameters } from '../../types.js';
+import * as GDocsHelpers from '../../googleDocsApiHelpers.js';
+const RangeTarget = z
+    .object({
+    startIndex: z.number().int().min(1).describe('Start of range (inclusive, 1-based).'),
+    endIndex: z.number().int().min(1).describe('End of range (exclusive).'),
+})
+    .refine((d) => d.endIndex > d.startIndex, {
+    message: 'endIndex must be greater than startIndex',
+    path: ['endIndex'],
+});
+const InsertionTarget = z.object({
+    insertionIndex: z.number().int().min(1).describe('Index to insert at (1-based).'),
+});
+const ModifyTextParameters = DocumentIdParameter.extend({
+    target: z
+        .union([RangeTarget, TextFindParameter, InsertionTarget])
+        .describe('Target by range indices, text search, or insertion index.'),
+    text: z.string().optional().describe('New text to insert or replace with.'),
+    style: TextStyleParameters.optional().describe('Text formatting to apply.'),
+    tabId: z
+        .string()
+        .optional()
+        .describe('The ID of the specific tab to operate on. If not specified, operates on the first tab.'),
+})
+    .refine((args) => args.text !== undefined || args.style !== undefined, {
+    message: 'At least one of text or style must be provided.',
+})
+    .refine((args) => {
+    if ('insertionIndex' in args.target && args.text === undefined)
+        return false;
+    return true;
+}, { message: 'text is required when using insertionIndex target (no existing range to format).' });
+/**
+ * Pure, sync function that builds the array of Google Docs API requests for a
+ * modifyText operation. Indices must already be resolved (no text-search here).
+ */
+export function buildModifyTextRequests(opts) {
+    const { startIndex, endIndex, text, style, tabId } = opts;
+    const requests = [];
+    if (!text && !style)
+        return requests;
+    // 1. Delete existing content (only when replacing, not insert-only)
+    if (endIndex !== undefined && text !== undefined) {
+        const range = { startIndex, endIndex };
+        if (tabId)
+            range.tabId = tabId;
+        requests.push({ deleteContentRange: { range } });
+    }
+    // 2. Insert new text
+    if (text !== undefined) {
+        const location = { index: startIndex };
+        if (tabId)
+            location.tabId = tabId;
+        requests.push({ insertText: { location, text } });
+    }
+    // 3. Apply formatting
+    if (style) {
+        const formatStart = startIndex;
+        const formatEnd = text !== undefined
+            ? startIndex + text.length
+            : endIndex !== undefined
+                ? endIndex
+                : startIndex;
+        if (formatEnd > formatStart) {
+            const requestInfo = GDocsHelpers.buildUpdateTextStyleRequest(formatStart, formatEnd, style, tabId);
+            if (requestInfo) {
+                requests.push(requestInfo.request);
+            }
+        }
+    }
+    return requests;
+}
+export function register(server) {
+    server.addTool({
+        name: 'modifyText',
+        description: 'Combines text replacement/insertion and formatting in one atomic operation. ' +
+            'Can insert text at a position, replace a range or found text, apply formatting, ' +
+            "or any combination. Use readGoogleDoc with format='json' to determine indices.",
+        parameters: ModifyTextParameters,
+        execute: async (args, { log }) => {
+            const docs = await getDocsClient();
+            log.info(`modifyText on doc ${args.documentId}: target=${JSON.stringify(args.target)}` +
+                `${args.text !== undefined ? `, text="${args.text.substring(0, 50)}"` : ''}` +
+                `${args.style ? `, style=${JSON.stringify(args.style)}` : ''}` +
+                `${args.tabId ? `, tab=${args.tabId}` : ''}`);
+            try {
+                // Verify tab exists if specified
+                if (args.tabId) {
+                    const docInfo = await docs.documents.get({
+                        documentId: args.documentId,
+                        includeTabsContent: true,
+                        fields: 'tabs(tabProperties,documentTab)',
+                    });
+                    const targetTab = GDocsHelpers.findTabById(docInfo.data, args.tabId);
+                    if (!targetTab) {
+                        throw new UserError(`Tab with ID "${args.tabId}" not found in document.`);
+                    }
+                    if (!targetTab.documentTab) {
+                        throw new UserError(`Tab "${args.tabId}" does not have content (may not be a document tab).`);
+                    }
+                }
+                // Resolve target to numeric indices
+                let startIndex;
+                let endIndex;
+                if ('insertionIndex' in args.target) {
+                    startIndex = args.target.insertionIndex;
+                    endIndex = undefined;
+                }
+                else if ('textToFind' in args.target) {
+                    const range = await GDocsHelpers.findTextRange(docs, args.documentId, args.target.textToFind, args.target.matchInstance, args.tabId);
+                    if (!range) {
+                        throw new UserError(`Could not find instance ${args.target.matchInstance ?? 1} of text "${args.target.textToFind}"${args.tabId ? ` in tab ${args.tabId}` : ''}.`);
+                    }
+                    startIndex = range.startIndex;
+                    endIndex = range.endIndex;
+                    log.info(`Found text "${args.target.textToFind}" at range ${startIndex}-${endIndex}`);
+                }
+                else {
+                    startIndex = args.target.startIndex;
+                    endIndex = args.target.endIndex;
+                }
+                // Clamp to minimum 1 (index 0 is the document section break)
+                if (startIndex < 1)
+                    startIndex = 1;
+                const requests = buildModifyTextRequests({
+                    startIndex,
+                    endIndex,
+                    text: args.text,
+                    style: args.style,
+                    tabId: args.tabId,
+                });
+                if (requests.length === 0) {
+                    return 'No operations to perform.';
+                }
+                await GDocsHelpers.executeBatchUpdate(docs, args.documentId, requests);
+                // Build descriptive result
+                const actions = [];
+                if (endIndex !== undefined && args.text !== undefined)
+                    actions.push('replaced text');
+                else if (args.text !== undefined)
+                    actions.push('inserted text');
+                if (args.style)
+                    actions.push('applied formatting');
+                return `Successfully ${actions.join(' and ')} at range ${startIndex}-${endIndex ?? startIndex + (args.text?.length ?? 0)}${args.tabId ? ` in tab ${args.tabId}` : ''}.`;
+            }
+            catch (error) {
+                log.error(`Error in modifyText for doc ${args.documentId}: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                throw new UserError(`Failed to modify text: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/docs/readGoogleDoc.js

@@ -0,0 +1,165 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDocsClient, getDriveClient } from '../../clients.js';
+import { DocumentIdParameter, NotImplementedError } from '../../types.js';
+import * as GDocsHelpers from '../../googleDocsApiHelpers.js';
+import { docsJsonToMarkdown } from '../../markdown-transformer/index.js';
+export function register(server) {
+    server.addTool({
+        name: 'readDocument',
+        description: "Reads the content of a Google Document. Returns plain text by default. Use format='markdown' to get formatted content suitable for editing and re-uploading with replaceDocumentWithMarkdown, or format='json' for the raw document structure.",
+        parameters: DocumentIdParameter.extend({
+            format: z
+                .enum(['text', 'json', 'markdown'])
+                .optional()
+                .default('text')
+                .describe("Output format: 'text' (plain text), 'json' (raw API structure, complex), 'markdown' (experimental conversion)."),
+            maxLength: z
+                .number()
+                .optional()
+                .describe('Maximum character limit for text output. If not specified, returns full document content. Use this to limit very large documents.'),
+            tabId: z
+                .string()
+                .optional()
+                .describe('The ID of the specific tab to read. If not specified, reads the first tab (or legacy document.body for documents without tabs).'),
+        }),
+        execute: async (args, { log }) => {
+            const docs = await getDocsClient();
+            log.info(`Reading Google Doc: ${args.documentId}, Format: ${args.format}${args.tabId ? `, Tab: ${args.tabId}` : ''}`);
+            try {
+                // Determine if we need tabs content
+                const needsTabsContent = !!args.tabId;
+                const fields = args.format === 'json' || args.format === 'markdown'
+                    ? '*' // Get everything for structure analysis
+                    : 'body(content(paragraph(elements(textRun(content)))))'; // Just text content
+                const res = await docs.documents.get({
+                    documentId: args.documentId,
+                    includeTabsContent: needsTabsContent,
+                    fields: needsTabsContent ? '*' : fields, // Get full document if using tabs
+                });
+                log.info(`Fetched doc: ${args.documentId}${args.tabId ? ` (tab: ${args.tabId})` : ''}`);
+                // If tabId is specified, find the specific tab
+                let contentSource;
+                if (args.tabId) {
+                    const targetTab = GDocsHelpers.findTabById(res.data, args.tabId);
+                    if (!targetTab) {
+                        throw new UserError(`Tab with ID "${args.tabId}" not found in document.`);
+                    }
+                    if (!targetTab.documentTab) {
+                        throw new UserError(`Tab "${args.tabId}" does not have content (may not be a document tab).`);
+                    }
+                    contentSource = { body: targetTab.documentTab.body };
+                    log.info(`Using content from tab: ${targetTab.tabProperties?.title || 'Untitled'}`);
+                }
+                else {
+                    // Use the document body (backward compatible)
+                    contentSource = res.data;
+                }
+                if (args.format === 'json') {
+                    const jsonContent = JSON.stringify(contentSource, null, 2);
+                    // Apply length limit to JSON if specified
+                    if (args.maxLength && jsonContent.length > args.maxLength) {
+                        return (jsonContent.substring(0, args.maxLength) +
+                            `\n... [JSON truncated: ${jsonContent.length} total chars]`);
+                    }
+                    return jsonContent;
+                }
+                if (args.format === 'markdown') {
+                    const markdownContent = docsJsonToMarkdown(contentSource);
+                    const totalLength = markdownContent.length;
+                    log.info(`Generated markdown: ${totalLength} characters`);
+                    // Apply length limit to markdown if specified
+                    if (args.maxLength && totalLength > args.maxLength) {
+                        const truncatedContent = markdownContent.substring(0, args.maxLength);
+                        return `${truncatedContent}\n\n... [Markdown truncated to ${args.maxLength} chars of ${totalLength} total. Use maxLength parameter to adjust limit or remove it to get full content.]`;
+                    }
+                    return markdownContent;
+                }
+                // Default: Text format - extract all text content
+                let textContent = '';
+                let elementCount = 0;
+                // Process all content elements from contentSource
+                contentSource.body?.content?.forEach((element) => {
+                    elementCount++;
+                    // Handle paragraphs
+                    if (element.paragraph?.elements) {
+                        element.paragraph.elements.forEach((pe) => {
+                            if (pe.textRun?.content) {
+                                textContent += pe.textRun.content;
+                            }
+                        });
+                    }
+                    // Handle tables
+                    if (element.table?.tableRows) {
+                        element.table.tableRows.forEach((row) => {
+                            row.tableCells?.forEach((cell) => {
+                                cell.content?.forEach((cellElement) => {
+                                    cellElement.paragraph?.elements?.forEach((pe) => {
+                                        if (pe.textRun?.content) {
+                                            textContent += pe.textRun.content;
+                                        }
+                                    });
+                                });
+                            });
+                        });
+                    }
+                });
+                if (!textContent.trim())
+                    return 'Document found, but appears empty.';
+                const totalLength = textContent.length;
+                log.info(`Document contains ${totalLength} characters across ${elementCount} elements`);
+                log.info(`maxLength parameter: ${args.maxLength || 'not specified'}`);
+                // Apply length limit only if specified
+                if (args.maxLength && totalLength > args.maxLength) {
+                    const truncatedContent = textContent.substring(0, args.maxLength);
+                    log.info(`Truncating content from ${totalLength} to ${args.maxLength} characters`);
+                    return `Content (truncated to ${args.maxLength} chars of ${totalLength} total):\n---\n${truncatedContent}\n\n... [Document continues for ${totalLength - args.maxLength} more characters. Use maxLength parameter to adjust limit or remove it to get full content.]`;
+                }
+                // Return full content
+                const fullResponse = `Content (${totalLength} characters):\n---\n${textContent}`;
+                const responseLength = fullResponse.length;
+                log.info(`Returning full content: ${responseLength} characters in response (${totalLength} content + ${responseLength - totalLength} metadata)`);
+                return fullResponse;
+            }
+            catch (error) {
+                log.error(`Error reading doc ${args.documentId}: ${error.message || error}`);
+                log.error(`Error details: ${JSON.stringify(error.response?.data || error)}`);
+                // Handle errors thrown by helpers or API directly
+                if (error instanceof UserError)
+                    throw error;
+                if (error instanceof NotImplementedError)
+                    throw error;
+                // Generic fallback for API errors not caught by helpers
+                if (error.code === 404)
+                    throw new UserError(`Doc not found (ID: ${args.documentId}).`);
+                if (error.code === 403) {
+                    // The Docs API may be blocked by Workspace admin policy even when the Drive API is
+                    // accessible. Fall back to drive.files.export() for plain-text format, which uses
+                    // the Drive API and respects supportsAllDrives for Shared Drive documents.
+                    if (!args.format || args.format === 'text') {
+                        try {
+                            log.info(`Docs API returned 403, falling back to Drive export for ${args.documentId}`);
+                            const drive = await getDriveClient();
+                            const exportRes = await drive.files.export({ fileId: args.documentId, mimeType: 'text/plain' }, { responseType: 'text' });
+                            const textContent = exportRes.data;
+                            if (!textContent?.trim())
+                                return 'Document found, but appears empty.';
+                            if (args.maxLength && textContent.length > args.maxLength) {
+                                return `Content (truncated to ${args.maxLength} chars of ${textContent.length} total):\n---\n${textContent.substring(0, args.maxLength)}\n\n... [Document continues. Use maxLength parameter to adjust limit or remove it to get full content.]`;
+                            }
+                            return `Content (${textContent.length} characters):\n---\n${textContent}`;
+                        }
+                        catch (exportError) {
+                            log.error(`Drive export fallback also failed: ${exportError.message}`);
+                        }
+                    }
+                    throw new UserError(`Permission denied for doc (ID: ${args.documentId}). The Google Docs API may be restricted by your Workspace admin.`);
+                }
+                // Extract detailed error information from Google API response
+                const errorDetails = error.response?.data?.error?.message || error.message || 'Unknown error';
+                const errorCode = error.response?.data?.error?.code || error.code;
+                throw new UserError(`Failed to read doc: ${errorDetails}${errorCode ? ` (Code: ${errorCode})` : ''}`);
+            }
+        },
+    });
+}

package/dist/tools/docs/renameTab.js

@@ -0,0 +1,61 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDocsClient } from '../../clients.js';
+import { DocumentIdParameter } from '../../types.js';
+import * as GDocsHelpers from '../../googleDocsApiHelpers.js';
+export function register(server) {
+    server.addTool({
+        name: 'renameTab',
+        description: 'Renames a tab in a Google Docs document. Use listDocumentTabs to get tab IDs first.',
+        parameters: DocumentIdParameter.extend({
+            tabId: z
+                .string()
+                .describe('The ID of the tab to rename. Use listDocumentTabs to get tab IDs.'),
+            newTitle: z.string().min(1).describe('The new title for the tab.'),
+        }),
+        execute: async (args, { log }) => {
+            const docs = await getDocsClient();
+            log.info(`Renaming tab ${args.tabId} to "${args.newTitle}" in doc ${args.documentId}`);
+            try {
+                // Verify the tab exists
+                const docInfo = await docs.documents.get({
+                    documentId: args.documentId,
+                    includeTabsContent: true,
+                    fields: 'tabs(tabProperties,documentTab)',
+                });
+                const targetTab = GDocsHelpers.findTabById(docInfo.data, args.tabId);
+                if (!targetTab) {
+                    throw new UserError(`Tab with ID "${args.tabId}" not found in document.`);
+                }
+                const oldTitle = targetTab.tabProperties?.title || '(untitled)';
+                await docs.documents.batchUpdate({
+                    documentId: args.documentId,
+                    requestBody: {
+                        requests: [
+                            {
+                                updateDocumentTabProperties: {
+                                    tabProperties: {
+                                        tabId: args.tabId,
+                                        title: args.newTitle,
+                                    },
+                                    fields: 'title',
+                                },
+                            },
+                        ],
+                    },
+                });
+                return `Successfully renamed tab from "${oldTitle}" to "${args.newTitle}".`;
+            }
+            catch (error) {
+                log.error(`Error renaming tab ${args.tabId} in doc ${args.documentId}: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                if (error.code === 404)
+                    throw new UserError(`Document not found (ID: ${args.documentId}).`);
+                if (error.code === 403)
+                    throw new UserError(`Permission denied for document (ID: ${args.documentId}).`);
+                throw new UserError(`Failed to rename tab: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/drive/copyFile.js

@@ -0,0 +1,63 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDriveClient } from '../../clients.js';
+export function register(server) {
+    server.addTool({
+        name: 'copyFile',
+        description: "Creates a copy of a file or document in Google Drive. Returns the new copy's ID and URL.",
+        parameters: z.object({
+            fileId: z
+                .string()
+                .describe('The file or folder ID from a Google Drive URL or a previous tool result.'),
+            newName: z
+                .string()
+                .optional()
+                .describe('Name for the copied file. If not provided, will use "Copy of [original name]".'),
+            parentFolderId: z
+                .string()
+                .optional()
+                .describe('ID of folder where copy should be placed. If not provided, places in same location as original.'),
+        }),
+        execute: async (args, { log }) => {
+            const drive = await getDriveClient();
+            log.info(`Copying file ${args.fileId} ${args.newName ? `as "${args.newName}"` : ''}`);
+            try {
+                // Get original file info
+                const originalFile = await drive.files.get({
+                    fileId: args.fileId,
+                    fields: 'name,parents',
+                    supportsAllDrives: true,
+                });
+                const copyMetadata = {
+                    name: args.newName || `Copy of ${originalFile.data.name}`,
+                };
+                if (args.parentFolderId) {
+                    copyMetadata.parents = [args.parentFolderId];
+                }
+                else if (originalFile.data.parents) {
+                    copyMetadata.parents = originalFile.data.parents;
+                }
+                const response = await drive.files.copy({
+                    fileId: args.fileId,
+                    requestBody: copyMetadata,
+                    fields: 'id,name,webViewLink',
+                    supportsAllDrives: true,
+                });
+                const copiedFile = response.data;
+                return JSON.stringify({
+                    id: copiedFile.id,
+                    name: copiedFile.name,
+                    url: copiedFile.webViewLink,
+                }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error copying file: ${error.message || error}`);
+                if (error.code === 404)
+                    throw new UserError('Original file or destination folder not found. Check the IDs.');
+                if (error.code === 403)
+                    throw new UserError('Permission denied. Make sure you have read access to the original file and write access to the destination.');
+                throw new UserError(`Failed to copy file: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/drive/createDocument.js

@@ -0,0 +1,89 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDriveClient, getDocsClient } from '../../clients.js';
+import { insertMarkdown, formatInsertResult } from '../../markdown-transformer/index.js';
+export function register(server) {
+    server.addTool({
+        name: 'createDocument',
+        description: 'Creates a new empty Google Document. Optionally places it in a specific folder and adds initial text content.',
+        parameters: z.object({
+            title: z.string().min(1).describe('Title for the new document.'),
+            parentFolderId: z
+                .string()
+                .optional()
+                .describe('ID of folder where document should be created. If not provided, creates in Drive root.'),
+            initialContent: z
+                .string()
+                .optional()
+                .describe('Initial content to add to the document. By default, markdown syntax is converted to formatted Google Docs content (headings, bold, italic, links, lists, etc.).'),
+            contentFormat: z
+                .enum(['markdown', 'raw'])
+                .optional()
+                .default('markdown')
+                .describe("How to interpret initialContent. 'markdown' (default) converts markdown to formatted Google Docs content. 'raw' inserts the text as-is without any conversion."),
+        }),
+        execute: async (args, { log }) => {
+            const drive = await getDriveClient();
+            log.info(`Creating new document "${args.title}"`);
+            try {
+                const documentMetadata = {
+                    name: args.title,
+                    mimeType: 'application/vnd.google-apps.document',
+                };
+                if (args.parentFolderId) {
+                    documentMetadata.parents = [args.parentFolderId];
+                }
+                const response = await drive.files.create({
+                    requestBody: documentMetadata,
+                    fields: 'id,name,webViewLink',
+                    supportsAllDrives: true,
+                });
+                const document = response.data;
+                // Add initial content if provided
+                if (args.initialContent) {
+                    try {
+                        const docs = await getDocsClient();
+                        if (args.contentFormat === 'raw') {
+                            await docs.documents.batchUpdate({
+                                documentId: document.id,
+                                requestBody: {
+                                    requests: [
+                                        {
+                                            insertText: {
+                                                location: { index: 1 },
+                                                text: args.initialContent,
+                                            },
+                                        },
+                                    ],
+                                },
+                            });
+                        }
+                        else {
+                            const result = await insertMarkdown(docs, document.id, args.initialContent, {
+                                startIndex: 1,
+                                firstHeadingAsTitle: true,
+                            });
+                            log.info(formatInsertResult(result));
+                        }
+                    }
+                    catch (contentError) {
+                        log.warn(`Document created but failed to add initial content: ${contentError.message}`);
+                    }
+                }
+                return JSON.stringify({
+                    id: document.id,
+                    name: document.name,
+                    url: document.webViewLink,
+                }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error creating document: ${error.message || error}`);
+                if (error.code === 404)
+                    throw new UserError('Parent folder not found. Check the folder ID.');
+                if (error.code === 403)
+                    throw new UserError('Permission denied. Make sure you have write access to the destination folder.');
+                throw new UserError(`Failed to create document: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/drive/createFolder.js

@@ -0,0 +1,48 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDriveClient } from '../../clients.js';
+export function register(server) {
+    server.addTool({
+        name: 'createFolder',
+        description: 'Creates a new folder in Google Drive. Optionally places it inside an existing parent folder.',
+        parameters: z.object({
+            name: z.string().min(1).describe('Name for the new folder.'),
+            parentFolderId: z
+                .string()
+                .optional()
+                .describe('Parent folder ID. If not provided, creates folder in Drive root.'),
+        }),
+        execute: async (args, { log }) => {
+            const drive = await getDriveClient();
+            log.info(`Creating folder "${args.name}" ${args.parentFolderId ? `in parent ${args.parentFolderId}` : 'in root'}`);
+            try {
+                const folderMetadata = {
+                    name: args.name,
+                    mimeType: 'application/vnd.google-apps.folder',
+                };
+                if (args.parentFolderId) {
+                    folderMetadata.parents = [args.parentFolderId];
+                }
+                const response = await drive.files.create({
+                    requestBody: folderMetadata,
+                    fields: 'id,name,parents,webViewLink',
+                    supportsAllDrives: true,
+                });
+                const folder = response.data;
+                return JSON.stringify({
+                    id: folder.id,
+                    name: folder.name,
+                    url: folder.webViewLink,
+                }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error creating folder: ${error.message || error}`);
+                if (error.code === 404)
+                    throw new UserError('Parent folder not found. Check the parent folder ID.');
+                if (error.code === 403)
+                    throw new UserError('Permission denied. Make sure you have write access to the parent folder.');
+                throw new UserError(`Failed to create folder: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}