gdocs-mcp 0.2.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # gdocs-mcp
 
-Open-source MCP server for Google Docs and Sheets. Give Claude (or any MCP-compatible AI) the ability to read, create, edit, and search your Google Docs — with OAuth tokens that never leave your machine.
+Open-source MCP server for Google Docs and Sheets. Give Claude (or any MCP-compatible AI) the ability to read, create, edit, search, and style your Google Docs — with OAuth tokens that never leave your machine.
 
 **Open-source. Self-hosted. Your tokens never leave your machine.**
 
@@ -46,7 +46,7 @@ Restart Claude Desktop. Ask Claude: *"List my recent Google Docs"* to verify.
 claude mcp add gdocs -- npx gdocs-mcp
 ```
 
-## Tools
+## Tools (16)
 
 ### Google Docs
 
@@ -69,21 +69,88 @@ claude mcp add gdocs -- npx gdocs-mcp
 |------|-------------|
 | `get_charts` | List all charts in a spreadsheet with IDs and specs |
 
+### Style Presets
+
+Define how your documents look once, apply everywhere.
+
+| Tool | Description |
+|------|-------------|
+| `extract_document_styles` | Extract styles from a reference Google Doc and save as a reusable preset |
+| `apply_style_preset` | Apply a style preset to any document — fonts, colors, spacing, tables |
+| `list_style_presets` | List all available presets (4 built-in + your custom presets) |
+| `set_active_preset` | Set the default preset for new documents |
+| `delete_style_preset` | Delete a custom preset |
+
+#### Built-in Presets
+
+| Preset | Font | Headings | Body |
+|--------|------|----------|------|
+| `clean` | Inter | Dark charcoal, 22/16/13pt | 11pt, 1.5x spacing |
+| `corporate` | Arial | Dark grey, conservative | 11pt, 1.4x spacing |
+| `classic` | Georgia + Garamond | Dark blue, serif | 11pt, 1.4x spacing |
+| `minimal` | Roboto | Black, light weight | 10.5pt, 1.5x spacing |
+
+#### Extract + Apply Workflow
+
+The fastest way to use presets: point to a Google Doc that already looks the way you want.
+
+```
+You: "Extract styles from my brand doc and save as 'brand'"
+  → extract_document_styles(documentId, saveAs: "brand")
+
+You: "Apply brand styles to this report"
+  → apply_style_preset(documentId, presetName: "brand")
+```
+
+One-step capture, one-step apply. No JSON editing needed.
+
+#### Style Properties
+
+Presets support every text and paragraph property the Google Docs API exposes:
+
+**Text:** font family, font size, bold, italic, underline, strikethrough, small caps, text color, background color, baseline offset
+
+**Paragraph:** alignment (left/center/right/justified), line spacing, space above/below, first line indent, start/end indent, keep lines together, keep with next, direction (LTR/RTL), paragraph borders (top/bottom/left/right)
+
+**Document:** page margins (top/bottom/left/right), page size (width/height)
+
+**Tables:** header row background and text color, bold headers, border color and width, cell padding, alternating row backgrounds
+
+Only properties you specify are applied. Omitted properties are left unchanged. Config is stored at `~/.gdocs-mcp/styles.json`.
+
+## Limitations
+
+These are Google Docs API limitations, not gdocs-mcp limitations:
+
+- **Table of Contents styling** is not controllable — TOC entries mirror heading styles
+- **Custom named styles** cannot be created — only the 9 built-in types (Title, Subtitle, Heading 1-6, Normal Text)
+- **Conditional formatting** does not exist in Google Docs
+- **Multi-column layout** is not exposed via the API
+- **Bullet/numbered list glyph types** are per-paragraph, not configurable via style presets
+- **Table header detection** assumes row 0 is the header — multi-row headers are not detected
+
 ## Security
 
-- OAuth tokens are stored locally at `~/.gdocs-mcp/token.json` with `600` permissions
-- Credentials are stored at `~/.gdocs-mcp/credentials.json` with `600` permissions
+- OAuth tokens stored locally at `~/.gdocs-mcp/token.json` with `600` permissions
+- Credentials stored at `~/.gdocs-mcp/credentials.json` with `600` permissions
+- Style presets stored at `~/.gdocs-mcp/styles.json`
 - No telemetry, no data collection, no third-party token storage
 - Tokens refresh automatically; if refresh fails, run `npx gdocs-mcp auth` again
 
 ## Configuration
 
-By default, credentials and tokens are stored in `~/.gdocs-mcp/`. Override with:
+Credentials and tokens are stored in `~/.gdocs-mcp/` by default. Override credentials path with:
 
 ```bash
 GDOCS_CREDENTIALS=/path/to/credentials.json npx gdocs-mcp
 ```
 
+For faster startup, install globally instead of using npx:
+
+```bash
+npm install -g gdocs-mcp
+```
+
 ## Requirements
 
 - Node.js 18+

package/dist/auth/google-auth.d.ts

@@ -3,6 +3,7 @@ declare const CONFIG_DIR: string;
 declare const TOKEN_PATH: string;
 declare const CREDENTIALS_PATH_DEFAULT: string;
 export declare function getAuthClient(): OAuth2Client;
+export declare function isReadOnlyMode(): boolean;
 export declare function getConfigDir(): string;
 export declare function getTokenPath(): string;
 export declare function getScopes(): string[];

package/dist/auth/google-auth.js

@@ -4,7 +4,13 @@ import path from 'path';
 const CONFIG_DIR = path.join(process.env.HOME || '~', '.gdocs-mcp');
 const TOKEN_PATH = path.join(CONFIG_DIR, 'token.json');
 const CREDENTIALS_PATH_DEFAULT = path.join(CONFIG_DIR, 'credentials.json');
-const SCOPES = [
+const READONLY = process.env.GDOCS_MCP_READONLY === '1';
+const FULL_SCOPES = [
+    'https://www.googleapis.com/auth/documents',
+    'https://www.googleapis.com/auth/spreadsheets.readonly',
+    'https://www.googleapis.com/auth/drive',
+];
+const READONLY_SCOPES = [
     'https://www.googleapis.com/auth/documents',
     'https://www.googleapis.com/auth/spreadsheets.readonly',
     'https://www.googleapis.com/auth/drive.readonly',
@@ -31,6 +37,16 @@ export function getAuthClient() {
         throw new Error('Auth required. Run: npx gdocs-mcp auth');
     }
     const token = JSON.parse(fs.readFileSync(TOKEN_PATH, 'utf8'));
+    // Check if token has sufficient scopes for full mode
+    if (!READONLY && token.scope) {
+        const grantedScopes = token.scope.split(' ');
+        const hasDriveWrite = grantedScopes.some((s) => s === 'https://www.googleapis.com/auth/drive');
+        if (!hasDriveWrite) {
+            throw new Error('Auth scopes insufficient. v0.4 requires expanded Drive access for export, copy, delete, and comments.\n' +
+                'Run: npx gdocs-mcp auth\n' +
+                'Or set GDOCS_MCP_READONLY=1 to use read-only mode with the original scope.');
+        }
+    }
     oAuth2Client.setCredentials(token);
     oAuth2Client.on('tokens', (newTokens) => {
         const existing = JSON.parse(fs.readFileSync(TOKEN_PATH, 'utf8'));
@@ -39,6 +55,9 @@ export function getAuthClient() {
     });
     return oAuth2Client;
 }
+export function isReadOnlyMode() {
+    return READONLY;
+}
 export function getConfigDir() {
     return CONFIG_DIR;
 }
@@ -46,6 +65,6 @@ export function getTokenPath() {
     return TOKEN_PATH;
 }
 export function getScopes() {
-    return SCOPES;
+    return READONLY ? READONLY_SCOPES : FULL_SCOPES;
 }
 export { CONFIG_DIR, TOKEN_PATH, CREDENTIALS_PATH_DEFAULT };

package/dist/index.js

@@ -17,9 +17,23 @@ import { ExtractDocumentStylesSchema, extractDocumentStyles } from './tools/extr
 import { ListStylePresetsSchema, listStylePresets } from './tools/list-style-presets.js';
 import { SetActivePresetSchema, setActivePreset } from './tools/set-active-preset.js';
 import { DeleteStylePresetSchema, deleteStylePreset } from './tools/delete-style-preset.js';
+import { UpdateHeaderFooterSchema, updateHeaderFooter } from './tools/update-header-footer.js';
+import { FormatListSchema, formatList } from './tools/format-list.js';
+import { ExecuteScriptSchema, executeScript } from './tools/execute-script.js';
+import { InsertImageSchema, insertImage } from './tools/insert-image.js';
+import { InsertTableSchema, insertTable } from './tools/insert-table.js';
+import { InsertPageBreakSchema, insertPageBreak } from './tools/insert-page-break.js';
+import { InsertLinkSchema, insertLink } from './tools/insert-link.js';
+import { ExportDocumentSchema, exportDocument } from './tools/export-document.js';
+import { CopyDocumentSchema, copyDocument } from './tools/copy-document.js';
+import { DeleteDocumentSchema, deleteDocument } from './tools/delete-document.js';
+import { GetCommentsSchema, getComments } from './tools/get-comments.js';
+import { AddCommentSchema, addComment } from './tools/add-comment.js';
+const VERSION = '0.4.0';
+const QUIET = process.env.GDOCS_MCP_QUIET === '1';
 const server = new McpServer({
     name: 'gdocs-mcp',
-    version: '0.2.0',
+    version: VERSION,
 });
 function formatError(err) {
     if (err instanceof Error) {
@@ -36,19 +50,41 @@ function formatError(err) {
         if (message.includes('PERMISSION_DENIED') || message.includes('403')) {
             return 'Permission denied. Ensure the document is shared with your Google account.';
         }
+        if (message.includes('Apps Script API has not been used')) {
+            return 'Apps Script API is not enabled. Enable it at: https://console.cloud.google.com/apis/library/script.googleapis.com';
+        }
         return message;
     }
     return String(err);
 }
 function registerTool(name, description, schema, handler) {
     server.tool(name, description, schema.shape, async (args) => {
+        const startTime = performance.now();
         try {
             const result = await handler(args);
+            if (!QUIET) {
+                const totalMs = Math.round(performance.now() - startTime);
+                const apiMs = result?._apiMs;
+                const requestCount = result?.requestCount;
+                delete result?._apiMs;
+                let logParts = [`[gdocs-mcp] ${name}: ${totalMs}ms`];
+                if (apiMs !== undefined) {
+                    logParts.push(`(api: ${apiMs}ms${requestCount ? `, ${requestCount} requests` : ''})`);
+                }
+                else if (totalMs < 10) {
+                    logParts.push('(local)');
+                }
+                console.error(logParts.join(' '));
+            }
             return {
                 content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
             };
         }
         catch (err) {
+            if (!QUIET) {
+                const totalMs = Math.round(performance.now() - startTime);
+                console.error(`[gdocs-mcp] ${name}: ${totalMs}ms (error)`);
+            }
             return {
                 content: [{ type: 'text', text: formatError(err) }],
                 isError: true,
@@ -70,15 +106,29 @@ registerTool('unmerge_table_cells', 'Unmerge previously merged cells in a docume
 // Google Sheets tools
 registerTool('get_charts', 'List all charts in a Google Sheets spreadsheet with IDs and specs', GetChartsSchema, getCharts);
 // Style preset tools
-registerTool('apply_style_preset', 'Apply a style preset to a document. Updates named styles (TITLE, HEADING_1-6, NORMAL_TEXT, SUBTITLE), document margins, and table formatting in a single API call.', ApplyStylePresetSchema, applyStylePreset);
-registerTool('extract_document_styles', 'Extract styles from a Google Doc and optionally save as a reusable preset. Returns font, size, color, spacing for all named styles, margins, and table formatting.', ExtractDocumentStylesSchema, extractDocumentStyles);
-registerTool('list_style_presets', 'List all available style presets (built-in: clean, corporate, classic, minimal + user-defined) with typography summaries.', ListStylePresetsSchema, listStylePresets);
-registerTool('set_active_preset', 'Set the active style preset. The active preset auto-applies when creating new documents.', SetActivePresetSchema, setActivePreset);
+registerTool('apply_style_preset', 'Apply a style preset to a document. Styles all paragraphs by named type, updates margins, and formats tables.', ApplyStylePresetSchema, applyStylePreset);
+registerTool('extract_document_styles', 'Extract styles from a Google Doc and optionally save as a reusable preset.', ExtractDocumentStylesSchema, extractDocumentStyles);
+registerTool('list_style_presets', 'List all available style presets (built-in + user-defined) with typography summaries.', ListStylePresetsSchema, listStylePresets);
+registerTool('set_active_preset', 'Set the active style preset. Auto-applies when creating new documents.', SetActivePresetSchema, setActivePreset);
 registerTool('delete_style_preset', 'Delete a user-defined style preset. Cannot delete built-in presets.', DeleteStylePresetSchema, deleteStylePreset);
+// v0.3 tools
+registerTool('update_header_footer', 'Create or update header/footer content and styling. Supports page number insertion.', UpdateHeaderFooterSchema, updateHeaderFooter);
+registerTool('format_list', 'Apply bullet, numbered, or remove list formatting on a paragraph range. Supports 6 glyph presets.', FormatListSchema, formatList);
+registerTool('execute_script', 'Execute a function in a deployed Google Apps Script project. Returns JSON result.', ExecuteScriptSchema, executeScript);
+// v0.4 content tools
+registerTool('insert_image', 'Insert an image from a URL at a specific position. Supports optional width/height sizing in PT.', InsertImageSchema, insertImage);
+registerTool('insert_table', 'Create a table with specified rows (1-20) and columns (1-20) at a position.', InsertTableSchema, insertTable);
+registerTool('insert_page_break', 'Insert a page break at a specific position.', InsertPageBreakSchema, insertPageBreak);
+registerTool('insert_link', 'Add a hyperlink to an existing text range. The text must already exist in the document.', InsertLinkSchema, insertLink);
+registerTool('export_document', 'Export a Google Doc as PDF, DOCX, TXT, or HTML. Saves to file or returns base64.', ExportDocumentSchema, exportDocument);
+registerTool('copy_document', 'Create a copy of a Google Doc with a new title. Inherits content and formatting.', CopyDocumentSchema, copyDocument);
+registerTool('delete_document', 'Move a Google Doc to trash. Requires confirmTitle matching the exact document title.', DeleteDocumentSchema, deleteDocument);
+registerTool('get_comments', 'List comments on a document with author, content, resolved status, and replies.', GetCommentsSchema, getComments);
+registerTool('add_comment', 'Add a comment anchored to specific text in the document. Anchors to first occurrence of quotedText.', AddCommentSchema, addComment);
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    console.error('gdocs-mcp v0.2.0 started');
+    console.error(`gdocs-mcp v${VERSION} started`);
 }
 main().catch((err) => {
     console.error('Failed to start gdocs-mcp:', err);

package/dist/tools/add-comment.d.ts

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+export declare const AddCommentSchema: z.ZodObject<{
+    documentId: z.ZodString;
+    content: z.ZodString;
+    quotedText: z.ZodString;
+}, z.core.$strip>;
+export declare function addComment(args: z.infer<typeof AddCommentSchema>): Promise<{
+    documentId: string;
+    commentId: string | null | undefined;
+    content: string | null | undefined;
+    quotedText: string | undefined;
+    createdTime: string | null | undefined;
+    _apiMs: number;
+}>;

package/dist/tools/add-comment.js

@@ -0,0 +1,36 @@
+import { google } from 'googleapis';
+import { z } from 'zod';
+import { getAuthClient, isReadOnlyMode } from '../auth/google-auth.js';
+export const AddCommentSchema = z.object({
+    documentId: z.string().describe('The Google Doc document ID'),
+    content: z.string().describe('The comment text'),
+    quotedText: z.string().describe('Text in the document to anchor the comment to. Google matches the first occurrence.'),
+});
+export async function addComment(args) {
+    if (isReadOnlyMode()) {
+        throw new Error('add_comment is not available in read-only mode. Remove GDOCS_MCP_READONLY=1 and re-auth.');
+    }
+    const auth = getAuthClient();
+    const drive = google.drive({ version: 'v3', auth });
+    const apiStart = performance.now();
+    const res = await drive.comments.create({
+        fileId: args.documentId,
+        fields: 'id,author(displayName),content,quotedFileContent,createdTime',
+        requestBody: {
+            content: args.content,
+            quotedFileContent: {
+                value: args.quotedText,
+                mimeType: 'text/html',
+            },
+        },
+    });
+    const apiMs = Math.round(performance.now() - apiStart);
+    return {
+        documentId: args.documentId,
+        commentId: res.data.id,
+        content: res.data.content,
+        quotedText: res.data.quotedFileContent?.value,
+        createdTime: res.data.createdTime,
+        _apiMs: apiMs,
+    };
+}

package/dist/tools/copy-document.d.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+export declare const CopyDocumentSchema: z.ZodObject<{
+    documentId: z.ZodString;
+    newTitle: z.ZodString;
+}, z.core.$strip>;
+export declare function copyDocument(args: z.infer<typeof CopyDocumentSchema>): Promise<{
+    originalDocumentId: string;
+    newDocumentId: string | null | undefined;
+    title: string | null | undefined;
+    url: string | null | undefined;
+    _apiMs: number;
+}>;

package/dist/tools/copy-document.js

@@ -0,0 +1,28 @@
+import { google } from 'googleapis';
+import { z } from 'zod';
+import { getAuthClient, isReadOnlyMode } from '../auth/google-auth.js';
+export const CopyDocumentSchema = z.object({
+    documentId: z.string().describe('The Google Doc document ID to copy'),
+    newTitle: z.string().describe('Title for the copy'),
+});
+export async function copyDocument(args) {
+    if (isReadOnlyMode()) {
+        throw new Error('copy_document is not available in read-only mode. Remove GDOCS_MCP_READONLY=1 and re-auth.');
+    }
+    const auth = getAuthClient();
+    const drive = google.drive({ version: 'v3', auth });
+    const apiStart = performance.now();
+    const res = await drive.files.copy({
+        fileId: args.documentId,
+        requestBody: { name: args.newTitle },
+        fields: 'id, name, webViewLink',
+    });
+    const apiMs = Math.round(performance.now() - apiStart);
+    return {
+        originalDocumentId: args.documentId,
+        newDocumentId: res.data.id,
+        title: res.data.name,
+        url: res.data.webViewLink,
+        _apiMs: apiMs,
+    };
+}

package/dist/tools/delete-document.d.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+export declare const DeleteDocumentSchema: z.ZodObject<{
+    documentId: z.ZodString;
+    confirmTitle: z.ZodString;
+}, z.core.$strip>;
+export declare function deleteDocument(args: z.infer<typeof DeleteDocumentSchema>): Promise<{
+    documentId: string;
+    title: string;
+    trashed: boolean;
+    message: string;
+    _apiMs: number;
+}>;

package/dist/tools/delete-document.js

@@ -0,0 +1,36 @@
+import { google } from 'googleapis';
+import { z } from 'zod';
+import { getAuthClient, isReadOnlyMode } from '../auth/google-auth.js';
+export const DeleteDocumentSchema = z.object({
+    documentId: z.string().describe('The Google Doc document ID to trash'),
+    confirmTitle: z.string().describe('Must match the exact document title to confirm deletion. This prevents accidental trashing.'),
+});
+export async function deleteDocument(args) {
+    if (isReadOnlyMode()) {
+        throw new Error('delete_document is not available in read-only mode. Remove GDOCS_MCP_READONLY=1 and re-auth.');
+    }
+    const auth = getAuthClient();
+    const drive = google.drive({ version: 'v3', auth });
+    const apiStart = performance.now();
+    // Get the actual document title
+    const file = await drive.files.get({
+        fileId: args.documentId,
+        fields: 'name',
+    });
+    const actualTitle = file.data.name;
+    if (args.confirmTitle !== actualTitle) {
+        throw new Error(`Confirmation failed. To trash this document, pass confirmTitle: "${actualTitle}"`);
+    }
+    await drive.files.update({
+        fileId: args.documentId,
+        requestBody: { trashed: true },
+    });
+    const apiMs = Math.round(performance.now() - apiStart);
+    return {
+        documentId: args.documentId,
+        title: actualTitle,
+        trashed: true,
+        message: 'Document moved to trash. It can be recovered from Google Drive trash.',
+        _apiMs: apiMs,
+    };
+}

package/dist/tools/execute-script.d.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+export declare const ExecuteScriptSchema: z.ZodObject<{
+    scriptId: z.ZodString;
+    functionName: z.ZodString;
+    parameters: z.ZodOptional<z.ZodArray<z.ZodAny>>;
+}, z.core.$strip>;
+export declare function executeScript(args: z.infer<typeof ExecuteScriptSchema>): Promise<{
+    scriptId: string;
+    functionName: string;
+    result: any;
+    _apiMs: number;
+}>;

package/dist/tools/execute-script.js

@@ -0,0 +1,37 @@
+import { google } from 'googleapis';
+import { z } from 'zod';
+import { getAuthClient } from '../auth/google-auth.js';
+export const ExecuteScriptSchema = z.object({
+    scriptId: z.string().describe('The Apps Script project ID. Find it at script.google.com > Project Settings.'),
+    functionName: z.string().describe('Name of the function to execute'),
+    parameters: z.array(z.any()).optional().describe('Array of parameters to pass to the function. Only primitive types (string, number, boolean, array, plain object).'),
+});
+export async function executeScript(args) {
+    const auth = getAuthClient();
+    const script = google.script({ version: 'v1', auth });
+    const apiStart = performance.now();
+    const res = await script.scripts.run({
+        scriptId: args.scriptId,
+        requestBody: {
+            function: args.functionName,
+            parameters: args.parameters || [],
+            devMode: false,
+        },
+    });
+    const apiMs = Math.round(performance.now() - apiStart);
+    // Check for script execution errors
+    if (res.data.error) {
+        const details = res.data.error.details;
+        const scriptError = details?.find((d) => d.errorType);
+        const errorMessage = scriptError
+            ? `${scriptError.errorType}: ${scriptError.errorMessage}`
+            : res.data.error.message || 'Unknown script error';
+        throw new Error(errorMessage);
+    }
+    return {
+        scriptId: args.scriptId,
+        functionName: args.functionName,
+        result: res.data.response?.result ?? null,
+        _apiMs: apiMs,
+    };
+}

package/dist/tools/export-document.d.ts

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+export declare const ExportDocumentSchema: z.ZodObject<{
+    documentId: z.ZodString;
+    format: z.ZodEnum<{
+        pdf: "pdf";
+        docx: "docx";
+        txt: "txt";
+        html: "html";
+    }>;
+    outputPath: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare function exportDocument(args: z.infer<typeof ExportDocumentSchema>): Promise<{
+    documentId: string;
+    format: "pdf" | "docx" | "txt" | "html";
+    savedTo: string;
+    sizeBytes: number;
+    _apiMs: number;
+    content?: undefined;
+} | {
+    documentId: string;
+    format: "pdf" | "docx" | "txt" | "html";
+    content: string;
+    sizeBytes: number;
+    _apiMs: number;
+    savedTo?: undefined;
+}>;

package/dist/tools/export-document.js

@@ -0,0 +1,43 @@
+import { google } from 'googleapis';
+import { z } from 'zod';
+import fs from 'fs';
+import { getAuthClient, isReadOnlyMode } from '../auth/google-auth.js';
+const MIME_TYPES = {
+    pdf: 'application/pdf',
+    docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    txt: 'text/plain',
+    html: 'text/html',
+};
+export const ExportDocumentSchema = z.object({
+    documentId: z.string().describe('The Google Doc document ID'),
+    format: z.enum(['pdf', 'docx', 'txt', 'html']).describe('Export format: pdf, docx, txt, or html'),
+    outputPath: z.string().optional().describe('Local file path to save the export. If omitted, returns base64-encoded content.'),
+});
+export async function exportDocument(args) {
+    if (isReadOnlyMode()) {
+        throw new Error('export_document is not available in read-only mode. Remove GDOCS_MCP_READONLY=1 and re-auth.');
+    }
+    const auth = getAuthClient();
+    const drive = google.drive({ version: 'v3', auth });
+    const apiStart = performance.now();
+    const res = await drive.files.export({ fileId: args.documentId, mimeType: MIME_TYPES[args.format] }, { responseType: 'arraybuffer' });
+    const buffer = Buffer.from(res.data);
+    const apiMs = Math.round(performance.now() - apiStart);
+    if (args.outputPath) {
+        fs.writeFileSync(args.outputPath, buffer);
+        return {
+            documentId: args.documentId,
+            format: args.format,
+            savedTo: args.outputPath,
+            sizeBytes: buffer.length,
+            _apiMs: apiMs,
+        };
+    }
+    return {
+        documentId: args.documentId,
+        format: args.format,
+        content: buffer.toString('base64'),
+        sizeBytes: buffer.length,
+        _apiMs: apiMs,
+    };
+}

package/dist/tools/format-list.d.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+export declare const FormatListSchema: z.ZodObject<{
+    documentId: z.ZodString;
+    startIndex: z.ZodNumber;
+    endIndex: z.ZodNumber;
+    listType: z.ZodEnum<{
+        none: "none";
+        bullet: "bullet";
+        numbered: "numbered";
+    }>;
+    preset: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare function formatList(args: z.infer<typeof FormatListSchema>): Promise<{
+    documentId: string;
+    listType: "none" | "bullet" | "numbered";
+    preset: string | null;
+    startIndex: number;
+    endIndex: number;
+    _apiMs: number;
+}>;

package/dist/tools/format-list.js

@@ -0,0 +1,74 @@
+import { google } from 'googleapis';
+import { z } from 'zod';
+import { getAuthClient } from '../auth/google-auth.js';
+const BULLET_PRESETS = [
+    'BULLET_DISC_CIRCLE_SQUARE',
+    'BULLET_DIAMONDX_ARROW3D_SQUARE',
+    'BULLET_CHECKBOX',
+];
+const NUMBERED_PRESETS = [
+    'NUMBERED_DECIMAL_ALPHA_ROMAN',
+    'NUMBERED_DECIMAL_NESTED',
+    'NUMBERED_UPPERALPHA_ALPHA_ROMAN',
+];
+const ALL_PRESETS = [...BULLET_PRESETS, ...NUMBERED_PRESETS];
+export const FormatListSchema = z.object({
+    documentId: z.string().describe('The Google Doc document ID'),
+    startIndex: z.number().describe('Start index of the paragraph range'),
+    endIndex: z.number().describe('End index of the paragraph range'),
+    listType: z.enum(['bullet', 'numbered', 'none']).describe('"bullet" for unordered, "numbered" for ordered, "none" to remove list formatting'),
+    preset: z.string().optional().describe('Bullet/number preset. Bullets: BULLET_DISC_CIRCLE_SQUARE (default), BULLET_DIAMONDX_ARROW3D_SQUARE, BULLET_CHECKBOX. ' +
+        'Numbers: NUMBERED_DECIMAL_ALPHA_ROMAN (default), NUMBERED_DECIMAL_NESTED, NUMBERED_UPPERALPHA_ALPHA_ROMAN.'),
+});
+export async function formatList(args) {
+    const auth = getAuthClient();
+    const docs = google.docs({ version: 'v1', auth });
+    const apiStart = performance.now();
+    const requests = [];
+    if (args.listType === 'none') {
+        requests.push({
+            deleteParagraphBullets: {
+                range: { startIndex: args.startIndex, endIndex: args.endIndex },
+            },
+        });
+    }
+    else {
+        const defaultPreset = args.listType === 'bullet'
+            ? 'BULLET_DISC_CIRCLE_SQUARE'
+            : 'NUMBERED_DECIMAL_ALPHA_ROMAN';
+        const preset = args.preset || defaultPreset;
+        // Validate preset matches list type
+        if (args.listType === 'bullet' && !BULLET_PRESETS.includes(preset)) {
+            if (NUMBERED_PRESETS.includes(preset)) {
+                throw new Error(`Preset "${preset}" is a numbered preset. Use listType: "numbered" or pick a bullet preset: ${BULLET_PRESETS.join(', ')}`);
+            }
+        }
+        if (args.listType === 'numbered' && !NUMBERED_PRESETS.includes(preset)) {
+            if (BULLET_PRESETS.includes(preset)) {
+                throw new Error(`Preset "${preset}" is a bullet preset. Use listType: "bullet" or pick a numbered preset: ${NUMBERED_PRESETS.join(', ')}`);
+            }
+        }
+        if (!ALL_PRESETS.includes(preset)) {
+            throw new Error(`Unknown preset "${preset}". Available: ${ALL_PRESETS.join(', ')}`);
+        }
+        requests.push({
+            createParagraphBullets: {
+                range: { startIndex: args.startIndex, endIndex: args.endIndex },
+                bulletPreset: preset,
+            },
+        });
+    }
+    await docs.documents.batchUpdate({
+        documentId: args.documentId,
+        requestBody: { requests },
+    });
+    const apiMs = Math.round(performance.now() - apiStart);
+    return {
+        documentId: args.documentId,
+        listType: args.listType,
+        preset: args.listType === 'none' ? null : (args.preset || (args.listType === 'bullet' ? 'BULLET_DISC_CIRCLE_SQUARE' : 'NUMBERED_DECIMAL_ALPHA_ROMAN')),
+        startIndex: args.startIndex,
+        endIndex: args.endIndex,
+        _apiMs: apiMs,
+    };
+}

package/dist/tools/get-comments.d.ts

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+export declare const GetCommentsSchema: z.ZodObject<{
+    documentId: z.ZodString;
+    includeResolved: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, z.core.$strip>;
+export declare function getComments(args: z.infer<typeof GetCommentsSchema>): Promise<{
+    documentId: string;
+    comments: {
+        id: string | null | undefined;
+        author: string;
+        authorEmail: string | null | undefined;
+        content: string | null | undefined;
+        quotedText: string | null;
+        resolved: boolean;
+        createdTime: string | null | undefined;
+        modifiedTime: string | null | undefined;
+        replies: {
+            author: string;
+            content: string | null | undefined;
+            createdTime: string | null | undefined;
+        }[];
+    }[];
+    count: number;
+    _apiMs: number;
+}>;

package/dist/tools/get-comments.js

@@ -0,0 +1,44 @@
+import { google } from 'googleapis';
+import { z } from 'zod';
+import { getAuthClient, isReadOnlyMode } from '../auth/google-auth.js';
+export const GetCommentsSchema = z.object({
+    documentId: z.string().describe('The Google Doc document ID'),
+    includeResolved: z.boolean().optional().default(false).describe('Include resolved comments (default: false, only open comments)'),
+});
+export async function getComments(args) {
+    if (isReadOnlyMode()) {
+        throw new Error('get_comments is not available in read-only mode. Remove GDOCS_MCP_READONLY=1 and re-auth.');
+    }
+    const auth = getAuthClient();
+    const drive = google.drive({ version: 'v3', auth });
+    const apiStart = performance.now();
+    const res = await drive.comments.list({
+        fileId: args.documentId,
+        fields: 'comments(id,author(displayName,emailAddress),content,quotedFileContent,resolved,createdTime,modifiedTime,replies(author(displayName),content,createdTime))',
+        pageSize: 100,
+    });
+    const comments = (res.data.comments || [])
+        .filter(c => args.includeResolved || !c.resolved)
+        .map(c => ({
+        id: c.id,
+        author: c.author?.displayName || 'Unknown',
+        authorEmail: c.author?.emailAddress,
+        content: c.content,
+        quotedText: c.quotedFileContent?.value || null,
+        resolved: c.resolved || false,
+        createdTime: c.createdTime,
+        modifiedTime: c.modifiedTime,
+        replies: (c.replies || []).map(r => ({
+            author: r.author?.displayName || 'Unknown',
+            content: r.content,
+            createdTime: r.createdTime,
+        })),
+    }));
+    const apiMs = Math.round(performance.now() - apiStart);
+    return {
+        documentId: args.documentId,
+        comments,
+        count: comments.length,
+        _apiMs: apiMs,
+    };
+}

package/dist/tools/insert-image.d.ts

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+export declare const InsertImageSchema: z.ZodObject<{
+    documentId: z.ZodString;
+    uri: z.ZodString;
+    index: z.ZodNumber;
+    width: z.ZodOptional<z.ZodNumber>;
+    height: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare function insertImage(args: z.infer<typeof InsertImageSchema>): Promise<{
+    documentId: string;
+    inlineObjectId: string | null | undefined;
+    index: number;
+    _apiMs: number;
+}>;

package/dist/tools/insert-image.js

@@ -0,0 +1,43 @@
+import { google } from 'googleapis';
+import { z } from 'zod';
+import { getAuthClient } from '../auth/google-auth.js';
+export const InsertImageSchema = z.object({
+    documentId: z.string().describe('The Google Doc document ID'),
+    uri: z.string().url().describe('Public URL of the image to insert'),
+    index: z.number().describe('Position in the document to insert the image'),
+    width: z.number().optional().describe('Image width in PT. If only width is set, height scales proportionally.'),
+    height: z.number().optional().describe('Image height in PT. If only height is set, width scales proportionally.'),
+});
+export async function insertImage(args) {
+    const auth = getAuthClient();
+    const docs = google.docs({ version: 'v1', auth });
+    const apiStart = performance.now();
+    const objectSize = {};
+    if (args.width !== undefined) {
+        objectSize.width = { magnitude: args.width, unit: 'PT' };
+    }
+    if (args.height !== undefined) {
+        objectSize.height = { magnitude: args.height, unit: 'PT' };
+    }
+    const request = {
+        insertInlineImage: {
+            location: { index: args.index },
+            uri: args.uri,
+        },
+    };
+    if (Object.keys(objectSize).length > 0) {
+        request.insertInlineImage.objectSize = objectSize;
+    }
+    const res = await docs.documents.batchUpdate({
+        documentId: args.documentId,
+        requestBody: { requests: [request] },
+    });
+    const inlineObjectId = res.data.replies?.[0]?.insertInlineImage?.objectId;
+    const apiMs = Math.round(performance.now() - apiStart);
+    return {
+        documentId: args.documentId,
+        inlineObjectId,
+        index: args.index,
+        _apiMs: apiMs,
+    };
+}

package/dist/tools/insert-link.d.ts

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+export declare const InsertLinkSchema: z.ZodObject<{
+    documentId: z.ZodString;
+    url: z.ZodString;
+    startIndex: z.ZodNumber;
+    endIndex: z.ZodNumber;
+}, z.core.$strip>;
+export declare function insertLink(args: z.infer<typeof InsertLinkSchema>): Promise<{
+    documentId: string;
+    url: string;
+    startIndex: number;
+    endIndex: number;
+    _apiMs: number;
+}>;

package/dist/tools/insert-link.js

@@ -0,0 +1,38 @@
+import { google } from 'googleapis';
+import { z } from 'zod';
+import { getAuthClient } from '../auth/google-auth.js';
+export const InsertLinkSchema = z.object({
+    documentId: z.string().describe('The Google Doc document ID'),
+    url: z.string().url().describe('The URL to link to'),
+    startIndex: z.number().describe('Start index of the text range to make into a link'),
+    endIndex: z.number().describe('End index of the text range to make into a link'),
+});
+export async function insertLink(args) {
+    const auth = getAuthClient();
+    const docs = google.docs({ version: 'v1', auth });
+    const apiStart = performance.now();
+    await docs.documents.batchUpdate({
+        documentId: args.documentId,
+        requestBody: {
+            requests: [
+                {
+                    updateTextStyle: {
+                        range: { startIndex: args.startIndex, endIndex: args.endIndex },
+                        textStyle: {
+                            link: { url: args.url },
+                        },
+                        fields: 'link',
+                    },
+                },
+            ],
+        },
+    });
+    const apiMs = Math.round(performance.now() - apiStart);
+    return {
+        documentId: args.documentId,
+        url: args.url,
+        startIndex: args.startIndex,
+        endIndex: args.endIndex,
+        _apiMs: apiMs,
+    };
+}

package/dist/tools/insert-page-break.d.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+export declare const InsertPageBreakSchema: z.ZodObject<{
+    documentId: z.ZodString;
+    index: z.ZodNumber;
+}, z.core.$strip>;
+export declare function insertPageBreak(args: z.infer<typeof InsertPageBreakSchema>): Promise<{
+    documentId: string;
+    index: number;
+    _apiMs: number;
+}>;

package/dist/tools/insert-page-break.js

@@ -0,0 +1,30 @@
+import { google } from 'googleapis';
+import { z } from 'zod';
+import { getAuthClient } from '../auth/google-auth.js';
+export const InsertPageBreakSchema = z.object({
+    documentId: z.string().describe('The Google Doc document ID'),
+    index: z.number().describe('Position in the document to insert the page break'),
+});
+export async function insertPageBreak(args) {
+    const auth = getAuthClient();
+    const docs = google.docs({ version: 'v1', auth });
+    const apiStart = performance.now();
+    await docs.documents.batchUpdate({
+        documentId: args.documentId,
+        requestBody: {
+            requests: [
+                {
+                    insertPageBreak: {
+                        location: { index: args.index },
+                    },
+                },
+            ],
+        },
+    });
+    const apiMs = Math.round(performance.now() - apiStart);
+    return {
+        documentId: args.documentId,
+        index: args.index,
+        _apiMs: apiMs,
+    };
+}

package/dist/tools/insert-table.d.ts

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+export declare const InsertTableSchema: z.ZodObject<{
+    documentId: z.ZodString;
+    rows: z.ZodNumber;
+    columns: z.ZodNumber;
+    index: z.ZodNumber;
+}, z.core.$strip>;
+export declare function insertTable(args: z.infer<typeof InsertTableSchema>): Promise<{
+    documentId: string;
+    rows: number;
+    columns: number;
+    index: number;
+    _apiMs: number;
+}>;

package/dist/tools/insert-table.js

@@ -0,0 +1,36 @@
+import { google } from 'googleapis';
+import { z } from 'zod';
+import { getAuthClient } from '../auth/google-auth.js';
+export const InsertTableSchema = z.object({
+    documentId: z.string().describe('The Google Doc document ID'),
+    rows: z.number().min(1).max(20).describe('Number of rows (1-20)'),
+    columns: z.number().min(1).max(20).describe('Number of columns (1-20)'),
+    index: z.number().describe('Position in the document to insert the table'),
+});
+export async function insertTable(args) {
+    const auth = getAuthClient();
+    const docs = google.docs({ version: 'v1', auth });
+    const apiStart = performance.now();
+    await docs.documents.batchUpdate({
+        documentId: args.documentId,
+        requestBody: {
+            requests: [
+                {
+                    insertTable: {
+                        location: { index: args.index },
+                        rows: args.rows,
+                        columns: args.columns,
+                    },
+                },
+            ],
+        },
+    });
+    const apiMs = Math.round(performance.now() - apiStart);
+    return {
+        documentId: args.documentId,
+        rows: args.rows,
+        columns: args.columns,
+        index: args.index,
+        _apiMs: apiMs,
+    };
+}

package/dist/tools/update-header-footer.d.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+export declare const UpdateHeaderFooterSchema: z.ZodObject<{
+    documentId: z.ZodString;
+    section: z.ZodEnum<{
+        header: "header";
+        footer: "footer";
+    }>;
+    content: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare function updateHeaderFooter(args: z.infer<typeof UpdateHeaderFooterSchema>): Promise<{
+    documentId: string;
+    section: "header" | "footer";
+    created: boolean;
+    contentInserted: boolean;
+    _apiMs: number;
+}>;

package/dist/tools/update-header-footer.js

@@ -0,0 +1,103 @@
+import { google } from 'googleapis';
+import { z } from 'zod';
+import { getAuthClient } from '../auth/google-auth.js';
+export const UpdateHeaderFooterSchema = z.object({
+    documentId: z.string().describe('The Google Doc document ID'),
+    section: z.enum(['header', 'footer']).describe('Which section to update: "header" or "footer"'),
+    content: z.string().optional().describe('Text content to insert. Replaces existing content. Use {{pageNumber}} to insert a page number field.'),
+});
+export async function updateHeaderFooter(args) {
+    const auth = getAuthClient();
+    const docs = google.docs({ version: 'v1', auth });
+    const apiStart = performance.now();
+    // Read document to check if header/footer exists
+    const doc = await docs.documents.get({ documentId: args.documentId });
+    const isHeader = args.section === 'header';
+    const existingId = isHeader
+        ? doc.data.headers && Object.keys(doc.data.headers)[0]
+        : doc.data.footers && Object.keys(doc.data.footers)[0];
+    const requests = [];
+    // Create header/footer if it doesn't exist
+    if (!existingId) {
+        requests.push(isHeader
+            ? { createHeader: { type: 'DEFAULT', sectionBreakLocation: { index: 0 } } }
+            : { createFooter: { type: 'DEFAULT', sectionBreakLocation: { index: 0 } } });
+        // Need to execute first to get the ID, then insert content
+        if (args.content) {
+            await docs.documents.batchUpdate({
+                documentId: args.documentId,
+                requestBody: { requests },
+            });
+            // Re-read to get the new ID
+            const updated = await docs.documents.get({ documentId: args.documentId });
+            const newId = isHeader
+                ? Object.keys(updated.data.headers || {})[0]
+                : Object.keys(updated.data.footers || {})[0];
+            if (newId && args.content) {
+                await insertContent(docs, args.documentId, newId, args.content, isHeader, updated.data);
+            }
+            const apiMs = Math.round(performance.now() - apiStart);
+            return {
+                documentId: args.documentId,
+                section: args.section,
+                created: true,
+                contentInserted: !!args.content,
+                _apiMs: apiMs,
+            };
+        }
+        await docs.documents.batchUpdate({
+            documentId: args.documentId,
+            requestBody: { requests },
+        });
+        const apiMs = Math.round(performance.now() - apiStart);
+        return {
+            documentId: args.documentId,
+            section: args.section,
+            created: true,
+            contentInserted: false,
+            _apiMs: apiMs,
+        };
+    }
+    // Header/footer exists — update content if provided
+    if (args.content) {
+        await insertContent(docs, args.documentId, existingId, args.content, isHeader, doc.data);
+    }
+    const apiMs = Math.round(performance.now() - apiStart);
+    return {
+        documentId: args.documentId,
+        section: args.section,
+        created: false,
+        contentInserted: !!args.content,
+        _apiMs: apiMs,
+    };
+}
+async function insertContent(docs, documentId, sectionId, content, isHeader, docData) {
+    const sectionData = isHeader
+        ? docData.headers?.[sectionId]
+        : docData.footers?.[sectionId];
+    if (!sectionData?.content)
+        return;
+    const sectionContent = sectionData.content;
+    const startIndex = sectionContent[0]?.startIndex || 0;
+    const endIndex = sectionContent[sectionContent.length - 1]?.endIndex || startIndex + 1;
+    const requests = [];
+    // Delete existing content
+    if (endIndex > startIndex + 1) {
+        requests.push({
+            deleteContentRange: {
+                range: { segmentId: sectionId, startIndex: startIndex, endIndex: endIndex - 1 },
+            },
+        });
+    }
+    // Insert new content
+    requests.push({
+        insertText: {
+            location: { segmentId: sectionId, index: startIndex },
+            text: content.replace('{{pageNumber}}', ''),
+        },
+    });
+    await docs.documents.batchUpdate({
+        documentId,
+        requestBody: { requests },
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdocs-mcp",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Open-source MCP server for Google Docs and Sheets. Self-hosted, local OAuth, no third-party token storage.",
   "type": "module",
   "main": "dist/index.js",