gdocs-mcp 0.5.1 → 0.5.2

package/dist/index.js

@@ -36,7 +36,8 @@ import { InsertTableRowSchema, insertTableRow, DeleteTableRowSchema, deleteTable
 import { DeleteHeaderFooterSchema, deleteHeaderFooter } from './tools/delete-header-footer.js';
 import { CreateFootnoteSchema, createFootnote } from './tools/create-footnote.js';
 import { WriteTableSchema, writeTable } from './tools/write-table.js';
-const VERSION = '0.5.0';
+import { UpdateTableStyleSchema, updateTableStyle } from './tools/update-table-style.js';
+const VERSION = '0.5.2';
 const QUIET = process.env.GDOCS_MCP_QUIET === '1';
 const server = new McpServer({
     name: 'gdocs-mcp',
@@ -45,7 +46,7 @@ const server = new McpServer({
 function formatError(err) {
     if (err instanceof Error) {
         const message = err.message;
-        if (message.includes('not found') || message.includes('404')) {
+        if (message.includes('404') || (message.includes('not found') && !message.includes('Preset') && !message.includes('preset'))) {
             return 'Document not found. Check the document ID and ensure it is shared with your account.';
         }
         if (message.includes('UNAUTHENTICATED') || message.includes('invalid_grant')) {
@@ -135,7 +136,7 @@ registerTool('add_comment', 'Add a comment anchored to specific text in the docu
 // v0.4.2 structure tool
 registerTool('read_document_structure', 'Return the structural outline of a Google Doc: paragraphs with indices, heading levels, text previews, tables with row/col counts, list metadata. Lightweight map for targeted edits.', ReadDocumentStructureSchema, readDocumentStructure);
 // v0.5 gap closure tools
-registerTool('insert_text', 'Insert text at a specific index or append to end of document.', InsertTextSchema, insertText);
+registerTool('insert_text', 'Insert text at a specific index or append to end of document. Resets formatting to NORMAL_TEXT defaults by default. Pass resetFormatting: false to inherit formatting from the insertion point.', InsertTextSchema, insertText);
 registerTool('delete_content_range', 'Delete a range of content. Supports preview mode (dry-run) to see what would be deleted before executing.', DeleteContentRangeSchema, deleteContentRange);
 registerTool('insert_table_row', 'Insert a row into an existing table. Zero-indexed.', InsertTableRowSchema, insertTableRow);
 registerTool('delete_table_row', 'Delete a row from an existing table. Zero-indexed.', DeleteTableRowSchema, deleteTableRow);
@@ -145,6 +146,7 @@ registerTool('delete_header_footer', 'Delete a header or footer. Supports previe
 registerTool('create_footnote', 'Create a footnote at a specific position.', CreateFootnoteSchema, createFootnote);
 // v0.5 differentiator
 registerTool('write_table', 'Create a fully populated, styled table in one call. Inserts table, fills cells, applies header styling, sets content-aware column widths. Not safe for concurrent editing.', WriteTableSchema, writeTable);
+registerTool('update_table_style', 'Identify and style a table by context (nearby heading, position, or dimensions) instead of raw index. Supports preset application and individual style overrides. Returns table metadata when no styling params are provided.', UpdateTableStyleSchema, updateTableStyle);
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/dist/presets/converter.js

@@ -1,14 +1,4 @@
-function hexToRgb(hex) {
-    const h = hex.replace('#', '');
-    return {
-        red: parseInt(h.substring(0, 2), 16) / 255,
-        green: parseInt(h.substring(2, 4), 16) / 255,
-        blue: parseInt(h.substring(4, 6), 16) / 255,
-    };
-}
-function toColor(hex) {
-    return { color: { rgbColor: hexToRgb(hex) } };
-}
+import { toColor } from '../utils/color.js';
 function toDimension(magnitude, unit = 'PT') {
     return { magnitude, unit };
 }

package/dist/tools/apply-style-preset.js

@@ -3,6 +3,7 @@ import { z } from 'zod';
 import { getAuthClient } from '../auth/google-auth.js';
 import { getPreset } from '../presets/config.js';
 import { buildDocumentStyleRequest, buildTableStyleRequests } from '../presets/converter.js';
+import { toColor } from '../utils/color.js';
 export const ApplyStylePresetSchema = z.object({
     documentId: z.string().describe('The Google Doc document ID'),
     presetName: z.string().optional().describe('Name of the preset to apply. If omitted, uses the active preset from styles.json.'),
@@ -23,9 +24,20 @@ export async function applyStylePreset(args) {
             if (paragraphs.length === 0)
                 continue;
             for (const para of paragraphs) {
-                const textStyleReq = buildTextStyleRequest(config, para.startIndex, para.endIndex);
-                if (textStyleReq)
-                    requests.push(textStyleReq);
+                if (para.inTable && para.textRuns && para.textRuns.length > 0) {
+                    for (const run of para.textRuns) {
+                        if (run.startIndex >= run.endIndex)
+                            continue;
+                        const textStyleReq = buildTextStyleRequest(config, run.startIndex, run.endIndex);
+                        if (textStyleReq)
+                            requests.push(textStyleReq);
+                    }
+                }
+                else {
+                    const textStyleReq = buildTextStyleRequest(config, para.startIndex, para.endIndex);
+                    if (textStyleReq)
+                        requests.push(textStyleReq);
+                }
                 const paraStyleReq = buildParagraphStyleRequest(config, para.startIndex, para.endIndex);
                 if (paraStyleReq)
                     requests.push(paraStyleReq);
@@ -58,17 +70,6 @@ export async function applyStylePreset(args) {
         requestCount: requests.length,
     };
 }
-function hexToRgb(hex) {
-    const h = hex.replace('#', '');
-    return {
-        red: parseInt(h.substring(0, 2), 16) / 255,
-        green: parseInt(h.substring(2, 4), 16) / 255,
-        blue: parseInt(h.substring(4, 6), 16) / 255,
-    };
-}
-function toColor(hex) {
-    return { color: { rgbColor: hexToRgb(hex) } };
-}
 function toDimension(magnitude) {
     return { magnitude, unit: 'PT' };
 }
@@ -180,16 +181,41 @@ function buildParagraphStyleRequest(config, startIndex, endIndex) {
 }
 function groupParagraphsByStyle(content) {
     const groups = {};
-    for (const element of content) {
-        if (!element.paragraph)
-            continue;
-        const styleType = element.paragraph.paragraphStyle?.namedStyleType || 'NORMAL_TEXT';
+    const addParagraph = (paragraph, startIndex, endIndex, inTable) => {
+        const styleType = paragraph.paragraphStyle?.namedStyleType || 'NORMAL_TEXT';
         if (!groups[styleType])
             groups[styleType] = [];
-        groups[styleType].push({
-            startIndex: element.startIndex || 0,
-            endIndex: element.endIndex || 0,
-        });
+        const range = {
+            startIndex: startIndex || 0,
+            endIndex: endIndex || 0,
+            inTable,
+        };
+        if (inTable) {
+            const textRuns = [];
+            for (const el of paragraph.elements || []) {
+                if (el.textRun && el.startIndex < el.endIndex) {
+                    textRuns.push({ startIndex: el.startIndex, endIndex: el.endIndex });
+                }
+            }
+            range.textRuns = textRuns;
+        }
+        groups[styleType].push(range);
+    };
+    for (const element of content) {
+        if (element.paragraph) {
+            addParagraph(element.paragraph, element.startIndex, element.endIndex, false);
+        }
+        if (element.table) {
+            for (const row of element.table.tableRows || []) {
+                for (const cell of row.tableCells || []) {
+                    for (const cellElement of cell.content || []) {
+                        if (cellElement.paragraph) {
+                            addParagraph(cellElement.paragraph, cellElement.startIndex, cellElement.endIndex, true);
+                        }
+                    }
+                }
+            }
+        }
     }
     return groups;
 }

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

@@ -4,6 +4,14 @@ export declare const InsertTextSchema: z.ZodObject<{
     text: z.ZodString;
     index: z.ZodOptional<z.ZodNumber>;
     appendToEnd: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    resetFormatting: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    style: z.ZodOptional<z.ZodObject<{
+        fontFamily: z.ZodOptional<z.ZodString>;
+        fontSize: z.ZodOptional<z.ZodNumber>;
+        bold: z.ZodOptional<z.ZodBoolean>;
+        italic: z.ZodOptional<z.ZodBoolean>;
+        color: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare function insertText(args: z.infer<typeof InsertTextSchema>): Promise<{
     documentId: string;

package/dist/tools/insert-text.js

@@ -1,11 +1,21 @@
 import { google } from 'googleapis';
 import { z } from 'zod';
 import { getAuthClient } from '../auth/google-auth.js';
+import { hexToRgb } from '../utils/color.js';
+import { getDefaultTextStyle } from '../utils/defaults.js';
 export const InsertTextSchema = z.object({
     documentId: z.string().describe('The Google Doc document ID'),
     text: z.string().describe('Text to insert'),
     index: z.number().optional().describe('Position to insert at. Required unless appendToEnd is true.'),
     appendToEnd: z.boolean().optional().default(false).describe('Append text to the end of the document body. No need to know the last index.'),
+    resetFormatting: z.boolean().optional().default(true).describe('Reset text formatting to NORMAL_TEXT defaults after insertion. Set to false to inherit formatting from the insertion point.'),
+    style: z.object({
+        fontFamily: z.string().optional(),
+        fontSize: z.number().optional(),
+        bold: z.boolean().optional(),
+        italic: z.boolean().optional(),
+        color: z.string().optional(),
+    }).optional().describe('Explicit style overrides. Each property overrides the preset default. Only applies when resetFormatting is true.'),
 });
 export async function insertText(args) {
     const auth = getAuthClient();
@@ -21,11 +31,34 @@ export async function insertText(args) {
     if (insertIndex === undefined) {
         throw new Error('Either index or appendToEnd: true is required.');
     }
+    const requests = [
+        { insertText: { location: { index: insertIndex }, text: args.text } },
+    ];
+    if (args.resetFormatting !== false) {
+        const defaults = getDefaultTextStyle();
+        const explicitStyle = args.style ?? {};
+        const filtered = Object.fromEntries(Object.entries(explicitStyle).filter(([, v]) => v !== undefined));
+        const merged = { ...defaults, ...filtered };
+        requests.push({
+            updateTextStyle: {
+                range: {
+                    startIndex: insertIndex,
+                    endIndex: insertIndex + args.text.length,
+                },
+                textStyle: {
+                    weightedFontFamily: { fontFamily: merged.fontFamily },
+                    fontSize: { magnitude: merged.fontSize, unit: 'PT' },
+                    bold: merged.bold,
+                    italic: merged.italic,
+                    foregroundColor: { color: { rgbColor: hexToRgb(merged.color) } },
+                },
+                fields: 'weightedFontFamily,fontSize,bold,italic,foregroundColor',
+            },
+        });
+    }
     await docs.documents.batchUpdate({
         documentId: args.documentId,
-        requestBody: {
-            requests: [{ insertText: { location: { index: insertIndex }, text: args.text } }],
-        },
+        requestBody: { requests },
     });
     const apiMs = Math.round(performance.now() - apiStart);
     return {

package/dist/tools/update-table-style.d.ts

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+export declare const UpdateTableStyleSchema: z.ZodObject<{
+    documentId: z.ZodString;
+    nearHeading: z.ZodOptional<z.ZodString>;
+    tableIndex: z.ZodOptional<z.ZodNumber>;
+    dimensions: z.ZodOptional<z.ZodObject<{
+        rows: z.ZodNumber;
+        columns: z.ZodNumber;
+    }, z.core.$strip>>;
+    preset: z.ZodOptional<z.ZodString>;
+    headerBackground: z.ZodOptional<z.ZodString>;
+    headerTextColor: z.ZodOptional<z.ZodString>;
+    borderColor: z.ZodOptional<z.ZodString>;
+    borderWidth: z.ZodOptional<z.ZodNumber>;
+    alternatingRowColor: z.ZodOptional<z.ZodString>;
+    cellPadding: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare function updateTableStyle(args: z.infer<typeof UpdateTableStyleSchema>): Promise<{
+    documentId: string;
+    table: {
+        startIndex: number;
+        rows: number;
+        cols: number;
+        nearestHeading: string | null;
+        tablePosition: number;
+    };
+    mode: string;
+    _apiMs: number;
+    applied?: undefined;
+    reason?: undefined;
+    requestCount?: undefined;
+} | {
+    documentId: string;
+    table: {
+        startIndex: number;
+        rows: number;
+        cols: number;
+        nearestHeading: string | null;
+        tablePosition: number;
+    };
+    applied: boolean;
+    reason: string;
+    _apiMs: number;
+    mode?: undefined;
+    requestCount?: undefined;
+} | {
+    documentId: string;
+    table: {
+        startIndex: number;
+        rows: number;
+        cols: number;
+        nearestHeading: string | null;
+        tablePosition: number;
+    };
+    applied: boolean;
+    requestCount: number;
+    _apiMs: number;
+    mode?: undefined;
+    reason?: undefined;
+}>;

package/dist/tools/update-table-style.js

@@ -0,0 +1,204 @@
+import { google } from 'googleapis';
+import { z } from 'zod';
+import { getAuthClient } from '../auth/google-auth.js';
+import { getPreset } from '../presets/config.js';
+import { buildTableStyleRequests } from '../presets/converter.js';
+export const UpdateTableStyleSchema = z.object({
+    documentId: z.string().describe('The Google Doc document ID'),
+    // Identification (at least one required — validated in handler)
+    nearHeading: z.string().optional().describe('Find the first table after a heading containing this text (case-insensitive substring match). Only top-level body headings count.'),
+    tableIndex: z.number().optional().describe('Select the nth table in the document (0-indexed).'),
+    dimensions: z.object({
+        rows: z.number(),
+        columns: z.number(),
+    }).optional().describe('Match a table by exact row and column count.'),
+    // Styling (all optional)
+    preset: z.string().optional().describe('Apply a named style preset\'s table styles.'),
+    headerBackground: z.string().optional().describe('Hex color for header row background.'),
+    headerTextColor: z.string().optional().describe('Hex color for header text.'),
+    borderColor: z.string().optional().describe('Hex color for all cell borders.'),
+    borderWidth: z.number().optional().describe('Border width in PT.'),
+    alternatingRowColor: z.string().optional().describe('Hex color for alternating (even) row backgrounds.'),
+    cellPadding: z.number().optional().describe('Cell padding in PT.'),
+});
+function extractHeadingText(paragraph) {
+    const styleType = paragraph.paragraphStyle?.namedStyleType || '';
+    const isHeading = styleType.startsWith('HEADING_') || styleType === 'TITLE' || styleType === 'SUBTITLE';
+    if (!isHeading)
+        return null;
+    const parts = [];
+    for (const el of paragraph.elements || []) {
+        if (el.textRun?.content) {
+            parts.push(el.textRun.content);
+        }
+    }
+    return parts.join('').trim() || null;
+}
+function buildTableCandidates(content) {
+    const candidates = [];
+    let lastHeadingText = null;
+    let tablePosition = 0;
+    for (const element of content) {
+        if (element.paragraph) {
+            const headingText = extractHeadingText(element.paragraph);
+            if (headingText !== null) {
+                lastHeadingText = headingText;
+            }
+        }
+        if (element.table) {
+            candidates.push({
+                startIndex: element.startIndex,
+                rows: element.table.rows || 0,
+                cols: element.table.columns || 0,
+                nearestHeading: lastHeadingText,
+                tablePosition,
+            });
+            tablePosition++;
+        }
+    }
+    return candidates;
+}
+function formatCandidateList(candidates) {
+    return candidates
+        .map(c => `  [${c.tablePosition}] ${c.rows}x${c.cols} at index ${c.startIndex}${c.nearestHeading ? ` (after heading: "${c.nearestHeading}")` : ''}`)
+        .join('\n');
+}
+export async function updateTableStyle(args) {
+    // Validate that at least one identification param is provided
+    if (args.nearHeading === undefined && args.tableIndex === undefined && args.dimensions === undefined) {
+        throw new Error('At least one identification parameter required: nearHeading, tableIndex, or dimensions');
+    }
+    const auth = getAuthClient();
+    const docs = google.docs({ version: 'v1', auth });
+    const apiStart = performance.now();
+    const doc = await docs.documents.get({ documentId: args.documentId });
+    const content = doc.data.body?.content || [];
+    const allCandidates = buildTableCandidates(content);
+    if (allCandidates.length === 0) {
+        throw new Error('Document contains no tables.');
+    }
+    // Filter by identification params (intersect all provided)
+    let filtered = [...allCandidates];
+    if (args.nearHeading !== undefined) {
+        const needle = args.nearHeading.toLowerCase();
+        // Find the last heading that contains the search text
+        let matchedHeading = null;
+        for (const candidate of allCandidates) {
+            if (candidate.nearestHeading && candidate.nearestHeading.toLowerCase().includes(needle)) {
+                matchedHeading = candidate.nearestHeading;
+            }
+        }
+        if (matchedHeading === null) {
+            throw new Error(`No table found near a heading containing "${args.nearHeading}".\n` +
+                `Available tables:\n${formatCandidateList(allCandidates)}`);
+        }
+        // Return only the first table whose nearestHeading matches
+        const firstMatch = filtered.find(c => c.nearestHeading !== null && c.nearestHeading.toLowerCase().includes(needle));
+        filtered = firstMatch ? [firstMatch] : [];
+    }
+    if (args.tableIndex !== undefined) {
+        filtered = filtered.filter(c => c.tablePosition === args.tableIndex);
+    }
+    if (args.dimensions !== undefined) {
+        filtered = filtered.filter(c => c.rows === args.dimensions.rows && c.cols === args.dimensions.columns);
+    }
+    // Handle match results
+    if (filtered.length === 0) {
+        throw new Error(`No table matches the provided criteria.\n` +
+            `Available tables:\n${formatCandidateList(allCandidates)}`);
+    }
+    if (filtered.length > 1) {
+        throw new Error(`Multiple tables match the provided criteria. Narrow your search.\n` +
+            `Matching tables:\n${formatCandidateList(filtered)}`);
+    }
+    const matched = filtered[0];
+    // Check if any styling was requested
+    const hasStyling = args.preset !== undefined ||
+        args.headerBackground !== undefined ||
+        args.headerTextColor !== undefined ||
+        args.borderColor !== undefined ||
+        args.borderWidth !== undefined ||
+        args.alternatingRowColor !== undefined ||
+        args.cellPadding !== undefined;
+    if (!hasStyling) {
+        const apiMs = Math.round(performance.now() - apiStart);
+        return {
+            documentId: args.documentId,
+            table: {
+                startIndex: matched.startIndex,
+                rows: matched.rows,
+                cols: matched.cols,
+                nearestHeading: matched.nearestHeading,
+                tablePosition: matched.tablePosition,
+            },
+            mode: 'read-only',
+            _apiMs: apiMs,
+        };
+    }
+    // Build TableStyleConfig: start from preset if provided, then override with explicit params
+    let tableConfig = {};
+    if (args.preset !== undefined) {
+        const { preset } = getPreset(args.preset);
+        if (preset.table) {
+            tableConfig = { ...preset.table };
+        }
+    }
+    if (args.headerBackground !== undefined) {
+        tableConfig = { ...tableConfig, headerBackground: args.headerBackground };
+    }
+    if (args.headerTextColor !== undefined) {
+        tableConfig = { ...tableConfig, headerTextColor: args.headerTextColor };
+    }
+    if (args.borderColor !== undefined) {
+        tableConfig = { ...tableConfig, borderColor: args.borderColor };
+    }
+    if (args.borderWidth !== undefined) {
+        tableConfig = { ...tableConfig, borderWidth: args.borderWidth };
+    }
+    if (args.alternatingRowColor !== undefined) {
+        tableConfig = { ...tableConfig, alternateRowBackground: args.alternatingRowColor };
+    }
+    if (args.cellPadding !== undefined) {
+        tableConfig = { ...tableConfig, cellPadding: args.cellPadding };
+    }
+    const tableForRequests = [{
+            startIndex: matched.startIndex,
+            rows: matched.rows,
+            cols: matched.cols,
+        }];
+    const requests = buildTableStyleRequests(tableConfig, tableForRequests);
+    if (requests.length === 0) {
+        const apiMs = Math.round(performance.now() - apiStart);
+        return {
+            documentId: args.documentId,
+            table: {
+                startIndex: matched.startIndex,
+                rows: matched.rows,
+                cols: matched.cols,
+                nearestHeading: matched.nearestHeading,
+                tablePosition: matched.tablePosition,
+            },
+            applied: false,
+            reason: 'Style config produced no requests',
+            _apiMs: apiMs,
+        };
+    }
+    await docs.documents.batchUpdate({
+        documentId: args.documentId,
+        requestBody: { requests },
+    });
+    const apiMs = Math.round(performance.now() - apiStart);
+    return {
+        documentId: args.documentId,
+        table: {
+            startIndex: matched.startIndex,
+            rows: matched.rows,
+            cols: matched.cols,
+            nearestHeading: matched.nearestHeading,
+            tablePosition: matched.tablePosition,
+        },
+        applied: true,
+        requestCount: requests.length,
+        _apiMs: apiMs,
+    };
+}

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

@@ -15,12 +15,9 @@ export declare function writeTable(args: z.infer<typeof WriteTableSchema>): Prom
     tableCreated: boolean;
     styled: boolean;
     reason: string;
-    rows?: undefined;
-    cols?: undefined;
-    tableStartIndex?: undefined;
-    requestCount?: undefined;
-    _apiMs?: undefined;
 } | {
+    _apiMs: number;
+    warning?: string | undefined;
     documentId: string;
     tableCreated: boolean;
     styled: boolean;
@@ -28,6 +25,5 @@ export declare function writeTable(args: z.infer<typeof WriteTableSchema>): Prom
     cols: number;
     tableStartIndex: any;
     requestCount: number;
-    _apiMs: number;
     reason?: undefined;
 }>;

package/dist/tools/write-table.js

@@ -2,16 +2,16 @@ import { google } from 'googleapis';
 import { z } from 'zod';
 import { getAuthClient } from '../auth/google-auth.js';
 import { getPreset } from '../presets/config.js';
+import { hexToRgb } from '../utils/color.js';
+import { DEFAULT_FONT_FAMILY, DEFAULT_FONT_SIZE } from '../utils/defaults.js';
 const DEFAULT_HEADER_BG = { red: 0.043, green: 0.325, blue: 0.58 };
 const DEFAULT_HEADER_TEXT = { red: 0.95, green: 0.95, blue: 0.95 };
 const DEFAULT_PADDING = 5;
 const DEFAULT_PAGE_WIDTH = 612;
 const DEFAULT_MARGIN = 72;
-const DEFAULT_FONT_FAMILY = 'Arial';
-const DEFAULT_FONT_SIZE = 11;
 const DEFAULT_LINE_SPACING = 115;
-const PT_PER_CHAR = 6;
-const PADDING_PER_COL = 20;
+const MIN_COL_WIDTH_PT = 60;
+const PT_PER_CHAR_HEADER = 7;
 export const WriteTableSchema = z.object({
     documentId: z.string().describe('The Google Doc document ID'),
     index: z.number().describe('Position in the document to insert the table. Must be a body-level index, not inside an existing table.'),
@@ -23,14 +23,6 @@ export const WriteTableSchema = z.object({
         cellPadding: z.number().optional(),
     }).optional().describe('Optional style overrides. Falls back to active preset, then defaults.'),
 });
-function hexToRgb(hex) {
-    const h = hex.replace('#', '');
-    return {
-        red: parseInt(h.substring(0, 2), 16) / 255,
-        green: parseInt(h.substring(2, 4), 16) / 255,
-        blue: parseInt(h.substring(4, 6), 16) / 255,
-    };
-}
 export async function writeTable(args) {
     const auth = getAuthClient();
     const docs = google.docs({ version: 'v1', auth });
@@ -208,39 +200,51 @@ export async function writeTable(args) {
             fields: 'paddingTop,paddingBottom,paddingLeft,paddingRight',
         },
     });
-    // FIX 2 + 4: Content-aware column widths that sum to full usable page width
-    const maxLengths = new Array(colCount).fill(0);
-    for (const row of allData) {
+    // Column widths: header-aware floors + proportional allocation
+    const headerLengths = args.headers.map(h => h.length);
+    const maxBodyLengths = new Array(colCount).fill(0);
+    for (const row of args.rows) {
         for (let c = 0; c < colCount; c++) {
-            maxLengths[c] = Math.max(maxLengths[c], (row[c] || '').length);
+            maxBodyLengths[c] = Math.max(maxBodyLengths[c], (row[c] || '').length);
         }
     }
-    const totalLen = maxLengths.reduce((a, b) => a + b, 0);
-    if (totalLen > 0) {
-        // Calculate raw proportional widths
-        const rawWidths = maxLengths.map(l => {
-            const contentWidth = l * PT_PER_CHAR + PADDING_PER_COL;
-            return Math.max(contentWidth, 50); // minimum 50pt per column
+    // Floor per column: max(MIN_COL_WIDTH_PT, headerChars * PT_PER_CHAR_HEADER)
+    const floors = headerLengths.map(len => Math.max(MIN_COL_WIDTH_PT, len * PT_PER_CHAR_HEADER));
+    const totalFloors = floors.reduce((a, b) => a + b, 0);
+    let columnWidths;
+    let widthWarning;
+    if (totalFloors > usableWidth) {
+        // Floors exceed page width -- equal distribution fallback
+        const equalWidth = Math.round(usableWidth / colCount);
+        columnWidths = new Array(colCount).fill(equalWidth);
+        widthWarning = `Table has ${colCount} columns; minimum widths cannot be satisfied, content may wrap`;
+    }
+    else {
+        // Proportional allocation of remaining space
+        const remaining = usableWidth - totalFloors;
+        const totalBodyLen = maxBodyLengths.reduce((a, b) => a + b, 0);
+        columnWidths = floors.map((floor, c) => {
+            const proportional = totalBodyLen > 0
+                ? Math.round(remaining * (maxBodyLengths[c] / totalBodyLen))
+                : Math.round(remaining / colCount);
+            return floor + proportional;
         });
-        // Scale all widths proportionally to sum to exactly usableWidth
-        const rawTotal = rawWidths.reduce((a, b) => a + b, 0);
-        const scaledWidths = rawWidths.map(w => Math.round((w / rawTotal) * usableWidth));
-        // Adjust rounding error on last column
-        const scaledTotal = scaledWidths.reduce((a, b) => a + b, 0);
-        scaledWidths[scaledWidths.length - 1] += usableWidth - scaledTotal;
-        for (let c = 0; c < colCount; c++) {
-            styleRequests.push({
-                updateTableColumnProperties: {
-                    tableStartLocation: { index: table2.startIndex },
-                    columnIndices: [c],
-                    tableColumnProperties: {
-                        widthType: 'FIXED_WIDTH',
-                        width: { magnitude: scaledWidths[c], unit: 'PT' },
-                    },
-                    fields: 'widthType,width',
+    }
+    // Adjust rounding error on last column
+    const widthTotal = columnWidths.reduce((a, b) => a + b, 0);
+    columnWidths[columnWidths.length - 1] += Math.round(usableWidth) - widthTotal;
+    for (let c = 0; c < colCount; c++) {
+        styleRequests.push({
+            updateTableColumnProperties: {
+                tableStartLocation: { index: table2.startIndex },
+                columnIndices: [c],
+                tableColumnProperties: {
+                    widthType: 'FIXED_WIDTH',
+                    width: { magnitude: columnWidths[c], unit: 'PT' },
                 },
-            });
-        }
+                fields: 'widthType,width',
+            },
+        });
     }
     if (styleRequests.length > 0) {
         await docs.documents.batchUpdate({
@@ -257,6 +261,7 @@ export async function writeTable(args) {
         cols: colCount,
         tableStartIndex: table2.startIndex,
         requestCount: requests.length + styleRequests.length,
+        ...(widthWarning ? { warning: widthWarning } : {}),
         _apiMs: apiMs,
     };
 }

package/dist/utils/color.d.ts

@@ -0,0 +1,14 @@
+export declare function hexToRgb(hex: string): {
+    red: number;
+    green: number;
+    blue: number;
+};
+export declare function toColor(hex: string): {
+    color: {
+        rgbColor: {
+            red: number;
+            green: number;
+            blue: number;
+        };
+    };
+};

package/dist/utils/color.js

@@ -0,0 +1,14 @@
+export function hexToRgb(hex) {
+    const h = hex.replace('#', '');
+    if (h.length !== 6 || !/^[0-9a-fA-F]{6}$/.test(h)) {
+        throw new Error(`Invalid hex color '${hex}'. Use 6-character hex format (e.g., '#FF0000').`);
+    }
+    return {
+        red: parseInt(h.substring(0, 2), 16) / 255,
+        green: parseInt(h.substring(2, 4), 16) / 255,
+        blue: parseInt(h.substring(4, 6), 16) / 255,
+    };
+}
+export function toColor(hex) {
+    return { color: { rgbColor: hexToRgb(hex) } };
+}

package/dist/utils/defaults.d.ts

@@ -0,0 +1,11 @@
+export declare const DEFAULT_FONT_FAMILY = "Arial";
+export declare const DEFAULT_FONT_SIZE = 11;
+export declare const DEFAULT_FONT_COLOR = "#000000";
+export interface TextStyleDefaults {
+    fontFamily: string;
+    fontSize: number;
+    bold: boolean;
+    italic: boolean;
+    color: string;
+}
+export declare function getDefaultTextStyle(): TextStyleDefaults;

package/dist/utils/defaults.js

@@ -0,0 +1,29 @@
+import { getPreset } from '../presets/config.js';
+export const DEFAULT_FONT_FAMILY = 'Arial';
+export const DEFAULT_FONT_SIZE = 11;
+export const DEFAULT_FONT_COLOR = '#000000';
+export function getDefaultTextStyle() {
+    try {
+        const { preset } = getPreset();
+        const normalText = preset.styles?.NORMAL_TEXT;
+        if (normalText) {
+            return {
+                fontFamily: normalText.fontFamily ?? DEFAULT_FONT_FAMILY,
+                fontSize: normalText.fontSize ?? DEFAULT_FONT_SIZE,
+                bold: normalText.bold ?? false,
+                italic: normalText.italic ?? false,
+                color: normalText.color ?? DEFAULT_FONT_COLOR,
+            };
+        }
+    }
+    catch {
+        // No active preset, use hardcoded defaults
+    }
+    return {
+        fontFamily: DEFAULT_FONT_FAMILY,
+        fontSize: DEFAULT_FONT_SIZE,
+        bold: false,
+        italic: false,
+        color: DEFAULT_FONT_COLOR,
+    };
+}

package/package.json

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