google-tools-mcp 1.0.17 → 1.1.1

package/dist/tools/index.js

@@ -6,21 +6,103 @@ import * as fs from 'fs/promises';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
 import * as os from 'os';
+import { exec } from 'child_process';
+import { promisify } from 'util';
 import { getTokenPath, getConfigDir, SCOPES } from '../auth.js';
 import { resetClients, withAuthRetry, getAuthClientIfReady } from '../clients.js';
 import { logger } from '../logger.js';
 import { google } from 'googleapis';
 
+const execAsync = promisify(exec);
+
+const REPO = 'karthikcsq/google-tools-mcp';
+
+async function tryGhCli(title, body, label) {
+    // Probe for gh CLI
+    try {
+        await execAsync('gh --version');
+    } catch {
+        return { ok: false, reason: 'gh CLI not installed' };
+    }
+    // Probe for auth
+    try {
+        await execAsync('gh auth status');
+    } catch {
+        return { ok: false, reason: 'gh CLI not authenticated (run: gh auth login)' };
+    }
+    // Write body to a temp file to avoid shell-escaping issues with newlines/quotes.
+    const tmpFile = path.join(os.tmpdir(), `gtm-feedback-${Date.now()}-${Math.random().toString(36).slice(2)}.md`);
+    try {
+        await fs.writeFile(tmpFile, body, 'utf8');
+        const { stdout } = await execAsync(
+            `gh issue create --repo ${REPO} --title ${JSON.stringify(title)} --label ${JSON.stringify(label)} --body-file ${JSON.stringify(tmpFile)}`,
+            { maxBuffer: 10 * 1024 * 1024 }
+        );
+        const issueUrl = stdout.trim().split('\n').pop();
+        return { ok: true, issueUrl };
+    } catch (err) {
+        return { ok: false, reason: `gh CLI failed: ${err.stderr || err.message || err}` };
+    } finally {
+        try { await fs.unlink(tmpFile); } catch {}
+    }
+}
+
+function openBrowser(url) {
+    const platform = process.platform;
+    let cmd;
+    if (platform === 'win32') {
+        cmd = `start "" "${url}"`;
+    } else if (platform === 'darwin') {
+        cmd = `open "${url}"`;
+    } else {
+        cmd = `xdg-open "${url}"`;
+    }
+    return new Promise((resolve) => {
+        exec(cmd, (err) => resolve(!err));
+    });
+}
+
 // ---------------------------------------------------------------------------
-// Wrap server.addTool so every tool's execute() auto-retries on invalid_grant.
+// Wrap server.addTool so every tool's execute() auto-retries on invalid_grant
+// and appends a troubleshoot/feedback hint to errors.
 // ---------------------------------------------------------------------------
