google-tools-mcp 1.0.17 → 1.1.2

package/dist/tools/docs/modifyText.js

@@ -3,6 +3,7 @@ import { z } from 'zod';
 import { getDocsClient } from '../../clients.js';
 import { DocumentIdParameter, TextFindParameter, TextStyleParameters, ParagraphStyleParameters } from '../../types.js';
 import * as GDocsHelpers from '../../googleDocsApiHelpers.js';
+import { guardMutation, trackMutation } from '../../readTracker.js';
 const RangeTarget = z
     .object({
     startIndex: z.number().int().min(1).describe('Start of range (inclusive, 1-based).'),
@@ -42,17 +43,17 @@ const ModifyTextParameters = DocumentIdParameter.extend({
 export function buildModifyTextRequests(opts) {
     const { startIndex, endIndex, text, style, paragraphStyle, tabId } = opts;
     const requests = [];
-    if (!text && !style && !paragraphStyle)
+    if (text === undefined && !style && !paragraphStyle)
         return requests;
-    // 1. Delete existing content (only when replacing, not insert-only)
+    // 1. Delete existing content (when replacing or deleting)
     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) {
+    // 2. Insert new text (skip if empty string — that means "delete only")
+    if (text !== undefined && text !== '') {
         const location = { index: startIndex };
         if (tabId)
             location.tabId = tabId;
@@ -93,11 +94,17 @@ export function buildModifyTextRequests(opts) {
 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 text styling (bold, italic, etc.), ' +
-            "apply paragraph styling (alignment, headings, spacing, etc.), or any combination. Use readGoogleDoc with format='json' to determine indices.",
+        description: 'Best for small, targeted, single-location changes within a line or paragraph. ' +
+            'Can insert text at a position, replace a range or found text, delete text (replace with empty string ""), ' +
+            'apply text styling (bold, italic, etc.), apply paragraph styling (alignment, headings, spacing, etc.), or any combination. ' +
+            "Use readDocument with format='json' to determine indices. " +
+            'Supports \\n for line breaks and \\t for tabs in replacement text. ' +
+            'When using textToFind, if multiple matches exist the tool returns all instances with context so you can specify matchInstance. ' +
+            'For multi-line or section-level rewrites, use replaceDocumentWithMarkdown instead. ' +
+            'To add content to the end of a doc, use appendMarkdown or appendText.',
         parameters: ModifyTextParameters,
         execute: async (args, { log }) => {
+            await guardMutation(args.documentId);
             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)}"` : ''}` +
@@ -130,7 +137,7 @@ export function register(server) {
                 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}` : ''}.`);
+                        throw new UserError(`Could not find text "${args.target.textToFind}"${args.target.matchInstance ? ` (instance ${args.target.matchInstance})` : ''}${args.tabId ? ` in tab ${args.tabId}` : ''}.`);
                     }
                     startIndex = range.startIndex;
                     endIndex = range.endIndex;
@@ -143,10 +150,15 @@ export function register(server) {
                 // Clamp to minimum 1 (index 0 is the document section break)
                 if (startIndex < 1)
                     startIndex = 1;
+                // Normalize escape sequences so literal \n / \t in the input
+                // are converted to real newline / tab characters (issue #9).
+                const normalizedText = args.text
+                    ?.replace(/\\n/g, '\n')
+                    .replace(/\\t/g, '\t');
                 const requests = buildModifyTextRequests({
                     startIndex,
                     endIndex,
-                    text: args.text,
+                    text: normalizedText,
                     style: args.style,
                     paragraphStyle: args.paragraphStyle,
                     tabId: args.tabId,
@@ -155,9 +167,12 @@ export function register(server) {
                     return 'No operations to perform.';
                 }
                 await GDocsHelpers.executeBatchUpdate(docs, args.documentId, requests);
+                trackMutation(args.documentId);
                 // Build descriptive result
                 const actions = [];
-                if (endIndex !== undefined && args.text !== undefined)
+                if (endIndex !== undefined && normalizedText === '')
+                    actions.push('deleted text');
+                else if (endIndex !== undefined && args.text !== undefined)
                     actions.push('replaced text');
                 else if (args.text !== undefined)
                     actions.push('inserted text');

package/dist/tools/docs/modifyText.test.js

@@ -0,0 +1,90 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { buildModifyTextRequests } from './modifyText.js';
+
+describe('buildModifyTextRequests', () => {
+  it('generates deleteContentRange + insertText for a replacement', () => {
+    const reqs = buildModifyTextRequests({
+      startIndex: 5,
+      endIndex: 10,
+      text: 'hello',
+    });
+    assert.equal(reqs.length, 2);
+    assert.deepEqual(reqs[0], {
+      deleteContentRange: { range: { startIndex: 5, endIndex: 10 } },
+    });
+    assert.deepEqual(reqs[1], {
+      insertText: { location: { index: 5 }, text: 'hello' },
+    });
+  });
+
+  it('generates only insertText for an insertion (no endIndex)', () => {
+    const reqs = buildModifyTextRequests({
+      startIndex: 3,
+      endIndex: undefined,
+      text: 'hi',
+    });
+    assert.equal(reqs.length, 1);
+    assert.deepEqual(reqs[0], {
+      insertText: { location: { index: 3 }, text: 'hi' },
+    });
+  });
+
+  it('returns empty array when no text/style/paragraphStyle given', () => {
+    const reqs = buildModifyTextRequests({
+      startIndex: 1,
+      endIndex: 5,
+    });
+    assert.equal(reqs.length, 0);
+  });
+
+  it('includes tabId in range and location when provided', () => {
+    const reqs = buildModifyTextRequests({
+      startIndex: 1,
+      endIndex: 4,
+      text: 'x',
+      tabId: 'tab1',
+    });
+    assert.deepEqual(reqs[0].deleteContentRange.range.tabId, 'tab1');
+    assert.deepEqual(reqs[1].insertText.location.tabId, 'tab1');
+  });
+});
+
+describe('escape sequence normalization (issue #9)', () => {
+  // Simulate the normalization that happens in the execute handler
+  function normalize(text) {
+    return text?.replace(/\\n/g, '\n').replace(/\\t/g, '\t');
+  }
+
+  it('converts literal \\n to real newline', () => {
+    const input = 'line one\\nline two\\nline three';
+    const result = normalize(input);
+    assert.equal(result, 'line one\nline two\nline three');
+  });
+
+  it('converts literal \\t to real tab', () => {
+    const input = 'col1\\tcol2\\tcol3';
+    const result = normalize(input);
+    assert.equal(result, 'col1\tcol2\tcol3');
+  });
+
+  it('handles mixed \\n and \\t', () => {
+    const input = 'row1\\tcol2\\nrow2\\tcol2';
+    const result = normalize(input);
+    assert.equal(result, 'row1\tcol2\nrow2\tcol2');
+  });
+
+  it('leaves text without escape sequences unchanged', () => {
+    const input = 'no escapes here';
+    assert.equal(normalize(input), 'no escapes here');
+  });
+
+  it('preserves real newlines that are already in the string', () => {
+    const input = 'already\nreal';
+    assert.equal(normalize(input), 'already\nreal');
+  });
+
+  it('returns undefined for undefined input', () => {
+    assert.equal(normalize(undefined), undefined);
+  });
+});

package/dist/tools/docs/readGoogleDoc.js

@@ -4,6 +4,7 @@ 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';
+import { trackRead } from '../../readTracker.js';
 export function register(server) {
     server.addTool({
         name: 'readDocument',
@@ -38,6 +39,7 @@ export function register(server) {
                     fields: needsTabsContent ? '*' : fields, // Get full document if using tabs
                 });
                 log.info(`Fetched doc: ${args.documentId}${args.tabId ? ` (tab: ${args.tabId})` : ''}`);
+                trackRead(args.documentId);
                 // If tabId is specified, find the specific tab
                 let contentSource;
                 if (args.tabId) {

package/dist/tools/drive/deleteFile.js

@@ -1,6 +1,7 @@
 import { UserError } from 'fastmcp';
 import { z } from 'zod';
 import { getDriveClient } from '../../clients.js';
+import { guardMutation } from '../../readTracker.js';
 export function register(server) {
     server.addTool({
         name: 'deleteFile',
@@ -16,6 +17,7 @@ export function register(server) {
                 .describe('If true, permanently deletes the file instead of moving it to trash.'),
         }),
         execute: async (args, { log }) => {
+            await guardMutation(args.fileId, { skipExternalCheck: true });
             const drive = await getDriveClient();
             log.info(`Deleting file ${args.fileId} ${args.permanent ? '(permanent)' : '(to trash)'}`);
             try {

package/dist/tools/drive/index.js

@@ -14,6 +14,7 @@ import { register as listSharedDrives } from './listSharedDrives.js';
 import { register as listSharedWithMe } from './listSharedWithMe.js';
 import { register as downloadFile } from './downloadFile.js';
 import { register as getFilePath } from './getFilePath.js';
+import { register as uploadFile } from './uploadFile.js';
 export function registerDriveTools(server) {
     listDriveFiles(server);
     searchGoogleDocs(server);
@@ -31,4 +32,5 @@ export function registerDriveTools(server) {
     listSharedWithMe(server);
     downloadFile(server);
     getFilePath(server);
+    uploadFile(server);
 }

package/dist/tools/drive/uploadFile.js

@@ -0,0 +1,111 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDriveClient } from '../../clients.js';
+
+// Common MIME type mappings for file extensions
+const MIME_TYPES = {
+    '.pdf': 'application/pdf',
+    '.doc': 'application/msword',
+    '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    '.xls': 'application/vnd.ms-excel',
+    '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    '.ppt': 'application/vnd.ms-powerpoint',
+    '.pptx': 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+    '.txt': 'text/plain',
+    '.csv': 'text/csv',
+    '.json': 'application/json',
+    '.xml': 'application/xml',
+    '.html': 'text/html',
+    '.htm': 'text/html',
+    '.md': 'text/markdown',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.svg': 'image/svg+xml',
+    '.webp': 'image/webp',
+    '.mp3': 'audio/mpeg',
+    '.mp4': 'video/mp4',
+    '.zip': 'application/zip',
+    '.gz': 'application/gzip',
+    '.tar': 'application/x-tar',
+};
+
+export function register(server) {
+    server.addTool({
+        name: 'uploadFile',
+        description:
+            'Uploads a local file from the filesystem to Google Drive. ' +
+            'Auto-detects MIME type from file extension. ' +
+            'Returns the uploaded file\'s Drive ID and URL.',
+        parameters: z.object({
+            localPath: z.string().describe('Absolute path to the local file to upload.'),
+            name: z
+                .string()
+                .optional()
+                .describe('Custom name for the file in Drive. If not provided, uses the local filename.'),
+            parentFolderId: z
+                .string()
+                .optional()
+                .describe('ID of the Drive folder to upload into. If not provided, uploads to the root of My Drive.'),
+            mimeType: z
+                .string()
+                .optional()
+                .describe('MIME type override. If not provided, auto-detected from file extension.'),
+        }),
+        execute: async (args, { log }) => {
+            const drive = await getDriveClient();
+
+            // Validate file exists
+            if (!fs.existsSync(args.localPath)) {
+                throw new UserError(`File not found: ${args.localPath}`);
+            }
+
+            const stats = fs.statSync(args.localPath);
+            if (!stats.isFile()) {
+                throw new UserError(`Path is not a file: ${args.localPath}`);
+            }
+
+            const fileName = args.name || path.basename(args.localPath);
+            const ext = path.extname(args.localPath).toLowerCase();
+            const mimeType = args.mimeType || MIME_TYPES[ext] || 'application/octet-stream';
+
+            log.info(`Uploading "${args.localPath}" as "${fileName}" (${mimeType}, ${stats.size} bytes)`);
+
+            try {
+                const fileMetadata = { name: fileName };
+                if (args.parentFolderId) {
+                    fileMetadata.parents = [args.parentFolderId];
+                }
+
+                const response = await drive.files.create({
+                    requestBody: fileMetadata,
+                    media: {
+                        mimeType,
+                        body: fs.createReadStream(args.localPath),
+                    },
+                    fields: 'id,name,webViewLink,mimeType,size',
+                    supportsAllDrives: true,
+                });
+
+                const file = response.data;
+                return JSON.stringify({
+                    id: file.id,
+                    name: file.name,
+                    url: file.webViewLink,
+                    mimeType: file.mimeType,
+                    size: file.size,
+                }, null, 2);
+            } catch (error) {
+                log.error(`Error uploading file: ${error.message || error}`);
+                if (error.code === 404)
+                    throw new UserError('Destination folder not found. Check the parentFolderId.');
+                if (error.code === 403)
+                    throw new UserError('Permission denied. Make sure you have write access to the destination folder.');
+                throw new UserError(`Failed to upload file: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/extras/index.js

@@ -1,7 +1,9 @@
 import { register as readFile } from './readFile.js';
 import { register as searchFileContents } from './searchFileContents.js';
+import { register as readDriveFile } from './readDriveFile.js';
 
 export function registerExtrasTools(server) {
     readFile(server);
     searchFileContents(server);
+    readDriveFile(server);
 }

package/dist/tools/extras/readDriveFile.js

@@ -0,0 +1,206 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDriveClient, getDocsClient, getSheetsClient } from '../../clients.js';
+import { docsJsonToMarkdown } from '../../markdown-transformer/index.js';
+import * as GDocsHelpers from '../../googleDocsApiHelpers.js';
+import { extractText, downloadBuffer } from './readFile.js';
+import { trackRead } from '../../readTracker.js';
+
+// Google-native MIME types
+const GOOGLE_DOC = 'application/vnd.google-apps.document';
+const GOOGLE_SHEET = 'application/vnd.google-apps.spreadsheet';
+const GOOGLE_SLIDES = 'application/vnd.google-apps.presentation';
+
+// Capabilities by file type category
+const CAPABILITIES = {
+    googleDoc: {
+        fileType: 'Google Doc',
+        capabilities: ['read', 'readDocument', 'modifyText', 'replaceDocumentWithMarkdown', 'appendMarkdown', 'appendText', 'findAndReplace', 'deleteRange'],
+    },
+    googleSheet: {
+        fileType: 'Google Sheet',
+        capabilities: ['read', 'readSpreadsheet', 'writeSpreadsheet', 'appendRows', 'formatCells'],
+    },
+    docx: {
+        fileType: 'Word Document (.docx)',
+        capabilities: ['read'],
+        note: 'This is a Word document. Editing tools (modifyText, appendMarkdown, etc.) are not available unless converted to a Google Doc via copyFile or Drive UI.',
+    },
+    pdf: {
+        fileType: 'PDF',
+        capabilities: ['read'],
+        note: 'This is a PDF file. Editing tools are not available. Convert to a Google Doc first if editing is needed.',
+    },
+    other: {
+        fileType: 'Unknown',
+        capabilities: ['download'],
+        note: 'This file type cannot be read as text. Use downloadFile to download it.',
+    },
+};
+
+export function register(server) {
+    server.addTool({
+        name: 'readDriveFile',
+        description:
+            'Unified read tool: accepts any Google Drive file ID, auto-detects the file type (Google Doc, Sheet, Word .docx, PDF), ' +
+            'and routes to the appropriate reader. Returns content along with metadata about available capabilities. ' +
+            'Use this when you have a file ID but don\'t know the file type, or when readDocument fails with a 400 error.',
+        parameters: z.object({
+            fileId: z
+                .string()
+                .describe('The Google Drive file ID (the long string between /d/ and /edit in a Drive URL).'),
+            format: z
+                .enum(['text', 'json', 'markdown'])
+                .optional()
+                .default('markdown')
+                .describe("Output format for Google Docs: 'markdown' (default), 'text' (plain text), 'json' (raw structure). Ignored for non-Doc files."),
+            range: z
+                .string()
+                .optional()
+                .describe("A1 notation range for Google Sheets (e.g., 'Sheet1!A1:C10'). Required for spreadsheets."),
+        }),
+        execute: async (args, { log }) => {
+            const drive = await getDriveClient();
+
+            // 1. Get file metadata to determine type
+            let fileMeta;
+            try {
+                const res = await drive.files.get({
+                    fileId: args.fileId,
+                    fields: 'id,name,mimeType,modifiedTime,size',
+                    supportsAllDrives: true,
+                });
+                fileMeta = res.data;
+            } catch (error) {
+                if (error.code === 404) throw new UserError(`File not found: ${args.fileId}`);
+                if (error.code === 403) throw new UserError('Permission denied. Check that the file is shared with this account.');
+                throw new UserError(`Failed to get file info: ${error.message}`);
+            }
+
+            log.info(`File "${fileMeta.name}" is ${fileMeta.mimeType}`);
+            trackRead(args.fileId, fileMeta.modifiedTime);
+
+            // 2. Route based on MIME type
+            if (fileMeta.mimeType === GOOGLE_DOC) {
+                return await readGoogleDoc(args, fileMeta, log);
+            }
+
+            if (fileMeta.mimeType === GOOGLE_SHEET) {
+                return await readGoogleSheet(args, fileMeta, log);
+            }
+
+            // Try reading as docx/pdf
+            const text = await tryReadBinaryFile(drive, args.fileId, fileMeta, log);
+            if (text !== null) {
+                return text;
+            }
+
+            // Unsupported type
+            const capInfo = CAPABILITIES.other;
+            capInfo.fileType = fileMeta.mimeType;
+            return JSON.stringify({
+                file: { id: fileMeta.id, name: fileMeta.name, mimeType: fileMeta.mimeType },
+                ...capInfo,
+                content: null,
+            }, null, 2);
+        },
+    });
+}
+
+async function readGoogleDoc(args, fileMeta, log) {
+    const docs = await getDocsClient();
+    const res = await docs.documents.get({
+        documentId: args.fileId,
+        fields: args.format === 'text' ? 'body(content(paragraph(elements(textRun(content)))))' : '*',
+    });
+
+    let content;
+    if (args.format === 'json') {
+        content = JSON.stringify(res.data, null, 2);
+    } else if (args.format === 'markdown') {
+        content = docsJsonToMarkdown(res.data);
+    } else {
+        // text
+        let textContent = '';
+        res.data.body?.content?.forEach((element) => {
+            if (element.paragraph?.elements) {
+                element.paragraph.elements.forEach((pe) => {
+                    if (pe.textRun?.content) textContent += pe.textRun.content;
+                });
+            }
+            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;
+                            });
+                        });
+                    });
+                });
+            }
+        });
+        content = textContent || '(empty document)';
+    }
+
+    return JSON.stringify({
+        file: { id: fileMeta.id, name: fileMeta.name, mimeType: fileMeta.mimeType },
+        ...CAPABILITIES.googleDoc,
+        content,
+    }, null, 2);
+}
+
+async function readGoogleSheet(args, fileMeta, log) {
+    if (!args.range) {
+        // Return sheet info without data
+        const sheets = await getSheetsClient();
+        const info = await sheets.spreadsheets.get({
+            spreadsheetId: args.fileId,
+            fields: 'sheets(properties(sheetId,title,gridProperties))',
+        });
+        const sheetList = info.data.sheets?.map(s => ({
+            title: s.properties.title,
+            sheetId: s.properties.sheetId,
+            rows: s.properties.gridProperties?.rowCount,
+            cols: s.properties.gridProperties?.columnCount,
+        }));
+        return JSON.stringify({
+            file: { id: fileMeta.id, name: fileMeta.name, mimeType: fileMeta.mimeType },
+            ...CAPABILITIES.googleSheet,
+            note: 'Provide a range parameter (e.g., "Sheet1!A1:C10") to read data. Available sheets listed below.',
+            sheets: sheetList,
+        }, null, 2);
+    }
+
+    const sheets = await getSheetsClient();
+    const response = await sheets.spreadsheets.values.get({
+        spreadsheetId: args.fileId,
+        range: args.range,
+    });
+    return JSON.stringify({
+        file: { id: fileMeta.id, name: fileMeta.name, mimeType: fileMeta.mimeType },
+        ...CAPABILITIES.googleSheet,
+        range: args.range,
+        values: response.data.values || [],
+    }, null, 2);
+}
+
+async function tryReadBinaryFile(drive, fileId, fileMeta, log) {
+    const { mimeType, name } = fileMeta;
+    const isDocxFile = mimeType === 'application/vnd.openxmlformats-officedocument.wordprocessingml.document' || name?.endsWith('.docx');
+    const isPdfFile = mimeType === 'application/pdf' || name?.endsWith('.pdf');
+
+    if (!isDocxFile && !isPdfFile) return null;
+
+    const buffer = await downloadBuffer(drive, fileId);
+    const text = await extractText(buffer, mimeType, name);
+
+    if (text === null) return null;
+
+    const capInfo = isDocxFile ? CAPABILITIES.docx : CAPABILITIES.pdf;
+    return JSON.stringify({
+        file: { id: fileMeta.id, name: fileMeta.name, mimeType: fileMeta.mimeType },
+        ...capInfo,
+        content: text,
+    }, null, 2);
+}

package/dist/tools/extras/readFile.js

@@ -1,6 +1,7 @@
 import { UserError } from 'fastmcp';
 import { z } from 'zod';
 import { getDriveClient } from '../../clients.js';
+import { trackRead } from '../../readTracker.js';
 import mammoth from 'mammoth';
 
 function isDocx(mimeType, name) {
@@ -58,6 +59,7 @@ export function register(server) {
                 });
 
                 const { name, mimeType } = meta.data;
+                trackRead(fileId);
                 const buffer = await downloadBuffer(drive, fileId);
                 const text = await extractText(buffer, mimeType, name);