@alanse/mcp-server-google-workspace 0.2.1 → 1.0.0

package/README.md

@@ -1,9 +1,9 @@
 # MCP Server - Google Workspace
 
-**The most comprehensive MCP server for Google Workspace** - Complete programmatic control over Sheets, Drive, and future Docs, Calendar, Forms integration.
+**The most comprehensive MCP server for Google Workspace** - Complete programmatic control over Sheets, Docs, Drive, and future Calendar, Forms integration.
 
-🚀 **Current Status**: 59 tools (Drive: 2, Sheets: 57)
-📅 **Roadmap**: Google Docs, Calendar, Forms, Gmail, Slides
+🚀 **Current Status**: 82 tools (Drive: 2, Sheets: 57, Docs: 23)
+📅 **Roadmap**: Calendar, Forms, Gmail, Slides
 
 Extended implementation by Alanse inc.
 
@@ -11,15 +11,34 @@ Extended implementation by Alanse inc.
 
 ## 🚀 Features
 
-### 📊 Extended Google Sheets API Implementation
+### 📊 Extended Google Workspace API Implementation
 
-**59 Total Tools** = 2 GDrive + **57 Google Sheets** operations
+**82 Total Tools** = 2 GDrive + **57 Google Sheets** + **23 Google Docs** operations
 
 #### Tool Categories
 
 **Google Drive Operations (2 tools)**
 - Search & File Management
 
+**Google Docs Operations (23 tools)**
+
+**Basic Operations (4 tools)**
+- Create, Read, Get Metadata, List Documents
+
+**Content & Formatting (10 tools)**
+- Insert/Update/Delete/Replace/Append Text
+- Format Text (Bold, Italic, Font, Color)
+- Create Headings (H1-H6)
+- Create Lists (Bulleted/Numbered)
+- Set Paragraph Alignment & Apply Styles
+
+**Elements & Advanced (9 tools)**
+- Insert Images, Tables, Page Breaks, Links
+- Insert Table of Contents
+- Batch Update Operations
+- Merge Documents, Export to PDF/DOCX/HTML
+- Suggestion Mode
+
 **Sheet Management (13 tools)**
 - Create, Read, List, Add, Delete, Rename Sheets
 - Insert/Delete Rows & Columns
