gdocs-mcp 0.3.0 → 0.4.1

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, search, and style 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, style, export, and collaborate on your Google Docs — with OAuth tokens that never leave your machine.
 
 **Open-source. Self-hosted. Your tokens never leave your machine.**
 
@@ -46,9 +46,9 @@ Restart Claude Desktop. Ask Claude: *"List my recent Google Docs"* to verify.
 claude mcp add gdocs -- npx gdocs-mcp
 ```
 
-## Tools (16)
+## Tools (28)
 
-### Google Docs
+### Google Docs — Read & Write
 
 | Tool | Description |
 |------|-------------|
@@ -63,11 +63,29 @@ claude mcp add gdocs -- npx gdocs-mcp
 | `update_document` | Raw batchUpdate with 35+ request types |
 | `unmerge_table_cells` | Unmerge previously merged table cells |
 
-### Google Sheets
+### Content Insertion
 
 | Tool | Description |
 |------|-------------|
-| `get_charts` | List all charts in a spreadsheet with IDs and specs |
+| `insert_image` | Insert an image from a URL with optional width/height sizing |
+| `insert_table` | Create a table with specified rows (1-20) and columns (1-20) |
+| `insert_page_break` | Insert a page break at a specific position |
+| `insert_link` | Add a hyperlink to an existing text range |
+
+### Document Management
+
+| Tool | Description |
+|------|-------------|
+| `export_document` | Export as PDF, DOCX, TXT, or HTML. Save to file or return base64 |
+| `copy_document` | Duplicate a doc with a new title. Great for templates |
+| `delete_document` | Move to trash. Requires exact title confirmation to prevent accidents |
+
+### Comments
+
+| Tool | Description |
+|------|-------------|
+| `get_comments` | List comments with author, content, resolved status, and replies |
+| `add_comment` | Add a comment anchored to specific text in the document |
 
 ### Style Presets
 
@@ -81,7 +99,28 @@ Define how your documents look once, apply everywhere.
 | `set_active_preset` | Set the default preset for new documents |
 | `delete_style_preset` | Delete a custom preset |
 
-#### Built-in Presets
+### Formatting
+
+| Tool | Description |
+|------|-------------|
+| `update_header_footer` | Create or update header/footer content and styling |
+| `format_list` | Apply bullet, numbered, or remove list formatting (6 glyph presets) |
+
+### Google Sheets
+
+| Tool | Description |
+|------|-------------|
+| `get_charts` | List all charts in a spreadsheet with IDs and specs |
+
+### Automation
+
+| Tool | Description |
+|------|-------------|
+| `execute_script` | Run a function in a deployed Google Apps Script project |
+
+## Style Presets
+
+### Built-in Presets
 
 | Preset | Font | Headings | Body |
 |--------|------|----------|------|
@@ -90,9 +129,9 @@ Define how your documents look once, apply everywhere.
 | `classic` | Georgia + Garamond | Dark blue, serif | 11pt, 1.4x spacing |
 | `minimal` | Roboto | Black, light weight | 10.5pt, 1.5x spacing |
 
-#### Extract + Apply Workflow
+### Extract + Apply Workflow
 
-The fastest way to use presets: point to a Google Doc that already looks the way you want.
+Point to a Google Doc that already looks the way you want:
 
 ```
 You: "Extract styles from my brand doc and save as 'brand'"
@@ -104,19 +143,41 @@ You: "Apply brand styles to this report"
 
 One-step capture, one-step apply. No JSON editing needed.
 
-#### Style Properties
+### 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)
+**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
 
