google-tools-mcp 1.2.11 → 2.0.0

package/dist/markdown-transformer/docsToMarkdown.js

@@ -4,6 +4,134 @@
  * When these are detected on a text run, we render backtick code in markdown.
  */
 const CODE_FONT_FAMILIES = new Set(['Roboto Mono', 'Courier New', 'Consolas', 'monospace']);
+/**
+ * Inspects the body content that replaceDocumentWithMarkdown will delete and
+ * re-insert, and reports anything docsJsonToMarkdown cannot represent at all.
+ * Returns an array of human-readable warning strings (empty if the content
+ * converts losslessly). Call before replaceDocumentWithMarkdown to warn the AI
+ * about what a body replacement will permanently lose.
+ *
+ * Checked: inline/positioned images and footnote references, neither of which
+ * has any markdown representation in either direction of this converter; a
+ * generated table of contents; and, generically, every OTHER Docs API
+ * `ParagraphElement` variant that `extractFormattedText()` does not render.
+ *
+ * `extractFormattedText()` only ever renders `textRun` (see below). The Docs
+ * API `ParagraphElement` union also defines `autoText`, `pageBreak`,
+ * `columnBreak`, `horizontalRule`, `equation`, `person`, `richLink`, and
+ * `dateElement` (https://developers.google.com/workspace/docs/api/reference/rest/v1/documents#ParagraphElement).
+ * None of those has a markdown representation, so a body replacement deletes
+ * them permanently and the current markdown output never mentions they were
+ * there. Rather than enumerate that list (and silently miss whatever variant
+ * Google adds next), this scanner is deny-by-default: any paragraph-element
+ * key other than `startIndex`/`endIndex` (position metadata) and the three
+ * keys explicitly handled elsewhere in this function (`textRun`, rendered;
+ * `inlineObjectElement`/`footnoteReference`, already counted above) is
+ * treated as an unhandled content variant and reported by name.
+ *
+ * NOT checked (intentionally): custom text/highlight colors and non-default
+ * paragraph alignment. Those round-trip losslessly through the rich-markdown
+ * HTML extensions this converter emits by default (`<span style="color:...">`,
+ * `<p align="...">`, table alignment markers) and their inverse parsing in
+ * markdownToDocs.js, so warning about them here would be inaccurate.
+ *
+ * IMPORTANT — accuracy: every warning is derived from `bodyContent` itself,
+ * i.e. the exact body (a specific tab's body in tab mode, the document body
+ * otherwise) that the replacement mutates. This deliberately does NOT inspect
+ * document-level `headers`/`footers`, which are separate document segments a
+ * body-content replacement does not delete, nor the global `inlineObjects`/
+ * `footnotes` maps, which can include content belonging to OTHER tabs that a
+ * scoped replacement never touches.
+ *
+ * @param {Array} bodyContent structural elements of the body being replaced
+ *   (e.g. `contentSource.body.content`).
+ * @returns {string[]} warnings
+ */
+// ParagraphElement keys this converter already accounts for: startIndex/
+// endIndex are position metadata (not content); textRun is rendered by
+// extractFormattedText(); inlineObjectElement/footnoteReference are counted
+// as their own dedicated warnings below. Any other key on a ParagraphElement
+// is, by the Docs API's own union contract, an unhandled content-bearing
+// variant (autoText, pageBreak, columnBreak, horizontalRule, equation,
+// person, richLink, dateElement, or a future addition) that extractFormattedText
+// silently drops.
+const HANDLED_PARAGRAPH_ELEMENT_KEYS = new Set([
+    'startIndex',
+    'endIndex',
+    'textRun',
+    'inlineObjectElement',
+    'footnoteReference',
+]);
+export function checkMarkdownFidelity(bodyContent) {
+    const warnings = [];
+    let imageCount = 0;
+    let footnoteCount = 0;
+    let tocCount = 0;
+    const unhandledElementCounts = {};
+    function scanParagraphElements(elements) {
+        for (const pe of elements) {
+            // Inline images embedded in the body flow — deleted with the body.
+            if (pe.inlineObjectElement) {
+                imageCount++;
+            }
+            // Footnote references live in the body; deleting the body removes them
+            // (and Docs then drops the orphaned footnote).
+            if (pe.footnoteReference) {
+                footnoteCount++;
+            }
+            // Deny-by-default: anything that isn't a key we explicitly handle is an
+            // unhandled ParagraphElement variant. Grouped and named below rather
+            // than warning per element.
+            for (const key of Object.keys(pe)) {
+                if (!HANDLED_PARAGRAPH_ELEMENT_KEYS.has(key)) {
+                    unhandledElementCounts[key] = (unhandledElementCounts[key] ?? 0) + 1;
+                }
+            }
+        }
+    }
+    function scanBodyContent(content) {
+        for (const element of content) {
+            if (element.paragraph) {
+                // Positioned (floating) images anchored to this paragraph are also
+                // removed when the paragraph is deleted.
+                if (Array.isArray(element.paragraph.positionedObjectIds)) {
+                    imageCount += element.paragraph.positionedObjectIds.length;
+                }
+                scanParagraphElements(element.paragraph.elements ?? []);
+            }
+            else if (element.table) {
+                for (const row of (element.table.tableRows ?? [])) {
+                    for (const cell of (row.tableCells ?? [])) {
+                        scanBodyContent(cell.content ?? []);
+                    }
+                }
+            }
+            // A generated table of contents sits in the body, so the replacement
+            // deletes it, and markdown has no way to express one, so the importer
+            // cannot put it back. Without this the whole round trip drops the TOC
+            // with nothing said about it.
+            else if (element.tableOfContents) {
+                tocCount++;
+            }
+        }
+    }
+    scanBodyContent(bodyContent ?? []);
+    if (imageCount > 0) {
+        warnings.push(`${imageCount} image(s) — will be removed`);
+    }
+    if (footnoteCount > 0) {
+        warnings.push(`${footnoteCount} footnote(s) — will be removed`);
+    }
+    if (tocCount > 0) {
+        warnings.push(`${tocCount} table(s) of contents — will be removed (markdown cannot express a generated TOC; reinsert it in Docs afterward)`);
+    }
+    const unhandledKeys = Object.keys(unhandledElementCounts).sort();
+    if (unhandledKeys.length > 0) {
+        const parts = unhandledKeys.map((key) => `${unhandledElementCounts[key]} ${key}`).join(', ');
+        warnings.push(`${parts} — unsupported content type(s) with no markdown representation; will be removed`);
+    }
+    return warnings;
+}
 // --- Main Conversion ---
 /**
  * Converts Google Docs JSON structure to a markdown string.
@@ -15,34 +143,43 @@ const CODE_FONT_FAMILIES = new Set(['Roboto Mono', 'Courier New', 'Consolas', 'm
  * underline, links, code), ordered & unordered lists with nesting, tables,
  * and section breaks.
  */
