gdocs-mcp 0.4.1 → 0.4.2

package/dist/index.js

@@ -29,7 +29,8 @@ import { CopyDocumentSchema, copyDocument } from './tools/copy-document.js';
 import { DeleteDocumentSchema, deleteDocument } from './tools/delete-document.js';
 import { GetCommentsSchema, getComments } from './tools/get-comments.js';
 import { AddCommentSchema, addComment } from './tools/add-comment.js';
-const VERSION = '0.4.0';
+import { ReadDocumentStructureSchema, readDocumentStructure } from './tools/read-document-structure.js';
+const VERSION = '0.4.2';
 const QUIET = process.env.GDOCS_MCP_QUIET === '1';
 const server = new McpServer({
     name: 'gdocs-mcp',
@@ -125,6 +126,8 @@ registerTool('copy_document', 'Create a copy of a Google Doc with a new title. I
 registerTool('delete_document', 'Move a Google Doc to trash. Requires confirmTitle matching the exact document title.', DeleteDocumentSchema, deleteDocument);
 registerTool('get_comments', 'List comments on a document with author, content, resolved status, and replies.', GetCommentsSchema, getComments);
 registerTool('add_comment', 'Add a comment anchored to specific text in the document. Anchors to first occurrence of quotedText.', AddCommentSchema, addComment);
+// 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);
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/dist/tools/read-document-structure.d.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+export declare const ReadDocumentStructureSchema: z.ZodObject<{
+    documentId: z.ZodString;
+}, z.core.$strip>;
+interface StructureElement {
+    type: 'paragraph' | 'table' | 'sectionBreak' | 'tableOfContents';
+    startIndex: number;
+    endIndex: number;
+    style?: string;
+    text?: string;
+    truncated?: boolean;
+    rows?: number;
+    cols?: number;
+    listId?: string;
+    nestingLevel?: number;
+}
+export declare function readDocumentStructure(args: z.infer<typeof ReadDocumentStructureSchema>): Promise<{
+    documentId: string;
+    title: string;
+    totalElements: number;
+    elements: StructureElement[];
+    _apiMs: number;
+}>;
+export {};

package/dist/tools/read-document-structure.js

@@ -0,0 +1,116 @@
+import { google } from 'googleapis';
+import { z } from 'zod';
+import { getAuthClient } from '../auth/google-auth.js';
+const TEXT_PREVIEW_LENGTH = 80;
+// Field mask: only structural data, no full text styling
+const FIELD_MASK = [
+    'title',
+    'body.content.startIndex',
+    'body.content.endIndex',
+    'body.content.paragraph.paragraphStyle.namedStyleType',
+    'body.content.paragraph.bullet',
+    'body.content.paragraph.elements.startIndex',
+    'body.content.paragraph.elements.endIndex',
+    'body.content.paragraph.elements.textRun.content',
+    'body.content.paragraph.elements.inlineObjectElement',
+    'body.content.table.rows',
+    'body.content.table.columns',
+    'body.content.sectionBreak',
+    'body.content.tableOfContents',
+].join(',');
+export const ReadDocumentStructureSchema = z.object({
+    documentId: z.string().describe('The Google Doc document ID'),
+});
+export async function readDocumentStructure(args) {
+    const auth = getAuthClient();
+    const docs = google.docs({ version: 'v1', auth });
+    const apiStart = performance.now();
+    const res = await docs.documents.get({
+        documentId: args.documentId,
+        fields: FIELD_MASK,
+    });
+    const apiMs = Math.round(performance.now() - apiStart);
+    const content = res.data.body?.content || [];
+    const elements = [];
+    for (const element of content) {
+        const startIndex = element.startIndex ?? 0;
+        const endIndex = element.endIndex ?? 0;
+        if (element.sectionBreak !== undefined) {
+            elements.push({ type: 'sectionBreak', startIndex, endIndex });
+            continue;
+        }
+        if (element.tableOfContents !== undefined) {
+            elements.push({ type: 'tableOfContents', startIndex, endIndex });
+            continue;
+        }
+        if (element.table) {
+            elements.push({
+                type: 'table',
+                startIndex,
+                endIndex,
+                rows: element.table.rows ?? 0,
+                cols: element.table.columns ?? 0,
+            });
+            continue;
+        }
+        if (element.paragraph) {
+            const style = element.paragraph.paragraphStyle?.namedStyleType || 'NORMAL_TEXT';
+            // Build text preview from elements
+            let hasInlineObject = false;
+            let fullText = '';
+            for (const el of element.paragraph.elements || []) {
+                if (el.inlineObjectElement) {
+                    hasInlineObject = true;
+                }
+                if (el.textRun?.content) {
+                    fullText += el.textRun.content;
+                }
+            }
+            // Clean trailing newline
+            fullText = fullText.replace(/\n$/, '');
+            // Determine text preview
+            let text;
+            let truncated;
+            if (!fullText && hasInlineObject) {
+                text = '[image]';
+                truncated = false;
+            }
+            else if (fullText.length > TEXT_PREVIEW_LENGTH) {
+                text = fullText.substring(0, TEXT_PREVIEW_LENGTH) + '...';
+                truncated = true;
+            }
+            else {
+                text = fullText;
+                truncated = false;
+            }
+            const entry = {
+                type: 'paragraph',
+                startIndex,
+                endIndex,
+                style,
+                text,
+                truncated,
+            };
+            // Add list metadata if present
+            const bullet = element.paragraph.bullet;
+            if (bullet) {
+                if (bullet.listId)
+                    entry.listId = bullet.listId;
+                if (bullet.nestingLevel !== undefined && bullet.nestingLevel !== null) {
+                    entry.nestingLevel = bullet.nestingLevel;
+                }
+                else if (bullet.listId) {
+                    entry.nestingLevel = 0;
+                }
+            }
+            elements.push(entry);
+        }
+    }
+    return {
+        documentId: args.documentId,
+        title: res.data.title || 'Untitled',
+        totalElements: elements.length,
+        elements,
+        _apiMs: apiMs,
+    };
+}

package/package.json

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