mcp-google-extras 1.0.0

package/dist/index.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+// src/index.ts
+//
+// Single entry point for the Google Docs MCP Server.
+//
+// Usage:
+//   mcp-google-extras          Start the MCP server (default)
+//   mcp-google-extras auth     Run the interactive OAuth flow
+import { FastMCP } from 'fastmcp';
+import { buildCachedToolsListPayload, collectToolsWhileRegistering, installCachedToolsListHandler, } from './cachedToolsList.js';
+import { initializeGoogleClient } from './clients.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 ---
+// Set up process-level unhandled error/rejection handlers to prevent crashes
+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: 'mcp-google-extras',
+    version: '1.0.0',
+});
+const registeredTools = [];
+collectToolsWhileRegistering(server, registeredTools);
+registerAllTools(server);
+try {
+    await initializeGoogleClient();
+    logger.info('Starting Ultimate Google Docs & Sheets MCP server...');
+    const cachedToolsList = await buildCachedToolsListPayload(registeredTools);
+    await server.start({ transportType: 'stdio' });
+    installCachedToolsListHandler(server, cachedToolsList);
+    logger.info('MCP Server running using stdio. Awaiting client connection...');
+    logger.info('Process-level error handling configured to prevent crashes from timeout errors.');
+}
+catch (startError) {
+    logger.error('FATAL: Server failed to start:', startError.message || startError);
+    process.exit(1);
+}

package/dist/logger.js

@@ -0,0 +1,58 @@
+// src/logger.ts
+//
+// Centralized logger with LOG_LEVEL support.
+//
+// Log levels (from most to least verbose):
+//   debug  - Detailed diagnostic info (text range mapping, request building, etc.)
+//   info   - General operational messages (server started, auth succeeded, etc.)
+//   warn   - Potentially harmful situations (missing content, fallback behavior)
+//   error  - Error conditions (API failures, auth failures, etc.)
+//
+// Set via the LOG_LEVEL environment variable. Defaults to "info".
+// Example: LOG_LEVEL=debug npm start
+//
+// MCP servers communicate over stdout, so all log output goes to stderr.
+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();
+/** Re-read LOG_LEVEL from the environment (useful for testing). */
+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),
+    };
+}