@@ -155,6 +174,91 @@ Replace `<YOUR_CLIENT_ID>`, `<YOUR_CLIENT_SECRET>`, and `/path/to/config/directo
 
 **Goal**: 100+ tools covering the entire Google Workspace ecosystem
 
+## 🛠️ Development
+
+### Prerequisites
+
+- Node.js 20 or higher
+- npm or pnpm
+- Google Cloud Platform account with OAuth credentials
+
+### Local Development
+
+```bash
+# Clone the repository
+git clone https://github.com/alanse-inc/mcp-server-google-workspace.git
+cd mcp-server-google-workspace
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Run tests
+npm test
+
+# Watch mode for development
+npm run watch
+```
+
+### Testing
+
+The project uses [Vitest](https://vitest.dev/) for testing:
+
+```bash
+# Run all tests
+npm test
+
+# Watch mode
+npm run test:watch
+
+# UI mode
+npm run test:ui
+
+# Coverage report
+npm run test:coverage
+```
+
+### Release Process
+
+This project uses [release-please](https://github.com/googleapis/release-please) for automated releases.
+
+**How it works:**
+
+1. Follow [Conventional Commits](https://www.conventionalcommits.org/) specification for commit messages
+2. When commits are merged to `main`, release-please creates/updates a release PR
+3. Merging the release PR triggers:
+   - CHANGELOG.md update
+   - Version bump in package.json
+   - GitHub Release creation
+   - npm package publication
+
+**Commit message format:**
+
+```text
+feat: add new feature
+fix: fix a bug
+docs: update documentation
+chore: update dependencies
+refactor: code refactoring
+test: add tests
+```
+
+**Example workflow:**
+
+```bash
+# Make changes
+git checkout -b feature/new-tool
+# ... make changes ...
+git commit -m "feat: add gdocs_insert_table tool"
+git push origin feature/new-tool
+
+# Create PR and merge to main
+# → release-please creates a release PR automatically
+# → Merge the release PR to publish
+```
+
 ## 📄 License
 
 This project is licensed under the **Elastic License 2.0**.

package/dist/auth.js

@@ -5,6 +5,7 @@ import path from "path";
 export const SCOPES = [
     "https://www.googleapis.com/auth/drive.readonly",
     "https://www.googleapis.com/auth/spreadsheets",
+    "https://www.googleapis.com/auth/documents",
 ];
 // Get credentials directory from environment variable or use default
 const CREDS_DIR = process.env.GWORKSPACE_CREDS_DIR ||

package/dist/index.js

@@ -9,7 +9,7 @@ import { tools } from "./tools/index.js";
 const drive = google.drive("v3");
 const server = new Server({
     name: "@alanse/mcp-server-google-workspace",
-    version: "0.2.1",
+    version: "0.2.2",
 }, {
     capabilities: {
         resources: {

package/dist/lib/document-id-resolver.js

@@ -0,0 +1,76 @@
+/**
+ * DocumentIdResolver - Resolves various document ID formats across Google Workspace
+ *
+ * Supports:
+ * - Direct document IDs
+ * - Full Google Workspace URLs (Docs, Sheets, Slides, Drive)
+ * - Service type detection
+ */
+export class DocumentIdResolver {
+    static URL_PATTERNS = {
+        docs: /docs\.google\.com\/document\/d\/([a-zA-Z0-9-_]+)/,
+        sheets: /docs\.google\.com\/spreadsheets\/d\/([a-zA-Z0-9-_]+)/,
+        slides: /docs\.google\.com\/presentation\/d\/([a-zA-Z0-9-_]+)/,
+        drive: /drive\.google\.com\/file\/d\/([a-zA-Z0-9-_]+)/,
+    };
+    static ID_PATTERN = /^[a-zA-Z0-9-_]{25,}$/;
+    /**
+     * Resolve a document reference from ID or URL
+     */
+    static resolve(input) {
+        // Try URL extraction first
+        const fromUrl = this.extractFromUrl(input);
+        if (fromUrl) {
+            return { id: fromUrl.id, type: fromUrl.type, url: input };
+        }
+        // Validate as direct ID
+        if (this.validate(input)) {
+            return { id: input, type: "unknown" };
+        }
+        throw new Error(`Invalid document reference: ${input}. Expected a Google Workspace URL or document ID.`);
+    }
+    /**
+     * Extract document ID from Google Workspace URL
+     */
+    static extractFromUrl(url) {
+        for (const [type, pattern] of Object.entries(this.URL_PATTERNS)) {
+            const match = url.match(pattern);
+            if (match) {
+                return {
+                    id: match[1],
+                    type: type,
+                };
+            }
+        }
+        return null;
+    }
+    /**
+     * Validate document ID format
+     */
+    static validate(id, type) {
+        if (!this.ID_PATTERN.test(id)) {
+            return false;
+        }
+        // Additional type-specific validation could go here
+        return true;
+    }
+    /**
+     * Get service type from URL or ID
+     */
+    static getServiceType(input) {
+        const ref = this.resolve(input);
+        return ref.type;
+    }
+    /**
+     * Create a Google Workspace URL from document ID and type
+     */
+    static createUrl(documentId, type) {
+        const urlTemplates = {
+            docs: `https://docs.google.com/document/d/${documentId}/edit`,
+            sheets: `https://docs.google.com/spreadsheets/d/${documentId}/edit`,
+            slides: `https://docs.google.com/presentation/d/${documentId}/edit`,
+            drive: `https://drive.google.com/file/d/${documentId}/view`,
+        };
+        return urlTemplates[type];
+    }
+}

package/dist/lib/response-formatter.js