+const ERROR_HINT =
+    '\n\nIf this error is unexpected or unclear, you can:\n' +
+    '  • Call the `troubleshoot` tool to run a health check (auth, API connectivity, recent logs).\n' +
+    '  • Call the `feedback` tool to file a bug report with diagnostics auto-attached.';
+
+// Tools that should NOT have the hint appended (would be circular/noisy).
+const HINT_EXCLUDED_TOOLS = new Set(['troubleshoot', 'feedback', 'help', 'logout']);
+
+function appendHintToError(error, toolName) {
+    if (HINT_EXCLUDED_TOOLS.has(toolName)) return error;
+    if (!error) return error;
+    // Avoid double-appending if something else (or a retry) already added it.
+    const existingMsg = error.message || '';
+    if (existingMsg.includes('`troubleshoot` tool')) return error;
+    try {
+        error.message = existingMsg + ERROR_HINT;
+    } catch {
+        // Some error types have non-writable message; fall back to a new error.
+        const wrapped = new Error(existingMsg + ERROR_HINT);
+        wrapped.cause = error;
+        return wrapped;
+    }
+    return error;
+}
+
 function wrapServerWithAuthRetry(server) {
     const originalAddTool = server.addTool.bind(server);
     server.addTool = function (toolDef) {
         const originalExecute = toolDef.execute;
+        const toolName = toolDef.name;
         if (originalExecute) {
-            toolDef.execute = function (...args) {
-                return withAuthRetry(() => originalExecute.apply(this, args));
+            toolDef.execute = async function (...args) {
+                try {
+                    return await withAuthRetry(() => originalExecute.apply(this, args));
+                } catch (err) {
+                    throw appendHintToError(err, toolName);
+                }
             };
         }
         return originalAddTool(toolDef);
@@ -109,15 +191,22 @@ export async function registerAllTools(server) {
     server.addTool({
         name: 'help',
         description:
-            'Show documentation for google-tools-mcp: setup instructions, available tool categories, environment variables, and troubleshooting. Call this when you need guidance on how to use the Google Workspace tools.',
+            'Show documentation for google-tools-mcp: setup instructions, available tool categories, environment variables, and troubleshooting. ' +
+            'Call this when you need guidance on how to use the Google Workspace tools. ' +
+            'Also available: `troubleshoot` (run health check when tools fail) and `feedback` (submit bug reports/feature requests with diagnostics auto-attached).',
         parameters: z.object({}),
         execute: async () => {
             const __dirname = path.dirname(fileURLToPath(import.meta.url));
             const readmePath = path.resolve(__dirname, '..', '..', 'README.md');
+            const diagnosticsSection = '\n\n## Diagnostics & Feedback\n\n' +
+                '- **`troubleshoot`** — Run a health check when tools fail (checks auth, API connectivity, config, recent logs).\n' +
+                '- **`feedback`** — Submit a bug report or feature request with diagnostics auto-attached (files via GitHub CLI or browser).\n' +
+                '- **`help`** — Show this documentation.\n';
             try {
-                return await fs.readFile(readmePath, 'utf-8');
+                const readme = await fs.readFile(readmePath, 'utf-8');
+                return readme + diagnosticsSection;
             } catch {
-                return 'README not found. Visit https://www.npmjs.com/package/google-tools-mcp for documentation.';
+                return 'README not found. Visit https://www.npmjs.com/package/google-tools-mcp for documentation.' + diagnosticsSection;
             }
         },
     });
@@ -275,7 +364,7 @@ export async function registerAllTools(server) {
     server.addTool({
         name: 'feedback',
         description:
-            'Submit feedback or a bug report for google-tools-mcp. Automatically collects diagnostic info and generates a pre-filled GitHub issue URL.',
+            'Submit feedback or a bug report for google-tools-mcp. Automatically collects diagnostic info, then files the issue via the GitHub CLI (`gh`) if available, or falls back to opening a pre-filled GitHub issue URL in the user\'s browser.',
         parameters: z.object({
             type: z.enum(['bug', 'feature']).describe('Type of feedback'),
             title: z.string().describe('Short summary'),
@@ -334,21 +423,38 @@ export async function registerAllTools(server) {
                 `</details>`,
             ].join('\n');
 
-            // Build GitHub issue URL
             const label = args.type === 'bug' ? 'bug' : 'enhancement';
+
+            // Try gh CLI first
+            const ghResult = await tryGhCli(args.title, body, label);
+            if (ghResult.ok) {
+                return JSON.stringify({
+                    method: 'gh-cli',
+                    issueUrl: ghResult.issueUrl,
+                    note: 'Issue filed successfully via GitHub CLI.',
+                }, null, 2);
+            }
+
+            // Fallback: open pre-filled GitHub issue URL in the user's browser
             const params = new URLSearchParams({
                 title: args.title,
                 body,
                 labels: label,
             });
-            const url = `https://github.com/karthikcsq/google-tools-mcp/issues/new?${params.toString()}`;
+            const url = `https://github.com/${REPO}/issues/new?${params.toString()}`;
+            const opened = await openBrowser(url);
 
             return JSON.stringify({
+                method: 'browser-fallback',
+                ghCliUnavailableReason: ghResult.reason,
                 url,
+                browserOpened: opened,
                 markdown: body,
                 note: url.length > 8000
-                    ? 'The URL may be too long for some browsers. Use the markdown body below to create the issue manually.'
-                    : 'Open the URL to create a pre-filled GitHub issue.',
+                    ? 'The URL may be too long for some browsers. Use the markdown body to create the issue manually.'
+                    : opened
+                        ? 'Opened the pre-filled GitHub issue in your browser. Click "Submit new issue" to file it.'
+                        : 'Could not auto-open browser. Please open the URL manually.',
             }, null, 2);
         },
     });

package/dist/tools/sheets/batchWrite.js

@@ -1,6 +1,7 @@
 import { UserError } from 'fastmcp';
 import { z } from 'zod';
 import { getSheetsClient } from '../../clients.js';
+import { guardMutation, trackMutation } from '../../readTracker.js';
 export function register(server) {
     server.addTool({
         name: 'batchWrite',
@@ -25,6 +26,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();
             const rangeNames = args.data.map((d) => d.range).join(', ');
             log.info(`Batch writing to ${args.data.length} range(s) in spreadsheet ${args.spreadsheetId}: ${rangeNames}`);

package/dist/tools/sheets/clearSpreadsheetRange.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: 'clearRange',
@@ -13,6 +14,7 @@ export function register(server) {
             range: z.string().describe('A1 notation range to clear (e.g., "A1:B10" or "Sheet1!A1:B10").'),
         }),
         execute: async (args, { log }) => {
+            await guardMutation(args.spreadsheetId);
             const sheets = await getSheetsClient();
             log.info(`Clearing range ${args.range} in spreadsheet ${args.spreadsheetId}`);
             try {

package/dist/tools/sheets/getSpreadsheetInfo.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: 'getSpreadsheetInfo',
@@ -16,6 +17,7 @@ export function register(server) {
             log.info(`Getting info for spreadsheet: ${args.spreadsheetId}`);
             try {
                 const metadata = await SheetsHelpers.getSpreadsheetMetadata(sheets, args.spreadsheetId);
+                trackRead(args.spreadsheetId);
                 const sheetList = metadata.sheets || [];
                 return JSON.stringify({
                     title: metadata.properties?.title || 'Untitled',

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/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 {

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,7 +92,7 @@ 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,
@@ -80,7 +100,8 @@ export function register(server) {
                 const debugSummary = formatInsertResult(result);
                 log.info(debugSummary);
                 const docUrl = `https://docs.google.com/document/d/${args.documentId}/edit`;
-                return `${docUrl}\nSuccessfully appended ${args.markdown.length} characters of markdown.\n\n${debugSummary}`;
+                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,15 +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);
+                trackMutation(args.documentId);
                 const docUrl = `https://docs.google.com/document/d/${args.documentId}/edit`;
-                return `${docUrl}\nSuccessfully replaced document content with ${args.markdown.length} characters of markdown.\n\n${debugSummary}`;
+                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.17",
+  "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"
   }
 }