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

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