@@ -0,0 +1,82 @@
+/**
+ * ResponseFormatter - Consistent response formatting across all tools
+ */
+export class ResponseFormatter {
+    /**
+     * Create a success response
+     */
+    static success(data, message) {
+        let text;
+        if (message) {
+            // If message is provided, combine it with data
+            if (typeof data === "object" && data !== null) {
+                text = `${message}\n\n${JSON.stringify(data, null, 2)}`;
+            }
+            else {
+                text = message;
+            }
+        }
+        else {
+            // Format data only
+            text = typeof data === "object" && data !== null
+                ? JSON.stringify(data, null, 2)
+                : String(data);
+        }
+        return {
+            content: [{ type: "text", text }],
+            isError: false,
+        };
+    }
+    /**
+     * Create an error response
+     */
+    static error(error) {
+        const message = error instanceof Error ? error.message : error;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error: ${message}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    /**
+     * Format Google Docs document data
+     */
+    static formatDocumentData(doc) {
+        const formatted = {
+            documentId: doc.documentId,
+            title: doc.title,
+            revisionId: doc.revisionId,
+            suggestionsViewMode: doc.suggestionsViewMode,
+        };
+        return JSON.stringify(formatted, null, 2);
+    }
+    /**
+     * Format metadata
+     */
+    static formatMetadata(metadata) {
+        return JSON.stringify(metadata, null, 2);
+    }
+    /**
+     * Format a simple success message
+     */
+    static simpleSuccess(message) {
+        return {
+            content: [{ type: "text", text: message }],
+            isError: false,
+        };
+    }
+    /**
+     * Format operation result with details
+     */
+    static operationResult(operation, details) {
+        const text = `${operation} completed successfully\n\n${JSON.stringify(details, null, 2)}`;
+        return {
+            content: [{ type: "text", text }],
+            isError: false,
+        };
+    }
+}

package/dist/lib/validation.js

@@ -0,0 +1,112 @@
+/**
+ * Validation - Shared validation logic for tool inputs
+ */
+export class Validator {
+    /**
+     * Validate that required fields exist in an object
+     */
+    static validateRequired(obj, fields) {
+        const missing = fields.filter((field) => obj[field] === undefined);
+        if (missing.length > 0) {
+            throw new Error(`Missing required fields: ${missing.join(", ")}`);
+        }
+    }
+    /**
+     * Validate RGB color values (0-1 range)
+     */
+    static validateColor(color) {
+        const values = [color.red, color.green, color.blue];
+        return values.every((v) => typeof v === "number" && v >= 0 && v <= 1);
+    }
+    /**
+     * Validate dimension type
+     */
+    static validateDimension(dimension) {
+        return dimension === "ROWS" || dimension === "COLUMNS";
+    }
+    /**
+     * Validate text style object
+     */
+    static validateTextStyle(style) {
+        // Check for at least one style property
+        const validProperties = [
+            "bold",
+            "italic",
+            "underline",
+            "fontSize",
+            "fontFamily",
+            "foregroundColor",
+            "backgroundColor",
+        ];
+        const hasValidProperty = validProperties.some((prop) => style[prop] !== undefined);
+        if (!hasValidProperty) {
+            return false;
+        }
+        // Validate color properties if they exist
+        if (style.foregroundColor && !this.validateColor(style.foregroundColor)) {
+            return false;
+        }
+        if (style.backgroundColor && !this.validateColor(style.backgroundColor)) {
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Validate index is a positive integer
+     */
+    static validateIndex(index, allowZero = false) {
+        if (!Number.isInteger(index)) {
+            return false;
+        }
+        return allowZero ? index >= 0 : index > 0;
+    }
+    /**
+     * Validate range (startIndex < endIndex)
+     */
+    static validateRange(startIndex, endIndex) {
+        return (this.validateIndex(startIndex) &&
+            this.validateIndex(endIndex) &&
+            startIndex < endIndex);
+    }
+    /**
+     * Validate alignment value
+     */
+    static validateAlignment(alignment) {
+        return ["START", "CENTER", "END", "JUSTIFIED"].includes(alignment);
+    }
+    /**
+     * Validate named style type
+     */
+    static validateNamedStyleType(styleType) {
+        const validTypes = [
+            "NORMAL_TEXT",
+            "HEADING_1",
+            "HEADING_2",
+            "HEADING_3",
+            "HEADING_4",
+            "HEADING_5",
+            "HEADING_6",
+            "TITLE",
+            "SUBTITLE",
+        ];
+        return validTypes.includes(styleType);
+    }
+    /**
+     * Validate URL format
+     */
+    static validateUrl(url) {
+        try {
+            new URL(url);
+            return url.startsWith("http://") || url.startsWith("https://");
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Validate positive number
+     */
+    static validatePositiveNumber(value) {
+        return typeof value === "number" && value > 0 && !isNaN(value);
+    }
+}

package/dist/tools/docs/basic/gdocs_create.js

@@ -0,0 +1,37 @@
+import { google } from "googleapis";
+import { ResponseFormatter } from "../../../lib/response-formatter.js";
+export const schema = {
+    name: "gdocs_create",
+    description: "Create a new Google Document",
+    inputSchema: {
+        type: "object",
+        properties: {
+            title: {
+                type: "string",
+                description: "The title of the new document",
+            },
+        },
+        required: ["title"],
+    },
+};
+export async function createDocument(args) {
+    try {
+        const docs = google.docs("v1");
+        const response = await docs.documents.create({
+            requestBody: {
+                title: args.title,
+            },
+        });
+        const documentId = response.data.documentId;
+        const documentUrl = `https://docs.google.com/document/d/${documentId}/edit`;
+        return ResponseFormatter.success({
+            documentId,
+            documentUrl,
+            title: response.data.title,
+            revisionId: response.data.revisionId,
+        }, "Document created successfully");
+    }
+    catch (error) {
+        return ResponseFormatter.error(error);
+    }
+}

package/dist/tools/docs/basic/gdocs_get_metadata.js

@@ -0,0 +1,45 @@
+import { google } from "googleapis";
+import { ResponseFormatter } from "../../../lib/response-formatter.js";
+import { DocumentIdResolver } from "../../../lib/document-id-resolver.js";
+export const schema = {
+    name: "gdocs_get_metadata",
+    description: "Get metadata for a Google Document including title, revision ID, and document style. Accepts either a document ID or a full Google Docs URL.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            documentId: {
+                type: "string",
+                description: "Document ID or full Google Docs URL (e.g., https://docs.google.com/document/d/DOCUMENT_ID/edit)",
+            },
+        },
+        required: ["documentId"],
+    },
+};
+export async function getMetadata(args) {
+    try {
+        // Resolve document ID from URL if needed
+        const docRef = DocumentIdResolver.resolve(args.documentId);
+        const documentId = docRef.id;
+        const docs = google.docs("v1");
+        const response = await docs.documents.get({
+            documentId,
+        });
+        const doc = response.data;
+        const metadata = {
+            documentId: doc.documentId,
+            title: doc.title,
+            revisionId: doc.revisionId,
+            suggestionsViewMode: doc.suggestionsViewMode,
+            documentStyle: doc.documentStyle,
+            namedStyles: doc.namedStyles,
+            headers: Object.keys(doc.headers || {}).length,
+            footers: Object.keys(doc.footers || {}).length,
+            inlineObjects: Object.keys(doc.inlineObjects || {}).length,
+            lists: Object.keys(doc.lists || {}).length,
+        };
+        return ResponseFormatter.success(metadata, "Document metadata retrieved successfully");
+    }
+    catch (error) {
+        return ResponseFormatter.error(error);
+    }
+}

package/dist/tools/docs/basic/gdocs_list_documents.js

@@ -0,0 +1,59 @@
+import { google } from "googleapis";
+import { ResponseFormatter } from "../../../lib/response-formatter.js";
+export const schema = {
+    name: "gdocs_list_documents",
+    description: "List Google Documents from Google Drive. Use query parameter to filter by name, owner, etc.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            query: {
+                type: "string",
+                description: "Search query to filter documents (e.g., 'name contains \"report\"'). Default: list all documents",
+            },
+            pageToken: {
+                type: "string",
+                description: "Token for pagination to get the next page of results",
+            },
+            pageSize: {
+                type: "number",
+                description: "Maximum number of documents to return (default: 10, max: 100)",
+            },
+        },
+        required: [],
+    },
+};
+export async function listDocuments(args) {
+    try {
+        const drive = google.drive("v3");
+        // Build query to find Google Docs files
+        let query = "mimeType='application/vnd.google-apps.document'";
+        if (args.query) {
+            query += ` and ${args.query}`;
+        }
+        const response = await drive.files.list({
+            q: query,
+            pageSize: args.pageSize || 10,
+            pageToken: args.pageToken,
+            fields: "nextPageToken, files(id, name, createdTime, modifiedTime, owners, webViewLink)",
+            orderBy: "modifiedTime desc",
+        });
+        const files = response.data.files || [];
+        const documents = files.map((file) => ({
+            documentId: file.id,
+            name: file.name,
+            createdTime: file.createdTime,
+            modifiedTime: file.modifiedTime,
+            owners: file.owners?.map((owner) => owner.emailAddress),
+            webViewLink: file.webViewLink,
+        }));
+        const result = {
+            documents,
+            count: documents.length,
+            nextPageToken: response.data.nextPageToken,
+        };
+        return ResponseFormatter.success(result, `Found ${documents.length} document(s)`);
+    }
+    catch (error) {
+        return ResponseFormatter.error(error);
+    }
+}

