google-tools-mcp 1.0.0

package/dist/helpers.js

@@ -0,0 +1,210 @@
+// Gmail message processing helpers.
+// Ported from @shinzolabs/gmail-mcp with minimal changes.
+
+const RESPONSE_HEADERS_LIST = [
+    'Date',
+    'From',
+    'To',
+    'Subject',
+    'Message-ID',
+    'In-Reply-To',
+    'References'
+];
+
+const decodedBody = (body) => {
+    if (!body?.data) return body;
+    const decodedData = Buffer.from(body.data, 'base64').toString('utf-8');
+    return {
+        data: decodedData,
+        size: body.data.length,
+        attachmentId: body.attachmentId
+    };
+};
+
+export const processMessagePart = (messagePart, includeBodyHtml = false) => {
+    if ((messagePart.mimeType !== 'text/html' || includeBodyHtml) && messagePart.body) {
+        messagePart.body = decodedBody(messagePart.body);
+    }
+    if (messagePart.parts) {
+        messagePart.parts = messagePart.parts.map(part => processMessagePart(part, includeBodyHtml));
+    }
+    if (messagePart.headers) {
+        messagePart.headers = messagePart.headers.filter(header => RESPONSE_HEADERS_LIST.includes(header.name || ''));
+    }
+    return messagePart;
+};
+
+export const getNestedHistory = (messagePart, level = 1) => {
+    if (messagePart.mimeType === 'text/plain' && messagePart.body?.data) {
+        const { data } = decodedBody(messagePart.body);
+        if (!data) return '';
+        return data.split('\n').map(line => '>' + (line.startsWith('>') ? '' : ' ') + line).join('\n');
+    }
+    return (messagePart.parts || []).map(p => getNestedHistory(p, level + 1)).filter(p => p).join('\n');
+};
+
+export const findHeader = (headers, name) => {
+    if (!headers || !Array.isArray(headers) || !name) return undefined;
+    return headers.find(h => h?.name?.toLowerCase() === name.toLowerCase())?.value ?? undefined;
+};
+
+export const formatEmailList = (emailList) => {
+    if (!emailList) return [];
+    return emailList.split(',').map(email => email.trim());
+};
+
+const getQuotedContent = (thread) => {
+    if (!thread.messages?.length) return '';
+    const sentMessages = thread.messages.filter(msg =>
+        msg.labelIds?.includes('SENT') ||
+        (!msg.labelIds?.includes('DRAFT') && findHeader(msg.payload?.headers || [], 'date'))
+    );
+    if (!sentMessages.length) return '';
+    const lastMessage = sentMessages[sentMessages.length - 1];
+    if (!lastMessage?.payload) return '';
+    let quotedContent = [];
+    if (lastMessage.payload.headers) {
+        const fromHeader = findHeader(lastMessage.payload.headers || [], 'from');
+        const dateHeader = findHeader(lastMessage.payload.headers || [], 'date');
+        if (fromHeader && dateHeader) {
+            quotedContent.push('');
+            quotedContent.push(`On ${dateHeader} ${fromHeader} wrote:`);
+            quotedContent.push('');
+        }
+    }
+    const nestedHistory = getNestedHistory(lastMessage.payload);
+    if (nestedHistory) {
+        quotedContent.push(nestedHistory);
+        quotedContent.push('');
+    }
+    return quotedContent.join('\n');
+};
+
+const getThreadHeaders = (thread) => {
+    let headers = [];
+    if (!thread.messages?.length) return headers;
+    const lastMessage = thread.messages[thread.messages.length - 1];
+    const references = [];
+    let subjectHeader = findHeader(lastMessage.payload?.headers || [], 'subject');
+    if (subjectHeader) {
+        if (!subjectHeader.toLowerCase().startsWith('re:')) {
+            subjectHeader = `Re: ${subjectHeader}`;
+        }
+        headers.push(`Subject: ${subjectHeader}`);
+    }
+    const messageIdHeader = findHeader(lastMessage.payload?.headers || [], 'message-id');
+    if (messageIdHeader) {
+        headers.push(`In-Reply-To: ${messageIdHeader}`);
+        references.push(messageIdHeader);
+    }
+    const referencesHeader = findHeader(lastMessage.payload?.headers || [], 'references');
+    if (referencesHeader) references.unshift(...referencesHeader.split(' '));
+    if (references.length > 0) headers.push(`References: ${references.join(' ')}`);
+    return headers;
+};
+
+export const wrapTextBody = (text) => text.split('\n').map(line => {
+    if (line.length <= 76) return line;
+    const chunks = line.match(/.{1,76}/g) || [];
+    return chunks.join('=\n');
+}).join('\n');
+
+export const constructRawMessage = async (gmail, params) => {
+    let thread = null;
+    if (params.threadId) {
+        const { data } = await gmail.users.threads.get({ userId: 'me', id: params.threadId, format: 'full' });
+        thread = data;
+    }
+    const message = [];
+    if (params.to?.length) message.push(`To: ${wrapTextBody(params.to.join(', '))}`);
+    if (params.cc?.length) message.push(`Cc: ${wrapTextBody(params.cc.join(', '))}`);
+    if (params.bcc?.length) message.push(`Bcc: ${wrapTextBody(params.bcc.join(', '))}`);
+    if (thread) {
+        message.push(...getThreadHeaders(thread).map(header => wrapTextBody(header)));
+    } else if (params.subject) {
+        message.push(`Subject: ${wrapTextBody(params.subject)}`);
+    } else {
+        message.push('Subject: (No Subject)');
+    }
+    message.push('Content-Type: text/plain; charset="UTF-8"');
+    message.push('Content-Transfer-Encoding: quoted-printable');
+    message.push('MIME-Version: 1.0');
+    message.push('');
+    if (params.body) message.push(wrapTextBody(params.body));
+    if (thread) {
+        const quotedContent = getQuotedContent(thread);
+        if (quotedContent) {
+            message.push('');
+            message.push(wrapTextBody(quotedContent));
+        }
+    }
+    return Buffer.from(message.join('\r\n')).toString('base64url').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+};
+
+export const constructRawMessageWithAttachments = async (gmail, params) => {
+    let thread = null;
+    if (params.threadId) {
+        const { data } = await gmail.users.threads.get({ userId: 'me', id: params.threadId, format: 'full' });
+        thread = data;
+    }
+    const boundary = `boundary_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+    const headers = [];
+    if (params.to?.length) headers.push(`To: ${params.to.join(', ')}`);
+    if (params.cc?.length) headers.push(`Cc: ${params.cc.join(', ')}`);
+    if (params.bcc?.length) headers.push(`Bcc: ${params.bcc.join(', ')}`);
+    if (thread) {
+        headers.push(...getThreadHeaders(thread));
+    } else if (params.subject) {
+        headers.push(`Subject: ${params.subject}`);
+    } else {
+        headers.push('Subject: (No Subject)');
+    }
+    headers.push('MIME-Version: 1.0');
+    headers.push(`Content-Type: multipart/mixed; boundary="${boundary}"`);
+    const parts = [];
+    // Text body part
+    let bodyText = params.body || '';
+    if (thread) {
+        const quotedContent = getQuotedContent(thread);
+        if (quotedContent) bodyText += '\n\n' + quotedContent;
+    }
+    parts.push([
+        `--${boundary}`,
+        'Content-Type: text/plain; charset="UTF-8"',
+        'Content-Transfer-Encoding: base64',
+        '',
+        Buffer.from(bodyText).toString('base64'),
+    ].join('\r\n'));
+    // Attachment parts
+    for (const att of params.attachments) {
+        const attHeaders = [
+            `--${boundary}`,
+            `Content-Type: ${att.mimeType}; name="${att.filename}"`,
+            'Content-Transfer-Encoding: base64',
+            `Content-Disposition: attachment; filename="${att.filename}"`,
+            '',
+            att.base64Data,
+        ];
+        parts.push(attHeaders.join('\r\n'));
+    }
+    const raw = [
+        headers.join('\r\n'),
+        '',
+        parts.join('\r\n'),
+        `--${boundary}--`,
+    ].join('\r\n');
+    return Buffer.from(raw).toString('base64url').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+};
+
+export const getPlainTextBody = (messagePart) => {
+    if (messagePart.mimeType === 'text/plain' && messagePart.body?.data) {
+        return Buffer.from(messagePart.body.data, 'base64').toString('utf-8');
+    }
+    if (messagePart.parts) {
+        for (const part of messagePart.parts) {
+            const text = getPlainTextBody(part);
+            if (text) return text;
+        }
+    }
+    return '';
+};

package/dist/index.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+// google-tools-mcp — Combined Google Workspace MCP server
+//
+// Provides lazy-loaded tool categories for Drive, Docs, Sheets, and Gmail.
+// Only a discovery tool is exposed at startup; individual tools are loaded on demand.
+//
+// Usage:
+//   google-tools-mcp          Start the MCP server (default)
+//   google-tools-mcp auth     Run the interactive OAuth flow
+import { FastMCP } from 'fastmcp';
+import { collectToolsWhileRegistering, installCachedToolsListHandler } from './cachedToolsList.js';
+import { registerAllTools } from './tools/index.js';
+import { logger } from './logger.js';
+
+// --- Auth subcommand ---
+if (process.argv[2] === 'auth') {
+    const { runAuthFlow } = await import('./auth.js');
+    try {
+        await runAuthFlow();
+        logger.info('Authorization complete. You can now start the MCP server.');
+        process.exit(0);
+    } catch (error) {
+        logger.error('Authorization failed:', error.message || error);
+        process.exit(1);
+    }
+}
+
+// --- Server startup ---
+process.on('uncaughtException', (error) => {
+    logger.error('Uncaught Exception:', error);
+});
+process.on('unhandledRejection', (reason, _promise) => {
+    logger.error('Unhandled Promise Rejection:', reason);
+});
+
+const server = new FastMCP({
+    name: 'google-tools-mcp',
+    version: '1.0.0',
+});
+
+const registeredTools = [];
+collectToolsWhileRegistering(server, registeredTools);
+registerAllTools(server);
+
+try {
+    logger.info('Starting google-tools-mcp server...');
+    await server.start({ transportType: 'stdio' });
+    installCachedToolsListHandler(server, registeredTools);
+    logger.info('MCP Server running using stdio. Awaiting client connection...');
+    logger.info('Google auth will run automatically on first tool call.');
+    logger.info(`${registeredTools.length} tools registered at startup (discovery + logout). Call load_google_tools to load more.`);
+} catch (startError) {
+    logger.error('FATAL: Server failed to start:', startError.message || startError);
+    process.exit(1);
+}

package/dist/logger.js

@@ -0,0 +1,45 @@
+// Centralized logger with LOG_LEVEL support.
+// All log output goes to stderr (stdout reserved for MCP protocol).
+const LOG_LEVELS = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+    silent: 4,
+};
+function resolveLevel() {
+    const env = process.env.LOG_LEVEL?.toLowerCase();
+    if (env && env in LOG_LEVELS) {
+        return env;
+    }
+    return 'info';
+}
+let currentLevel = resolveLevel();
+export function refreshLogLevel() {
+    currentLevel = resolveLevel();
+}
+function shouldLog(level) {
+    return LOG_LEVELS[level] >= LOG_LEVELS[currentLevel];
+}
+export const logger = {
+    debug(...args) {
+        if (shouldLog('debug')) {
+            console.error('[DEBUG]', ...args);
+        }
+    },
+    info(...args) {
+        if (shouldLog('info')) {
+            console.error('[INFO]', ...args);
+        }
+    },
+    warn(...args) {
+        if (shouldLog('warn')) {
+            console.error('[WARN]', ...args);
+        }
+    },
+    error(...args) {
+        if (shouldLog('error')) {
+            console.error('[ERROR]', ...args);
+        }
+    },
+};

package/dist/markdown-transformer/docsToMarkdown.js

@@ -0,0 +1,259 @@
+// src/markdown-transformer/docsToMarkdown.ts
+/**
+ * Font families used by the markdown-to-docs direction for code styling.
+ * 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']);
+// --- Main Conversion ---
+/**
+ * Converts Google Docs JSON structure to a markdown string.
+ *
+ * Accepts the raw response from `docs.documents.get()`, or a subset with
+ * `{ body, lists }` (e.g. when extracting a specific tab).
+ *
+ * Handles headings, paragraphs, text formatting (bold, italic, strikethrough,
+ * underline, links, code), ordered & unordered lists with nesting, tables,
+ * and section breaks.
+ */
+export function docsJsonToMarkdown(docData) {
+    const body = docData.body;
+    if (!body?.content) {
+        return '';
+    }
+    const lists = docData.lists ?? {};
+    let markdown = '';
+    for (const element of body.content) {
+        if (element.paragraph) {
+            markdown += convertParagraph(element.paragraph, lists);
+        }
+        else if (element.table) {
+            markdown += convertTable(element.table);
+        }
+        else if (element.sectionBreak) {
+            markdown += '\n---\n\n';
+        }
+    }
+    return markdown.trim();
+}
+// --- Paragraph Conversion ---
+function convertParagraph(paragraph, lists) {
+    // 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);
+    // 3. Format based on type
+    if (headingLevel && text.trim()) {
+        const hashes = '#'.repeat(Math.min(headingLevel, 6));
+        return `${hashes} ${text.trim()}\n\n`;
+    }
+    if (listInfo && text.trim()) {
+        const indent = '  '.repeat(listInfo.nestingLevel);
+        const marker = listInfo.ordered ? `1.` : `-`;
+        return `${indent}${marker} ${text.trim()}\n`;
+    }
+    if (text.trim()) {
+        return `${text.trim()}\n\n`;
+    }
+    return '\n';
+}
+// --- Heading Detection ---
+function getHeadingLevel(paragraph) {
+    const styleType = paragraph.paragraphStyle?.namedStyleType;
+    if (!styleType)
+        return null;
+    if (styleType === 'TITLE')
+        return 1;
+    if (styleType === 'SUBTITLE')
+        return 2;
+    const match = styleType.match(/^HEADING_(\d)$/);
+    return match ? parseInt(match[1], 10) : null;
+}
+function getListInfo(paragraph, lists) {
+    if (!paragraph.bullet)
+        return null;
+    const nestingLevel = paragraph.bullet.nestingLevel ?? 0;
+    const listId = paragraph.bullet.listId;
+    let ordered = false;
+    if (listId && lists[listId]?.listProperties?.nestingLevels) {
+        const nestingLevels = lists[listId].listProperties.nestingLevels;
+        const level = nestingLevels[nestingLevel];
+        if (level) {
+            // glyphType is set for ordered lists (e.g., DECIMAL, ALPHA, ROMAN)
+            // glyphSymbol is set for unordered lists (e.g., bullet characters)
+            // If glyphType is present and not empty, it's ordered
+            if (level.glyphType && level.glyphType !== 'GLYPH_TYPE_UNSPECIFIED') {
+                ordered = true;
+            }
+        }
+    }
+    return { ordered, nestingLevel };
+}
+// --- Text Run Conversion ---
+function extractFormattedText(elements) {
+    let result = '';
+    for (const element of elements) {
+        if (element.textRun) {
+            result += convertTextRun(element.textRun);
+        }
+    }
+    return result;
+}
+function convertTextRun(textRun) {
+    let text = textRun.content ?? '';
+    const style = textRun.textStyle;
+    if (!style)
+        return text;
+    // Detect code-styled text (monospace font) -- wrap in backticks and skip
+    // other formatting since markdown code spans don't support nested formatting.
+    if (isCodeStyled(style)) {
+        const trimmed = text.replace(/\n$/, '');
+        if (trimmed) {
+            return `\`${trimmed}\`${text.endsWith('\n') ? '\n' : ''}`;
+        }
+        return text;
+    }
+    // Strip trailing newline before applying formatting markers, then re-add.
+    // This prevents markers from wrapping the newline (e.g., "**text\n**").
+    const trailingNewline = text.endsWith('\n');
+    const content = trailingNewline ? text.slice(0, -1) : text;
+    if (!content)
+        return text;
+    let formatted = content;
+    // Apply inline formatting (bold + italic combined, or individually)
+    if (style.bold && style.italic) {
+        formatted = `***${formatted}***`;
+    }
+    else if (style.bold) {
+        formatted = `**${formatted}**`;
+    }
+    else if (style.italic) {
+        formatted = `*${formatted}*`;
+    }
+    if (style.strikethrough) {
+        formatted = `~~${formatted}~~`;
+    }
+    if (style.underline && !style.link) {
+        formatted = `<u>${formatted}</u>`;
+    }
+    if (style.link?.url) {
+        formatted = `[${formatted}](${style.link.url})`;
+    }
+    return formatted + (trailingNewline ? '\n' : '');
+}
+function isCodeStyled(style) {
+    const fontFamily = style.weightedFontFamily?.fontFamily;
+    return typeof fontFamily === 'string' && CODE_FONT_FAMILIES.has(fontFamily);
+}
+// --- Table Conversion ---
+function convertTable(table) {
+    if (!table.tableRows || table.tableRows.length === 0) {
+        return '';
+    }
+    // Detect code block tables (1x1 table with monospace font or gray background)
+    if (isCodeBlockTable(table)) {
+        return convertCodeBlockTable(table);
+    }
+    let markdown = '\n';
+    let isFirstRow = true;
+    for (const row of table.tableRows) {
+        if (!row.tableCells)
+            continue;
+        let rowText = '|';
+        for (const cell of row.tableCells) {
+            const cellText = extractCellText(cell);
+            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 += ' --- |';
+            }
+            markdown += separator + '\n';
+            isFirstRow = false;
+        }
+    }
+    return markdown + '\n';
+}
+/**
+ * Detects if a table is a code block (1x1 table with monospace font or gray background).
+ * Google Docs "Code Block" building blocks are represented as styled 1x1 tables.
+ */
+function isCodeBlockTable(table) {
+    // Must be a 1x1 table
+    if (!table.tableRows || table.tableRows.length !== 1)
+        return false;
+    const row = table.tableRows[0];
+    if (!row.tableCells || row.tableCells.length !== 1)
+        return false;
+    const cell = row.tableCells[0];
+    // Check for gray/colored background on the cell
+    const cellStyle = cell.tableCellStyle;
+    if (cellStyle?.backgroundColor?.color?.rgbColor) {
+        const bg = cellStyle.backgroundColor.color.rgbColor;
+        // Detect light gray backgrounds (typical of code blocks)
+        // Allow a range of light grays
+        const r = bg.red ?? 0;
+        const g = bg.green ?? 0;
+        const b = bg.blue ?? 0;
+        if (r > 0.85 && g > 0.85 && b > 0.85 && r < 1 && g < 1 && b < 1) {
+            return true;
+        }
+    }
+    // Check for monospace font in cell content
+    if (cell.content) {
+        for (const element of cell.content) {
+            if (element.paragraph?.elements) {
+                for (const pe of element.paragraph.elements) {
+                    if (pe.textRun?.textStyle) {
+                        if (isCodeStyled(pe.textRun.textStyle)) {
+                            return true;
+                        }
+                    }
+                }
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Converts a code block table (1x1 table) to a fenced markdown code block.
+ */
+function convertCodeBlockTable(table) {
+    const cell = table.tableRows[0].tableCells[0];
+    let codeText = '';
+    if (cell.content) {
+        for (const element of cell.content) {
+            if (element.paragraph?.elements) {
+                for (const pe of element.paragraph.elements) {
+                    if (pe.textRun?.content) {
+                        codeText += pe.textRun.content;
+                    }
+                }
+            }
+        }
+    }
+    // Remove trailing newline (cells always end with one)
+    if (codeText.endsWith('\n')) {
+        codeText = codeText.slice(0, -1);
+    }
+    return '\n```\n' + codeText + '\n```\n\n';
+}
+function extractCellText(cell) {
+    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();
+                }
+            }
+        }
+    }
+    return text;
+}

