bn-google-workspace-mcp-server 0.0.1

package/README.md

@@ -0,0 +1,718 @@
+# Google Workspace MCP Server
+
+A comprehensive Model Context Protocol (MCP) server for Google Workspace services including Gmail, Drive, Calendar, Docs, Sheets, Slides, Forms, Tasks, and Chat with OAuth2 authentication.
+
+## Features
+
+- **Gmail Operations**: List labels, search messages, send emails, get message content
+- **Google Drive**: File management, content access, and file creation
+- **Google Calendar**: Event management and calendar operations
+- **Google Docs**: Document creation and content access
+- **Google Sheets**: Spreadsheet operations, data reading and creation
+- **Google Slides**: Presentation management and creation
+- **Google Forms**: Form creation and management
+- **Google Tasks**: Task list and task management
+- **Google Chat**: Space management and messaging
+- **OAuth2 Authentication**: Secure access via Google Access Tokens
+- **Stateless Architecture**: Each request is independent with Bearer token authentication
+- **TypeScript Implementation**: Built with TypeScript for type safety and maintainability
+
+## Quick Start
+
+### Installation
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build the TypeScript project
+pnpm run build
+
+# Start the server
+pnpm start
+
+# Or run in development mode with auto-reload
+pnpm run dev
+
+# Run with debug logging enabled
+pnpm run dev:debug
+```
+
+### Docker
+
+```bash
+# Build the Docker image
+docker build -t google-workspace-mcp .
+
+# Run the container
+docker run -p 30000:30000 google-workspace-mcp
+```
+
+The server provides these endpoints:
+- **`POST /mcp`** - Main MCP endpoint for tool execution
+- **`GET /health`** - Health check endpoint
+
+### Authentication
+
+All requests require a Google Access Token via Authorization header:
+
+```bash
+Authorization: Bearer ya29.your-google-access-token
+```
+
+[Set up Google OAuth2](https://developers.google.com/workspace/guides/auth-overview) and obtain access tokens with appropriate scopes.
+
+## Tools
+
+The server provides 25 tools for comprehensive Google Workspace API access. Each tool requires `Authorization: Bearer <token>` header.
+
+### Gmail Tools
+
+#### 1. gmail_list_labels
+List all Gmail labels.
+
+```bash
+curl -X POST http://localhost:30000/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Authorization: Bearer ya29.your-google-access-token" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "1",
+    "method": "tools/call",
+    "params": {
+      "name": "gmail_list_labels",
+      "arguments": {}
+    }
+  }'
+```
+
+#### 2. gmail_search_messages
+Search Gmail messages.
+
+```bash
+curl -X POST http://localhost:30000/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Authorization: Bearer ya29.your-google-access-token" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "2",
+    "method": "tools/call",
+    "params": {
+      "name": "gmail_search_messages",
+      "arguments": {
+        "query": "is:unread from:important@example.com",
+        "maxResults": 20
+      }
+    }
+  }'
+```
+
+#### 3. gmail_get_message_content
+Get detailed information about a specific Gmail message.
+
+```bash
+curl -X POST http://localhost:30000/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Authorization: Bearer ya29.your-google-access-token" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "3",
+    "method": "tools/call",
+    "params": {
+      "name": "gmail_get_message_content",
+      "arguments": {
+        "messageId": "1234567890abcdef"
+      }
+    }
+  }'
+```
+
+#### 4. gmail_send_message
+Send a Gmail message.
+
+```bash
+curl -X POST http://localhost:30000/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Authorization: Bearer ya29.your-google-access-token" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "4",
+    "method": "tools/call",
+    "params": {
+      "name": "gmail_send_message",
+      "arguments": {
+        "to": "recipient@example.com",
+        "subject": "Hello from Google Workspace MCP",
+        "body": "This email was sent via the MCP server!"
+      }
+    }
+  }'
+```
+
+### Google Drive Tools
+
+#### 5. drive_list_files
+List Google Drive files.
+
+```bash
+curl -X POST http://localhost:30000/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Authorization: Bearer ya29.your-google-access-token" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "5",
+    "method": "tools/call",
+    "params": {
+      "name": "drive_list_files",
+      "arguments": {
+        "query": "project",
+        "maxResults": 15
+      }
+    }
+  }'
+```
+
+#### 6. drive_get_file_content
+Get Google Drive file content.
+
+```bash
+curl -X POST http://localhost:30000/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Authorization: Bearer ya29.your-google-access-token" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "6",
+    "method": "tools/call",
+    "params": {
+      "name": "drive_get_file_content",
+      "arguments": {
+        "fileId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
+      }
+    }
+  }'
+```
+
+#### 7. drive_create_file
+Create a Google Drive file.
+
+```bash
+curl -X POST http://localhost:30000/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Authorization: Bearer ya29.your-google-access-token" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "7",
+    "method": "tools/call",
+    "params": {
+      "name": "drive_create_file",
+      "arguments": {
+        "name": "my-document.txt",
+        "content": "Hello, this is my new document content!",
+        "parentFolderId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
+      }
+    }
+  }'
+```
+
+### Google Calendar Tools
+
+#### 8. calendar_list_events
+List Google Calendar events.
+
+```bash
+curl -X POST http://localhost:30000/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Authorization: Bearer ya29.your-google-access-token" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "8",
+    "method": "tools/call",
+    "params": {
+      "name": "calendar_list_events",
+      "arguments": {
+        "maxResults": 25
+      }
+    }
+  }'
+```
+
+#### 9. calendar_list_calendars
+List Google Calendars.
+
+```bash
+curl -X POST http://localhost:30000/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Authorization: Bearer ya29.your-google-access-token" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "9",
+    "method": "tools/call",
+    "params": {
+      "name": "calendar_list_calendars",
+      "arguments": {}
+    }
+  }'
+```
+
+#### 10. calendar_create_event
+Create a Google Calendar event.
+
+```bash
+curl -X POST http://localhost:30000/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Authorization: Bearer ya29.your-google-access-token" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "10",
+    "method": "tools/call",
+    "params": {
+      "name": "calendar_create_event",
+      "arguments": {
+        "summary": "Team Meeting",
+        "startTime": "2024-01-15T10:00:00-08:00",
+        "endTime": "2024-01-15T11:00:00-08:00"
+      }
+    }
+  }'
+```
+
+### Google Docs Tools
+
+#### 11. docs_get_document
+Get Google Docs document.
+
+```bash
+curl -X POST http://localhost:30000/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Authorization: Bearer ya29.your-google-access-token" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "11",
+    "method": "tools/call",
+    "params": {
+      "name": "docs_get_document",
+      "arguments": {
+        "documentId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
+      }
+    }
+  }'
+```
+
+#### 12. docs_create_document
+Create a Google Docs document.
+
+```bash
+curl -X POST http://localhost:30000/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Authorization: Bearer ya29.your-google-access-token" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "12",
+    "method": "tools/call",
+    "params": {
+      "name": "docs_create_document",
+      "arguments": {
+        "title": "My New Document",
+        "content": "This is the initial content of my document."
+      }
+    }
+  }'
+```
+
+### Google Sheets Tools
+
+#### 13. sheets_get_spreadsheet
+Get Google Sheets spreadsheet.
+
+```bash
+curl -X POST http://localhost:30000/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Authorization: Bearer ya29.your-google-access-token" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "13",
+    "method": "tools/call",
+    "params": {
+      "name": "sheets_get_spreadsheet",
+      "arguments": {
+        "spreadsheetId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
+      }
+    }
+  }'
+```
+
+#### 14. sheets_read_values
+Read values from Google Sheets.
+
+```bash
+curl -X POST http://localhost:30000/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Authorization: Bearer ya29.your-google-access-token" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "14",
+    "method": "tools/call",
+    "params": {
+      "name": "sheets_read_values",
+      "arguments": {
+        "spreadsheetId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
+        "range": "A1:D10"
+      }
+    }
+  }'
+```
+
+#### 15. sheets_create_spreadsheet
+Create a Google Sheets spreadsheet.
+
+```bash
+curl -X POST http://localhost:30000/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Authorization: Bearer ya29.your-google-access-token" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "15",
+    "method": "tools/call",
+    "params": {
+      "name": "sheets_create_spreadsheet",
+      "arguments": {
+        "title": "My New Spreadsheet"
+      }
+    }
+  }'
+```
+
+### Google Slides Tools
+
+#### 16. slides_get_presentation
+Get Google Slides presentation.
+
+```bash
+curl -X POST http://localhost:30000/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Authorization: Bearer ya29.your-google-access-token" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "16",
+    "method": "tools/call",
+    "params": {
+      "name": "slides_get_presentation",
+      "arguments": {
+        "presentationId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
+      }
+    }
+  }'
+```
+
+#### 17. slides_create_presentation
+Create a Google Slides presentation.
+
+```bash
+curl -X POST http://localhost:30000/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Authorization: Bearer ya29.your-google-access-token" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "17",
+    "method": "tools/call",
+    "params": {
+      "name": "slides_create_presentation",
+      "arguments": {
+        "title": "My New Presentation"
+      }
+    }
+  }'
+```
+
+### Google Tasks Tools
+
+#### 18. tasks_list_task_lists
+List Google Tasks task lists.
+
+```bash
+curl -X POST http://localhost:30000/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Authorization: Bearer ya29.your-google-access-token" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "18",
+    "method": "tools/call",
+    "params": {
+      "name": "tasks_list_task_lists",
+      "arguments": {}
+    }
+  }'
+```
+
+#### 19. tasks_list_tasks
+List tasks from a Google Tasks list.
+
+```bash
+curl -X POST http://localhost:30000/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Authorization: Bearer ya29.your-google-access-token" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "19",
+    "method": "tools/call",
+    "params": {
+      "name": "tasks_list_tasks",
+      "arguments": {
+        "taskListId": "@default"
+      }
+    }
+  }'
+```
+
+#### 20. tasks_create_task
+Create a task in Google Tasks.
+
+```bash
+curl -X POST http://localhost:30000/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Authorization: Bearer ya29.your-google-access-token" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "20",
+    "method": "tools/call",
+    "params": {
+      "name": "tasks_create_task",
+      "arguments": {
+        "taskListId": "@default",
+        "title": "Complete project documentation",
+        "notes": "Review and finalize all documentation for the project"
+      }
+    }
+  }'
+```
+
+### Google Forms Tools
+
+#### 21. forms_create_form
+Create a Google Form.
+
+```bash
+curl -X POST http://localhost:30000/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Authorization: Bearer ya29.your-google-access-token" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "21",
+    "method": "tools/call",
+    "params": {
+      "name": "forms_create_form",
+      "arguments": {
+        "title": "Customer Feedback Survey"
+      }
+    }
+  }'
+```
+
+#### 22. forms_get_form
+Get Google Form information.
+
+```bash
+curl -X POST http://localhost:30000/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Authorization: Bearer ya29.your-google-access-token" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "22",
+    "method": "tools/call",
+    "params": {
+      "name": "forms_get_form",
+      "arguments": {
+        "formId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
+      }
+    }
+  }'
+```
+
+### Google Chat Tools
+
+#### 23. chat_list_spaces
+List Google Chat spaces.
+
+```bash
+curl -X POST http://localhost:30000/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Authorization: Bearer ya29.your-google-access-token" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "23",
+    "method": "tools/call",
+    "params": {
+      "name": "chat_list_spaces",
+      "arguments": {}
+    }
+  }'
+```
+
+#### 24. chat_send_message
+Send a message to Google Chat.
+
+```bash
+curl -X POST http://localhost:30000/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Authorization: Bearer ya29.your-google-access-token" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "24",
+    "method": "tools/call",
+    "params": {
+      "name": "chat_send_message",
+      "arguments": {
+        "spaceName": "spaces/AAAAxxxxxxx",
+        "text": "Hello from the Google Workspace MCP Server!"
+      }
+    }
+  }'
+```
+
+## List Available Tools
+
+Get the complete list of available tools:
+
+```bash
+curl -X POST http://localhost:30000/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Authorization: Bearer ya29.your-google-access-token" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "tools-list",
+    "method": "tools/list",
+    "params": {}
+  }'
+```
+
+## Project Structure
+
+```
+google-workspace/
+├── package.json          # NPM configuration
+├── tsconfig.json         # TypeScript configuration
+├── Dockerfile            # Container configuration
+├── tools.json            # Tool definitions for MCP
+├── nodemon.json          # Dev mode configuration
+├── src/
+│   ├── index.ts          # Main server entry point
+│   ├── schemas.ts        # Zod schemas for all tools
+│   ├── tool-registry.ts  # Tool registration system
+│   ├── tool-loader.ts    # Tool definitions loader
+│   ├── debug-middleware.ts # Debug logging
+│   ├── types.ts          # TypeScript interfaces
+│   ├── helpers.ts        # Utility functions
+│   ├── google-api-client.ts # Google API service factories
+│   └── tools/
+│       ├── index.ts      # Tool exports
+│       ├── gmail.ts      # Gmail tools
+│       ├── drive.ts      # Drive tools
+│       ├── calendar.ts   # Calendar tools
+│       ├── docs.ts       # Docs tools
+│       ├── sheets.ts     # Sheets tools
+│       ├── slides.ts     # Slides tools
+│       ├── tasks.ts      # Tasks tools
+│       ├── forms.ts      # Forms tools
+│       └── chat.ts       # Chat tools
+└── dist/                 # Compiled JavaScript
+```
+
+## Authentication Setup
+
+1. **Create Google Cloud Project:**
+   - Go to [Google Cloud Console](https://console.cloud.google.com/)
+   - Create a new project or select existing
+   - Enable required APIs (Gmail, Drive, Calendar, etc.)
+
+2. **Set up OAuth2:**
+   - Go to "Credentials" → "Create Credentials" → "OAuth 2.0 Client IDs"
+   - Configure OAuth consent screen
+   - Download client configuration
+
+3. **Required Scopes:**
+   ```
+   https://www.googleapis.com/auth/gmail.readonly
+   https://www.googleapis.com/auth/gmail.send
+   https://www.googleapis.com/auth/drive
+   https://www.googleapis.com/auth/calendar
+   https://www.googleapis.com/auth/documents
+   https://www.googleapis.com/auth/spreadsheets
+   https://www.googleapis.com/auth/presentations
+   https://www.googleapis.com/auth/tasks
+   https://www.googleapis.com/auth/forms.body
+   https://www.googleapis.com/auth/chat.spaces
+   ```
+
+4. **Get Access Token:**
+   - Use Google OAuth2 flow to obtain access tokens
+   - Pass tokens via `Authorization: Bearer` header
+
+## Configuration
+
+### Environment Variables
+
+```bash
+# Server Configuration
+PORT=30000           # Server port (default: 30000)
+DEBUG=true           # Enable debug logging
+
+# Tool Configuration
+TOOLS_CONFIG_PATH=./tools.json  # Custom path to tools.json
+```
+
+## Development
+
+### Run in Development Mode
+
+```bash
+# Auto-reload on file changes
+pnpm run dev
+
+# With debug logging enabled
+pnpm run dev:debug
+```
+
+### Build for Production
+
+```bash
+pnpm run build
+pnpm start
+```
+
+## Error Handling
+
+The server provides detailed error messages for common issues:
+- **401**: Invalid or expired Google access token
+- **403**: Insufficient permissions or missing scopes
+- **404**: Resource not found (document, file, etc.)
+- **429**: Rate limit exceeded
+- **500**: Internal server errors
+
+## License
+
+This MCP server is licensed under the MIT License.