package/dist/tools/docs/basic/gdocs_read.js

@@ -0,0 +1,62 @@
+import { google } from "googleapis";
+import { ResponseFormatter } from "../../../lib/response-formatter.js";
+import { DocumentIdResolver } from "../../../lib/document-id-resolver.js";
+export const schema = {
+    name: "gdocs_read",
+    description: "Read content from a Google Document. Accepts either a document ID or a full Google Docs URL.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            documentId: {
+                type: "string",
+                description: "Document ID or full Google Docs URL (e.g., https://docs.google.com/document/d/DOCUMENT_ID/edit)",
+            },
+            includeFormatting: {
+                type: "boolean",
+                description: "Whether to include text formatting information (default: false)",
+            },
+        },
+        required: ["documentId"],
+    },
+};
+export async function readDocument(args) {
+    try {
+        // Resolve document ID from URL if needed
+        const docRef = DocumentIdResolver.resolve(args.documentId);
+        const documentId = docRef.id;
+        const docs = google.docs("v1");
+        const response = await docs.documents.get({
+            documentId,
+        });
+        const doc = response.data;
+        // Extract plain text content
+        let textContent = "";
+        if (doc.body?.content) {
+            for (const element of doc.body.content) {
+                if (element.paragraph?.elements) {
+                    for (const textElement of element.paragraph.elements) {
+                        if (textElement.textRun?.content) {
+                            textContent += textElement.textRun.content;
+                        }
+                    }
+                }
+            }
+        }
+        const result = {
+            documentId: doc.documentId,
+            title: doc.title,
+            revisionId: doc.revisionId,
+            textContent,
+        };
+        // Include formatting if requested
+        if (args.includeFormatting) {
+            result.body = doc.body;
+            result.documentStyle = doc.documentStyle;
+            result.namedStyles = doc.namedStyles;
+        }
+        return ResponseFormatter.success(result, "Document read successfully");
+    }
+    catch (error) {
+        return ResponseFormatter.error(error);
+    }
+}