-**Document:** page margins (top/bottom/left/right), page size (width/height)
+**Document:** page margins, page size
 
 **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`.
+Only properties you specify are applied. Omitted properties are left unchanged. Config stored at `~/.gdocs-mcp/styles.json`.
+
+## Upgrading to v0.4
+
+v0.4 expands the Drive scope from `drive.readonly` to `drive` (needed for export, copy, delete, and comments). You must re-authenticate:
+
+```bash
+npx gdocs-mcp auth
+```
+
+If you don't need the new tools and want to keep the old scope:
+
+```bash
+GDOCS_MCP_READONLY=1 npx gdocs-mcp
+```
+
+### Scope Justification
+
+| Scope | Tools |
+|-------|-------|
+| `documents` | read, create, replace, update, insert image/table/link/page break, style presets, header/footer, format list |
+| `spreadsheets.readonly` | get_charts |
+| `drive` | search, export, copy, delete, get/add comments |
 
 ## Limitations
 
@@ -126,8 +187,22 @@ These are Google Docs API limitations, not gdocs-mcp limitations:
 - **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
+- **Suggested edits** (propose mode) are not yet supported
+- **Comment replies** are not yet supported — only top-level comments
+- **Image URLs** are passed directly to Google's API — the MCP server does not fetch them
+
+## Performance Logging
+
+Every tool call logs latency to stderr:
+
+```
+[gdocs-mcp] read_document: 342ms (api: 298ms)
+[gdocs-mcp] apply_style_preset: 1247ms (api: 1102ms, 1593 requests)
+[gdocs-mcp] list_style_presets: 2ms (local)
+```
+
+Disable with `GDOCS_MCP_QUIET=1`.
 
 ## Security
 
@@ -136,16 +211,25 @@ These are Google Docs API limitations, not gdocs-mcp limitations:
 - 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
+- `delete_document` requires exact title match — not a boolean flag
 
 ## Configuration
 
-Credentials and tokens are stored in `~/.gdocs-mcp/` by default. Override credentials path with:
+Credentials and tokens stored in `~/.gdocs-mcp/` by default. Override with:
 
 ```bash
 GDOCS_CREDENTIALS=/path/to/credentials.json npx gdocs-mcp
 ```
 
-For faster startup, install globally instead of using npx:
+Environment variables:
+
+| Variable | Effect |
+|----------|--------|
+| `GDOCS_CREDENTIALS` | Override credentials.json path |
+| `GDOCS_MCP_READONLY` | Set to `1` to disable write tools (export, copy, delete, comments) |
+| `GDOCS_MCP_QUIET` | Set to `1` to disable performance logging |
+
+For faster startup, install globally:
 
 ```bash
 npm install -g gdocs-mcp

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

@@ -20,7 +20,16 @@ import { DeleteStylePresetSchema, deleteStylePreset } from './tools/delete-style
 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';
-const VERSION = '0.3.0';
+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',
@@ -106,6 +115,16 @@ registerTool('delete_style_preset', 'Delete a user-defined style preset. Cannot
 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);

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/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/extract-document-styles.d.ts

@@ -8,5 +8,7 @@ export declare function extractDocumentStyles(args: z.infer<typeof ExtractDocume
     documentId: string;
     title: string | null | undefined;
     preset: StylePreset;
+    warnings: string[] | undefined;
     savedAs: string | null;
+    _apiMs: number;
 }>;

package/dist/tools/extract-document-styles.js

