gdocs-mcp 0.2.0 → 0.3.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/index.js

@@ -17,9 +17,14 @@ 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';
+const VERSION = '0.3.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 +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,
@@ -70,15 +97,19 @@ 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);
 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/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/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/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.3.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",