gdocs-mcp 0.1.0 → 0.3.0

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

@@ -0,0 +1,149 @@
+import { google } from 'googleapis';
+import { z } from 'zod';
+import { getAuthClient } from '../auth/google-auth.js';
+import { savePreset } from '../presets/config.js';
+import { VALID_NAMED_STYLE_TYPES } from '../presets/types.js';
+export const ExtractDocumentStylesSchema = z.object({
+    documentId: z.string().describe('The Google Doc document ID to extract styles from'),
+    saveAs: z.string().optional().describe('If provided, saves the extracted styles as a named preset in ~/.gdocs-mcp/styles.json'),
+});
+export async function extractDocumentStyles(args) {
+    const auth = getAuthClient();
+    const docs = google.docs({ version: 'v1', auth });
+    const doc = await docs.documents.get({ documentId: args.documentId });
+    const preset = {
+        document: extractDocumentStyle(doc.data.documentStyle),
+        styles: extractNamedStyles(doc.data.namedStyles),
+        table: extractTableStyles(doc.data.body?.content || []),
+    };
+    if (args.saveAs) {
+        savePreset(args.saveAs, preset);
+    }
+    return {
+        documentId: args.documentId,
+        title: doc.data.title,
+        preset,
+        savedAs: args.saveAs || null,
+    };
+}
+function extractDocumentStyle(docStyle) {
+    const config = {};
+    if (docStyle?.marginTop?.magnitude !== undefined)
+        config.marginTop = docStyle.marginTop.magnitude;
+    if (docStyle?.marginBottom?.magnitude !== undefined)
+        config.marginBottom = docStyle.marginBottom.magnitude;
+    if (docStyle?.marginLeft?.magnitude !== undefined)
+        config.marginLeft = docStyle.marginLeft.magnitude;
+    if (docStyle?.marginRight?.magnitude !== undefined)
+        config.marginRight = docStyle.marginRight.magnitude;
+    if (docStyle?.pageSize?.width?.magnitude !== undefined)
+        config.pageWidth = docStyle.pageSize.width.magnitude;
+    if (docStyle?.pageSize?.height?.magnitude !== undefined)
+        config.pageHeight = docStyle.pageSize.height.magnitude;
+    return config;
+}
+function extractNamedStyles(namedStyles) {
+    const result = {};
+    if (!namedStyles?.styles)
+        return result;
+    for (const style of namedStyles.styles) {
+        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;
+        if (Object.keys(config).length > 0) {
+            result[type] = config;
+        }
+    }
+    return result;
+}
+function extractTableStyles(content) {
+    // Find first table and extract its styling as the template
+    for (const element of content) {
+        if (!element.table)
+            continue;
+        const table = element.table;
+        const firstRow = table.tableRows?.[0];
+        if (!firstRow)
+            continue;
+        const config = {};
+        const firstCell = firstRow.tableCells?.[0];
+        if (firstCell?.tableCellStyle) {
+            const cs = firstCell.tableCellStyle;
+            if (cs.backgroundColor?.color?.rgbColor) {
+                config.headerBackground = rgbToHex(cs.backgroundColor.color.rgbColor);
+            }
+            if (cs.borderTop?.width?.magnitude !== undefined) {
+                config.borderWidth = cs.borderTop.width.magnitude;
+            }
+            if (cs.borderTop?.color?.color?.rgbColor) {
+                config.borderColor = rgbToHex(cs.borderTop.color.color.rgbColor);
+            }
+            if (cs.paddingTop?.magnitude !== undefined) {
+                config.cellPadding = cs.paddingTop.magnitude;
+            }
+        }
+        // Check second row for alternating background
+        if (table.tableRows?.length > 2) {
+            const thirdRow = table.tableRows[2];
+            const thirdCell = thirdRow?.tableCells?.[0];
+            if (thirdCell?.tableCellStyle?.backgroundColor?.color?.rgbColor) {
+                config.alternateRowBackground = rgbToHex(thirdCell.tableCellStyle.backgroundColor.color.rgbColor);
+            }
+        }
+        if (Object.keys(config).length > 0)
+            return config;
+        break;
+    }
+    return undefined;
+}
+function rgbToHex(rgb) {
+    const r = Math.round((rgb.red || 0) * 255);
+    const g = Math.round((rgb.green || 0) * 255);
+    const b = Math.round((rgb.blue || 0) * 255);
+    return '#' + [r, g, b].map(c => c.toString(16).padStart(2, '0')).join('');
+}

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/list-style-presets.d.ts

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+export declare const ListStylePresetsSchema: z.ZodObject<{}, z.core.$strip>;
+export declare function listStylePresets(): Promise<{
+    activePreset: string;
+    presets: {
+        name: string;
+        source: "built-in" | "user";
+        isActive: boolean;
+        summary: {
+            bodyFont: string;
+            bodySize: string | number;
+            headingFont: string;
+            headingColor: string;
+            lineSpacing: string | number;
+        };
+    }[];
+    count: number;
+}>;

package/dist/tools/list-style-presets.js

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+import { listAllPresets, getActivePresetName } from '../presets/config.js';
+export const ListStylePresetsSchema = z.object({});
+export async function listStylePresets() {
+    const presets = listAllPresets();
+    const activePreset = getActivePresetName();
+    const result = Object.entries(presets).map(([name, { source, preset }]) => {
+        const styles = preset.styles || {};
+        const normalText = styles.NORMAL_TEXT || {};
+        const heading1 = styles.HEADING_1 || {};
+        return {
+            name,
+            source,
+            isActive: name === activePreset,
+            summary: {
+                bodyFont: normalText.fontFamily || 'default',
+                bodySize: normalText.fontSize || 'default',
+                headingFont: heading1.fontFamily || normalText.fontFamily || 'default',
+                headingColor: heading1.color || 'default',
+                lineSpacing: normalText.lineSpacing || 'default',
+            },
+        };
+    });
+    return {
+        activePreset: activePreset || 'none',
+        presets: result,
+        count: result.length,
+    };
+}

package/dist/tools/set-active-preset.d.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+export declare const SetActivePresetSchema: z.ZodObject<{
+    presetName: z.ZodString;
+}, z.core.$strip>;
+export declare function setActivePreset(args: z.infer<typeof SetActivePresetSchema>): Promise<{
+    activePreset: string;
+    message: string;
+}>;

package/dist/tools/set-active-preset.js

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+import { setActivePreset as setActive } from '../presets/config.js';
+export const SetActivePresetSchema = z.object({
+    presetName: z.string().describe('Name of the preset to set as active. The active preset auto-applies when creating new documents.'),
+});
+export async function setActivePreset(args) {
+    setActive(args.presetName);
+    return {
+        activePreset: args.presetName,
+        message: `Active preset set to "${args.presetName}". New documents will use this preset automatically.`,
+    };
+}

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.1.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",
@@ -30,7 +30,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/apurwa-sudo/gdocs-mcp"
+    "url": "https://github.com/Apurwa/gdocs-mcp"
   },
   "engines": {
     "node": ">=18"