package/dist/markdown-transformer/index.js

@@ -0,0 +1,126 @@
+// src/markdown-transformer/index.ts
+//
+// Public API for bidirectional markdown <-> Google Docs conversion.
+//
+// Main methods:
+//   extractMarkdown() - Fetch a Google Doc and return its content as markdown
+//   insertMarkdown()  - Convert markdown and insert it into a Google Doc
+//
+// Helper:
+//   docsJsonToMarkdown() - Convert already-fetched Docs JSON to markdown
+//
+import { docsJsonToMarkdown } from './docsToMarkdown.js';
+import { convertMarkdownToRequests } from './markdownToDocs.js';
+import { executeBatchUpdateWithSplitting, findTabById } from '../googleDocsApiHelpers.js';
+export { docsJsonToMarkdown } from './docsToMarkdown.js';
+/** Formats InsertMarkdownResult into a concise human-readable debug summary. */
+export function formatInsertResult(result) {
+    const lines = [];
+    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) {
+        lines.push(`    Delete phase: ${phases.delete.requests} requests, ${phases.delete.apiCalls} calls, ${phases.delete.elapsedMs}ms`);
+    }
+    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) {
+        lines.push(`    Format phase: ${phases.format.requests} requests, ${phases.format.apiCalls} calls, ${phases.format.elapsedMs}ms`);
+    }
+    return lines.join('\n');
+}
+// --- extractMarkdown ---
+/**
+ * Fetches a Google Document and returns its content as a markdown string.
+ *
+ * @param docs - An authenticated Google Docs API client
+ * @param documentId - The document ID (from the URL)
+ * @param options - Optional: tabId to target a specific tab
+ * @returns The document content as markdown
+ */
+export async function extractMarkdown(docs, documentId, options) {
+    const tabId = options?.tabId;
+    const res = await docs.documents.get({
+        documentId,
+        includeTabsContent: !!tabId,
+        fields: tabId ? '*' : '*',
+    });
+    if (tabId) {
+        const targetTab = findTabById(res.data, tabId);
+        if (!targetTab) {
+            throw new Error(`Tab with ID "${tabId}" not found in document.`);
+        }
+        if (!targetTab.documentTab) {
+            throw new Error(`Tab "${tabId}" does not have content (may not be a document tab).`);
+        }
+        return docsJsonToMarkdown({
+            body: targetTab.documentTab.body,
+            lists: targetTab.documentTab.lists,
+        });
+    }
+    return docsJsonToMarkdown({
+        body: res.data.body,
+        lists: res.data.lists,
+    });
+}
+// --- insertMarkdown ---
+/**
+ * Converts markdown to Google Docs formatting and inserts it into a document.
+ *
+ * Handles the full pipeline: markdown parsing, request generation, and batch
+ * execution against the Docs API. Callers never see raw API requests.
+ *
+ * @param docs - An authenticated Google Docs API client
+ * @param documentId - The document ID
+ * @param markdown - The markdown content to insert
+ * @param options - Optional: startIndex (default 1), tabId
+ * @returns Debug metadata about the operation (request counts, timing, API calls)
+ */
+export async function insertMarkdown(docs, documentId, markdown, options) {
+    const overallStart = performance.now();
+    const startIndex = options?.startIndex ?? 1;
+    const tabId = options?.tabId;
+    const parseStart = performance.now();
+    const conversionOptions = options?.firstHeadingAsTitle
+        ? { firstHeadingAsTitle: true }
+        : undefined;
+    const requests = convertMarkdownToRequests(markdown, startIndex, tabId, conversionOptions);
+    const parseElapsedMs = Math.round(performance.now() - parseStart);
+    // Count requests by type
+    const requestsByType = {};
+    for (const r of requests) {
+        const type = Object.keys(r)[0];
+        requestsByType[type] = (requestsByType[type] || 0) + 1;
+    }
+    if (requests.length === 0) {
+        return {
+            totalRequests: 0,
+            requestsByType,
+            parseElapsedMs,
+            batchUpdate: {
+                totalRequests: 0,
+                phases: {
+                    delete: { requests: 0, apiCalls: 0, elapsedMs: 0 },
+                    insert: { requests: 0, apiCalls: 0, elapsedMs: 0 },
+                    format: { requests: 0, apiCalls: 0, elapsedMs: 0 },
+                },
+                totalApiCalls: 0,
+                totalElapsedMs: 0,
+            },
+            totalElapsedMs: Math.round(performance.now() - overallStart),
+        };
+    }
+    const batchUpdate = await executeBatchUpdateWithSplitting(docs, documentId, requests);
+    return {
+        totalRequests: requests.length,
+        requestsByType,
+        parseElapsedMs,
+        batchUpdate,
+        totalElapsedMs: Math.round(performance.now() - overallStart),
+    };
+}