-export function docsJsonToMarkdown(docData) {
+export function docsJsonToMarkdown(docData, options = {}) {
     const body = docData.body;
     if (!body?.content) {
         return '';
     }
     const lists = docData.lists ?? {};
+    const conversionOptions = {
+        richMarkdown: options.plainMarkdown ? false : options.richMarkdown ?? true,
+    };
     let markdown = '';
     for (const element of body.content) {
         if (element.paragraph) {
-            markdown += convertParagraph(element.paragraph, lists);
+            markdown += convertParagraph(element.paragraph, lists, conversionOptions);
         }
         else if (element.table) {
-            markdown += convertTable(element.table);
+            markdown += convertTable(element.table, conversionOptions);
         }
         else if (element.sectionBreak) {
+            if (isInitialDocumentSectionBreak(element)) {
+                continue;
+            }
             markdown += '\n---\n\n';
         }
     }
     return markdown.trim();
 }
+function isInitialDocumentSectionBreak(element) {
+    return element.endIndex === 1 && element.startIndex === undefined;
+}
 // --- Paragraph Conversion ---
-function convertParagraph(paragraph, lists) {
+function convertParagraph(paragraph, lists, options) {
     // 1. Determine paragraph type
     const headingLevel = getHeadingLevel(paragraph);
     const listInfo = getListInfo(paragraph, lists);
     // 2. Extract text content with inline formatting
     const elements = paragraph.elements ?? [];
-    const text = extractFormattedText(elements);
+    const text = extractFormattedText(elements, options);
     // 3. Format based on type
     if (headingLevel && text.trim()) {
         const hashes = '#'.repeat(Math.min(headingLevel, 6));
@@ -54,7 +191,15 @@ function convertParagraph(paragraph, lists) {
         return `${indent}${marker} ${text.trim()}\n`;
     }
     if (text.trim()) {
-        return `${text.trim()}\n\n`;
+        const trimmed = text.trim();
+        if (options.richMarkdown && isBlockquoteParagraph(paragraph)) {
+            return `<blockquote>${trimmed}</blockquote>\n\n`;
+        }
+        const alignment = paragraphAlignmentToHtml(paragraph.paragraphStyle?.alignment);
+        if (options.richMarkdown && alignment) {
+            return `<p align="${alignment}">${trimmed}</p>\n\n`;
+        }
+        return `${trimmed}\n\n`;
     }
     return '\n';
 }
@@ -91,16 +236,16 @@ function getListInfo(paragraph, lists) {
     return { ordered, nestingLevel };
 }
 // --- Text Run Conversion ---
-function extractFormattedText(elements) {
+function extractFormattedText(elements, options) {
     let result = '';
     for (const element of elements) {
         if (element.textRun) {
-            result += convertTextRun(element.textRun);
+            result += convertTextRun(element.textRun, options);
         }
     }
     return result;
 }
-function convertTextRun(textRun) {
+function convertTextRun(textRun, options) {
     let text = textRun.content ?? '';
     const style = textRun.textStyle;
     if (!style)
@@ -134,20 +279,72 @@ function convertTextRun(textRun) {
     if (style.strikethrough) {
         formatted = `~~${formatted}~~`;
     }
-    if (style.underline && !style.link) {
+    if (options.richMarkdown && style.underline && !style.link) {
         formatted = `<u>${formatted}</u>`;
     }
+    if (options.richMarkdown) {
+        formatted = applyRichTextStyle(formatted, style);
+    }
     if (style.link?.url) {
         formatted = `[${formatted}](${style.link.url})`;
     }
     return formatted + (trailingNewline ? '\n' : '');
 }
+function applyRichTextStyle(text, style) {
+    const styles = [];
+    const fg = rgbColorToHex(style.foregroundColor?.color?.rgbColor);
+    const bg = rgbColorToHex(style.backgroundColor?.color?.rgbColor);
+    const fontSize = style.fontSize?.magnitude;
+    const fontFamily = style.weightedFontFamily?.fontFamily;
+    if (fg)
+        styles.push(`color:${fg}`);
+    if (bg)
+        styles.push(`background-color:${bg}`);
+    if (typeof fontSize === 'number')
+        styles.push(`font-size:${fontSize}pt`);
+    if (fontFamily && !CODE_FONT_FAMILIES.has(fontFamily))
+        styles.push(`font-family:${escapeHtmlAttr(fontFamily)}`);
+    if (styles.length === 0)
+        return text;
+    return `<span style="${styles.join(';')}">${text}</span>`;
+}
 function isCodeStyled(style) {
     const fontFamily = style.weightedFontFamily?.fontFamily;
     return typeof fontFamily === 'string' && CODE_FONT_FAMILIES.has(fontFamily);
 }
+function isBlockquoteParagraph(paragraph) {
+    const style = paragraph.paragraphStyle;
+    return Boolean(style?.borderLeft ||
+        style?.indentStart?.magnitude >= 30 ||
+        style?.indentFirstLine?.magnitude >= 30);
+}
+function paragraphAlignmentToHtml(alignment) {
+    switch (alignment) {
+        case 'CENTER':
+            return 'center';
+        case 'END':
+        case 'RIGHT':
+            return 'right';
+        case 'JUSTIFIED':
+            return 'justify';
+        default:
+            return null;
+    }
+}
+function rgbColorToHex(rgb) {
+    if (!rgb)
+        return null;
+    const toHex = (value) => {
+        const normalized = Math.max(0, Math.min(255, Math.round((value ?? 0) * 255)));
+        return normalized.toString(16).padStart(2, '0');
+    };
+    return `#${toHex(rgb.red)}${toHex(rgb.green)}${toHex(rgb.blue)}`;
+}
+function escapeHtmlAttr(value) {
+    return value.replace(/&/g, '&amp;').replace(/"/g, '&quot;');
+}
 // --- Table Conversion ---
-function convertTable(table) {
+function convertTable(table, options) {
     if (!table.tableRows || table.tableRows.length === 0) {
         return '';
     }
@@ -162,15 +359,15 @@ function convertTable(table) {
             continue;
         let rowText = '|';
         for (const cell of row.tableCells) {
-            const cellText = extractCellText(cell);
+            const cellText = extractCellText(cell, options);
             rowText += ` ${cellText} |`;
         }
         markdown += rowText + '\n';
         // Add header separator after the first row
         if (isFirstRow) {
             let separator = '|';
-            for (let i = 0; i < row.tableCells.length; i++) {
-                separator += ' --- |';
+            for (const cell of row.tableCells) {
+                separator += ` ${tableAlignmentMarker(cell)} |`;
             }
             markdown += separator + '\n';
             isFirstRow = false;
@@ -242,18 +439,22 @@ function convertCodeBlockTable(table) {
     }
     return '\n```\n' + codeText + '\n```\n\n';
 }
-function extractCellText(cell) {
+function tableAlignmentMarker(cell) {
+    const alignment = paragraphAlignmentToHtml(cell.content?.[0]?.paragraph?.paragraphStyle?.alignment);
+    if (alignment === 'center')
+        return ':---:';
+    if (alignment === 'right')
+        return '---:';
+    return '---';
+}
+function extractCellText(cell, options) {
     let text = '';
     if (!cell.content)
         return text;
     for (const element of cell.content) {
         if (element.paragraph?.elements) {
-            for (const pe of element.paragraph.elements) {
-                if (pe.textRun?.content) {
-                    text += pe.textRun.content.replace(/\n/g, ' ').trim();
-                }
-            }
+            text += extractFormattedText(element.paragraph.elements, options).replace(/\n/g, ' ');
         }
     }
-    return text;
+    return text.trim().replace(/\|/g, '\\|');
 }

package/dist/markdown-transformer/index.js

@@ -12,24 +12,31 @@
 import { docsJsonToMarkdown } from './docsToMarkdown.js';
 import { convertMarkdownToRequests } from './markdownToDocs.js';
 import { executeBatchUpdateWithSplitting, findTabById } from '../googleDocsApiHelpers.js';
-export { docsJsonToMarkdown } from './docsToMarkdown.js';
+export { docsJsonToMarkdown, checkMarkdownFidelity } from './docsToMarkdown.js';
 /** Formats InsertMarkdownResult into a concise human-readable debug summary. */
 export function formatInsertResult(result) {
     const lines = [];
+    if (result.warnings?.length) {
+        lines.push('WARNINGS (content dropped):');
+        for (const warning of result.warnings) {
+            lines.push(`  - ${warning}`);
+        }
+        lines.push('');
+    }
     lines.push(`Markdown insert completed in ${result.totalElapsedMs}ms`);
     lines.push(`  Parse: ${result.parseElapsedMs}ms`);
     lines.push(`  Requests: ${result.totalRequests} total (${Object.entries(result.requestsByType)
         .map(([k, v]) => `${v} ${k}`)
         .join(', ')})`);
     lines.push(`  API calls: ${result.batchUpdate.totalApiCalls} batchUpdate calls in ${result.batchUpdate.totalElapsedMs}ms`);
-    const { phases } = result.batchUpdate;
-    if (phases.delete.requests > 0) {
+    const phases = result.batchUpdate.phases;
+    if (phases?.delete?.requests > 0) {
         lines.push(`    Delete phase: ${phases.delete.requests} requests, ${phases.delete.apiCalls} calls, ${phases.delete.elapsedMs}ms`);
     }
-    if (phases.insert.requests > 0) {
+    if (phases?.insert?.requests > 0) {
         lines.push(`    Insert phase: ${phases.insert.requests} requests, ${phases.insert.apiCalls} calls, ${phases.insert.elapsedMs}ms`);
     }
-    if (phases.format.requests > 0) {
+    if (phases?.format?.requests > 0) {
         lines.push(`    Format phase: ${phases.format.requests} requests, ${phases.format.apiCalls} calls, ${phases.format.elapsedMs}ms`);
     }
     return lines.join('\n');
@@ -61,12 +68,12 @@ export async function extractMarkdown(docs, documentId, options) {
         return docsJsonToMarkdown({
             body: targetTab.documentTab.body,
             lists: targetTab.documentTab.lists,
-        });
+        }, options);
     }
     return docsJsonToMarkdown({
         body: res.data.body,
         lists: res.data.lists,
-    });
+    }, options);
 }
 // --- insertMarkdown ---
 /**
@@ -85,6 +92,7 @@ export async function insertMarkdown(docs, documentId, markdown, options) {
     const overallStart = performance.now();
     const startIndex = options?.startIndex ?? 1;
     const tabId = options?.tabId;
+    const writeControl = options?.writeControl;
     // Fetch the document's default text style so we can explicitly set
     // foreground color on inserted text (fixes issue #14 — text without
     // explicit color shows "no color selected" in the Docs color picker).
@@ -109,7 +117,7 @@ export async function insertMarkdown(docs, documentId, markdown, options) {
         ...(options?.firstHeadingAsTitle && { firstHeadingAsTitle: true }),
         ...(defaultForegroundColor && { defaultForegroundColor }),
     };
-    const requests = convertMarkdownToRequests(markdown, startIndex, tabId, conversionOptions);
+    const { requests, warnings } = convertMarkdownToRequests(markdown, startIndex, tabId, conversionOptions);
     const parseElapsedMs = Math.round(performance.now() - parseStart);
     // Count requests by type
     const requestsByType = {};
@@ -119,6 +127,7 @@ export async function insertMarkdown(docs, documentId, markdown, options) {
     }
     if (requests.length === 0) {
         return {
+            warnings,
             totalRequests: 0,
             requestsByType,
             parseElapsedMs,
@@ -135,8 +144,9 @@ export async function insertMarkdown(docs, documentId, markdown, options) {
             totalElapsedMs: Math.round(performance.now() - overallStart),
         };
     }
-    const batchUpdate = await executeBatchUpdateWithSplitting(docs, documentId, requests);
+    const batchUpdate = await executeBatchUpdateWithSplitting(docs, documentId, requests, undefined, writeControl);
     return {
+        warnings,
         totalRequests: requests.length,
         requestsByType,
         parseElapsedMs,