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

package/LICENSE

@@ -1,21 +1,95 @@
-MIT License
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
 
 Copyright (c) 2026 Alanse inc.
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor's trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that
+organization. **control** means ownership of substantially all the assets of an
+entity, or the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

package/README.md

@@ -1,32 +1,44 @@
 # 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
 
-This is an extended version of [@isaacphi/mcp-gdrive](https://github.com/isaacphi/mcp-gdrive), adding **53 additional Google Sheets API tools** for complete spreadsheet management and preparing for comprehensive Google Workspace coverage.
+Extended implementation by Alanse inc.
 
-## Credits
-
-This project is based on:
-- Original code by **Anthropic, PBC** from [MCP Servers](https://github.com/modelcontextprotocol/servers/tree/main/src/gdrive) (MIT License)
-- Enhanced by **Phil Isaac** in [@isaacphi/mcp-gdrive](https://github.com/isaacphi/mcp-gdrive) (MIT License)
-- **Extended implementation** by **Alanse株式会社 / Daichi Okazaki** (2026)
-
-All contributions are licensed under the MIT License.
+---
 
 ## 🚀 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
@@ -65,7 +77,7 @@ For complete tool documentation, see [docs/api-comparison.md](./docs/api-compari
 
 The server provides access to Google Drive files:
 
-- **Files** (`gdrive:///<file_id>`)
+- **Files** (`gworkspace:///<file_id>`)
   - Supports all file types
   - Google Workspace files are automatically exported:
     - Docs → Markdown
@@ -83,12 +95,12 @@ The server provides access to Google Drive files:
 5. In order to allow interaction with sheets and docs you will also need to enable the [Google Sheets API](https://console.cloud.google.com/apis/api/sheets.googleapis.com/) and [Google Docs API](https://console.cloud.google.com/marketplace/product/google/docs.googleapis.com) in your workspaces Enabled API and Services section.
 6. [Create an OAuth Client ID](https://console.cloud.google.com/apis/credentials/oauthclient) for application type "Desktop App"
 7. Download the JSON file of your client's OAuth keys
-8. Rename the key file to `gcp-oauth.keys.json` and place into the path you specify with `GDRIVE_CREDS_DIR` (i.e. `/Users/username/.config/mcp-gdrive`)
+8. Rename the key file to `gcp-oauth.keys.json` and place into the path you specify with `GWORKSPACE_CREDS_DIR` (i.e. `/Users/username/.config/mcp-google-workspace`)
 9. Note your OAuth Client ID and Client Secret. They must be provided as environment variables along with your configuration directory.
 10. You will also need to setup a .env file within the project with the following fields. You can find the Client ID and Client Secret in the Credentials section of the Google Cloud Console.
 
-```
-GDRIVE_CREDS_DIR=/path/to/config/directory
+```bash
+GWORKSPACE_CREDS_DIR=/path/to/config/directory
 CLIENT_ID=<CLIENT_ID>
 CLIENT_SECRET=<CLIENT_SECRET>
 ```
@@ -101,9 +113,7 @@ Next you will need to run `node ./dist/index.js` to trigger the authentication s
 
 You will be prompted to authenticate with your browser. You must authenticate with an account in the same organization as your Google Cloud project.
 
-Your OAuth token is saved in the directory specified by the `GDRIVE_CREDS_DIR` environment variable.
-
-![Authentication Prompt](https://i.imgur.com/TbyV6Yq.png)
+Your OAuth token is saved in the directory specified by the `GWORKSPACE_CREDS_DIR` environment variable.
 
 ### Usage with Desktop App
 
@@ -118,13 +128,28 @@ To integrate this server with the desktop app, add the following to your app's s
       "env": {
         "CLIENT_ID": "<CLIENT_ID>",
         "CLIENT_SECRET": "<CLIENT_SECRET>",
-        "GDRIVE_CREDS_DIR": "/path/to/config/directory"
+        "GWORKSPACE_CREDS_DIR": "/path/to/config/directory"
       }
     }
   }
 }
 ```
 
+### Usage with Claude Code CLI
+
+To add this server to Claude Code CLI, use the following command:
+
+```bash
+claude mcp add google-workspace \
+  -e CLIENT_ID=<YOUR_CLIENT_ID> \
+  -e CLIENT_SECRET=<YOUR_CLIENT_SECRET> \
+  -e GWORKSPACE_CREDS_DIR=/path/to/config/directory \
+  -- npx -y @alanse/mcp-server-google-workspace \
+  -s user
+```
+
+Replace `<YOUR_CLIENT_ID>`, `<YOUR_CLIENT_SECRET>`, and `/path/to/config/directory` with your actual values.
+
 ## 📈 Project Status
 
 ✅ **Phase 1-12 Complete** (2026-01-06)
@@ -149,25 +174,99 @@ To integrate this server with the desktop app, add the following to your app's s
 
 **Goal**: 100+ tools covering the entire Google Workspace ecosystem
 
-## 📄 License
+## 🛠️ Development
+
+### Prerequisites
 
-This project is licensed under the **MIT License**.
+- Node.js 20 or higher
+- npm or pnpm
+- Google Cloud Platform account with OAuth credentials
 
-### Copyright Notices
+### Local Development
 
-- Original code: © 2024 Anthropic, PBC
-- Base implementation: © 2024 Phil Isaac
-- Extended implementation: © 2026 Alanse株式会社 / Daichi Okazaki
+```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
+```
 
-You are free to use, modify, and distribute this software under the terms of the MIT License. See the [LICENSE](./LICENSE) file for details.
+### 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
 
-## 🙏 Acknowledgments
+This project is licensed under the **Elastic License 2.0**.
 
-Special thanks to:
-- **Anthropic, PBC** for the original MCP server implementation
-- **Phil Isaac** for the enhanced Google Drive & Sheets integration
-- The **Model Context Protocol** team for the excellent framework
+Copyright © 2026 Alanse inc.
 
-## 📚 Related Documentation
+See the [LICENSE](./LICENSE) file for details.
 
-- [docs/api-comparison.md](./docs/api-comparison.md) - MCP vs Google Sheets API comparison
+**Key restrictions**:
+- You may not provide the software to third parties as a hosted or managed service where the service provides users with access to any substantial set of the features or functionality of the software.
+- You may not alter, remove, or obscure any licensing, copyright, or other notices of the licensor in the software.

package/dist/auth.js

@@ -5,9 +5,10 @@ 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.GDRIVE_CREDS_DIR ||
+const CREDS_DIR = process.env.GWORKSPACE_CREDS_DIR ||
     path.join(path.dirname(new URL(import.meta.url).pathname), "../../../");
 // Ensure the credentials directory exists
 function ensureCredsDirectory() {
@@ -20,7 +21,7 @@ function ensureCredsDirectory() {
         throw error;
     }
 }
-const credentialsPath = path.join(CREDS_DIR, ".gdrive-server-credentials.json");
+const credentialsPath = path.join(CREDS_DIR, ".gworkspace-credentials.json");
 async function authenticateWithTimeout(keyfilePath, SCOPES, timeoutMs = 30000) {
     const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error("Authentication timed out")), timeoutMs));
     const authPromise = authenticate({

package/dist/index.js

@@ -8,12 +8,12 @@ import { getValidCredentials, setupTokenRefresh, loadCredentialsQuietly, } from
 import { tools } from "./tools/index.js";
 const drive = google.drive("v3");
 const server = new Server({
-    name: "example-servers/gdrive",
-    version: "0.1.0",
+    name: "@alanse/mcp-server-google-workspace",
+    version: "0.2.2",
 }, {
     capabilities: {
         resources: {
-            schemes: ["gdrive"], // Declare that we handle gdrive:/// URIs
+            schemes: ["gworkspace"], // Declare that we handle gworkspace:/// URIs
             listable: true, // Support listing available resources
             readable: true, // Support reading resource contents
         },
@@ -47,7 +47,7 @@ server.setRequestHandler(ListResourcesRequestSchema, async (request) => {
     const files = res.data.files;
     return {
         resources: files.map((file) => ({
-            uri: `gdrive:///${file.id}`,
+            uri: `gworkspace:///${file.id}`,
             mimeType: file.mimeType,
             name: file.name,
         })),
@@ -56,8 +56,8 @@ server.setRequestHandler(ListResourcesRequestSchema, async (request) => {
 });
 server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
     await ensureAuthQuietly();
-    const fileId = request.params.uri.replace("gdrive:///", "");
-    const readFileTool = tools[1]; // gdrive_read_file is the second tool
+    const fileId = request.params.uri.replace("gworkspace:///", "");
+    const readFileTool = tools[1]; // drive_read_file is the second tool
     const result = await readFileTool.handler({ fileId });
     // Extract the file contents from the tool response
     const fileContents = result.content[0].text.split("\n\n")[1]; // Skip the "Contents of file:" prefix

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);
+    }
+}