google-tools-mcp 1.0.16 → 1.1.1

package/dist/tools/sheets/insertChart.js

@@ -212,7 +212,8 @@ export function register(server) {
                     },
                 });
                 const chartId = response.data.replies?.[0]?.addChart?.chart?.chartId;
-                return `Chart created successfully${chartId ? ` (Chart ID: ${chartId})` : ''}.`;
+                const sheetUrl = `https://docs.google.com/spreadsheets/d/${args.spreadsheetId}/edit`;
+                return `${sheetUrl}\nChart created successfully${chartId ? ` (Chart ID: ${chartId})` : ''}.`;
             }
             catch (error) {
                 log.error(`Error inserting chart: ${error.message || error}`);

package/dist/tools/sheets/readSpreadsheet.js

@@ -2,6 +2,7 @@ import { UserError } from 'fastmcp';
 import { z } from 'zod';
 import { getSheetsClient } from '../../clients.js';
 import * as SheetsHelpers from '../../googleSheetsApiHelpers.js';
+import { trackRead } from '../../readTracker.js';
 export function register(server) {
     server.addTool({
         name: 'readSpreadsheet',
@@ -22,6 +23,7 @@ export function register(server) {
             log.info(`Reading spreadsheet ${args.spreadsheetId}, range: ${args.range}`);
             try {
                 const response = await SheetsHelpers.readRange(sheets, args.spreadsheetId, args.range, args.valueRenderOption);
+                trackRead(args.spreadsheetId);
                 const values = response.values || [];
                 return JSON.stringify({ range: args.range, values }, null, 2);
             }

package/dist/tools/sheets/renameSheet.js

@@ -35,7 +35,8 @@ export function register(server) {
                         ],
                     },
                 });
-                return `Successfully renamed sheet (ID: ${args.sheetId}) to "${args.newName}".`;
+                const sheetUrl = `https://docs.google.com/spreadsheets/d/${args.spreadsheetId}/edit`;
+                return `${sheetUrl}\nSuccessfully renamed sheet (ID: ${args.sheetId}) to "${args.newName}".`;
             }
             catch (error) {
                 log.error(`Error renaming sheet in spreadsheet ${args.spreadsheetId}: ${error.message || error}`);

package/dist/tools/sheets/setColumnWidths.js

@@ -30,7 +30,8 @@ export function register(server) {
             try {
                 await SheetsHelpers.setColumnWidths(sheets, args.spreadsheetId, args.sheetName, args.columnWidths);
                 const summary = args.columnWidths.map((cw) => `${cw.column}=${cw.width}px`).join(', ');
-                return `Successfully set column widths: ${summary}.`;
+                const sheetUrl = `https://docs.google.com/spreadsheets/d/${args.spreadsheetId}/edit`;
+                return `${sheetUrl}\nSuccessfully set column widths: ${summary}.`;
             }
             catch (error) {
                 log.error(`Error setting column widths: ${error.message || error}`);

package/dist/tools/sheets/setDropdownValidation.js

@@ -35,10 +35,11 @@ export function register(server) {
                 : `Setting dropdown validation on "${args.range}" with ${args.values.length} options in spreadsheet ${args.spreadsheetId}`);
             try {
                 await SheetsHelpers.setDropdownValidation(sheets, args.spreadsheetId, args.range, args.values, args.strict, args.inputMessage);
+                const sheetUrl = `https://docs.google.com/spreadsheets/d/${args.spreadsheetId}/edit`;
                 if (isClearing) {
-                    return `Successfully removed dropdown validation from range "${args.range}".`;
+                    return `${sheetUrl}\nSuccessfully removed dropdown validation from range "${args.range}".`;
                 }
-                return `Successfully added dropdown validation to range "${args.range}" with ${args.values.length} options: ${args.values.join(', ')}.`;
+                return `${sheetUrl}\nSuccessfully added dropdown validation to range "${args.range}" with ${args.values.length} options: ${args.values.join(', ')}.`;
             }
             catch (error) {
                 log.error(`Error setting dropdown validation: ${error.message || error}`);

package/dist/tools/sheets/ungroupAllRows.js

@@ -53,7 +53,8 @@ export function register(server) {
                         break;
                     }
                 }
-                return `Successfully removed all row groups (${removed} level(s) cleared).`;
+                const sheetUrl = `https://docs.google.com/spreadsheets/d/${args.spreadsheetId}/edit`;
+                return `${sheetUrl}\nSuccessfully removed all row groups (${removed} level(s) cleared).`;
             }
             catch (error) {
                 log.error(`Error removing row groups: ${error.message || error}`);

package/dist/tools/sheets/updateTableRange.js

@@ -30,6 +30,7 @@ export function register(server) {
                 // Update the table range
                 const updatedTable = await SheetsHelpers.updateTableRangeHelper(sheets, args.spreadsheetId, table.tableId || '', newRange);
                 return JSON.stringify({
+                    url: `https://docs.google.com/spreadsheets/d/${args.spreadsheetId}/edit`,
                     tableId: updatedTable.tableId,
                     name: updatedTable.name,
                     oldRange: table.range

package/dist/tools/sheets/writeSpreadsheet.js

@@ -2,6 +2,7 @@ import { UserError } from 'fastmcp';
 import { z } from 'zod';
 import { getSheetsClient } from '../../clients.js';
 import * as SheetsHelpers from '../../googleSheetsApiHelpers.js';
+import { guardMutation, trackMutation } from '../../readTracker.js';
 export function register(server) {
     server.addTool({
         name: 'writeSpreadsheet',
@@ -23,6 +24,7 @@ export function register(server) {
                 .describe('How input data should be interpreted. RAW: values are stored as-is. USER_ENTERED: values are parsed as if typed by a user.'),
         }),
         execute: async (args, { log }) => {
+            await guardMutation(args.spreadsheetId);
             const sheets = await getSheetsClient();
             log.info(`Writing to spreadsheet ${args.spreadsheetId}, range: ${args.range}`);
             try {
@@ -30,7 +32,8 @@ export function register(server) {
                 const updatedCells = response.updatedCells || 0;
                 const updatedRows = response.updatedRows || 0;
                 const updatedColumns = response.updatedColumns || 0;
-                return `Successfully wrote ${updatedCells} cells (${updatedRows} rows, ${updatedColumns} columns) to range ${args.range}.`;
+                const sheetUrl = `https://docs.google.com/spreadsheets/d/${args.spreadsheetId}/edit`;
+                return `${sheetUrl}\nSuccessfully wrote ${updatedCells} cells (${updatedRows} rows, ${updatedColumns} columns) to range ${args.range}.`;
             }
             catch (error) {
                 log.error(`Error writing to spreadsheet ${args.spreadsheetId}: ${error.message || error}`);

package/dist/tools/utils/appendMarkdownToGoogleDoc.js

@@ -1,15 +1,21 @@
+import * as fs from 'fs/promises';
 import { UserError } from 'fastmcp';
 import { z } from 'zod';
 import { getDocsClient } from '../../clients.js';
 import { DocumentIdParameter, MarkdownConversionError } from '../../types.js';
 import * as GDocsHelpers from '../../googleDocsApiHelpers.js';
 import { insertMarkdown, formatInsertResult } from '../../markdown-transformer/index.js';
+import { guardMutation, trackMutation } from '../../readTracker.js';
 export function register(server) {
     server.addTool({
         name: 'appendMarkdown',
-        description: 'Appends formatted content to the end of a document using markdown syntax. Supports headings, bold, italic, strikethrough, links, and bullet/numbered lists. Use this instead of appendText when you need formatting.',
+        description: 'Best for adding new formatted content to the end of a document. ' +
+            'Supports headings, bold, italic, strikethrough, links, and bullet/numbered lists. ' +
+            'Use this instead of appendText when you need formatting. ' +
+            'To edit existing content, use modifyText (single-location) or replaceDocumentWithMarkdown (section/full rewrite).',
         parameters: DocumentIdParameter.extend({
-            markdown: z.string().min(1).describe('The markdown content to append.'),
+            markdown: z.string().optional().describe('The markdown content to append. For content longer than ~2000 characters, prefer writing to a local file first and passing filePath instead.'),
+            filePath: z.string().optional().describe('Path to a local markdown file to use as content. Takes precedence over the markdown parameter.'),
             addNewlineIfNeeded: z
                 .boolean()
                 .optional()
@@ -26,8 +32,22 @@ export function register(server) {
                 .describe('If true, the first H1 heading (# ...) in the markdown is styled as a Google Docs TITLE instead of Heading 1. Useful when the markdown represents a full document whose first line is the document title.'),
         }),
         execute: async (args, { log }) => {
+            await guardMutation(args.documentId);
             const docs = await getDocsClient();
-            log.info(`Appending markdown to doc ${args.documentId} (${args.markdown.length} chars)${args.tabId ? ` in tab ${args.tabId}` : ''}`);
+            // Resolve markdown content from filePath or inline parameter
+            let markdown = args.markdown;
+            if (args.filePath) {
+                try {
+                    markdown = await fs.readFile(args.filePath, 'utf-8');
+                    log.info(`Read ${markdown.length} chars from file: ${args.filePath}`);
+                } catch (err) {
+                    throw new UserError(`Failed to read file at "${args.filePath}": ${err.message}`);
+                }
+            }
+            if (!markdown || markdown.length === 0) {
+                throw new UserError('Either markdown or filePath must be provided with non-empty content.');
+            }
+            log.info(`Appending markdown to doc ${args.documentId} (${markdown.length} chars)${args.tabId ? ` in tab ${args.tabId}` : ''}`);
             try {
                 // 1. Get document end index
                 const doc = await docs.documents.get({
@@ -72,14 +92,16 @@ export function register(server) {
                     log.info(`Added spacing, new start index: ${startIndex}`);
                 }
                 // 3. Convert and append markdown
-                const result = await insertMarkdown(docs, args.documentId, args.markdown, {
+                const result = await insertMarkdown(docs, args.documentId, markdown, {
                     startIndex,
                     tabId: args.tabId,
                     firstHeadingAsTitle: args.firstHeadingAsTitle,
                 });
                 const debugSummary = formatInsertResult(result);
                 log.info(debugSummary);
-                return `Successfully appended ${args.markdown.length} characters of markdown.\n\n${debugSummary}`;
+                const docUrl = `https://docs.google.com/document/d/${args.documentId}/edit`;
+                trackMutation(args.documentId);
+                return `${docUrl}\nSuccessfully appended ${markdown.length} characters of markdown.\n\n${debugSummary}`;
             }
             catch (error) {
                 log.error(`Error appending markdown: ${error.message}`);

package/dist/tools/utils/replaceDocumentWithMarkdown.js

@@ -1,15 +1,22 @@
+import * as fs from 'fs/promises';
 import { UserError } from 'fastmcp';
 import { z } from 'zod';
 import { getDocsClient } from '../../clients.js';
 import { DocumentIdParameter, MarkdownConversionError } from '../../types.js';
 import * as GDocsHelpers from '../../googleDocsApiHelpers.js';
 import { insertMarkdown, formatInsertResult } from '../../markdown-transformer/index.js';
+import { guardMutation, trackMutation } from '../../readTracker.js';
 export function register(server) {
     server.addTool({
         name: 'replaceDocumentWithMarkdown',
-        description: "Replaces the entire document body with content parsed from markdown. Supports headings, bold, italic, strikethrough, links, and bullet/numbered lists. Use readDocument with format='markdown' first to get the current content, edit it, then call this tool to apply changes.",
+        description: "Best for rewriting entire sections or full documents. Replaces the entire document body with content parsed from markdown. " +
+            "Supports headings, bold, italic, strikethrough, links, and bullet/numbered lists. " +
+            "Use readDocument with format='markdown' first to get the current content, edit it, then call this tool to apply changes. " +
+            "For small single-location edits (one line or paragraph), use modifyText instead. " +
+            "To add content without rewriting, use appendMarkdown.",
         parameters: DocumentIdParameter.extend({
-            markdown: z.string().min(1).describe('The markdown content to apply to the document.'),
+            markdown: z.string().optional().describe('The markdown content to apply to the document. For content longer than ~2000 characters, prefer writing to a local file first and passing filePath instead.'),
+            filePath: z.string().optional().describe('Path to a local markdown file to use as content. Takes precedence over the markdown parameter. Use this for large documents to avoid truncation.'),
             preserveTitle: z
                 .boolean()
                 .optional()
@@ -26,8 +33,22 @@ export function register(server) {
                 .describe('If true (default), the first H1 heading (# ...) in the markdown is styled as a Google Docs TITLE instead of Heading 1. Useful when the markdown represents a full document whose first line is the document title. Set to false if the first H1 should remain a Heading 1.'),
         }),
         execute: async (args, { log }) => {
+            await guardMutation(args.documentId);
             const docs = await getDocsClient();
-            log.info(`Replacing doc ${args.documentId} with markdown (${args.markdown.length} chars)${args.tabId ? ` in tab ${args.tabId}` : ''}`);
+            // Resolve markdown content from filePath or inline parameter
+            let markdown = args.markdown;
+            if (args.filePath) {
+                try {
+                    markdown = await fs.readFile(args.filePath, 'utf-8');
+                    log.info(`Read ${markdown.length} chars from file: ${args.filePath}`);
+                } catch (err) {
+                    throw new UserError(`Failed to read file at "${args.filePath}": ${err.message}`);
+                }
+            }
+            if (!markdown || markdown.length === 0) {
+                throw new UserError('Either markdown or filePath must be provided with non-empty content.');
+            }
+            log.info(`Replacing doc ${args.documentId} with markdown (${markdown.length} chars)${args.tabId ? ` in tab ${args.tabId}` : ''}`);
             try {
                 // 1. Get document structure
                 const doc = await docs.documents.get({
@@ -133,14 +154,16 @@ export function register(server) {
                 }
                 // 5. Convert markdown and insert (indices calculated for empty document)
                 log.info(`Inserting markdown starting at index ${startIndex} (after delete, document should be empty)`);
-                const result = await insertMarkdown(docs, args.documentId, args.markdown, {
+                const result = await insertMarkdown(docs, args.documentId, markdown, {
                     startIndex,
                     tabId: args.tabId,
                     firstHeadingAsTitle: args.firstHeadingAsTitle,
                 });
                 const debugSummary = formatInsertResult(result);
                 log.info(debugSummary);
-                return `Successfully replaced document content with ${args.markdown.length} characters of markdown.\n\n${debugSummary}`;
+                trackMutation(args.documentId);
+                const docUrl = `https://docs.google.com/document/d/${args.documentId}/edit`;
+                return `${docUrl}\nSuccessfully replaced document content with ${markdown.length} characters of markdown.\n\n${debugSummary}`;
             }
             catch (error) {
                 log.error(`Error replacing document with markdown: ${error.message}`);

package/dist/types.js

@@ -66,8 +66,7 @@ export const TextFindParameter = z.object({
         .int()
         .min(1)
         .optional()
-        .default(1)
-        .describe('Which instance of the text to target (1st, 2nd, etc.). Defaults to 1.'),
+        .describe('Which instance of the text to target (1st, 2nd, etc.). Required when multiple matches exist — omit to auto-select if only one match.'),
 });
 // --- Style Parameter Schemas ---
 export const TextStyleParameters = z

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "google-tools-mcp",
-  "version": "1.0.16",
+  "version": "1.1.1",
   "description": "Combined Google Workspace MCP server (Drive, Docs, Sheets, Gmail) with lazy-loaded tool categories",
   "type": "module",
   "bin": {
@@ -17,14 +17,22 @@
     "sheets",
     "docs"
   ],
+  "scripts": {
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+    "test:ci": "node --experimental-vm-modules node_modules/jest/bin/jest.js --ci --coverage"
+  },
   "license": "MIT",
   "dependencies": {
     "fastmcp": "^3.24.0",
     "google-auth-library": "^10.5.0",
     "googleapis": "^171.4.0",
-    "markdown-it": "^14.1.0",
     "mammoth": "^1.9.0",
+    "markdown-it": "^14.1.0",
     "pdf-parse": "^1.1.1",
     "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@jest/globals": "^30.3.0",
+    "jest": "^30.3.0"
   }
 }