Merge branch 'main' of github.com:taylorwilsdon/google_workspace_mcp into feature/forms-batch-update

Author: taylorwilsdon

.github/pull_request_template.md

@@ -0,0 +1,31 @@
+## Description
+Brief description of the changes in this PR.
+
+## Type of Change
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Documentation update
+
+## Testing
+- [ ] I have added tests that prove my fix is effective or that my feature works
+- [ ] New and existing unit tests pass locally with my changes
+- [ ] I have tested this change manually
+
+## Checklist
+- [ ] My code follows the style guidelines of this project
+- [ ] I have performed a self-review of my own code
+- [ ] I have commented my code, particularly in hard-to-understand areas
+- [ ] My changes generate no new warnings
+- [ ] **I have enabled "Allow edits from maintainers" for this pull request**
+
+## Additional Notes
+Add any other context about the pull request here.
+
+---
+
+**⚠️ IMPORTANT:** This repository requires that you enable "Allow edits from maintainers" when creating your pull request. This allows maintainers to make small fixes and improvements directly to your branch, speeding up the review process.
+
+To enable this setting:
+1. When creating the PR, check the "Allow edits from maintainers" checkbox
+2. If you've already created the PR, you can enable this in the PR sidebar under "Allow edits from maintainers"

.github/workflows/check-maintainer-edits.yml

@@ -0,0 +1,53 @@
+name: Check Maintainer Edits Enabled
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, edited]
+
+jobs:
+  check-maintainer-edits:
+    runs-on: ubuntu-latest
+    if: github.event.pull_request.head.repo.fork == true || github.event.pull_request.head.repo.full_name != github.repository
+
+    steps:
+      - name: Check if maintainer edits are enabled
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const { data: pr } = await github.rest.pulls.get({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              pull_number: context.issue.number
+            });
+
+            if (!pr.maintainer_can_modify) {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body: `⚠️ **Maintainer edits not enabled**
+
+This repository requires that you enable "Allow edits from maintainers" for your pull request. This allows maintainers to make small fixes and improvements directly to your branch, which speeds up the review process.
+
+**To enable this setting:**
+1. Go to your pull request page
+2. In the right sidebar, look for "Allow edits from maintainers"
+3. Check the checkbox to enable it
+
+Once you've enabled this setting, this check will automatically pass. Thank you! 🙏`
+              });
+
+              core.setFailed('Maintainer edits must be enabled for this pull request');
+            } else {
+              console.log('✅ Maintainer edits are enabled');
+            }
+
+  check-maintainer-edits-internal:
+    runs-on: ubuntu-latest
+    if: github.event.pull_request.head.repo.fork == false && github.event.pull_request.head.repo.full_name == github.repository
+
+    steps:
+      - name: Skip check for internal PRs
+        run: |
+          echo "✅ Skipping maintainer edits check for internal pull request"
+          echo "This check only applies to external contributors and forks"

README.md

@@ -481,28 +481,30 @@ export GOOGLE_PSE_ENGINE_ID=\
 
 ### Start the Server
 
+> **📌 Transport Mode Guidance**: Use **streamable HTTP mode** (`--transport streamable-http`) for all modern MCP clients including Claude Code, VS Code MCP, and MCP Inspector. Stdio mode is only for clients with incomplete MCP specification support.
+
 <details open>
 <summary>▶ <b>Launch Commands</b> <sub><sup>← Choose your startup mode</sup></sub></summary>
 
 <table>
 <tr>
 <td width="33%" align="center">
 
-**▶ Quick Start**
+**▶ Legacy Mode**
 ```bash
 uv run main.py
 ```
-<sub>Default stdio mode</sub>
+<sub>⚠️ Stdio mode (incomplete MCP clients only)</sub>
 
 </td>
 <td width="33%" align="center">
 
-**◆ HTTP Mode**
+**◆ HTTP Mode (Recommended)**
 ```bash
 uv run main.py \
   --transport streamable-http
 ```
-<sub>Web interfaces & debugging</sub>
+<sub>✅ Full MCP spec compliance & OAuth 2.1</sub>
 
 </td>
 <td width="34%" align="center">
