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

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, Gmail, Calendar, and future Forms integration.
 
-🚀 **Current Status**: 59 tools (Drive: 2, Sheets: 57)
-📅 **Roadmap**: Google Docs, Calendar, Forms, Gmail, Slides
+🚀 **Current Status**: 130 tools (Drive: 21, Sheets: 57, Docs: 23, Gmail: 11, Calendar: 18)
+📅 **Roadmap**: Forms, Slides
 
 Extended implementation by Alanse inc.
 
@@ -11,14 +11,124 @@ 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
+**130 Total Tools** = **21 Google Drive** + **57 Google Sheets** + **23 Google Docs** + **11 Gmail** + **18 Calendar** operations
 
 #### Tool Categories
 
-**Google Drive Operations (2 tools)**
-- Search & File Management
+**Google Drive Operations (21 tools)**
+
+#### Basic Operations (4 tools)
+
+- Search Files (Advanced Query Support)
+- Read File Contents
+- List Files (Filter, Pagination, Sorting)
+- Get File Metadata
+
+#### File Operations (7 tools)
+
+- Upload File
+- Create File
+- Delete File (Move to Trash)
+- Copy File
+- Move File
+- Rename File
+- Update File Content
+
+#### Folder Management (3 tools)
+
+- Create Folder
+- List Folder Contents
+- Move File to Folder
+
+#### Permissions Management (4 tools)
+
+- Share File (User/Group/Domain/Anyone)
+- List File Permissions
+- Update Permission Role
+- Remove Permission
+
+#### Advanced Operations (3 tools)
+
+- Export File (Google Workspace Docs to PDF/DOCX/etc)
+- List File Revisions
+- Empty Trash
+
+**Gmail Operations (11 tools)**
+
+#### Basic Operations (4 tools)
+
+- List Labels, Search Messages, Get Message, Get Thread
+
+#### Label Management (2 tools)
+
+- Modify Labels (Add/Remove), Manage Labels (Create/Update/Delete)
+
+#### Send Operations (2 tools)
+
+- Send Message (Plain/HTML with CC/BCC), Draft Message
+
+#### Batch Operations (3 tools)
+
+- Get Messages Batch, Get Threads Batch, Batch Modify Labels
+
+**Google Calendar Operations (18 tools)**
+
+#### Basic Event Operations (5 tools)
+
+- List Events (Time range, search, pagination)
+- Get Event (Full event details)
+- Create Event (Title, time, location, attendees, Google Meet)
+- Update Event (Modify any event properties)
+- Delete Event (Remove with notifications)
+
+#### Advanced Event Operations (3 tools)
+
+- Quick Add Event (Natural language: "Meeting tomorrow at 2pm")
+- List Event Instances (Recurring event occurrences)
+- Move Event (Transfer between calendars)
+
+#### Calendar List Operations (2 tools)
+
+- List Calendars (User's calendar list with access roles)
+- Get Calendar from List (Detailed calendar information)
+
+#### Calendar Management (3 tools)
+
+- Create Calendar (New secondary calendar)
+- Get Calendar Metadata (Calendar details and settings)
+- Update Calendar (Modify title, description, timezone)
+
+#### Access Control (2 tools)
+
+- List ACL Rules (View sharing settings)
+- Add ACL Rule (Share calendar with users/groups/domains)
+
+#### Utility Operations (3 tools)
+
+- Get Color Palette (Available calendar/event colors)
+- Query Free/Busy (Check availability across calendars)
+- List Settings (User's Calendar preferences)
+
+**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
@@ -72,8 +182,11 @@ The server provides access to Google Drive files:
 1. [Create a new Google Cloud project](https://console.cloud.google.com/projectcreate)
 2. [Enable the Google Drive API](https://console.cloud.google.com/workspace-api/products)
 3. [Configure an OAuth consent screen](https://console.cloud.google.com/apis/credentials/consent) ("internal" is fine for testing)
-4. Add OAuth scopes `https://www.googleapis.com/auth/drive.readonly`, `https://www.googleapis.com/auth/spreadsheets`
-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.
+4. Add OAuth scopes:
+   - `https://www.googleapis.com/auth/drive` (for Drive file operations - read & write)
+   - `https://www.googleapis.com/auth/spreadsheets` (for Sheets operations)
+   - `https://www.googleapis.com/auth/gmail.modify` (for Gmail operations)
+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/), [Google Docs API](https://console.cloud.google.com/marketplace/product/google/docs.googleapis.com), and [Gmail API](https://console.cloud.google.com/apis/api/gmail.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 `GWORKSPACE_CREDS_DIR` (i.e. `/Users/username/.config/mcp-google-workspace`)
@@ -133,27 +246,147 @@ Replace `<YOUR_CLIENT_ID>`, `<YOUR_CLIENT_SECRET>`, and `/path/to/config/directo
 
 ## 📈 Project Status
 
-✅ **Phase 1-12 Complete** (2026-01-06)
-- **59 Tools Implemented** (57 Sheets + 2 GDrive)
-- **155 Tests** (100% Pass Rate)
+✅ **Complete** (2026-01-06)
+
+- **112 Tools Implemented** (21 Drive + 57 Sheets + 23 Docs + 11 Gmail)
+- **268+ Tests** (100% Pass Rate)
 - **Production Ready**
 
 ## 🗺️ Roadmap
 
-### Current: Google Sheets & Drive ✅
+### Completed ✅
 
-- ✅ **Google Drive**: 2 tools (Search, Read)
+- ✅ **Google Drive**: 21 tools (File operations, folder management, permissions, advanced features)
 - ✅ **Google Sheets**: 57 tools (Complete API coverage)
+- ✅ **Google Docs**: 23 tools (Document creation, editing, formatting, elements)
+- ✅ **Gmail**: 11 tools (Labels, search, send, batch operations)
 
 ### Coming Soon
 
-- 📝 **Google Docs**: Document creation, editing, formatting (~15-20 tools)
 - 📅 **Google Calendar**: Event management, scheduling (~10-15 tools)
 - 📋 **Google Forms**: Form creation, response management (~10-15 tools)
-- 📧 **Gmail**: Email operations, thread management (~10-15 tools)
 - 🎬 **Google Slides**: Presentation creation, editing (~15-20 tools)
 
-**Goal**: 100+ tools covering the entire Google Workspace ecosystem
+**Goal**: 150+ 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 unit 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
+```
+
+### Interactive Testing with MCP Inspector
+
+[MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) is the official debugging tool for MCP servers. It provides an interactive interface to test all 130 tools in real-time.
+
+**Launch Inspector:**
+
+```bash
+npm run inspect
+```
+
+This opens a browser interface where you can:
+
+- 🔍 **Browse all 130 tools** - View complete tool schemas and descriptions
+- ⚡ **Test tools interactively** - Execute any tool with custom parameters
+- 📊 **Monitor responses** - See real-time responses and error messages
+- 🐛 **Debug issues** - View server logs and notifications
+- 🧪 **Test edge cases** - Try invalid inputs and concurrent operations
+
+**Example workflow:**
+
+1. Start the inspector: `npm run inspect`
+2. Navigate to the **Tools** tab
+3. Select a tool (e.g., `calendar_create_event`)
+4. Fill in the parameters (summary, startTime, endTime)
+5. Click **Execute** to test the tool
+6. View the response and verify the behavior
+
+**Recommended for:**
+
+- Testing new Calendar API tools
+- Verifying OAuth authentication flow
+- Debugging API errors and edge cases
+- Exploring available tools before integration
+
+### 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
 

package/dist/auth.js

@@ -5,6 +5,12 @@ 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",
+    "https://www.googleapis.com/auth/gmail.readonly",
+    "https://www.googleapis.com/auth/gmail.send",
+    "https://www.googleapis.com/auth/gmail.modify",
+    "https://www.googleapis.com/auth/gmail.labels",
+    "https://www.googleapis.com/auth/calendar",
 ];
 // 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/calendar-helpers.js

@@ -0,0 +1,197 @@
+/**
+ * Google Calendar Helper Functions
+ *
+ * Utilities for Google Calendar API operations including:
+ * - Event formatting and display
+ * - Date/time parsing and formatting
+ * - Calendar URL generation
+ * - Free/busy data formatting
+ * - Attendee and recurrence handling
+ */
+/**
+ * Format a single calendar event for display
+ */
+export function formatEvent(event, calendarId = "primary") {
+    const lines = [];
+    // Event ID and status
+    lines.push(`Event ID: ${event.id}`);
+    if (event.status) {
+        lines.push(`Status: ${event.status}`);
+    }
+    // Summary (title)
+    if (event.summary) {
+        lines.push(`Title: ${event.summary}`);
+    }
+    // Date and time
+    const { startFormatted, endFormatted } = formatDateTime(event);
+    lines.push(`Start: ${startFormatted}`);
+    lines.push(`End: ${endFormatted}`);
+    // Location
+    if (event.location) {
+        lines.push(`Location: ${event.location}`);
+    }
+    // Description
+    if (event.description) {
+        const desc = event.description.length > 200
+            ? event.description.substring(0, 200) + "..."
+            : event.description;
+        lines.push(`Description: ${desc}`);
+    }
+    // Attendees
+    if (event.attendees && event.attendees.length > 0) {
+        lines.push(`Attendees (${event.attendees.length}):`);
+        event.attendees.forEach((attendee) => {
+            const status = attendee.responseStatus || "needsAction";
+            const organizer = attendee.organizer ? " (organizer)" : "";
+            lines.push(`  - ${attendee.email} [${status}]${organizer}`);
+        });
+    }
+    // Recurrence
+    if (event.recurrence && event.recurrence.length > 0) {
+        lines.push(`Recurrence: ${event.recurrence.join(", ")}`);
+    }
+    // Web link
+    if (event.htmlLink) {
+        lines.push(`Link: ${event.htmlLink}`);
+    }
+    // Conference data (Google Meet, Zoom, etc.)
+    if (event.conferenceData?.entryPoints) {
+        const meetLink = event.conferenceData.entryPoints.find((ep) => ep.entryPointType === "video");
+        if (meetLink?.uri) {
+            lines.push(`Meeting Link: ${meetLink.uri}`);
+        }
+    }
+    return lines.join("\n");
+}
+/**
+ * Format a list of calendar events
+ */
+export function formatEventList(events, calendarId = "primary") {
+    if (!events || events.length === 0) {
+        return "No events found.";
+    }
+    const lines = [];
+    lines.push(`Found ${events.length} event(s):\n`);
+    events.forEach((event, index) => {
+        lines.push(`[${index + 1}] ${event.summary || "(No title)"}`);
+        const { startFormatted } = formatDateTime(event);
+        lines.push(`    Time: ${startFormatted}`);
+        if (event.location) {
+            lines.push(`    Location: ${event.location}`);
+        }
+        if (event.attendees) {
+            lines.push(`    Attendees: ${event.attendees.length}`);
+        }
+        lines.push(`    ID: ${event.id}`);
+        lines.push("");
+    });
+    return lines.join("\n");
+}
+/**
+ * Format event date/time for display
+ */
+export function formatDateTime(event) {
+    let startFormatted = "Unknown";
+    let endFormatted = "Unknown";
+    let isAllDay = false;
+    // Check if all-day event
+    if (event.start?.date) {
+        startFormatted = event.start.date;
+        endFormatted = event.end?.date || event.start.date;
+        isAllDay = true;
+    }
+    else if (event.start?.dateTime) {
+        const startDate = new Date(event.start.dateTime);
+        const endDate = event.end?.dateTime ? new Date(event.end.dateTime) : startDate;
+        const options = {
+            year: "numeric",
+            month: "short",
+            day: "numeric",
+            hour: "2-digit",
+            minute: "2-digit",
+            timeZoneName: "short",
+        };
+        startFormatted = startDate.toLocaleString("en-US", options);
+        endFormatted = endDate.toLocaleString("en-US", options);
+    }
+    return { startFormatted, endFormatted, isAllDay };
+}
+/**
+ * Generate Google Calendar web URL for an event
+ */
+export function generateCalendarWebUrl(eventId, calendarId = "primary") {
+    const encodedCalendarId = encodeURIComponent(calendarId);
+    const encodedEventId = encodeURIComponent(eventId);
+    return `https://calendar.google.com/calendar/u/0/r/eventedit/${encodedEventId}?calendarId=${encodedCalendarId}`;
+}
+/**
+ * Format free/busy query response
+ */
+export function formatFreeBusyResponse(response) {
+    const lines = [];
+    if (!response.calendars) {
+        return "No calendar data available.";
+    }
+    Object.entries(response.calendars).forEach(([calendarId, calendarData]) => {
+        lines.push(`\nCalendar: ${calendarId}`);
+        if (calendarData.errors && calendarData.errors.length > 0) {
+            lines.push("  Errors:");
+            calendarData.errors.forEach((error) => {
+                lines.push(`    - ${error.reason}: ${error.domain}`);
+            });
+        }
+        if (calendarData.busy && calendarData.busy.length > 0) {
+            lines.push(`  Busy periods (${calendarData.busy.length}):`);
+            calendarData.busy.forEach((period, index) => {
+                const start = period.start ? new Date(period.start).toLocaleString() : "Unknown";
+                const end = period.end ? new Date(period.end).toLocaleString() : "Unknown";
+                lines.push(`    ${index + 1}. ${start} - ${end}`);
+            });
+        }
+        else {
+            lines.push("  No busy periods - calendar is free!");
+        }
+    });
+    return lines.join("\n");
+}
+/**
+ * Parse ISO 8601 datetime or date string to appropriate format for Calendar API
+ */
+export function parseDateTime(dateTimeStr) {
+    // Check if it's a date-only string (YYYY-MM-DD)
+    if (/^\d{4}-\d{2}-\d{2}$/.test(dateTimeStr)) {
+        return { date: dateTimeStr };
+    }
+    // Otherwise, treat as datetime
+    return { dateTime: dateTimeStr };
+}
+/**
+ * Format attendee list for API request
+ */
+export function formatAttendees(emails) {
+    return emails.map((email) => ({
+        email: email.trim(),
+    }));
+}
+/**
+ * Validate event time range
+ */
+export function validateTimeRange(startTime, endTime) {
+    try {
+        const start = new Date(startTime);
+        const end = new Date(endTime);
+        if (isNaN(start.getTime())) {
+            return { valid: false, error: "Invalid start time format" };
+        }
+        if (isNaN(end.getTime())) {
+            return { valid: false, error: "Invalid end time format" };
+        }
+        if (end <= start) {
+            return { valid: false, error: "End time must be after start time" };
+        }
+        return { valid: true };
+    }
+    catch (error) {
+        return { valid: false, error: "Error parsing time range" };
+    }
+}

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