@@ -10,11 +10,23 @@ export const ExtractDocumentStylesSchema = z.object({
 export async function extractDocumentStyles(args) {
     const auth = getAuthClient();
     const docs = google.docs({ version: 'v1', auth });
+    const apiStart = performance.now();
     const doc = await docs.documents.get({ documentId: args.documentId });
+    const bodyContent = doc.data.body?.content || [];
+    // Step 1: Extract named style definitions (baseline)
+    const namedStyleDefs = extractNamedStyleDefinitions(doc.data.namedStyles);
+    // Step 2: Extract actual rendered styles from paragraphs (majority vote)
+    const renderedStyles = extractRenderedStyles(bodyContent);
+    // Step 3: Merge — rendered values take priority, collect warnings
+    const warnings = [];
+    const mergedStyles = mergeStyles(namedStyleDefs, renderedStyles, warnings);
+    // Step 4: Propagate inherited properties from NORMAL_TEXT to headings
+    propagateInheritedProperties(mergedStyles);
+    const apiMs = Math.round(performance.now() - apiStart);
     const preset = {
         document: extractDocumentStyle(doc.data.documentStyle),
-        styles: extractNamedStyles(doc.data.namedStyles),
-        table: extractTableStyles(doc.data.body?.content || []),
+        styles: mergedStyles,
+        table: extractTableStyles(bodyContent),
     };
     if (args.saveAs) {
         savePreset(args.saveAs, preset);
@@ -23,7 +35,9 @@ export async function extractDocumentStyles(args) {
         documentId: args.documentId,
         title: doc.data.title,
         preset,
+        warnings: warnings.length > 0 ? warnings : undefined,
         savedAs: args.saveAs || null,
+        _apiMs: apiMs,
     };
 }
 function extractDocumentStyle(docStyle) {
@@ -42,7 +56,51 @@ function extractDocumentStyle(docStyle) {
         config.pageHeight = docStyle.pageSize.height.magnitude;
     return config;
 }
-function extractNamedStyles(namedStyles) {
+function extractStyleFromRaw(ts, ps) {
+    const config = {};
+    if (ts.weightedFontFamily?.fontFamily)
+        config.fontFamily = ts.weightedFontFamily.fontFamily;
+    if (ts.fontSize?.magnitude !== undefined)
+        config.fontSize = ts.fontSize.magnitude;
+    if (ts.bold !== undefined)
+        config.bold = ts.bold;
+    if (ts.italic !== undefined)
+        config.italic = ts.italic;
+    if (ts.underline !== undefined)
+        config.underline = ts.underline;
+    if (ts.strikethrough !== undefined)
+        config.strikethrough = ts.strikethrough;
+    if (ts.smallCaps !== undefined)
+        config.smallCaps = ts.smallCaps;
+    if (ts.foregroundColor?.color?.rgbColor)
+        config.color = rgbToHex(ts.foregroundColor.color.rgbColor);
+    if (ts.backgroundColor?.color?.rgbColor)
+        config.backgroundColor = rgbToHex(ts.backgroundColor.color.rgbColor);
+    if (ts.baselineOffset)
+        config.baselineOffset = ts.baselineOffset;
+    if (ps.alignment)
+        config.alignment = ps.alignment;
+    if (ps.lineSpacing !== undefined)
+        config.lineSpacing = ps.lineSpacing;
+    if (ps.spaceAbove?.magnitude !== undefined)
+        config.spaceAbove = ps.spaceAbove.magnitude;
+    if (ps.spaceBelow?.magnitude !== undefined)
+        config.spaceBelow = ps.spaceBelow.magnitude;
+    if (ps.indentFirstLine?.magnitude !== undefined)
+        config.indentFirstLine = ps.indentFirstLine.magnitude;
+    if (ps.indentStart?.magnitude !== undefined)
+        config.indentStart = ps.indentStart.magnitude;
+    if (ps.indentEnd?.magnitude !== undefined)
+        config.indentEnd = ps.indentEnd.magnitude;
+    if (ps.keepLinesTogether !== undefined)
+        config.keepLinesTogether = ps.keepLinesTogether;
+    if (ps.keepWithNext !== undefined)
+        config.keepWithNext = ps.keepWithNext;
+    if (ps.direction)
+        config.direction = ps.direction;
+    return config;
+}
+function extractNamedStyleDefinitions(namedStyles) {
     const result = {};
     if (!namedStyles?.styles)
         return result;
@@ -50,59 +108,122 @@ function extractNamedStyles(namedStyles) {
         const type = style.namedStyleType;
         if (!VALID_NAMED_STYLE_TYPES.includes(type))
             continue;
-        const config = {};
-        const ts = style.textStyle || {};
-        const ps = style.paragraphStyle || {};
-        // Text style
-        if (ts.weightedFontFamily?.fontFamily)
-            config.fontFamily = ts.weightedFontFamily.fontFamily;
-        if (ts.fontSize?.magnitude !== undefined)
-            config.fontSize = ts.fontSize.magnitude;
-        if (ts.bold !== undefined)
-            config.bold = ts.bold;
-        if (ts.italic !== undefined)
-            config.italic = ts.italic;
-        if (ts.underline !== undefined)
-            config.underline = ts.underline;
-        if (ts.strikethrough !== undefined)
-            config.strikethrough = ts.strikethrough;
-        if (ts.smallCaps !== undefined)
-            config.smallCaps = ts.smallCaps;
-        if (ts.foregroundColor?.color?.rgbColor)
-            config.color = rgbToHex(ts.foregroundColor.color.rgbColor);
-        if (ts.backgroundColor?.color?.rgbColor)
-            config.backgroundColor = rgbToHex(ts.backgroundColor.color.rgbColor);
-        if (ts.baselineOffset)
-            config.baselineOffset = ts.baselineOffset;
-        // Paragraph style
-        if (ps.alignment)
-            config.alignment = ps.alignment;
-        if (ps.lineSpacing !== undefined)
-            config.lineSpacing = ps.lineSpacing;
-        if (ps.spaceAbove?.magnitude !== undefined)
-            config.spaceAbove = ps.spaceAbove.magnitude;
-        if (ps.spaceBelow?.magnitude !== undefined)
-            config.spaceBelow = ps.spaceBelow.magnitude;
-        if (ps.indentFirstLine?.magnitude !== undefined)
-            config.indentFirstLine = ps.indentFirstLine.magnitude;
-        if (ps.indentStart?.magnitude !== undefined)
-            config.indentStart = ps.indentStart.magnitude;
-        if (ps.indentEnd?.magnitude !== undefined)
-            config.indentEnd = ps.indentEnd.magnitude;
-        if (ps.keepLinesTogether !== undefined)
-            config.keepLinesTogether = ps.keepLinesTogether;
-        if (ps.keepWithNext !== undefined)
-            config.keepWithNext = ps.keepWithNext;
-        if (ps.direction)
-            config.direction = ps.direction;
+        const config = extractStyleFromRaw(style.textStyle || {}, style.paragraphStyle || {});
         if (Object.keys(config).length > 0) {
             result[type] = config;
         }
     }
     return result;
 }
+// Majority vote: returns the most common value for a property across samples
+function majorityVote(values) {
+    const counts = new Map();
+    for (const v of values) {
+        if (v === undefined)
+            continue;
+        const key = JSON.stringify(v);
+        const existing = counts.get(key);
+        if (existing) {
+            existing.count++;
+        }
+        else {
+            counts.set(key, { value: v, count: 1 });
+        }
+    }
+    let winner = undefined;
+    let maxCount = 0;
+    for (const { value, count } of counts.values()) {
+        if (count > maxCount) {
+            maxCount = count;
+            winner = value;
+        }
+    }
+    return winner;
+}
+function extractRenderedStyles(content) {
+    const result = {};
+    // Collect up to 10 paragraphs per style type
+    const samplesByType = {};
+    for (const element of content) {
+        if (!element.paragraph)
+            continue;
+        const styleType = element.paragraph.paragraphStyle?.namedStyleType;
+        if (!styleType || !VALID_NAMED_STYLE_TYPES.includes(styleType))
+            continue;
+        const text = element.paragraph.elements
+            ?.map((el) => el.textRun?.content || '').join('').trim();
+        if (!text)
+            continue;
+        if (!samplesByType[styleType])
+            samplesByType[styleType] = [];
+        if (samplesByType[styleType].length >= 10)
+            continue;
+        // Read paragraph-level text style from first text run
+        const firstRunTextStyle = element.paragraph.elements?.[0]?.textRun?.textStyle || {};
+        const paragraphStyle = element.paragraph.paragraphStyle || {};
+        const config = extractStyleFromRaw(firstRunTextStyle, paragraphStyle);
+        samplesByType[styleType].push(config);
+    }
+    // Majority vote per property across sampled paragraphs
+    const allProperties = [
+        'fontFamily', 'fontSize', 'bold', 'italic', 'underline', 'strikethrough',
+        'smallCaps', 'color', 'backgroundColor', 'baselineOffset',
+        'alignment', 'lineSpacing', 'spaceAbove', 'spaceBelow',
+        'indentFirstLine', 'indentStart', 'indentEnd',
+        'keepLinesTogether', 'keepWithNext', 'direction',
+    ];
+    for (const [styleType, samples] of Object.entries(samplesByType)) {
+        const merged = {};
+        for (const prop of allProperties) {
+            const values = samples.map(s => s[prop]);
+            const winner = majorityVote(values);
+            if (winner !== undefined) {
+                ;
+                merged[prop] = winner;
+            }
+        }
+        if (Object.keys(merged).length > 0) {
+            result[styleType] = merged;
+        }
+    }
+    return result;
+}
+function mergeStyles(definitions, rendered, warnings) {
+    const merged = {};
+    const allTypes = new Set([...Object.keys(definitions), ...Object.keys(rendered)]);
+    for (const type of allTypes) {
+        const def = definitions[type] || {};
+        const ren = rendered[type] || {};
+        // Check for differences and log warnings
+        for (const [key, renValue] of Object.entries(ren)) {
+            const defValue = def[key];
+            if (defValue !== undefined && renValue !== undefined && JSON.stringify(defValue) !== JSON.stringify(renValue)) {
+                warnings.push(`${type}.${key}: definition says ${JSON.stringify(defValue)}, rendered shows ${JSON.stringify(renValue)} (using rendered)`);
+            }
+        }
+        // Rendered values override definitions
+        merged[type] = { ...def, ...ren };
+    }
+    return merged;
+}
+// Propagate fontFamily, color, bold, italic from NORMAL_TEXT to headings that don't specify them
+function propagateInheritedProperties(styles) {
+    const normalText = styles['NORMAL_TEXT'];
+    if (!normalText)
+        return;
+    const propertiesToPropagate = ['fontFamily', 'color', 'bold', 'italic'];
+    for (const [type, config] of Object.entries(styles)) {
+        if (type === 'NORMAL_TEXT')
+            continue;
+        for (const prop of propertiesToPropagate) {
+            if (config[prop] === undefined && normalText[prop] !== undefined) {
+                ;
+                config[prop] = normalText[prop];
+            }
+        }
+    }
+}
 function extractTableStyles(content) {
-    // Find first table and extract its styling as the template
     for (const element of content) {
         if (!element.table)
             continue;
@@ -127,7 +248,17 @@ function extractTableStyles(content) {
                 config.cellPadding = cs.paddingTop.magnitude;
             }
         }
-        // Check second row for alternating background
+        // Check header text style
+        const headerTextRun = firstRow.tableCells?.[0]?.content?.[0]?.paragraph?.elements?.[0]?.textRun;
+        if (headerTextRun?.textStyle) {
+            const hts = headerTextRun.textStyle;
+            if (hts.bold !== undefined)
+                config.headerBold = hts.bold;
+            if (hts.foregroundColor?.color?.rgbColor) {
+                config.headerTextColor = rgbToHex(hts.foregroundColor.color.rgbColor);
+            }
+        }
+        // Check third row for alternating background
         if (table.tableRows?.length > 2) {
             const thirdRow = table.tableRows[2];
             const thirdCell = thirdRow?.tableCells?.[0];

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdocs-mcp",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "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",