@@ -513,6 +515,7 @@ uv run main.py \
   --single-user
 ```
 <sub>Simplified authentication</sub>
+<sub>⚠️ Cannot be used with OAuth 2.1 mode</sub>
 
 </td>
 </tr>
@@ -713,6 +716,7 @@ cp .env.oauth21 .env
 | `share_drive_file` | **Core** | Share file with users/groups/domains/anyone |
 | `get_drive_shareable_link` | **Core** | Get shareable links for a file |
 | `list_drive_items` | Extended | List folder contents |
+| `copy_drive_file` | Extended | Copy existing files (templates) with optional renaming |
 | `update_drive_file` | Extended | Update file metadata, move between folders |
 | `batch_share_drive_file` | Extended | Share file with multiple recipients |
 | `update_drive_permission` | Extended | Modify permission role |
@@ -743,7 +747,7 @@ cp .env.oauth21 .env
 | `draft_gmail_message` | Extended | Create drafts |
 | `get_gmail_threads_content_batch` | Complete | Batch retrieve thread content |
 | `batch_modify_gmail_message_labels` | Complete | Batch modify labels |
-| `start_google_auth` | Complete | Initialize authentication |
+| `start_google_auth` | Complete | Legacy OAuth 2.0 auth (disabled when OAuth 2.1 is enabled) |
 
 </td>
 <td width="50%" valign="top">
@@ -894,7 +898,9 @@ cp .env.oauth21 .env
 
 The server supports two transport modes:
 
-#### Stdio Mode (Default - Recommended for Claude Desktop)
+#### Stdio Mode (Legacy - For Clients with Incomplete MCP Support)
+
+> **⚠️ Important**: Stdio mode is a **legacy fallback** for clients that don't properly implement the MCP specification with OAuth 2.1 and streamable HTTP support. **Claude Code and other modern MCP clients should use streamable HTTP mode** (`--transport streamable-http`) for proper OAuth flow and multi-user support.
 
 In general, you should use the one-click DXT installer package for Claude Desktop.
 If you are unable to for some reason, you can configure it manually via `claude_desktop_config.json`
@@ -999,6 +1005,14 @@ The server includes OAuth 2.1 support for bearer token authentication, enabling
 - Production environments requiring secure session management
 - Browser-based clients requiring CORS support
 
+**⚠️ Important: OAuth 2.1 and Single-User Mode are mutually exclusive**
+
+OAuth 2.1 mode (`MCP_ENABLE_OAUTH21=true`) cannot be used together with the `--single-user` flag:
+- **Single-user mode**: For legacy clients that pass user emails in tool calls
+- **OAuth 2.1 mode**: For modern multi-user scenarios with bearer token authentication
+
+Choose one authentication method - using both will result in a startup error.
+
 **Enabling OAuth 2.1:**
 To enable OAuth 2.1, set the `MCP_ENABLE_OAUTH21` environment variable to `true`.
 
@@ -1148,6 +1162,8 @@ uv run main.py --transport streamable-http
 
 ### VS Code MCP Client Support
 
+> **✅ Recommended**: VS Code MCP extension properly supports the full MCP specification. **Always use HTTP transport mode** for proper OAuth 2.1 authentication.
+
 <details>
 <summary>🆚 <b>VS Code Configuration</b> <sub><sup>← Setup for VS Code MCP extension</sup></sub></summary>
 
@@ -1161,14 +1177,22 @@ uv run main.py --transport streamable-http
     }
 }
 ```
+
+*Note: Make sure to start the server with `--transport streamable-http` when using VS Code MCP.*
 </details>
 
 ### Claude Code MCP Client Support
 
+> **✅ Recommended**: Claude Code is a modern MCP client that properly supports the full MCP specification. **Always use HTTP transport mode** with Claude Code for proper OAuth 2.1 authentication and multi-user support.
+
 <details>
 <summary>🆚 <b>Claude Code Configuration</b> <sub><sup>← Setup for Claude Code MCP support</sup></sub></summary>
 
-```json
+```bash
+# Start the server in HTTP mode first
+uv run main.py --transport streamable-http
+
+# Then add to Claude Code
 claude mcp add --transport http workspace-mcp http://localhost:8000/mcp
 ```
 </details>