gdocs-mcp 0.1.0 → 0.3.0

package/README.md

@@ -1,8 +1,8 @@
 # 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.
 
-**Like Composio, but open-source and self-hosted.**
+**Open-source. Self-hosted. Your tokens never leave your machine.**
 
 ## Quick Start
 
@@ -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/index.js

@@ -12,9 +12,19 @@ import { UpdateDocumentStyleSchema, updateDocumentStyle } from './tools/update-d
 import { UpdateDocumentSchema, updateDocument } from './tools/update-document.js';
 import { UnmergeTableCellsSchema, unmergeTableCells } from './tools/unmerge-table-cells.js';
 import { GetChartsSchema, getCharts } from './tools/get-charts.js';
+import { ApplyStylePresetSchema, applyStylePreset } from './tools/apply-style-preset.js';
+import { ExtractDocumentStylesSchema, extractDocumentStyles } from './tools/extract-document-styles.js';
+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';
+const VERSION = '0.3.0';
+const QUIET = process.env.GDOCS_MCP_QUIET === '1';
 const server = new McpServer({
     name: 'gdocs-mcp',
-    version: '0.1.0',
+    version: VERSION,
 });
 function formatError(err) {
     if (err instanceof Error) {
@@ -31,19 +41,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,
@@ -64,10 +96,20 @@ registerTool('update_document', 'Apply batch updates to a document (insertText,
 registerTool('unmerge_table_cells', 'Unmerge previously merged cells in a document table', UnmergeTableCellsSchema, unmergeTableCells);
 // 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. 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);
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    console.error('gdocs-mcp v0.1.0 started');
+    console.error(`gdocs-mcp v${VERSION} started`);
 }
 main().catch((err) => {
     console.error('Failed to start gdocs-mcp:', err);

package/dist/presets/built-in.d.ts

@@ -0,0 +1,2 @@
+import type { StylePreset } from './types.js';
+export declare const BUILT_IN_PRESETS: Record<string, StylePreset>;

package/dist/presets/built-in.js

@@ -0,0 +1,270 @@
+export const BUILT_IN_PRESETS = {
+    clean: {
+        document: {
+            marginTop: 72,
+            marginBottom: 72,
+            marginLeft: 72,
+            marginRight: 72,
+        },
+        styles: {
+            TITLE: {
+                fontFamily: 'Inter',
+                fontSize: 28,
+                bold: true,
+                color: '#1a1a2e',
+                spaceBelow: 4,
+            },
+            SUBTITLE: {
+                fontFamily: 'Inter',
+                fontSize: 13,
+                italic: true,
+                color: '#666666',
+                spaceBelow: 16,
+            },
+            HEADING_1: {
+                fontFamily: 'Inter',
+                fontSize: 22,
+                bold: true,
+                color: '#1a1a2e',
+                spaceAbove: 24,
+                spaceBelow: 8,
+                keepWithNext: true,
+            },
+            HEADING_2: {
+                fontFamily: 'Inter',
+                fontSize: 16,
+                bold: true,
+                color: '#333333',
+                spaceAbove: 18,
+                spaceBelow: 6,
+                keepWithNext: true,
+            },
+            HEADING_3: {
+                fontFamily: 'Inter',
+                fontSize: 13,
+                bold: true,
+                color: '#555555',
+                spaceAbove: 14,
+                spaceBelow: 4,
+                keepWithNext: true,
+            },
+            NORMAL_TEXT: {
+                fontFamily: 'Inter',
+                fontSize: 11,
+                color: '#1a1a1a',
+                lineSpacing: 150,
+                spaceBelow: 6,
+            },
+        },
+        table: {
+            headerBackground: '#1a1a2e',
+            headerTextColor: '#ffffff',
+            headerBold: true,
+            borderColor: '#dddddd',
+            borderWidth: 0.5,
+            alternateRowBackground: '#f9f9f9',
+            cellPadding: 5,
+        },
+    },
+    corporate: {
+        document: {
+            marginTop: 72,
+            marginBottom: 72,
+            marginLeft: 72,
+            marginRight: 72,
+        },
+        styles: {
+            TITLE: {
+                fontFamily: 'Arial',
+                fontSize: 24,
+                bold: true,
+                color: '#333333',
+                spaceBelow: 4,
+            },
+            SUBTITLE: {
+                fontFamily: 'Arial',
+                fontSize: 12,
+                italic: true,
+                color: '#666666',
+                spaceBelow: 14,
+            },
+            HEADING_1: {
+                fontFamily: 'Arial',
+                fontSize: 18,
+                bold: true,
+                color: '#333333',
+                spaceAbove: 20,
+                spaceBelow: 6,
+                keepWithNext: true,
+            },
+            HEADING_2: {
+                fontFamily: 'Arial',
+                fontSize: 14,
+                bold: true,
+                color: '#444444',
+                spaceAbove: 16,
+                spaceBelow: 4,
+                keepWithNext: true,
+            },
+            HEADING_3: {
+                fontFamily: 'Arial',
+                fontSize: 12,
+                bold: true,
+                color: '#555555',
+                spaceAbove: 12,
+                spaceBelow: 4,
+                keepWithNext: true,
+            },
+            NORMAL_TEXT: {
+                fontFamily: 'Arial',
+                fontSize: 11,
+                color: '#333333',
+                lineSpacing: 140,
+                spaceBelow: 4,
+            },
+        },
+        table: {
+            headerBackground: '#4472C4',
+            headerTextColor: '#ffffff',
+            headerBold: true,
+            borderColor: '#cccccc',
+            borderWidth: 0.5,
+            alternateRowBackground: '#f2f2f2',
+            cellPadding: 5,
+        },
+    },
+    classic: {
+        document: {
+            marginTop: 72,
+            marginBottom: 72,
+            marginLeft: 72,
+            marginRight: 72,
+        },
+        styles: {
+            TITLE: {
+                fontFamily: 'Georgia',
+                fontSize: 26,
+                bold: true,
+                color: '#1a3c6e',
+                spaceBelow: 4,
+            },
+            SUBTITLE: {
+                fontFamily: 'Garamond',
+                fontSize: 13,
+                italic: true,
+                color: '#555555',
+                spaceBelow: 16,
+            },
+            HEADING_1: {
+                fontFamily: 'Georgia',
+                fontSize: 20,
+                bold: true,
+                color: '#1a3c6e',
+                spaceAbove: 22,
+                spaceBelow: 8,
+                keepWithNext: true,
+            },
+            HEADING_2: {
+                fontFamily: 'Georgia',
+                fontSize: 15,
+                bold: true,
+                color: '#2a5a8e',
+                spaceAbove: 18,
+                spaceBelow: 6,
+                keepWithNext: true,
+            },
+            HEADING_3: {
+                fontFamily: 'Georgia',
+                fontSize: 12,
+                bold: true,
+                italic: true,
+                color: '#3a6a9e',
+                spaceAbove: 14,
+                spaceBelow: 4,
+                keepWithNext: true,
+            },
+            NORMAL_TEXT: {
+                fontFamily: 'Garamond',
+                fontSize: 11,
+                color: '#222222',
+                lineSpacing: 140,
+                spaceBelow: 6,
+            },
+        },
+        table: {
+            headerBackground: '#1a3c6e',
+            headerTextColor: '#ffffff',
+            headerBold: true,
+            borderColor: '#999999',
+            borderWidth: 0.75,
+            alternateRowBackground: '#eef3f8',
+            cellPadding: 5,
+        },
+    },
+    minimal: {
+        document: {
+            marginTop: 72,
+            marginBottom: 72,
+            marginLeft: 72,
+            marginRight: 72,
+        },
+        styles: {
+            TITLE: {
+                fontFamily: 'Roboto',
+                fontSize: 24,
+                bold: false,
+                color: '#000000',
+                spaceBelow: 4,
+            },
+            SUBTITLE: {
+                fontFamily: 'Roboto',
+                fontSize: 12,
+                color: '#888888',
+                spaceBelow: 16,
+            },
+            HEADING_1: {
+                fontFamily: 'Roboto',
+                fontSize: 18,
+                bold: false,
+                color: '#000000',
+                spaceAbove: 24,
+                spaceBelow: 8,
+                keepWithNext: true,
+            },
+            HEADING_2: {
+                fontFamily: 'Roboto',
+                fontSize: 14,
+                bold: true,
+                color: '#333333',
+                spaceAbove: 18,
+                spaceBelow: 6,
+                keepWithNext: true,
+            },
+            HEADING_3: {
+                fontFamily: 'Roboto',
+                fontSize: 11,
+                bold: true,
+                color: '#555555',
+                spaceAbove: 14,
+                spaceBelow: 4,
+                keepWithNext: true,
+            },
+            NORMAL_TEXT: {
+                fontFamily: 'Roboto',
+                fontSize: 10.5,
+                color: '#222222',
+                lineSpacing: 150,
+                spaceBelow: 6,
+            },
+        },
+        table: {
+            headerBackground: '#f5f5f5',
+            headerTextColor: '#000000',
+            headerBold: true,
+            borderColor: '#e0e0e0',
+            borderWidth: 0.5,
+            alternateRowBackground: '#fafafa',
+            cellPadding: 5,
+        },
+    },
+};

package/dist/presets/config.d.ts

@@ -0,0 +1,14 @@
+import type { StylePreset } from './types.js';
+export declare function getPreset(presetName?: string): {
+    name: string;
+    preset: StylePreset;
+};
+export declare function listAllPresets(): Record<string, {
+    source: 'built-in' | 'user';
+    preset: StylePreset;
+}>;
+export declare function listAllPresetNames(): string[];
+export declare function savePreset(name: string, preset: StylePreset): void;
+export declare function deletePreset(name: string): void;
+export declare function setActivePreset(name: string): void;
+export declare function getActivePresetName(): string | undefined;

package/dist/presets/config.js

@@ -0,0 +1,87 @@
+import fs from 'fs';
+import path from 'path';
+import { BUILT_IN_PRESETS } from './built-in.js';
+const CONFIG_DIR = path.join(process.env.HOME || '~', '.gdocs-mcp');
+const STYLES_PATH = path.join(CONFIG_DIR, 'styles.json');
+const BUILT_IN_NAMES = new Set(Object.keys(BUILT_IN_PRESETS));
+function readConfig() {
+    if (!fs.existsSync(STYLES_PATH)) {
+        return { presets: {} };
+    }
+    return JSON.parse(fs.readFileSync(STYLES_PATH, 'utf8'));
+}
+function writeConfig(config) {
+    if (!fs.existsSync(CONFIG_DIR)) {
+        fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+    }
+    fs.writeFileSync(STYLES_PATH, JSON.stringify(config, null, 2));
+    fs.chmodSync(STYLES_PATH, 0o600);
+}
+export function getPreset(presetName) {
+    const config = readConfig();
+    const name = presetName || config.activePreset;
+    if (!name) {
+        throw new Error('No preset specified and no activePreset set. Run set_active_preset or pass a presetName.');
+    }
+    // User presets override built-ins
+    const preset = config.presets[name] || BUILT_IN_PRESETS[name];
+    if (!preset) {
+        const available = listAllPresetNames();
+        throw new Error(`Preset "${name}" not found. Available: ${available.join(', ')}`);
+    }
+    return { name, preset };
+}
+export function listAllPresets() {
+    const config = readConfig();
+    const result = {};
+    for (const [name, preset] of Object.entries(BUILT_IN_PRESETS)) {
+        result[name] = { source: 'built-in', preset };
+    }
+    // User presets override built-ins
+    for (const [name, preset] of Object.entries(config.presets)) {
+        result[name] = { source: BUILT_IN_NAMES.has(name) ? 'built-in' : 'user', preset };
+    }
+    return result;
+}
+export function listAllPresetNames() {
+    return Object.keys(listAllPresets());
+}
+export function savePreset(name, preset) {
+    const config = readConfig();
+    config.presets = { ...config.presets, [name]: preset };
+    writeConfig(config);
+}
+export function deletePreset(name) {
+    if (BUILT_IN_NAMES.has(name)) {
+        const config = readConfig();
+        if (!config.presets[name]) {
+            throw new Error(`Cannot delete built-in preset "${name}". You can override it by creating a preset with the same name.`);
+        }
+        // User override of built-in — remove the override, built-in remains
+        const { [name]: _, ...rest } = config.presets;
+        writeConfig({ ...config, presets: rest });
+        return;
+    }
+    const config = readConfig();
+    if (!config.presets[name]) {
+        throw new Error(`Preset "${name}" not found.`);
+    }
+    const { [name]: _, ...rest } = config.presets;
+    const updated = { ...config, presets: rest };
+    // Clear activePreset if it was the deleted one
+    if (config.activePreset === name) {
+        delete updated.activePreset;
+    }
+    writeConfig(updated);
+}
+export function setActivePreset(name) {
+    const allNames = listAllPresetNames();
+    if (!allNames.includes(name)) {
+        throw new Error(`Preset "${name}" not found. Available: ${allNames.join(', ')}`);
+    }
+    const config = readConfig();
+    writeConfig({ ...config, activePreset: name });
+}
+export function getActivePresetName() {
+    return readConfig().activePreset;
+}

package/dist/presets/converter.d.ts

@@ -0,0 +1,12 @@
+import type { NamedStyleConfig, DocumentStyleConfig, TableStyleConfig } from './types.js';
+export declare function buildNamedStyleRequest(styles: Record<string, NamedStyleConfig>): {
+    updateNamedStyles: any;
+};
+export declare function buildDocumentStyleRequest(config: DocumentStyleConfig): {
+    updateDocumentStyle: any;
+};
+export declare function buildTableStyleRequests(tableConfig: TableStyleConfig, tables: Array<{
+    startIndex: number;
+    rows: number;
+    cols: number;
+}>): any[];