package/dist/tools/docs/content/gdocs_append_text.js

@@ -0,0 +1,57 @@
+import { google } from "googleapis";
+import { ResponseFormatter } from "../../../lib/response-formatter.js";
+import { DocumentIdResolver } from "../../../lib/document-id-resolver.js";
+export const schema = {
+    name: "gdocs_append_text",
+    description: "Append text to the end of a Google Document.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            documentId: {
+                type: "string",
+                description: "Document ID or full Google Docs URL",
+            },
+            text: {
+                type: "string",
+                description: "Text to append to the end of the document",
+            },
+        },
+        required: ["documentId", "text"],
+    },
+};
+export async function appendText(args) {
+    try {
+        // Resolve document ID from URL if needed
+        const docRef = DocumentIdResolver.resolve(args.documentId);
+        const documentId = docRef.id;
+        const docs = google.docs("v1");
+        // First get the document to find the end index
+        const doc = await docs.documents.get({ documentId });
+        const endIndex = doc.data.body?.content?.[doc.data.body.content.length - 1]?.endIndex || 1;
+        // Insert text at the end (endIndex - 1 because endIndex is exclusive)
+        const response = await docs.documents.batchUpdate({
+            documentId,
+            requestBody: {
+                requests: [
+                    {
+                        insertText: {
+                            text: args.text,
+                            location: {
+                                index: endIndex - 1,
+                            },
+                        },
+                    },
+                ],
+            },
+        });
+        return ResponseFormatter.success({
+            documentId,
+            appendedText: args.text,
+            appendedAt: endIndex - 1,
+            length: args.text.length,
+        }, "Text appended successfully");
+    }
+    catch (error) {
+        return ResponseFormatter.error(error);
+    }
+}