new

.dockerignore

@@ -0,0 +1,42 @@
+# Git and version control
+.git
+.gitignore
+gitdiff.txt
+
+# Documentation and notes
+*.md
+AUTHENTICATION_REFACTOR_PROPOSAL.md
+leverage_fastmcp_responses.md
+
+# Test files and coverage
+tests/
+htmlcov/
+.coverage
+pytest_out.txt
+
+# Build artifacts
+build/
+dist/
+*.egg-info/
+
+# Development files
+mcp_server_debug.log
+.credentials/
+
+# Cache and temporary files
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+.pytest_cache/
+
+# IDE files
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS files
+.DS_Store
+Thumbs.db

.dxtignore

@@ -0,0 +1,46 @@
+# ---- Python artefacts --------------------------------------------------
+__pycache__/
+*.py[cod]
+*.so
+
+# ---- Packaging ---------------------------------------------------------
+*.egg-info/
+build/
+dist/
+
+# ---- Environments & tooling -------------------------------------------
+.env
+.venv/
+venv/
+.idea/
+.vscode/
+.claude/
+
+# ---- macOS clutter -----------------------------------------------------
+.DS_Store
+
+# ---- Secrets & Credentials --------------------------------------------
+client_secret.json
+.credentials/
+*.key
+*.pem
+*.p12
+*.crt
+*.der
+token.pickle
+credentials.json
+
+# ---- Test & Debug Files -----------------------------------------------
+.coverage
+pytest_out.txt
+mcp_server_debug.log
+diff_output.txt
+
+# ---- Temporary & Build Files ------------------------------------------
+*.tmp
+*.log
+*.pid
+*.swp
+*.swo
+*~
+

.github/ISSUE_TEMPLATE/bug-report.md

@@ -0,0 +1,35 @@
+---
+name: Bug Report
+about: Create a report to help us improve Google Workspace MCP
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**Startup Logs**
+Include the startup output including everything from the Active Configuration section to "Uvicorn running"
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Platform (please complete the following information):**
+ - OS: [e.g. macOS, Ubuntu, Windows]
+- Container: [if applicable, e.g. Docker)
+ - Version [e.g. v1.2.0]
+
+**Additional context**
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

.github/dependabot.yml

@@ -0,0 +1,11 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  - package-ecosystem: "" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"

.github/workflows/ruff-format.yml

@@ -0,0 +1,22 @@
+name: Ruff Format
+
+on:
+  pull_request:
+    branches: [ main ]
+  push:
+    branches: [ main ]
+
+jobs:
+  ruff-format:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+    - name: Install dependencies
+      run: uv sync
+    - name: Run ruff format check
+      run: uv run ruff format --check

.github/workflows/ruff.yml

@@ -0,0 +1,22 @@
+name: Ruff Check
+
+on:
+  pull_request:
+    branches: [ main ]
+  push:
+    branches: [ main ]
+
+jobs:
+  ruff:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+    - name: Install dependencies
+      run: uv sync
+    - name: Run ruff check
+      run: uv run ruff check

.gitignore

@@ -0,0 +1,32 @@
+# ---- Python artefacts --------------------------------------------------
+__pycache__/
+*.py[cod]
+*.so
+.mcp.json
+claude.md
+
+# ---- Packaging ---------------------------------------------------------
+*.egg-info/
+build/
+dist/
+*.dxt
+
+# ---- Environments & tooling -------------------------------------------
+.env
+.venv/
+venv/
+.idea/
+.vscode/
+
+# ---- macOS clutter -----------------------------------------------------
+.DS_Store
+
+# ---- Secrets -----------------------------------------------------------
+client_secret.json
+
+# ---- Logs --------------------------------------------------------------
+mcp_server_debug.log
+
+# ---- Local development files -------------------------------------------
+/.credentials
+/.claude

.python-version

@@ -0,0 +1 @@
+3.11

Dockerfile

@@ -0,0 +1,45 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install uv for faster dependency management
+RUN pip install --no-cache-dir uv
+
+COPY . .
+
+# Install Python dependencies using uv sync
+RUN uv sync --frozen --no-dev
+
+# Create non-root user for security
+RUN useradd --create-home --shell /bin/bash app \
+    && chown -R app:app /app
+
+# Give read and write access to the store_creds volume
+RUN mkdir -p /app/store_creds \
+    && chown -R app:app /app/store_creds \
+    && chmod 755 /app/store_creds
+
+USER app
+
+# Expose port (use default of 8000 if PORT not set)
+EXPOSE 8000
+# Expose additional port if PORT environment variable is set to a different value
+ARG PORT
+EXPOSE ${PORT:-8000}
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
+    CMD sh -c 'curl -f http://localhost:${PORT:-8000}/health || exit 1'
+
+# Set environment variables for Python startup args
+ENV TOOL_TIER=""
+ENV TOOLS=""
+
+# Use entrypoint for the base command and CMD for args
+ENTRYPOINT ["/bin/sh", "-c"]
+CMD ["uv run main.py --transport streamable-http ${TOOL_TIER:+--tool-tier \"$TOOL_TIER\"} ${TOOLS:+--tools $TOOLS}"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Taylor Wilsdon
+
+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.

README_NEW.md

@@ -0,0 +1,464 @@
+<div align="center">
+
+# Google Workspace MCP Server
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
+[![PyPI](https://img.shields.io/pypi/v/workspace-mcp.svg)](https://pypi.org/project/workspace-mcp/)
+
+**Complete Google Workspace control through natural language.** Gmail, Calendar, Drive, Docs, Sheets, Slides, Forms, Tasks, Chat, Apps Script, and Custom Search—all via MCP.
+
+[Quick Start](#-quick-start) • [Tools Reference](#-tools-reference) • [Configuration](#-configuration) • [OAuth Setup](#-oauth-setup)
+
+</div>
+
+---
+
+## ⚡ Quick Start
+
+### One-Click Install (Claude Desktop)
+
+1. Download `google_workspace_mcp.dxt` from [Releases](https://github.com/taylorwilsdon/google_workspace_mcp/releases)
+2. Double-click → Claude Desktop installs automatically
+3. Add your Google OAuth credentials in Settings → Extensions
+
+### CLI Install
+
+```bash
+# Instant run (no install)
+uvx workspace-mcp
+
+# With specific tools only
+uvx workspace-mcp --tools gmail drive calendar
+
+# With tool tier
+uvx workspace-mcp --tool-tier core
+```
+
+### Environment Variables
+
+```bash
+export GOOGLE_OAUTH_CLIENT_ID="your-client-id"
+export GOOGLE_OAUTH_CLIENT_SECRET="your-client-secret"
+export OAUTHLIB_INSECURE_TRANSPORT=1  # Development only
+```
+
+---
+
+## 🛠 Tools Reference
+
+### Gmail (11 tools)
+
+| Tool | Tier | Description |
+|------|------|-------------|
+| `search_gmail_messages` | Core | Search with Gmail operators, returns message/thread IDs with web links |
+| `get_gmail_message_content` | Core | Get full message: subject, sender, body, attachments |
+| `get_gmail_messages_content_batch` | Core | Batch retrieve up to 25 messages |
+| `send_gmail_message` | Core | Send emails with HTML support, CC/BCC, threading |
+| `get_gmail_thread_content` | Extended | Get complete conversation thread |
+| `draft_gmail_message` | Extended | Create drafts with threading support |
+| `list_gmail_labels` | Extended | List all system and user labels |
+| `manage_gmail_label` | Extended | Create, update, delete labels |
+| `modify_gmail_message_labels` | Extended | Add/remove labels (archive, trash, etc.) |
+| `get_gmail_threads_content_batch` | Complete | Batch retrieve threads |
+| `batch_modify_gmail_message_labels` | Complete | Bulk label operations |
+
+**Also includes:** `get_gmail_attachment_content`, `list_gmail_filters`, `create_gmail_filter`, `delete_gmail_filter`
+
+### Google Drive (7 tools)
+
+| Tool | Tier | Description |
+|------|------|-------------|
+| `search_drive_files` | Core | Search files with Drive query syntax or free text |
+| `get_drive_file_content` | Core | Read content from Docs, Sheets, Office files (.docx, .xlsx, .pptx) |
+| `create_drive_file` | Core | Create files from content or URL (supports file://, http://, https://) |
+| `list_drive_items` | Extended | List folder contents with shared drive support |
+| `update_drive_file` | Extended | Update metadata, move between folders, star, trash |
+| `get_drive_file_permissions` | Complete | Check sharing status and permissions |
+| `check_drive_file_public_access` | Complete | Verify public link sharing for Docs image insertion |
+
+**Also includes:** `get_drive_file_download_url` for generating download URLs
+
+### Google Calendar (5 tools)
+
+| Tool | Tier | Description |
+|------|------|-------------|
+| `list_calendars` | Core | List all accessible calendars |
+| `get_events` | Core | Query events by time range, search, or specific ID |
+| `create_event` | Core | Create events with attendees, reminders, Google Meet, attachments |
+| `modify_event` | Core | Update any event property including conferencing |
+| `delete_event` | Extended | Remove events |
+
+**Event features:** Timezone support, transparency (busy/free), visibility settings, up to 5 custom reminders
+
+### Google Docs (16 tools)
+
+| Tool | Tier | Description |
+|------|------|-------------|
+| `get_doc_content` | Core | Extract text from Docs or .docx files (supports tabs) |
+| `create_doc` | Core | Create new documents with optional initial content |
+| `modify_doc_text` | Core | Insert, replace, format text (bold, italic, colors, fonts) |
+| `search_docs` | Extended | Find documents by name |
+| `find_and_replace_doc` | Extended | Global find/replace with case matching |
+| `list_docs_in_folder` | Extended | List Docs in a specific folder |
+| `insert_doc_elements` | Extended | Add tables, lists, page breaks |
+| `export_doc_to_pdf` | Extended | Export to PDF and save to Drive |
+| `insert_doc_image` | Complete | Insert images from Drive or URLs |
+| `update_doc_headers_footers` | Complete | Modify headers/footers |
+| `batch_update_doc` | Complete | Execute multiple operations atomically |
+| `inspect_doc_structure` | Complete | Analyze document structure for safe insertion points |
+| `create_table_with_data` | Complete | Create and populate tables in one operation |
+| `debug_table_structure` | Complete | Debug table cell positions and content |
+
+**Comments:** `read_document_comments`, `create_document_comment`, `reply_to_document_comment`, `resolve_document_comment`
+
+### Google Sheets (13 tools)
+
+| Tool | Tier | Description |
+|------|------|-------------|
+| `read_sheet_values` | Core | Read cell ranges with formatted output |
+| `modify_sheet_values` | Core | Write, update, or clear cell values |
+| `create_spreadsheet` | Core | Create new spreadsheets with multiple sheets |
+| `list_spreadsheets` | Extended | List accessible spreadsheets |
+| `get_spreadsheet_info` | Extended | Get metadata, sheets, conditional formats |
+| `create_sheet` | Complete | Add sheets to existing spreadsheets |
+| `format_sheet_range` | Complete | Apply colors and number formats |
+| `add_conditional_formatting` | Complete | Add boolean or gradient rules |
+| `update_conditional_formatting` | Complete | Modify existing rules |
+| `delete_conditional_formatting` | Complete | Remove formatting rules |
+
+**Comments:** `read_spreadsheet_comments`, `create_spreadsheet_comment`, `reply_to_spreadsheet_comment`, `resolve_spreadsheet_comment`
+
+### Google Slides (9 tools)
+
+| Tool | Tier | Description |
+|------|------|-------------|
+| `create_presentation` | Core | Create new presentations |
+| `get_presentation` | Core | Get presentation details with slide text extraction |
+| `batch_update_presentation` | Extended | Apply multiple updates (create slides, shapes, etc.) |
+| `get_page` | Extended | Get specific slide details and elements |
+| `get_page_thumbnail` | Extended | Generate PNG thumbnails |
+
+**Comments:** `read_presentation_comments`, `create_presentation_comment`, `reply_to_presentation_comment`, `resolve_presentation_comment`
+
+### Google Forms (5 tools)
+
+| Tool | Tier | Description |
+|------|------|-------------|
+| `create_form` | Core | Create forms with title and description |
+| `get_form` | Core | Get form details, questions, and URLs |
+| `list_form_responses` | Extended | List responses with pagination |
+| `set_publish_settings` | Complete | Configure template and authentication settings |
+| `get_form_response` | Complete | Get individual response details |
+
+### Google Tasks (12 tools)
+
+| Tool | Tier | Description |
+|------|------|-------------|
+| `list_tasks` | Core | List tasks with filtering, subtask hierarchy preserved |
+| `get_task` | Core | Get task details |
+| `create_task` | Core | Create tasks with notes, due dates, parent/sibling positioning |
+| `update_task` | Core | Update task properties |
+| `delete_task` | Extended | Remove tasks |
+| `list_task_lists` | Complete | List all task lists |
+| `get_task_list` | Complete | Get task list details |
+| `create_task_list` | Complete | Create new task lists |
+| `update_task_list` | Complete | Rename task lists |
+| `delete_task_list` | Complete | Delete task lists (and all tasks) |
+| `move_task` | Complete | Reposition or move between lists |
+| `clear_completed_tasks` | Complete | Hide completed tasks |
+
+### Google Apps Script (11 tools)
+
+| Tool | Tier | Description |
+|------|------|-------------|
+| `list_script_projects` | Core | List accessible Apps Script projects |
+| `get_script_project` | Core | Get complete project with all files |
+| `get_script_content` | Core | Retrieve specific file content |
+| `create_script_project` | Core | Create new standalone or bound project |
+| `update_script_content` | Core | Update or create script files |
+| `run_script_function` | Core | Execute function with parameters |
+| `create_deployment` | Extended | Create new script deployment |
+| `list_deployments` | Extended | List all project deployments |
+| `update_deployment` | Extended | Update deployment configuration |
+| `delete_deployment` | Extended | Remove deployment |
+| `list_script_processes` | Extended | View recent executions and status |
+
+**Enables:** Cross-app automation, persistent workflows, custom business logic execution, script development and debugging
+
+**Note:** Trigger management is not currently supported via MCP tools.
+
+### Google Chat (4 tools)
+
+| Tool | Tier | Description |
+|------|------|-------------|
+| `get_messages` | Core | Retrieve messages from a space |
+| `send_message` | Core | Send messages with optional threading |
+| `search_messages` | Core | Search across chat history |
+| `list_spaces` | Extended | List rooms and DMs |
+
+### Google Custom Search (3 tools)
+
+| Tool | Tier | Description |
+|------|------|-------------|
+| `search_custom` | Core | Web search with filters (date, file type, language, safe search) |
+| `search_custom_siterestrict` | Extended | Search within specific domains |
+| `get_search_engine_info` | Complete | Get search engine metadata |
+
+**Requires:** `GOOGLE_PSE_API_KEY` and `GOOGLE_PSE_ENGINE_ID` environment variables
+
+---
+
+## 📊 Tool Tiers
+
+Choose a tier based on your needs:
+
+| Tier | Tools | Use Case |
+|------|-------|----------|
+| **Core** | ~30 | Essential operations: search, read, create, send |
+| **Extended** | ~50 | Core + management: labels, folders, batch ops |
+| **Complete** | ~80 | Full API: comments, headers, admin functions |
+
+```bash
+uvx workspace-mcp --tool-tier core      # Start minimal
+uvx workspace-mcp --tool-tier extended  # Add management
+uvx workspace-mcp --tool-tier complete  # Everything
+```
+
+Mix tiers with specific services:
+```bash
+uvx workspace-mcp --tools gmail drive --tool-tier extended
+```
+
+---
+
+## ⚙ Configuration
+
+### Required
+
+| Variable | Description |
+|----------|-------------|
+| `GOOGLE_OAUTH_CLIENT_ID` | OAuth client ID from Google Cloud |
+| `GOOGLE_OAUTH_CLIENT_SECRET` | OAuth client secret |
+
+### Optional
+
+| Variable | Description |
+|----------|-------------|
+| `USER_GOOGLE_EMAIL` | Default email for single-user mode |
+| `GOOGLE_PSE_API_KEY` | Custom Search API key |
+| `GOOGLE_PSE_ENGINE_ID` | Programmable Search Engine ID |
+| `MCP_ENABLE_OAUTH21` | Enable OAuth 2.1 multi-user support |
+| `WORKSPACE_MCP_STATELESS_MODE` | No file writes (container-friendly) |
+| `EXTERNAL_OAUTH21_PROVIDER` | External OAuth flow with bearer tokens |
+| `WORKSPACE_MCP_BASE_URI` | Server base URL (default: `http://localhost`) |
+| `WORKSPACE_MCP_PORT` | Server port (default: `8000`) |
+| `WORKSPACE_EXTERNAL_URL` | External URL for reverse proxy setups |
+| `GOOGLE_MCP_CREDENTIALS_DIR` | Custom credentials storage path |
+
+---
+
+## 🔐 OAuth Setup
+
+### 1. Create Google Cloud Project
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/)
+2. Create a new project
+3. Navigate to **APIs & Services → Credentials**
+4. Click **Create Credentials → OAuth Client ID**
+5. Select **Desktop Application**
+6. Download credentials
+
+### 2. Enable APIs
+
+Click to enable each API:
+
+- [Calendar](https://console.cloud.google.com/flows/enableapi?apiid=calendar-json.googleapis.com)
+- [Drive](https://console.cloud.google.com/flows/enableapi?apiid=drive.googleapis.com)
+- [Gmail](https://console.cloud.google.com/flows/enableapi?apiid=gmail.googleapis.com)
+- [Docs](https://console.cloud.google.com/flows/enableapi?apiid=docs.googleapis.com)
+- [Sheets](https://console.cloud.google.com/flows/enableapi?apiid=sheets.googleapis.com)
+- [Slides](https://console.cloud.google.com/flows/enableapi?apiid=slides.googleapis.com)
+- [Forms](https://console.cloud.google.com/flows/enableapi?apiid=forms.googleapis.com)
+- [Tasks](https://console.cloud.google.com/flows/enableapi?apiid=tasks.googleapis.com)
+- [Chat](https://console.cloud.google.com/flows/enableapi?apiid=chat.googleapis.com)
+- [Custom Search](https://console.cloud.google.com/flows/enableapi?apiid=customsearch.googleapis.com)
+
+### 3. First Authentication
+
+When you first call a tool:
+1. Server returns an authorization URL
+2. Open URL in browser, authorize access
+3. Paste the authorization code when prompted
+4. Credentials are cached for future use
+
+---
+
+## 🚀 Transport Modes
+
+### Stdio (Default)
+
+Best for Claude Desktop and local MCP clients:
+
+```bash
+uvx workspace-mcp
+```
+
+### HTTP (Streamable)
+
+For web interfaces, debugging, or multi-client setups:
+
+```bash
+uvx workspace-mcp --transport streamable-http
+```
+
+Access at `http://localhost:8000/mcp/`
+
+### Docker
+
+```bash
+docker build -t workspace-mcp .
+docker run -p 8000:8000 \
+  -e GOOGLE_OAUTH_CLIENT_ID="..." \
+  -e GOOGLE_OAUTH_CLIENT_SECRET="..." \
+  workspace-mcp --transport streamable-http
+```
+
+---
+
+## 🔧 Client Configuration
+
+### Claude Desktop
+
+```json
+{
+  "mcpServers": {
+    "google_workspace": {
+      "command": "uvx",
+      "args": ["workspace-mcp", "--tool-tier", "core"],
+      "env": {
+        "GOOGLE_OAUTH_CLIENT_ID": "your-client-id",
+        "GOOGLE_OAUTH_CLIENT_SECRET": "your-secret",
+        "OAUTHLIB_INSECURE_TRANSPORT": "1"
+      }
+    }
+  }
+}
+```
+
+### LM Studio
+
+```json
+{
+  "mcpServers": {
+    "google_workspace": {
+      "command": "uvx",
+      "args": ["workspace-mcp"],
+      "env": {
+        "GOOGLE_OAUTH_CLIENT_ID": "your-client-id",
+        "GOOGLE_OAUTH_CLIENT_SECRET": "your-secret",
+        "OAUTHLIB_INSECURE_TRANSPORT": "1",
+        "USER_GOOGLE_EMAIL": "you@example.com"
+      }
+    }
+  }
+}
+```
+
+### VS Code
+
+```json
+{
+  "servers": {
+    "google-workspace": {
+      "url": "http://localhost:8000/mcp/",
+      "type": "http"
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add --transport http workspace-mcp http://localhost:8000/mcp
+```
+
+---
+
+## 🏗 Architecture
+
+```
+google_workspace_mcp/
+├── auth/                 # OAuth 2.0/2.1, credential storage, decorators
+├── core/                 # MCP server, tool registry, utilities
+├── gcalendar/           # Calendar tools
+├── gchat/               # Chat tools
+├── gdocs/               # Docs tools + managers (tables, headers, batch)
+├── gdrive/              # Drive tools + helpers
+├── gforms/              # Forms tools
+├── gmail/               # Gmail tools
+├── gsearch/             # Custom Search tools
+├── gsheets/             # Sheets tools + helpers
+���── gslides/             # Slides tools
+├── gtasks/              # Tasks tools
+└── main.py              # Entry point
+```
+
+### Key Patterns
+
+**Service Decorator:** All tools use `@require_google_service()` for automatic authentication with 30-minute service caching.
+
+```python
+@server.tool()
+@require_google_service("gmail", "gmail_read")
+async def search_gmail_messages(service, user_google_email: str, query: str):
+    # service is injected automatically
+    ...
+```
+
+**Multi-Service Tools:** Some tools need multiple APIs:
+
+```python
+@require_multiple_services([
+    {"service_type": "drive", "scopes": "drive_read", "param_name": "drive_service"},
+    {"service_type": "docs", "scopes": "docs_read", "param_name": "docs_service"},
+])
+async def get_doc_content(drive_service, docs_service, ...):
+    ...
+```
+
+---
+
+## 🧪 Development
+
+```bash
+git clone https://github.com/taylorwilsdon/google_workspace_mcp.git
+cd google_workspace_mcp
+
+# Install with dev dependencies
+uv sync --group dev
+
+# Run locally
+uv run main.py
+
+# Run tests
+uv run pytest
+
+# Lint
+uv run ruff check .
+```
+
+---
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+---
+
+<div align="center">
+
+**[Documentation](https://workspacemcp.com)** • **[Issues](https://github.com/taylorwilsdon/google_workspace_mcp/issues)** • **[PyPI](https://pypi.org/project/workspace-mcp/)**
+
+</div>

SECURITY.md

@@ -0,0 +1,48 @@
+# Security Policy
+
+## Reporting Security Issues
+
+**Please do not report security vulnerabilities through public GitHub issues, discussions, or pull requests.**
+
+Instead, please email us at **taylor@workspacemcp.com**
+
+Please include as much of the following information as you can to help us better understand and resolve the issue:
+
+- The type of issue (e.g., authentication bypass, credential exposure, command injection, etc.)
+- Full paths of source file(s) related to the manifestation of the issue
+- The location of the affected source code (tag/branch/commit or direct URL)
+- Any special configuration required to reproduce the issue
+- Step-by-step instructions to reproduce the issue
+- Proof-of-concept or exploit code (if possible)
+- Impact of the issue, including how an attacker might exploit the issue
+
+This information will help us triage your report more quickly.
+
+## Supported Versions
+
+We release patches for security vulnerabilities. Which versions are eligible for receiving such patches depends on the CVSS v3.0 Rating:
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 1.4.x   | :white_check_mark: |
+| < 1.4   | :x:                |
+
+## Security Considerations
+
+When using this MCP server, please ensure:
+
+1. Store Google OAuth credentials securely
+2. Never commit credentials to version control
+3. Use environment variables for sensitive configuration
+4. Regularly rotate OAuth refresh tokens
+5. Limit OAuth scopes to only what's necessary
+
+For more information on securing your use of the project, see https://workspacemcp.com/privacy
+
+## Preferred Languages
+
+We prefer all communications to be in English.
+
+## Policy
+
+We follow the principle of responsible disclosure. We will make every effort to address security issues in a timely manner and will coordinate with reporters to understand and resolve issues before public disclosure.

auth/__init__.py

@@ -0,0 +1 @@
+# Make the auth directory a Python package

auth/auth_info_middleware.py

@@ -0,0 +1,425 @@
+"""
+Authentication middleware to populate context state with user information
+"""
+
+import jwt
+import logging
+import os
+import time
+from types import SimpleNamespace
+from fastmcp.server.middleware import Middleware, MiddlewareContext
+from fastmcp.server.dependencies import get_http_headers
+
+from auth.oauth21_session_store import ensure_session_from_access_token
+
+# Configure logging
+logger = logging.getLogger(__name__)
+
+
+class AuthInfoMiddleware(Middleware):
+    """
+    Middleware to extract authentication information from JWT tokens
+    and populate the FastMCP context state for use in tools and prompts.
+    """
+
+    def __init__(self):
+        super().__init__()
+        self.auth_provider_type = "GoogleProvider"
+
+    async def _process_request_for_auth(self, context: MiddlewareContext):
+        """Helper to extract, verify, and store auth info from a request."""
+        if not context.fastmcp_context:
+            logger.warning("No fastmcp_context available")
+            return
+
+        # Return early if authentication state is already set
+        if context.fastmcp_context.get_state("authenticated_user_email"):
+            logger.info("Authentication state already set.")
+            return
+
+        # Try to get the HTTP request to extract Authorization header
+        try:
+            # Use the new FastMCP method to get HTTP headers
+            headers = get_http_headers()
+            if headers:
+                logger.debug("Processing HTTP headers for authentication")
+
+                # Get the Authorization header
+                auth_header = headers.get("authorization", "")
+                if auth_header.startswith("Bearer "):
+                    token_str = auth_header[7:]  # Remove "Bearer " prefix
+                    logger.debug("Found Bearer token")
+
+                    # For Google OAuth tokens (ya29.*), we need to verify them differently
+                    if token_str.startswith("ya29."):
+                        logger.debug("Detected Google OAuth access token format")
+
+                        # Verify the token to get user info
+                        from core.server import get_auth_provider
+
+                        auth_provider = get_auth_provider()
+
+                        if auth_provider:
+                            try:
+                                # Verify the token
+                                verified_auth = await auth_provider.verify_token(
+                                    token_str
+                                )
+                                if verified_auth:
+                                    # Extract user info from verified token
+                                    user_email = None
+                                    if hasattr(verified_auth, "claims"):
+                                        user_email = verified_auth.claims.get("email")
+
+                                    # Get expires_at, defaulting to 1 hour from now if not available
+                                    if hasattr(verified_auth, "expires_at"):
+                                        expires_at = verified_auth.expires_at
+                                    else:
+                                        expires_at = (
+                                            int(time.time()) + 3600
+                                        )  # Default to 1 hour
+
+                                    # Get client_id from verified auth or use default
+                                    client_id = (
+                                        getattr(verified_auth, "client_id", None)
+                                        or "google"
+                                    )
+
+                                    access_token = SimpleNamespace(
+                                        token=token_str,
+                                        client_id=client_id,
+                                        scopes=verified_auth.scopes
+                                        if hasattr(verified_auth, "scopes")
+                                        else [],
+                                        session_id=f"google_oauth_{token_str[:8]}",
+                                        expires_at=expires_at,
+                                        # Add other fields that might be needed
+                                        sub=verified_auth.sub
+                                        if hasattr(verified_auth, "sub")
+                                        else user_email,
+                                        email=user_email,
+                                    )
+
+                                    # Store in context state - this is the authoritative authentication state
+                                    context.fastmcp_context.set_state(
+                                        "access_token", access_token
+                                    )
+                                    mcp_session_id = getattr(
+                                        context.fastmcp_context, "session_id", None
+                                    )
+                                    ensure_session_from_access_token(
+                                        verified_auth,
+                                        user_email,
+                                        mcp_session_id,
+                                    )
+                                    context.fastmcp_context.set_state(
+                                        "access_token_obj", verified_auth
+                                    )
+                                    context.fastmcp_context.set_state(
+                                        "auth_provider_type", self.auth_provider_type
+                                    )
+                                    context.fastmcp_context.set_state(
+                                        "token_type", "google_oauth"
+                                    )
+                                    context.fastmcp_context.set_state(
+                                        "user_email", user_email
+                                    )
+                                    context.fastmcp_context.set_state(
+                                        "username", user_email
+                                    )
+                                    # Set the definitive authentication state
+                                    context.fastmcp_context.set_state(
+                                        "authenticated_user_email", user_email
+                                    )
+                                    context.fastmcp_context.set_state(
+                                        "authenticated_via", "bearer_token"
+                                    )
+
+                                    logger.info(
+                                        f"Authenticated via Google OAuth: {user_email}"
+                                    )
+                                else:
+                                    logger.error("Failed to verify Google OAuth token")
+                                # Don't set authenticated_user_email if verification failed
+                            except Exception as e:
+                                logger.error(f"Error verifying Google OAuth token: {e}")
+                                # Still store the unverified token - service decorator will handle verification
+                                access_token = SimpleNamespace(
+                                    token=token_str,
+                                    client_id=os.getenv(
+                                        "GOOGLE_OAUTH_CLIENT_ID", "google"
+                                    ),
+                                    scopes=[],
+                                    session_id=f"google_oauth_{token_str[:8]}",
+                                    expires_at=int(time.time())
+                                    + 3600,  # Default to 1 hour
+                                    sub="unknown",
+                                    email="",
+                                )
+                                context.fastmcp_context.set_state(
+                                    "access_token", access_token
+                                )
+                                context.fastmcp_context.set_state(
+                                    "auth_provider_type", self.auth_provider_type
+                                )
+                                context.fastmcp_context.set_state(
+                                    "token_type", "google_oauth"
+                                )
+                        else:
+                            logger.warning(
+                                "No auth provider available to verify Google token"
+                            )
+                            # Store unverified token
+                            access_token = SimpleNamespace(
+                                token=token_str,
+                                client_id=os.getenv("GOOGLE_OAUTH_CLIENT_ID", "google"),
+                                scopes=[],
+                                session_id=f"google_oauth_{token_str[:8]}",
+                                expires_at=int(time.time()) + 3600,  # Default to 1 hour
+                                sub="unknown",
+                                email="",
+                            )
+                            context.fastmcp_context.set_state(
+                                "access_token", access_token
+                            )
+                            context.fastmcp_context.set_state(
+                                "auth_provider_type", self.auth_provider_type
+                            )
+                            context.fastmcp_context.set_state(
+                                "token_type", "google_oauth"
+                            )
+
+                    else:
+                        # Decode JWT to get user info
+                        try:
+                            token_payload = jwt.decode(
+                                token_str, options={"verify_signature": False}
+                            )
+                            logger.debug(
+                                f"JWT payload decoded: {list(token_payload.keys())}"
+                            )
+
+                            # Create an AccessToken-like object
+                            access_token = SimpleNamespace(
+                                token=token_str,
+                                client_id=token_payload.get("client_id", "unknown"),
+                                scopes=token_payload.get("scope", "").split()
+                                if token_payload.get("scope")
+                                else [],
+                                session_id=token_payload.get(
+                                    "sid",
+                                    token_payload.get(
+                                        "jti",
+                                        token_payload.get("session_id", "unknown"),
+                                    ),
+                                ),
+                                expires_at=token_payload.get("exp", 0),
+                            )
+
+                            # Store in context state
+                            context.fastmcp_context.set_state(
+                                "access_token", access_token
+                            )
+
+                            # Store additional user info
+                            context.fastmcp_context.set_state(
+                                "user_id", token_payload.get("sub")
+                            )
+                            context.fastmcp_context.set_state(
+                                "username",
+                                token_payload.get(
+                                    "username", token_payload.get("email")
+                                ),
+                            )
+                            context.fastmcp_context.set_state(
+                                "name", token_payload.get("name")
+                            )
+                            context.fastmcp_context.set_state(
+                                "auth_time", token_payload.get("auth_time")
+                            )
+                            context.fastmcp_context.set_state(
+                                "issuer", token_payload.get("iss")
+                            )
+                            context.fastmcp_context.set_state(
+                                "audience", token_payload.get("aud")
+                            )
+                            context.fastmcp_context.set_state(
+                                "jti", token_payload.get("jti")
+                            )
+                            context.fastmcp_context.set_state(
+                                "auth_provider_type", self.auth_provider_type
+                            )
+
+                            # Set the definitive authentication state for JWT tokens
+                            user_email = token_payload.get(
+                                "email", token_payload.get("username")
+                            )
+                            if user_email:
+                                context.fastmcp_context.set_state(
+                                    "authenticated_user_email", user_email
+                                )
+                                context.fastmcp_context.set_state(
+                                    "authenticated_via", "jwt_token"
+                                )
+
+                            logger.debug("JWT token processed successfully")
+
+                        except jwt.DecodeError as e:
+                            logger.error(f"Failed to decode JWT: {e}")
+                        except Exception as e:
+                            logger.error(f"Error processing JWT: {e}")
+                else:
+                    logger.debug("No Bearer token in Authorization header")
+            else:
+                logger.debug(
+                    "No HTTP headers available (might be using stdio transport)"
+                )
+        except Exception as e:
+            logger.debug(f"Could not get HTTP request: {e}")
+
+        # After trying HTTP headers, check for other authentication methods
+        # This consolidates all authentication logic in the middleware
+        if not context.fastmcp_context.get_state("authenticated_user_email"):
+            logger.debug(
+                "No authentication found via bearer token, checking other methods"
+            )
+
+            # Check transport mode
+            from core.config import get_transport_mode
+
+            transport_mode = get_transport_mode()
+
+            if transport_mode == "stdio":
+                # In stdio mode, check if there's a session with credentials
+                # This is ONLY safe in stdio mode because it's single-user
+                logger.debug("Checking for stdio mode authentication")
+
+                # Get the requested user from the context if available
+                requested_user = None
+                if hasattr(context, "request") and hasattr(context.request, "params"):
+                    requested_user = context.request.params.get("user_google_email")
+                elif hasattr(context, "arguments"):
+                    # FastMCP may store arguments differently
+                    requested_user = context.arguments.get("user_google_email")
+
+                if requested_user:
+                    try:
+                        from auth.oauth21_session_store import get_oauth21_session_store
+
+                        store = get_oauth21_session_store()
+
+                        # Check if user has a recent session
+                        if store.has_session(requested_user):
+                            logger.debug(
+                                f"Using recent stdio session for {requested_user}"
+                            )
+                            # In stdio mode, we can trust the user has authenticated recently
+                            context.fastmcp_context.set_state(
+                                "authenticated_user_email", requested_user
+                            )
+                            context.fastmcp_context.set_state(
+                                "authenticated_via", "stdio_session"
+                            )
+                            context.fastmcp_context.set_state(
+                                "auth_provider_type", "oauth21_stdio"
+                            )
+                    except Exception as e:
+                        logger.debug(f"Error checking stdio session: {e}")
+
+                # If no requested user was provided but exactly one session exists, assume it in stdio mode
+                if not context.fastmcp_context.get_state("authenticated_user_email"):
+                    try:
+                        from auth.oauth21_session_store import get_oauth21_session_store
+
+                        store = get_oauth21_session_store()
+                        single_user = store.get_single_user_email()
+                        if single_user:
+                            logger.debug(
+                                f"Defaulting to single stdio OAuth session for {single_user}"
+                            )
+                            context.fastmcp_context.set_state(
+                                "authenticated_user_email", single_user
+                            )
+                            context.fastmcp_context.set_state(
+                                "authenticated_via", "stdio_single_session"
+                            )
+                            context.fastmcp_context.set_state(
+                                "auth_provider_type", "oauth21_stdio"
+                            )
+                            context.fastmcp_context.set_state("user_email", single_user)
+                            context.fastmcp_context.set_state("username", single_user)
+                    except Exception as e:
+                        logger.debug(
+                            f"Error determining stdio single-user session: {e}"
+                        )
+
+            # Check for MCP session binding
+            if not context.fastmcp_context.get_state(
+                "authenticated_user_email"
+            ) and hasattr(context.fastmcp_context, "session_id"):
+                mcp_session_id = context.fastmcp_context.session_id
+                if mcp_session_id:
+                    try:
+                        from auth.oauth21_session_store import get_oauth21_session_store
+
+                        store = get_oauth21_session_store()
+
+                        # Check if this MCP session is bound to a user
+                        bound_user = store.get_user_by_mcp_session(mcp_session_id)
+                        if bound_user:
+                            logger.debug(f"MCP session bound to {bound_user}")
+                            context.fastmcp_context.set_state(
+                                "authenticated_user_email", bound_user
+                            )
+                            context.fastmcp_context.set_state(
+                                "authenticated_via", "mcp_session_binding"
+                            )
+                            context.fastmcp_context.set_state(
+                                "auth_provider_type", "oauth21_session"
+                            )
+                    except Exception as e:
+                        logger.debug(f"Error checking MCP session binding: {e}")
+
+    async def on_call_tool(self, context: MiddlewareContext, call_next):
+        """Extract auth info from token and set in context state"""
+        logger.debug("Processing tool call authentication")
+
+        try:
+            await self._process_request_for_auth(context)
+
+            logger.debug("Passing to next handler")
+            result = await call_next(context)
+            logger.debug("Handler completed")
+            return result
+
+        except Exception as e:
+            # Check if this is an authentication error - don't log traceback for these
+            if "GoogleAuthenticationError" in str(
+                type(e)
+            ) or "Access denied: Cannot retrieve credentials" in str(e):
+                logger.info(f"Authentication check failed: {e}")
+            else:
+                logger.error(f"Error in on_call_tool middleware: {e}", exc_info=True)
+            raise
+
+    async def on_get_prompt(self, context: MiddlewareContext, call_next):
+        """Extract auth info for prompt requests too"""
+        logger.debug("Processing prompt authentication")
+
+        try:
+            await self._process_request_for_auth(context)
+
+            logger.debug("Passing prompt to next handler")
+            result = await call_next(context)
+            logger.debug("Prompt handler completed")
+            return result
+
+        except Exception as e:
+            # Check if this is an authentication error - don't log traceback for these
+            if "GoogleAuthenticationError" in str(
+                type(e)
+            ) or "Access denied: Cannot retrieve credentials" in str(e):
+                logger.info(f"Authentication check failed in prompt: {e}")
+            else:
+                logger.error(f"Error in on_get_prompt middleware: {e}", exc_info=True)
+            raise

auth/credential_store.py

@@ -0,0 +1,246 @@
+"""
+Credential Store API for Google Workspace MCP
+
+This module provides a standardized interface for credential storage and retrieval,
+supporting multiple backends configurable via environment variables.
+"""
+
+import os
+import json
+import logging
+from abc import ABC, abstractmethod
+from typing import Optional, List
+from datetime import datetime
+from google.oauth2.credentials import Credentials
+
+logger = logging.getLogger(__name__)
+
+
+class CredentialStore(ABC):
+    """Abstract base class for credential storage."""
+
+    @abstractmethod
+    def get_credential(self, user_email: str) -> Optional[Credentials]:
+        """
+        Get credentials for a user by email.
+
+        Args:
+            user_email: User's email address
+
+        Returns:
+            Google Credentials object or None if not found
+        """
+        pass
+
+    @abstractmethod
+    def store_credential(self, user_email: str, credentials: Credentials) -> bool:
+        """
+        Store credentials for a user.
+
+        Args:
+            user_email: User's email address
+            credentials: Google Credentials object to store
+
+        Returns:
+            True if successfully stored, False otherwise
+        """
+        pass
+
+    @abstractmethod
+    def delete_credential(self, user_email: str) -> bool:
+        """
+        Delete credentials for a user.
+
+        Args:
+            user_email: User's email address
+
+        Returns:
+            True if successfully deleted, False otherwise
+        """
+        pass
+
+    @abstractmethod
+    def list_users(self) -> List[str]:
+        """
+        List all users with stored credentials.
+
+        Returns:
+            List of user email addresses
+        """
+        pass
+
+
+class LocalDirectoryCredentialStore(CredentialStore):
+    """Credential store that uses local JSON files for storage."""
+
+    def __init__(self, base_dir: Optional[str] = None):
+        """
+        Initialize the local JSON credential store.
+
+        Args:
+            base_dir: Base directory for credential files. If None, uses the directory
+                     configured by the GOOGLE_MCP_CREDENTIALS_DIR environment variable,
+                     or defaults to ~/.google_workspace_mcp/credentials if the environment
+                     variable is not set.
+        """
+        if base_dir is None:
+            if os.getenv("GOOGLE_MCP_CREDENTIALS_DIR"):
+                base_dir = os.getenv("GOOGLE_MCP_CREDENTIALS_DIR")
+            else:
+                home_dir = os.path.expanduser("~")
+                if home_dir and home_dir != "~":
+                    base_dir = os.path.join(
+                        home_dir, ".google_workspace_mcp", "credentials"
+                    )
+                else:
+                    base_dir = os.path.join(os.getcwd(), ".credentials")
+
+        self.base_dir = base_dir
+        logger.info(f"LocalJsonCredentialStore initialized with base_dir: {base_dir}")
+
+    def _get_credential_path(self, user_email: str) -> str:
+        """Get the file path for a user's credentials."""
+        if not os.path.exists(self.base_dir):
+            os.makedirs(self.base_dir)
+            logger.info(f"Created credentials directory: {self.base_dir}")
+        return os.path.join(self.base_dir, f"{user_email}.json")
+
+    def get_credential(self, user_email: str) -> Optional[Credentials]:
+        """Get credentials from local JSON file."""
+        creds_path = self._get_credential_path(user_email)
+
+        if not os.path.exists(creds_path):
+            logger.debug(f"No credential file found for {user_email} at {creds_path}")
+            return None
+
+        try:
+            with open(creds_path, "r") as f:
+                creds_data = json.load(f)
+
+            # Parse expiry if present
+            expiry = None
+            if creds_data.get("expiry"):
+                try:
+                    expiry = datetime.fromisoformat(creds_data["expiry"])
+                    # Ensure timezone-naive datetime for Google auth library compatibility
+                    if expiry.tzinfo is not None:
+                        expiry = expiry.replace(tzinfo=None)
+                except (ValueError, TypeError) as e:
+                    logger.warning(f"Could not parse expiry time for {user_email}: {e}")
+
+            credentials = Credentials(
+                token=creds_data.get("token"),
+                refresh_token=creds_data.get("refresh_token"),
+                token_uri=creds_data.get("token_uri"),
+                client_id=creds_data.get("client_id"),
+                client_secret=creds_data.get("client_secret"),
+                scopes=creds_data.get("scopes"),
+                expiry=expiry,
+            )
+
+            logger.debug(f"Loaded credentials for {user_email} from {creds_path}")
+            return credentials
+
+        except (IOError, json.JSONDecodeError, KeyError) as e:
+            logger.error(
+                f"Error loading credentials for {user_email} from {creds_path}: {e}"
+            )
+            return None
+
+    def store_credential(self, user_email: str, credentials: Credentials) -> bool:
+        """Store credentials to local JSON file."""
+        creds_path = self._get_credential_path(user_email)
+
+        creds_data = {
+            "token": credentials.token,
+            "refresh_token": credentials.refresh_token,
+            "token_uri": credentials.token_uri,
+            "client_id": credentials.client_id,
+            "client_secret": credentials.client_secret,
+            "scopes": credentials.scopes,
+            "expiry": credentials.expiry.isoformat() if credentials.expiry else None,
+        }
+
+        try:
+            with open(creds_path, "w") as f:
+                json.dump(creds_data, f, indent=2)
+            logger.info(f"Stored credentials for {user_email} to {creds_path}")
+            return True
+        except IOError as e:
+            logger.error(
+                f"Error storing credentials for {user_email} to {creds_path}: {e}"
+            )
+            return False
+
+    def delete_credential(self, user_email: str) -> bool:
+        """Delete credential file for a user."""
+        creds_path = self._get_credential_path(user_email)
+
+        try:
+            if os.path.exists(creds_path):
+                os.remove(creds_path)
+                logger.info(f"Deleted credentials for {user_email} from {creds_path}")
+                return True
+            else:
+                logger.debug(
+                    f"No credential file to delete for {user_email} at {creds_path}"
+                )
+                return True  # Consider it a success if file doesn't exist
+        except IOError as e:
+            logger.error(
+                f"Error deleting credentials for {user_email} from {creds_path}: {e}"
+            )
+            return False
+
+    def list_users(self) -> List[str]:
+        """List all users with credential files."""
+        if not os.path.exists(self.base_dir):
+            return []
+
+        users = []
+        try:
+            for filename in os.listdir(self.base_dir):
+                if filename.endswith(".json"):
+                    user_email = filename[:-5]  # Remove .json extension
+                    users.append(user_email)
+            logger.debug(
+                f"Found {len(users)} users with credentials in {self.base_dir}"
+            )
+        except OSError as e:
+            logger.error(f"Error listing credential files in {self.base_dir}: {e}")
+
+        return sorted(users)
+
+
+# Global credential store instance
+_credential_store: Optional[CredentialStore] = None
+
+
+def get_credential_store() -> CredentialStore:
+    """
+    Get the global credential store instance.
+
+    Returns:
+        Configured credential store instance
+    """
+    global _credential_store
+
+    if _credential_store is None:
+        # always use LocalJsonCredentialStore as the default
+        # Future enhancement: support other backends via environment variables
+        _credential_store = LocalDirectoryCredentialStore()
+        logger.info(f"Initialized credential store: {type(_credential_store).__name__}")
+
+    return _credential_store
+
+
+def set_credential_store(store: CredentialStore):
+    """
+    Set the global credential store instance.
+
+    Args:
+        store: Credential store instance to use
+    """
+    global _credential_store
+    _credential_store = store
+    logger.info(f"Set credential store: {type(store).__name__}")

auth/external_oauth_provider.py

@@ -0,0 +1,99 @@
+"""
+External OAuth Provider for Google Workspace MCP
+
+Extends FastMCP's GoogleProvider to support external OAuth flows where
+access tokens (ya29.*) are issued by external systems and need validation.
+"""
+
+import logging
+import time
+from typing import Optional
+
+from fastmcp.server.auth.providers.google import GoogleProvider
+from fastmcp.server.auth import AccessToken
+from google.oauth2.credentials import Credentials
+
+logger = logging.getLogger(__name__)
+
+
+class ExternalOAuthProvider(GoogleProvider):
+    """
+    Extended GoogleProvider that supports validating external Google OAuth access tokens.
+
+    This provider handles ya29.* access tokens by calling Google's userinfo API,
+    while maintaining compatibility with standard JWT ID tokens.
+    """
+
+    def __init__(self, client_id: str, client_secret: str, **kwargs):
+        """Initialize and store client credentials for token validation."""
+        super().__init__(client_id=client_id, client_secret=client_secret, **kwargs)
+        # Store credentials as they're not exposed by parent class
+        self._client_id = client_id
+        self._client_secret = client_secret
+
+    async def verify_token(self, token: str) -> Optional[AccessToken]:
+        """
+        Verify a token - supports both JWT ID tokens and ya29.* access tokens.
+
+        For ya29.* access tokens (issued externally), validates by calling
+        Google's userinfo API. For JWT tokens, delegates to parent class.
+
+        Args:
+            token: Token string to verify (JWT or ya29.* access token)
+
+        Returns:
+            AccessToken object if valid, None otherwise
+        """
+        # For ya29.* access tokens, validate using Google's userinfo API
+        if token.startswith("ya29."):
+            logger.debug("Validating external Google OAuth access token")
+
+            try:
+                from auth.google_auth import get_user_info
+
+                # Create minimal Credentials object for userinfo API call
+                credentials = Credentials(
+                    token=token,
+                    token_uri="https://oauth2.googleapis.com/token",
+                    client_id=self._client_id,
+                    client_secret=self._client_secret,
+                )
+
+                # Validate token by calling userinfo API
+                user_info = get_user_info(credentials)
+
+                if user_info and user_info.get("email"):
+                    # Token is valid - create AccessToken object
+                    logger.info(
+                        f"Validated external access token for: {user_info['email']}"
+                    )
+
+                    # Create a mock AccessToken that the middleware expects
+                    # This matches the structure that FastMCP's AccessToken would have
+                    from types import SimpleNamespace
+
+                    scope_list = list(getattr(self, "required_scopes", []) or [])
+                    access_token = SimpleNamespace(
+                        token=token,
+                        scopes=scope_list,
+                        expires_at=int(time.time())
+                        + 3600,  # Default to 1-hour validity
+                        claims={
+                            "email": user_info["email"],
+                            "sub": user_info.get("id"),
+                        },
+                        client_id=self._client_id,
+                        email=user_info["email"],
+                        sub=user_info.get("id"),
+                    )
+                    return access_token
+                else:
+                    logger.error("Could not get user info from access token")
+                    return None
+
+            except Exception as e:
+                logger.error(f"Error validating external access token: {e}")
+                return None
+
+        # For JWT tokens, use parent class implementation
+        return await super().verify_token(token)

auth/google_auth.py

@@ -0,0 +1,934 @@
+# auth/google_auth.py
+
+import asyncio
+import json
+import jwt
+import logging
+import os
+
+from typing import List, Optional, Tuple, Dict, Any
+from urllib.parse import parse_qs, urlparse
+
+from google.oauth2.credentials import Credentials
+from google_auth_oauthlib.flow import Flow
+from google.auth.transport.requests import Request
+from google.auth.exceptions import RefreshError
+from googleapiclient.discovery import build
+from googleapiclient.errors import HttpError
+from auth.scopes import SCOPES, get_current_scopes  # noqa
+from auth.oauth21_session_store import get_oauth21_session_store
+from auth.credential_store import get_credential_store
+from auth.oauth_config import get_oauth_config, is_stateless_mode
+from core.config import (
+    get_transport_mode,
+    get_oauth_redirect_uri,
+)
+from core.context import get_fastmcp_session_id
+
+# Try to import FastMCP dependencies (may not be available in all environments)
+try:
+    from fastmcp.server.dependencies import get_context as get_fastmcp_context
+except ImportError:
+    get_fastmcp_context = None
+
+# Configure logging
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+# Constants
+def get_default_credentials_dir():
+    """Get the default credentials directory path, preferring user-specific locations."""
+    # Check for explicit environment variable override
+    if os.getenv("GOOGLE_MCP_CREDENTIALS_DIR"):
+        return os.getenv("GOOGLE_MCP_CREDENTIALS_DIR")
+
+    # Use user home directory for credentials storage
+    home_dir = os.path.expanduser("~")
+    if home_dir and home_dir != "~":  # Valid home directory found
+        return os.path.join(home_dir, ".google_workspace_mcp", "credentials")
+
+    # Fallback to current working directory if home directory is not accessible
+    return os.path.join(os.getcwd(), ".credentials")
+
+
+DEFAULT_CREDENTIALS_DIR = get_default_credentials_dir()
+
+# Session credentials now handled by OAuth21SessionStore - no local cache needed
+# Centralized Client Secrets Path Logic
+_client_secrets_env = os.getenv("GOOGLE_CLIENT_SECRET_PATH") or os.getenv(
+    "GOOGLE_CLIENT_SECRETS"
+)
+if _client_secrets_env:
+    CONFIG_CLIENT_SECRETS_PATH = _client_secrets_env
+else:
+    # Assumes this file is in auth/ and client_secret.json is in the root
+    CONFIG_CLIENT_SECRETS_PATH = os.path.join(
+        os.path.dirname(os.path.dirname(os.path.abspath(__file__))),
+        "client_secret.json",
+    )
+
+# --- Helper Functions ---
+
+
+def _find_any_credentials(
+    base_dir: str = DEFAULT_CREDENTIALS_DIR,
+) -> Optional[Credentials]:
+    """
+    Find and load any valid credentials from the credentials directory.
+    Used in single-user mode to bypass session-to-OAuth mapping.
+
+    Returns:
+        First valid Credentials object found, or None if none exist.
+    """
+    try:
+        store = get_credential_store()
+        users = store.list_users()
+        if not users:
+            logger.info(
+                "[single-user] No users found with credentials via credential store"
+            )
+            return None
+
+        # Prefer USER_GOOGLE_EMAIL from environment if set
+        preferred_user = os.getenv("USER_GOOGLE_EMAIL", "").strip()
+        if preferred_user and preferred_user in users:
+            credentials = store.get_credential(preferred_user)
+            if credentials:
+                logger.info(
+                    f"[single-user] Found credentials for preferred user {preferred_user} via credential store"
+                )
+                return credentials
+
+        # Fallback to first user found
+        first_user = users[0]
+        credentials = store.get_credential(first_user)
+        if credentials:
+            logger.info(
+                f"[single-user] Found credentials for {first_user} via credential store"
+            )
+            return credentials
+        else:
+            logger.warning(
+                f"[single-user] Could not load credentials for {first_user} via credential store"
+            )
+
+    except Exception as e:
+        logger.error(
+            f"[single-user] Error finding credentials via credential store: {e}"
+        )
+
+    logger.info("[single-user] No valid credentials found via credential store")
+    return None
+
+
+def save_credentials_to_session(session_id: str, credentials: Credentials):
+    """Saves user credentials using OAuth21SessionStore."""
+    # Get user email from credentials if possible
+    user_email = None
+    if credentials and credentials.id_token:
+        try:
+            decoded_token = jwt.decode(
+                credentials.id_token, options={"verify_signature": False}
+            )
+            user_email = decoded_token.get("email")
+        except Exception as e:
+            logger.debug(f"Could not decode id_token to get email: {e}")
+
+    if user_email:
+        store = get_oauth21_session_store()
+        store.store_session(
+            user_email=user_email,
+            access_token=credentials.token,
+            refresh_token=credentials.refresh_token,
+            token_uri=credentials.token_uri,
+            client_id=credentials.client_id,
+            client_secret=credentials.client_secret,
+            scopes=credentials.scopes,
+            expiry=credentials.expiry,
+            mcp_session_id=session_id,
+        )
+        logger.debug(
+            f"Credentials saved to OAuth21SessionStore for session_id: {session_id}, user: {user_email}"
+        )
+    else:
+        logger.warning(
+            f"Could not save credentials to session store - no user email found for session: {session_id}"
+        )
+
+
+def load_credentials_from_session(session_id: str) -> Optional[Credentials]:
+    """Loads user credentials from OAuth21SessionStore."""
+    store = get_oauth21_session_store()
+    credentials = store.get_credentials_by_mcp_session(session_id)
+    if credentials:
+        logger.debug(
+            f"Credentials loaded from OAuth21SessionStore for session_id: {session_id}"
+        )
+    else:
+        logger.debug(
+            f"No credentials found in OAuth21SessionStore for session_id: {session_id}"
+        )
+    return credentials
+
+
+def load_client_secrets_from_env() -> Optional[Dict[str, Any]]:
+    """
+    Loads the client secrets from environment variables.
+
+    Environment variables used:
+        - GOOGLE_OAUTH_CLIENT_ID: OAuth 2.0 client ID
+        - GOOGLE_OAUTH_CLIENT_SECRET: OAuth 2.0 client secret
+        - GOOGLE_OAUTH_REDIRECT_URI: (optional) OAuth redirect URI
+
+    Returns:
+        Client secrets configuration dict compatible with Google OAuth library,
+        or None if required environment variables are not set.
+    """
+    client_id = os.getenv("GOOGLE_OAUTH_CLIENT_ID")
+    client_secret = os.getenv("GOOGLE_OAUTH_CLIENT_SECRET")
+    redirect_uri = os.getenv("GOOGLE_OAUTH_REDIRECT_URI")
+
+    if client_id and client_secret:
+        # Create config structure that matches Google client secrets format
+        web_config = {
+            "client_id": client_id,
+            "client_secret": client_secret,
+            "auth_uri": "https://accounts.google.com/o/oauth2/auth",
+            "token_uri": "https://oauth2.googleapis.com/token",
+            "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
+        }
+
+        # Add redirect_uri if provided via environment variable
+        if redirect_uri:
+            web_config["redirect_uris"] = [redirect_uri]
+
+        # Return the full config structure expected by Google OAuth library
+        config = {"web": web_config}
+
+        logger.info("Loaded OAuth client credentials from environment variables")
+        return config
+
+    logger.debug("OAuth client credentials not found in environment variables")
+    return None
+
+
+def load_client_secrets(client_secrets_path: str) -> Dict[str, Any]:
+    """
+    Loads the client secrets from environment variables (preferred) or from the client secrets file.
+
+    Priority order:
+    1. Environment variables (GOOGLE_OAUTH_CLIENT_ID, GOOGLE_OAUTH_CLIENT_SECRET)
+    2. File-based credentials at the specified path
+
+    Args:
+        client_secrets_path: Path to the client secrets JSON file (used as fallback)
+
+    Returns:
+        Client secrets configuration dict
+
+    Raises:
+        ValueError: If client secrets file has invalid format
+        IOError: If file cannot be read and no environment variables are set
+    """
+    # First, try to load from environment variables
+    env_config = load_client_secrets_from_env()
+    if env_config:
+        # Extract the "web" config from the environment structure
+        return env_config["web"]
+
+    # Fall back to loading from file
+    try:
+        with open(client_secrets_path, "r") as f:
+            client_config = json.load(f)
+            # The file usually contains a top-level key like "web" or "installed"
+            if "web" in client_config:
+                logger.info(
+                    f"Loaded OAuth client credentials from file: {client_secrets_path}"
+                )
+                return client_config["web"]
+            elif "installed" in client_config:
+                logger.info(
+                    f"Loaded OAuth client credentials from file: {client_secrets_path}"
+                )
+                return client_config["installed"]
+            else:
+                logger.error(
+                    f"Client secrets file {client_secrets_path} has unexpected format."
+                )
+                raise ValueError("Invalid client secrets file format")
+    except (IOError, json.JSONDecodeError) as e:
+        logger.error(f"Error loading client secrets file {client_secrets_path}: {e}")
+        raise
+
+
+def check_client_secrets() -> Optional[str]:
+    """
+    Checks for the presence of OAuth client secrets, either as environment
+    variables or as a file.
+
+    Returns:
+        An error message string if secrets are not found, otherwise None.
+    """
+    env_config = load_client_secrets_from_env()
+    if not env_config and not os.path.exists(CONFIG_CLIENT_SECRETS_PATH):
+        logger.error(
+            f"OAuth client credentials not found. No environment variables set and no file at {CONFIG_CLIENT_SECRETS_PATH}"
+        )
+        return f"OAuth client credentials not found. Please set GOOGLE_OAUTH_CLIENT_ID and GOOGLE_OAUTH_CLIENT_SECRET environment variables or provide a client secrets file at {CONFIG_CLIENT_SECRETS_PATH}."
+    return None
+
+
+def create_oauth_flow(
+    scopes: List[str], redirect_uri: str, state: Optional[str] = None
+) -> Flow:
+    """Creates an OAuth flow using environment variables or client secrets file."""
+    # Try environment variables first
+    env_config = load_client_secrets_from_env()
+    if env_config:
+        # Use client config directly
+        flow = Flow.from_client_config(
+            env_config, scopes=scopes, redirect_uri=redirect_uri, state=state
+        )
+        logger.debug("Created OAuth flow from environment variables")
+        return flow
+
+    # Fall back to file-based config
+    if not os.path.exists(CONFIG_CLIENT_SECRETS_PATH):
+        raise FileNotFoundError(
+            f"OAuth client secrets file not found at {CONFIG_CLIENT_SECRETS_PATH} and no environment variables set"
+        )
+
+    flow = Flow.from_client_secrets_file(
+        CONFIG_CLIENT_SECRETS_PATH,
+        scopes=scopes,
+        redirect_uri=redirect_uri,
+        state=state,
+    )
+    logger.debug(
+        f"Created OAuth flow from client secrets file: {CONFIG_CLIENT_SECRETS_PATH}"
+    )
+    return flow
+
+
+# --- Core OAuth Logic ---
+
+
+async def start_auth_flow(
+    user_google_email: Optional[str],
+    service_name: str,  # e.g., "Google Calendar", "Gmail" for user messages
+    redirect_uri: str,  # Added redirect_uri as a required parameter
+) -> str:
+    """
+    Initiates the Google OAuth flow and returns an actionable message for the user.
+
+    Args:
+        user_google_email: The user's specified Google email, if provided.
+        service_name: The name of the Google service requiring auth (for user messages).
+        redirect_uri: The URI Google will redirect to after authorization.
+
+    Returns:
+        A formatted string containing guidance for the LLM/user.
+
+    Raises:
+        Exception: If the OAuth flow cannot be initiated.
+    """
+    initial_email_provided = bool(
+        user_google_email
+        and user_google_email.strip()
+        and user_google_email.lower() != "default"
+    )
+    user_display_name = (
+        f"{service_name} for '{user_google_email}'"
+        if initial_email_provided
+        else service_name
+    )
+
+    logger.info(
+        f"[start_auth_flow] Initiating auth for {user_display_name} with scopes for enabled tools."
+    )
+
+    # Note: Caller should ensure OAuth callback is available before calling this function
+
+    try:
+        if "OAUTHLIB_INSECURE_TRANSPORT" not in os.environ and (
+            "localhost" in redirect_uri or "127.0.0.1" in redirect_uri
+        ):  # Use passed redirect_uri
+            logger.warning(
+                "OAUTHLIB_INSECURE_TRANSPORT not set. Setting it for localhost/local development."
+            )
+            os.environ["OAUTHLIB_INSECURE_TRANSPORT"] = "1"
+
+        oauth_state = os.urandom(16).hex()
+
+        flow = create_oauth_flow(
+            scopes=get_current_scopes(),  # Use scopes for enabled tools only
+            redirect_uri=redirect_uri,  # Use passed redirect_uri
+            state=oauth_state,
+        )
+
+        auth_url, _ = flow.authorization_url(access_type="offline", prompt="consent")
+
+        session_id = None
+        try:
+            session_id = get_fastmcp_session_id()
+        except Exception as e:
+            logger.debug(
+                f"Could not retrieve FastMCP session ID for state binding: {e}"
+            )
+
+        store = get_oauth21_session_store()
+        store.store_oauth_state(oauth_state, session_id=session_id)
+
+        logger.info(
+            f"Auth flow started for {user_display_name}. State: {oauth_state[:8]}... Advise user to visit: {auth_url}"
+        )
+
+        message_lines = [
+            f"**ACTION REQUIRED: Google Authentication Needed for {user_display_name}**\n",
+            f"To proceed, the user must authorize this application for {service_name} access using all required permissions.",
+            "**LLM, please present this exact authorization URL to the user as a clickable hyperlink:**",
+            f"Authorization URL: {auth_url}",
+            f"Markdown for hyperlink: [Click here to authorize {service_name} access]({auth_url})\n",
+            "**LLM, after presenting the link, instruct the user as follows:**",
+            "1. Click the link and complete the authorization in their browser.",
+        ]
+        session_info_for_llm = ""
+
+        if not initial_email_provided:
+            message_lines.extend(
+                [
+                    f"2. After successful authorization{session_info_for_llm}, the browser page will display the authenticated email address.",
+                    "   **LLM: Instruct the user to provide you with this email address.**",
+                    "3. Once you have the email, **retry their original command, ensuring you include this `user_google_email`.**",
+                ]
+            )
+        else:
+            message_lines.append(
+                f"2. After successful authorization{session_info_for_llm}, **retry their original command**."
+            )
+
+        message_lines.append(
+            f"\nThe application will use the new credentials. If '{user_google_email}' was provided, it must match the authenticated account."
+        )
+        return "\n".join(message_lines)
+
+    except FileNotFoundError as e:
+        error_text = f"OAuth client credentials not found: {e}. Please either:\n1. Set environment variables: GOOGLE_OAUTH_CLIENT_ID and GOOGLE_OAUTH_CLIENT_SECRET\n2. Ensure '{CONFIG_CLIENT_SECRETS_PATH}' file exists"
+        logger.error(error_text, exc_info=True)
+        raise Exception(error_text)
+    except Exception as e:
+        error_text = f"Could not initiate authentication for {user_display_name} due to an unexpected error: {str(e)}"
+        logger.error(
+            f"Failed to start the OAuth flow for {user_display_name}: {e}",
+            exc_info=True,
+        )
+        raise Exception(error_text)
+
+
+def handle_auth_callback(
+    scopes: List[str],
+    authorization_response: str,
+    redirect_uri: str,
+    credentials_base_dir: str = DEFAULT_CREDENTIALS_DIR,
+    session_id: Optional[str] = None,
+    client_secrets_path: Optional[
+        str
+    ] = None,  # Deprecated: kept for backward compatibility
+) -> Tuple[str, Credentials]:
+    """
+    Handles the callback from Google, exchanges the code for credentials,
+    fetches user info, determines user_google_email, saves credentials (file & session),
+    and returns them.
+
+    Args:
+        scopes: List of OAuth scopes requested.
+        authorization_response: The full callback URL from Google.
+        redirect_uri: The redirect URI.
+        credentials_base_dir: Base directory for credential files.
+        session_id: Optional MCP session ID to associate with the credentials.
+        client_secrets_path: (Deprecated) Path to client secrets file. Ignored if environment variables are set.
+
+    Returns:
+        A tuple containing the user_google_email and the obtained Credentials object.
+
+    Raises:
+        ValueError: If the state is missing or doesn't match.
+        FlowExchangeError: If the code exchange fails.
+        HttpError: If fetching user info fails.
+    """
+    try:
+        # Log deprecation warning if old parameter is used
+        if client_secrets_path:
+            logger.warning(
+                "The 'client_secrets_path' parameter is deprecated. Use GOOGLE_OAUTH_CLIENT_ID and GOOGLE_OAUTH_CLIENT_SECRET environment variables instead."
+            )
+
+        # Allow HTTP for localhost in development
+        if "OAUTHLIB_INSECURE_TRANSPORT" not in os.environ:
+            logger.warning(
+                "OAUTHLIB_INSECURE_TRANSPORT not set. Setting it for localhost development."
+            )
+            os.environ["OAUTHLIB_INSECURE_TRANSPORT"] = "1"
+
+        store = get_oauth21_session_store()
+        parsed_response = urlparse(authorization_response)
+        state_values = parse_qs(parsed_response.query).get("state")
+        state = state_values[0] if state_values else None
+
+        state_info = store.validate_and_consume_oauth_state(
+            state, session_id=session_id
+        )
+        logger.debug(
+            "Validated OAuth callback state %s for session %s",
+            (state[:8] if state else "<missing>"),
+            state_info.get("session_id") or "<unknown>",
+        )
+
+        flow = create_oauth_flow(scopes=scopes, redirect_uri=redirect_uri, state=state)
+
+        # Exchange the authorization code for credentials
+        # Note: fetch_token will use the redirect_uri configured in the flow
+        flow.fetch_token(authorization_response=authorization_response)
+        credentials = flow.credentials
+        logger.info("Successfully exchanged authorization code for tokens.")
+
+        # Get user info to determine user_id (using email here)
+        user_info = get_user_info(credentials)
+        if not user_info or "email" not in user_info:
+            logger.error("Could not retrieve user email from Google.")
+            raise ValueError("Failed to get user email for identification.")
+
+        user_google_email = user_info["email"]
+        logger.info(f"Identified user_google_email: {user_google_email}")
+
+        # Save the credentials
+        credential_store = get_credential_store()
+        credential_store.store_credential(user_google_email, credentials)
+
+        # Always save to OAuth21SessionStore for centralized management
+        store = get_oauth21_session_store()
+        store.store_session(
+            user_email=user_google_email,
+            access_token=credentials.token,
+            refresh_token=credentials.refresh_token,
+            token_uri=credentials.token_uri,
+            client_id=credentials.client_id,
+            client_secret=credentials.client_secret,
+            scopes=credentials.scopes,
+            expiry=credentials.expiry,
+            mcp_session_id=session_id,
+            issuer="https://accounts.google.com",  # Add issuer for Google tokens
+        )
+
+        # If session_id is provided, also save to session cache for compatibility
+        if session_id:
+            save_credentials_to_session(session_id, credentials)
+
+        return user_google_email, credentials
+
+    except Exception as e:  # Catch specific exceptions like FlowExchangeError if needed
+        logger.error(f"Error handling auth callback: {e}")
+        raise  # Re-raise for the caller
+
+
+def get_credentials(
+    user_google_email: Optional[str],  # Can be None if relying on session_id
+    required_scopes: List[str],
+    client_secrets_path: Optional[str] = None,
+    credentials_base_dir: str = DEFAULT_CREDENTIALS_DIR,
+    session_id: Optional[str] = None,
+) -> Optional[Credentials]:
+    """
+    Retrieves stored credentials, prioritizing OAuth 2.1 store, then session, then file. Refreshes if necessary.
+    If credentials are loaded from file and a session_id is present, they are cached in the session.
+    In single-user mode, bypasses session mapping and uses any available credentials.
+
+    Args:
+        user_google_email: Optional user's Google email.
+        required_scopes: List of scopes the credentials must have.
+        client_secrets_path: Optional path to client secrets (legacy; refresh uses embedded client info).
+        credentials_base_dir: Base directory for credential files.
+        session_id: Optional MCP session ID.
+
+    Returns:
+        Valid Credentials object or None.
+    """
+    # First, try OAuth 2.1 session store if we have a session_id (FastMCP session)
+    if session_id:
+        try:
+            store = get_oauth21_session_store()
+
+            # Try to get credentials by MCP session
+            credentials = store.get_credentials_by_mcp_session(session_id)
+            if credentials:
+                logger.info(
+                    f"[get_credentials] Found OAuth 2.1 credentials for MCP session {session_id}"
+                )
+
+                # Check scopes
+                if not all(scope in credentials.scopes for scope in required_scopes):
+                    logger.warning(
+                        f"[get_credentials] OAuth 2.1 credentials lack required scopes. Need: {required_scopes}, Have: {credentials.scopes}"
+                    )
+                    return None
+
+                # Return if valid
+                if credentials.valid:
+                    return credentials
+                elif credentials.expired and credentials.refresh_token:
+                    # Try to refresh
+                    try:
+                        credentials.refresh(Request())
+                        logger.info(
+                            f"[get_credentials] Refreshed OAuth 2.1 credentials for session {session_id}"
+                        )
+                        # Update stored credentials
+                        user_email = store.get_user_by_mcp_session(session_id)
+                        if user_email:
+                            store.store_session(
+                                user_email=user_email,
+                                access_token=credentials.token,
+                                refresh_token=credentials.refresh_token,
+                                scopes=credentials.scopes,
+                                expiry=credentials.expiry,
+                                mcp_session_id=session_id,
+                            )
+                        return credentials
+                    except Exception as e:
+                        logger.error(
+                            f"[get_credentials] Failed to refresh OAuth 2.1 credentials: {e}"
+                        )
+                        return None
+        except ImportError:
+            pass  # OAuth 2.1 store not available
+        except Exception as e:
+            logger.debug(f"[get_credentials] Error checking OAuth 2.1 store: {e}")
+
+    # Check for single-user mode
+    if os.getenv("MCP_SINGLE_USER_MODE") == "1":
+        logger.info(
+            "[get_credentials] Single-user mode: bypassing session mapping, finding any credentials"
+        )
+        credentials = _find_any_credentials(credentials_base_dir)
+        if not credentials:
+            logger.info(
+                f"[get_credentials] Single-user mode: No credentials found in {credentials_base_dir}"
+            )
+            return None
+
+        # In single-user mode, if user_google_email wasn't provided, try to get it from user info
+        # This is needed for proper credential saving after refresh
+        if not user_google_email and credentials.valid:
+            try:
+                user_info = get_user_info(credentials)
+                if user_info and "email" in user_info:
+                    user_google_email = user_info["email"]
+                    logger.debug(
+                        f"[get_credentials] Single-user mode: extracted user email {user_google_email} from credentials"
+                    )
+            except Exception as e:
+                logger.debug(
+                    f"[get_credentials] Single-user mode: could not extract user email: {e}"
+                )
+    else:
+        credentials: Optional[Credentials] = None
+
+        # Session ID should be provided by the caller
+        if not session_id:
+            logger.debug("[get_credentials] No session_id provided")
+
+        logger.debug(
+            f"[get_credentials] Called for user_google_email: '{user_google_email}', session_id: '{session_id}', required_scopes: {required_scopes}"
+        )
+
+        if session_id:
+            credentials = load_credentials_from_session(session_id)
+            if credentials:
+                logger.debug(
+                    f"[get_credentials] Loaded credentials from session for session_id '{session_id}'."
+                )
+
+        if not credentials and user_google_email:
+            if not is_stateless_mode():
+                logger.debug(
+                    f"[get_credentials] No session credentials, trying credential store for user_google_email '{user_google_email}'."
+                )
+                store = get_credential_store()
+                credentials = store.get_credential(user_google_email)
+            else:
+                logger.debug(
+                    f"[get_credentials] No session credentials, skipping file store in stateless mode for user_google_email '{user_google_email}'."
+                )
+
+            if credentials and session_id:
+                logger.debug(
+                    f"[get_credentials] Loaded from file for user '{user_google_email}', caching to session '{session_id}'."
+                )
+                save_credentials_to_session(
+                    session_id, credentials
+                )  # Cache for current session
+
+        if not credentials:
+            logger.info(
+                f"[get_credentials] No credentials found for user '{user_google_email}' or session '{session_id}'."
+            )
+            return None
+
+    logger.debug(
+        f"[get_credentials] Credentials found. Scopes: {credentials.scopes}, Valid: {credentials.valid}, Expired: {credentials.expired}"
+    )
+
+    if not all(scope in credentials.scopes for scope in required_scopes):
+        logger.warning(
+            f"[get_credentials] Credentials lack required scopes. Need: {required_scopes}, Have: {credentials.scopes}. User: '{user_google_email}', Session: '{session_id}'"
+        )
+        return None  # Re-authentication needed for scopes
+
+    logger.debug(
+        f"[get_credentials] Credentials have sufficient scopes. User: '{user_google_email}', Session: '{session_id}'"
+    )
+
+    if credentials.valid:
+        logger.debug(
+            f"[get_credentials] Credentials are valid. User: '{user_google_email}', Session: '{session_id}'"
+        )
+        return credentials
+    elif credentials.expired and credentials.refresh_token:
+        logger.info(
+            f"[get_credentials] Credentials expired. Attempting refresh. User: '{user_google_email}', Session: '{session_id}'"
+        )
+        try:
+            logger.debug(
+                "[get_credentials] Refreshing token using embedded client credentials"
+            )
+            # client_config = load_client_secrets(client_secrets_path) # Not strictly needed if creds have client_id/secret
+            credentials.refresh(Request())
+            logger.info(
+                f"[get_credentials] Credentials refreshed successfully. User: '{user_google_email}', Session: '{session_id}'"
+            )
+
+            # Save refreshed credentials (skip file save in stateless mode)
+            if user_google_email:  # Always save to credential store if email is known
+                if not is_stateless_mode():
+                    credential_store = get_credential_store()
+                    credential_store.store_credential(user_google_email, credentials)
+                else:
+                    logger.info(
+                        f"Skipping credential file save in stateless mode for {user_google_email}"
+                    )
+
+                # Also update OAuth21SessionStore
+                store = get_oauth21_session_store()
+                store.store_session(
+                    user_email=user_google_email,
+                    access_token=credentials.token,
+                    refresh_token=credentials.refresh_token,
+                    token_uri=credentials.token_uri,
+                    client_id=credentials.client_id,
+                    client_secret=credentials.client_secret,
+                    scopes=credentials.scopes,
+                    expiry=credentials.expiry,
+                    mcp_session_id=session_id,
+                    issuer="https://accounts.google.com",  # Add issuer for Google tokens
+                )
+
+            if session_id:  # Update session cache if it was the source or is active
+                save_credentials_to_session(session_id, credentials)
+            return credentials
+        except RefreshError as e:
+            logger.warning(
+                f"[get_credentials] RefreshError - token expired/revoked: {e}. User: '{user_google_email}', Session: '{session_id}'"
+            )
+            # For RefreshError, we should return None to trigger reauthentication
+            return None
+        except Exception as e:
+            logger.error(
+                f"[get_credentials] Error refreshing credentials: {e}. User: '{user_google_email}', Session: '{session_id}'",
+                exc_info=True,
+            )
+            return None  # Failed to refresh
+    else:
+        logger.warning(
+            f"[get_credentials] Credentials invalid/cannot refresh. Valid: {credentials.valid}, Refresh Token: {credentials.refresh_token is not None}. User: '{user_google_email}', Session: '{session_id}'"
+        )
+        return None
+
+
+def get_user_info(credentials: Credentials) -> Optional[Dict[str, Any]]:
+    """Fetches basic user profile information (requires userinfo.email scope)."""
+    if not credentials or not credentials.valid:
+        logger.error("Cannot get user info: Invalid or missing credentials.")
+        return None
+    try:
+        # Using googleapiclient discovery to get user info
+        # Requires 'google-api-python-client' library
+        service = build("oauth2", "v2", credentials=credentials)
+        user_info = service.userinfo().get().execute()
+        logger.info(f"Successfully fetched user info: {user_info.get('email')}")
+        return user_info
+    except HttpError as e:
+        logger.error(f"HttpError fetching user info: {e.status_code} {e.reason}")
+        # Handle specific errors, e.g., 401 Unauthorized might mean token issue
+        return None
+    except Exception as e:
+        logger.error(f"Unexpected error fetching user info: {e}")
+        return None
+
+
+# --- Centralized Google Service Authentication ---
+
+
+class GoogleAuthenticationError(Exception):
+    """Exception raised when Google authentication is required or fails."""
+
+    def __init__(self, message: str, auth_url: Optional[str] = None):
+        super().__init__(message)
+        self.auth_url = auth_url
+
+
+async def get_authenticated_google_service(
+    service_name: str,  # "gmail", "calendar", "drive", "docs"
+    version: str,  # "v1", "v3"
+    tool_name: str,  # For logging/debugging
+    user_google_email: str,  # Required - no more Optional
+    required_scopes: List[str],
+    session_id: Optional[str] = None,  # Session context for logging
+) -> tuple[Any, str]:
+    """
+    Centralized Google service authentication for all MCP tools.
+    Returns (service, user_email) on success or raises GoogleAuthenticationError.
+
+    Args:
+        service_name: The Google service name ("gmail", "calendar", "drive", "docs")
+        version: The API version ("v1", "v3", etc.)
+        tool_name: The name of the calling tool (for logging/debugging)
+        user_google_email: The user's Google email address (required)
+        required_scopes: List of required OAuth scopes
+
+    Returns:
+        tuple[service, user_email] on success
+
+    Raises:
+        GoogleAuthenticationError: When authentication is required or fails
+    """
+
+    # Try to get FastMCP session ID if not provided
+    if not session_id:
+        try:
+            # First try context variable (works in async context)
+            session_id = get_fastmcp_session_id()
+            if session_id:
+                logger.debug(
+                    f"[{tool_name}] Got FastMCP session ID from context: {session_id}"
+                )
+            else:
+                logger.debug(
+                    f"[{tool_name}] Context variable returned None/empty session ID"
+                )
+        except Exception as e:
+            logger.debug(
+                f"[{tool_name}] Could not get FastMCP session from context: {e}"
+            )
+
+        # Fallback to direct FastMCP context if context variable not set
+        if not session_id and get_fastmcp_context:
+            try:
+                fastmcp_ctx = get_fastmcp_context()
+                if fastmcp_ctx and hasattr(fastmcp_ctx, "session_id"):
+                    session_id = fastmcp_ctx.session_id
+                    logger.debug(
+                        f"[{tool_name}] Got FastMCP session ID directly: {session_id}"
+                    )
+                else:
+                    logger.debug(
+                        f"[{tool_name}] FastMCP context exists but no session_id attribute"
+                    )
+            except Exception as e:
+                logger.debug(
+                    f"[{tool_name}] Could not get FastMCP context directly: {e}"
+                )
+
+        # Final fallback: log if we still don't have session_id
+        if not session_id:
+            logger.warning(
+                f"[{tool_name}] Unable to obtain FastMCP session ID from any source"
+            )
+
+    logger.info(
+        f"[{tool_name}] Attempting to get authenticated {service_name} service. Email: '{user_google_email}', Session: '{session_id}'"
+    )
+
+    # Validate email format
+    if not user_google_email or "@" not in user_google_email:
+        error_msg = f"Authentication required for {tool_name}. No valid 'user_google_email' provided. Please provide a valid Google email address."
+        logger.info(f"[{tool_name}] {error_msg}")
+        raise GoogleAuthenticationError(error_msg)
+
+    credentials = await asyncio.to_thread(
+        get_credentials,
+        user_google_email=user_google_email,
+        required_scopes=required_scopes,
+        client_secrets_path=CONFIG_CLIENT_SECRETS_PATH,
+        session_id=session_id,  # Pass through session context
+    )
+
+    if not credentials or not credentials.valid:
+        logger.warning(
+            f"[{tool_name}] No valid credentials. Email: '{user_google_email}'."
+        )
+        logger.info(
+            f"[{tool_name}] Valid email '{user_google_email}' provided, initiating auth flow."
+        )
+
+        # Ensure OAuth callback is available
+        from auth.oauth_callback_server import ensure_oauth_callback_available
+
+        redirect_uri = get_oauth_redirect_uri()
+        config = get_oauth_config()
+        success, error_msg = ensure_oauth_callback_available(
+            get_transport_mode(), config.port, config.base_uri
+        )
+        if not success:
+            error_detail = f" ({error_msg})" if error_msg else ""
+            raise GoogleAuthenticationError(
+                f"Cannot initiate OAuth flow - callback server unavailable{error_detail}"
+            )
+
+        # Generate auth URL and raise exception with it
+        auth_response = await start_auth_flow(
+            user_google_email=user_google_email,
+            service_name=f"Google {service_name.title()}",
+            redirect_uri=redirect_uri,
+        )
+
+        # Extract the auth URL from the response and raise with it
+        raise GoogleAuthenticationError(auth_response)
+
+    try:
+        service = build(service_name, version, credentials=credentials)
+        log_user_email = user_google_email
+
+        # Try to get email from credentials if needed for validation
+        if credentials and credentials.id_token:
+            try:
+                # Decode without verification (just to get email for logging)
+                decoded_token = jwt.decode(
+                    credentials.id_token, options={"verify_signature": False}
+                )
+                token_email = decoded_token.get("email")
+                if token_email:
+                    log_user_email = token_email
+                    logger.info(f"[{tool_name}] Token email: {token_email}")
+            except Exception as e:
+                logger.debug(f"[{tool_name}] Could not decode id_token: {e}")
+
+        logger.info(
+            f"[{tool_name}] Successfully authenticated {service_name} service for user: {log_user_email}"
+        )
+        return service, log_user_email
+
+    except Exception as e:
+        error_msg = f"[{tool_name}] Failed to build {service_name} service: {str(e)}"
+        logger.error(error_msg, exc_info=True)
+        raise GoogleAuthenticationError(error_msg)

auth/mcp_session_middleware.py

@@ -0,0 +1,120 @@
+"""
+MCP Session Middleware
+
+This middleware intercepts MCP requests and sets the session context
+for use by tool functions.
+"""
+
+import logging
+from typing import Callable, Any
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+
+from auth.oauth21_session_store import (
+    SessionContext,
+    SessionContextManager,
+    extract_session_from_headers,
+)
+# OAuth 2.1 is now handled by FastMCP auth
+
+logger = logging.getLogger(__name__)
+
+
+class MCPSessionMiddleware(BaseHTTPMiddleware):
+    """
+    Middleware that extracts session information from requests and makes it
+    available to MCP tool functions via context variables.
+    """
+
+    async def dispatch(self, request: Request, call_next: Callable) -> Any:
+        """Process request and set session context."""
+
+        logger.debug(
+            f"MCPSessionMiddleware processing request: {request.method} {request.url.path}"
+        )
+
+        # Skip non-MCP paths
+        if not request.url.path.startswith("/mcp"):
+            logger.debug(f"Skipping non-MCP path: {request.url.path}")
+            return await call_next(request)
+
+        session_context = None
+
+        try:
+            # Extract session information
+            headers = dict(request.headers)
+            session_id = extract_session_from_headers(headers)
+
+            # Try to get OAuth 2.1 auth context from FastMCP
+            auth_context = None
+            user_email = None
+            mcp_session_id = None
+            # Check for FastMCP auth context
+            if hasattr(request.state, "auth"):
+                auth_context = request.state.auth
+                # Extract user email from auth claims if available
+                if hasattr(auth_context, "claims") and auth_context.claims:
+                    user_email = auth_context.claims.get("email")
+
+            # Check for FastMCP session ID (from streamable HTTP transport)
+            if hasattr(request.state, "session_id"):
+                mcp_session_id = request.state.session_id
+                logger.debug(f"Found FastMCP session ID: {mcp_session_id}")
+
+            # Also check Authorization header for bearer tokens
+            auth_header = headers.get("authorization")
+            if (
+                auth_header
+                and auth_header.lower().startswith("bearer ")
+                and not user_email
+            ):
+                try:
+                    import jwt
+
+                    token = auth_header[7:]  # Remove "Bearer " prefix
+                    # Decode without verification to extract email
+                    claims = jwt.decode(token, options={"verify_signature": False})
+                    user_email = claims.get("email")
+                    if user_email:
+                        logger.debug(f"Extracted user email from JWT: {user_email}")
+                except Exception:
+                    pass
+
+            # Build session context
+            if session_id or auth_context or user_email or mcp_session_id:
+                # Create session ID hierarchy: explicit session_id > Google user session > FastMCP session
+                effective_session_id = session_id
+                if not effective_session_id and user_email:
+                    effective_session_id = f"google_{user_email}"
+                elif not effective_session_id and mcp_session_id:
+                    effective_session_id = mcp_session_id
+
+                session_context = SessionContext(
+                    session_id=effective_session_id,
+                    user_id=user_email
+                    or (auth_context.user_id if auth_context else None),
+                    auth_context=auth_context,
+                    request=request,
+                    metadata={
+                        "path": request.url.path,
+                        "method": request.method,
+                        "user_email": user_email,
+                        "mcp_session_id": mcp_session_id,
+                    },
+                )
+
+                logger.debug(
+                    f"MCP request with session: session_id={session_context.session_id}, "
+                    f"user_id={session_context.user_id}, path={request.url.path}"
+                )
+
+            # Process request with session context
+            with SessionContextManager(session_context):
+                response = await call_next(request)
+                return response
+
+        except Exception as e:
+            logger.error(f"Error in MCP session middleware: {e}")
+            # Continue without session context
+            return await call_next(request)

auth/oauth21_session_store.py

@@ -0,0 +1,893 @@
+"""
+OAuth 2.1 Session Store for Google Services
+
+This module provides a global store for OAuth 2.1 authenticated sessions
+that can be accessed by Google service decorators. It also includes
+session context management and credential conversion functionality.
+"""
+
+import contextvars
+import logging
+from typing import Dict, Optional, Any, Tuple
+from threading import RLock
+from datetime import datetime, timedelta, timezone
+from dataclasses import dataclass
+
+from fastmcp.server.auth import AccessToken
+from google.oauth2.credentials import Credentials
+
+logger = logging.getLogger(__name__)
+
+
+def _normalize_expiry_to_naive_utc(expiry: Optional[Any]) -> Optional[datetime]:
+    """
+    Convert expiry values to timezone-naive UTC datetimes for google-auth compatibility.
+
+    Naive datetime inputs are assumed to already represent UTC and are returned unchanged so that
+    google-auth Credentials receive naive UTC datetimes for expiry comparison.
+    """
+    if expiry is None:
+        return None
+
+    if isinstance(expiry, datetime):
+        if expiry.tzinfo is not None:
+            try:
+                return expiry.astimezone(timezone.utc).replace(tzinfo=None)
+            except Exception:  # pragma: no cover - defensive
+                logger.debug(
+                    "Failed to normalize aware expiry; returning without tzinfo"
+                )
+                return expiry.replace(tzinfo=None)
+        return expiry  # Already naive; assumed to represent UTC
+
+    if isinstance(expiry, str):
+        try:
+            parsed = datetime.fromisoformat(expiry.replace("Z", "+00:00"))
+        except ValueError:
+            logger.debug("Failed to parse expiry string '%s'", expiry)
+            return None
+        return _normalize_expiry_to_naive_utc(parsed)
+
+    logger.debug("Unsupported expiry type '%s' (%s)", expiry, type(expiry))
+    return None
+
+
+# Context variable to store the current session information
+_current_session_context: contextvars.ContextVar[Optional["SessionContext"]] = (
+    contextvars.ContextVar("current_session_context", default=None)
+)
+
+
+@dataclass
+class SessionContext:
+    """Container for session-related information."""
+
+    session_id: Optional[str] = None
+    user_id: Optional[str] = None
+    auth_context: Optional[Any] = None
+    request: Optional[Any] = None
+    metadata: Dict[str, Any] = None
+    issuer: Optional[str] = None
+
+    def __post_init__(self):
+        if self.metadata is None:
+            self.metadata = {}
+
+
+def set_session_context(context: Optional[SessionContext]):
+    """
+    Set the current session context.
+
+    Args:
+        context: The session context to set
+    """
+    _current_session_context.set(context)
+    if context:
+        logger.debug(
+            f"Set session context: session_id={context.session_id}, user_id={context.user_id}"
+        )
+    else:
+        logger.debug("Cleared session context")
+
+
+def get_session_context() -> Optional[SessionContext]:
+    """
+    Get the current session context.
+
+    Returns:
+        The current session context or None
+    """
+    return _current_session_context.get()
+
+
+def clear_session_context():
+    """Clear the current session context."""
+    set_session_context(None)
+
+
+class SessionContextManager:
+    """
+    Context manager for temporarily setting session context.
+
+    Usage:
+        with SessionContextManager(session_context):
+            # Code that needs access to session context
+            pass
+    """
+
+    def __init__(self, context: Optional[SessionContext]):
+        self.context = context
+        self.token = None
+
+    def __enter__(self):
+        """Set the session context."""
+        self.token = _current_session_context.set(self.context)
+        return self.context
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Reset the session context."""
+        if self.token:
+            _current_session_context.reset(self.token)
+
+
+def extract_session_from_headers(headers: Dict[str, str]) -> Optional[str]:
+    """
+    Extract session ID from request headers.
+
+    Args:
+        headers: Request headers
+
+    Returns:
+        Session ID if found
+    """
+    # Try different header names
+    session_id = headers.get("mcp-session-id") or headers.get("Mcp-Session-Id")
+    if session_id:
+        return session_id
+
+    session_id = headers.get("x-session-id") or headers.get("X-Session-ID")
+    if session_id:
+        return session_id
+
+    # Try Authorization header for Bearer token
+    auth_header = headers.get("authorization") or headers.get("Authorization")
+    if auth_header and auth_header.lower().startswith("bearer "):
+        # Extract bearer token and try to find associated session
+        token = auth_header[7:]  # Remove "Bearer " prefix
+        if token:
+            # Look for a session that has this access token
+            # This requires scanning sessions, but bearer tokens should be unique
+            store = get_oauth21_session_store()
+            for user_email, session_info in store._sessions.items():
+                if session_info.get("access_token") == token:
+                    return session_info.get("session_id") or f"bearer_{user_email}"
+
+        # If no session found, create a temporary session ID from token hash
+        # This allows header-based authentication to work with session context
+        import hashlib
+
+        token_hash = hashlib.sha256(token.encode()).hexdigest()[:8]
+        return f"bearer_token_{token_hash}"
+
+    return None
+
+
+# =============================================================================
+# OAuth21SessionStore - Main Session Management
+# =============================================================================
+
+
+class OAuth21SessionStore:
+    """
+    Global store for OAuth 2.1 authenticated sessions.
+
+    This store maintains a mapping of user emails to their OAuth 2.1
+    authenticated credentials, allowing Google services to access them.
+    It also maintains a mapping from FastMCP session IDs to user emails.
+
+    Security: Sessions are bound to specific users and can only access
+    their own credentials.
+    """
+
+    def __init__(self):
+        self._sessions: Dict[str, Dict[str, Any]] = {}
+        self._mcp_session_mapping: Dict[
+            str, str
+        ] = {}  # Maps FastMCP session ID -> user email
+        self._session_auth_binding: Dict[
+            str, str
+        ] = {}  # Maps session ID -> authenticated user email (immutable)
+        self._oauth_states: Dict[str, Dict[str, Any]] = {}
+        self._lock = RLock()
+
+    def _cleanup_expired_oauth_states_locked(self):
+        """Remove expired OAuth state entries. Caller must hold lock."""
+        now = datetime.now(timezone.utc)
+        expired_states = [
+            state
+            for state, data in self._oauth_states.items()
+            if data.get("expires_at") and data["expires_at"] <= now
+        ]
+        for state in expired_states:
+            del self._oauth_states[state]
+            logger.debug(
+                "Removed expired OAuth state: %s",
+                state[:8] if len(state) > 8 else state,
+            )
+
+    def store_oauth_state(
+        self,
+        state: str,
+        session_id: Optional[str] = None,
+        expires_in_seconds: int = 600,
+    ) -> None:
+        """Persist an OAuth state value for later validation."""
+        if not state:
+            raise ValueError("OAuth state must be provided")
+        if expires_in_seconds < 0:
+            raise ValueError("expires_in_seconds must be non-negative")
+
+        with self._lock:
+            self._cleanup_expired_oauth_states_locked()
+            now = datetime.now(timezone.utc)
+            expiry = now + timedelta(seconds=expires_in_seconds)
+            self._oauth_states[state] = {
+                "session_id": session_id,
+                "expires_at": expiry,
+                "created_at": now,
+            }
+            logger.debug(
+                "Stored OAuth state %s (expires at %s)",
+                state[:8] if len(state) > 8 else state,
+                expiry.isoformat(),
+            )
+
+    def validate_and_consume_oauth_state(
+        self,
+        state: str,
+        session_id: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Validate that a state value exists and consume it.
+
+        Args:
+            state: The OAuth state returned by Google.
+            session_id: Optional session identifier that initiated the flow.
+
+        Returns:
+            Metadata associated with the state.
+
+        Raises:
+            ValueError: If the state is missing, expired, or does not match the session.
+        """
+        if not state:
+            raise ValueError("Missing OAuth state parameter")
+
+        with self._lock:
+            self._cleanup_expired_oauth_states_locked()
+            state_info = self._oauth_states.get(state)
+
+            if not state_info:
+                logger.error(
+                    "SECURITY: OAuth callback received unknown or expired state"
+                )
+                raise ValueError("Invalid or expired OAuth state parameter")
+
+            bound_session = state_info.get("session_id")
+            if bound_session and session_id and bound_session != session_id:
+                # Consume the state to prevent replay attempts
+                del self._oauth_states[state]
+                logger.error(
+                    "SECURITY: OAuth state session mismatch (expected %s, got %s)",
+                    bound_session,
+                    session_id,
+                )
+                raise ValueError("OAuth state does not match the initiating session")
+
+            # State is valid – consume it to prevent reuse
+            del self._oauth_states[state]
+            logger.debug(
+                "Validated OAuth state %s",
+                state[:8] if len(state) > 8 else state,
+            )
+            return state_info
+
+    def store_session(
+        self,
+        user_email: str,
+        access_token: str,
+        refresh_token: Optional[str] = None,
+        token_uri: str = "https://oauth2.googleapis.com/token",
+        client_id: Optional[str] = None,
+        client_secret: Optional[str] = None,
+        scopes: Optional[list] = None,
+        expiry: Optional[Any] = None,
+        session_id: Optional[str] = None,
+        mcp_session_id: Optional[str] = None,
+        issuer: Optional[str] = None,
+    ):
+        """
+        Store OAuth 2.1 session information.
+
+        Args:
+            user_email: User's email address
+            access_token: OAuth 2.1 access token
+            refresh_token: OAuth 2.1 refresh token
+            token_uri: Token endpoint URI
+            client_id: OAuth client ID
+            client_secret: OAuth client secret
+            scopes: List of granted scopes
+            expiry: Token expiry time
+            session_id: OAuth 2.1 session ID
+            mcp_session_id: FastMCP session ID to map to this user
+            issuer: Token issuer (e.g., "https://accounts.google.com")
+        """
+        with self._lock:
+            normalized_expiry = _normalize_expiry_to_naive_utc(expiry)
+            session_info = {
+                "access_token": access_token,
+                "refresh_token": refresh_token,
+                "token_uri": token_uri,
+                "client_id": client_id,
+                "client_secret": client_secret,
+                "scopes": scopes or [],
+                "expiry": normalized_expiry,
+                "session_id": session_id,
+                "mcp_session_id": mcp_session_id,
+                "issuer": issuer,
+            }
+
+            self._sessions[user_email] = session_info
+
+            # Store MCP session mapping if provided
+            if mcp_session_id:
+                # Create immutable session binding (first binding wins, cannot be changed)
+                if mcp_session_id not in self._session_auth_binding:
+                    self._session_auth_binding[mcp_session_id] = user_email
+                    logger.info(
+                        f"Created immutable session binding: {mcp_session_id} -> {user_email}"
+                    )
+                elif self._session_auth_binding[mcp_session_id] != user_email:
+                    # Security: Attempt to bind session to different user
+                    logger.error(
+                        f"SECURITY: Attempt to rebind session {mcp_session_id} from {self._session_auth_binding[mcp_session_id]} to {user_email}"
+                    )
+                    raise ValueError(
+                        f"Session {mcp_session_id} is already bound to a different user"
+                    )
+
+                self._mcp_session_mapping[mcp_session_id] = user_email
+                logger.info(
+                    f"Stored OAuth 2.1 session for {user_email} (session_id: {session_id}, mcp_session_id: {mcp_session_id})"
+                )
+            else:
+                logger.info(
+                    f"Stored OAuth 2.1 session for {user_email} (session_id: {session_id})"
+                )
+
+            # Also create binding for the OAuth session ID
+            if session_id and session_id not in self._session_auth_binding:
+                self._session_auth_binding[session_id] = user_email
+
+    def get_credentials(self, user_email: str) -> Optional[Credentials]:
+        """
+        Get Google credentials for a user from OAuth 2.1 session.
+
+        Args:
+            user_email: User's email address
+
+        Returns:
+            Google Credentials object or None
+        """
+        with self._lock:
+            session_info = self._sessions.get(user_email)
+            if not session_info:
+                logger.debug(f"No OAuth 2.1 session found for {user_email}")
+                return None
+
+            try:
+                # Create Google credentials from session info
+                credentials = Credentials(
+                    token=session_info["access_token"],
+                    refresh_token=session_info.get("refresh_token"),
+                    token_uri=session_info["token_uri"],
+                    client_id=session_info.get("client_id"),
+                    client_secret=session_info.get("client_secret"),
+                    scopes=session_info.get("scopes", []),
+                    expiry=session_info.get("expiry"),
+                )
+
+                logger.debug(f"Retrieved OAuth 2.1 credentials for {user_email}")
+                return credentials
+
+            except Exception as e:
+                logger.error(f"Failed to create credentials for {user_email}: {e}")
+                return None
+
+    def get_credentials_by_mcp_session(
+        self, mcp_session_id: str
+    ) -> Optional[Credentials]:
+        """
+        Get Google credentials using FastMCP session ID.
+
+        Args:
+            mcp_session_id: FastMCP session ID
+
+        Returns:
+            Google Credentials object or None
+        """
+        with self._lock:
+            # Look up user email from MCP session mapping
+            user_email = self._mcp_session_mapping.get(mcp_session_id)
+            if not user_email:
+                logger.debug(f"No user mapping found for MCP session {mcp_session_id}")
+                return None
+
+            logger.debug(f"Found user {user_email} for MCP session {mcp_session_id}")
+            return self.get_credentials(user_email)
+
+    def get_credentials_with_validation(
+        self,
+        requested_user_email: str,
+        session_id: Optional[str] = None,
+        auth_token_email: Optional[str] = None,
+        allow_recent_auth: bool = False,
+    ) -> Optional[Credentials]:
+        """
+        Get Google credentials with session validation.
+
+        This method ensures that a session can only access credentials for its
+        authenticated user, preventing cross-account access.
+
+        Args:
+            requested_user_email: The email of the user whose credentials are requested
+            session_id: The current session ID (MCP or OAuth session)
+            auth_token_email: Email from the verified auth token (if available)
+
+        Returns:
+            Google Credentials object if validation passes, None otherwise
+        """
+        with self._lock:
+            # Priority 1: Check auth token email (most secure, from verified JWT)
+            if auth_token_email:
+                if auth_token_email != requested_user_email:
+                    logger.error(
+                        f"SECURITY VIOLATION: Token for {auth_token_email} attempted to access "
+                        f"credentials for {requested_user_email}"
+                    )
+                    return None
+                # Token email matches, allow access
+                return self.get_credentials(requested_user_email)
+
+            # Priority 2: Check session binding
+            if session_id:
+                bound_user = self._session_auth_binding.get(session_id)
+                if bound_user:
+                    if bound_user != requested_user_email:
+                        logger.error(
+                            f"SECURITY VIOLATION: Session {session_id} (bound to {bound_user}) "
+                            f"attempted to access credentials for {requested_user_email}"
+                        )
+                        return None
+                    # Session binding matches, allow access
+                    return self.get_credentials(requested_user_email)
+
+                # Check if this is an MCP session
+                mcp_user = self._mcp_session_mapping.get(session_id)
+                if mcp_user:
+                    if mcp_user != requested_user_email:
+                        logger.error(
+                            f"SECURITY VIOLATION: MCP session {session_id} (user {mcp_user}) "
+                            f"attempted to access credentials for {requested_user_email}"
+                        )
+                        return None
+                    # MCP session matches, allow access
+                    return self.get_credentials(requested_user_email)
+
+            # Special case: Allow access if user has recently authenticated (for clients that don't send tokens)
+            # CRITICAL SECURITY: This is ONLY allowed in stdio mode, NEVER in OAuth 2.1 mode
+            if allow_recent_auth and requested_user_email in self._sessions:
+                # Check transport mode to ensure this is only used in stdio
+                try:
+                    from core.config import get_transport_mode
+
+                    transport_mode = get_transport_mode()
+                    if transport_mode != "stdio":
+                        logger.error(
+                            f"SECURITY: Attempted to use allow_recent_auth in {transport_mode} mode. "
+                            f"This is only allowed in stdio mode!"
+                        )
+                        return None
+                except Exception as e:
+                    logger.error(f"Failed to check transport mode: {e}")
+                    return None
+
+                logger.info(
+                    f"Allowing credential access for {requested_user_email} based on recent authentication "
+                    f"(stdio mode only - client not sending bearer token)"
+                )
+                return self.get_credentials(requested_user_email)
+
+            # No session or token info available - deny access for security
+            logger.warning(
+                f"Credential access denied for {requested_user_email}: No valid session or token"
+            )
+            return None
+
+    def get_user_by_mcp_session(self, mcp_session_id: str) -> Optional[str]:
+        """
+        Get user email by FastMCP session ID.
+
+        Args:
+            mcp_session_id: FastMCP session ID
+
+        Returns:
+            User email or None
+        """
+        with self._lock:
+            return self._mcp_session_mapping.get(mcp_session_id)
+
+    def get_session_info(self, user_email: str) -> Optional[Dict[str, Any]]:
+        """
+        Get complete session information including issuer.
+
+        Args:
+            user_email: User's email address
+
+        Returns:
+            Session information dictionary or None
+        """
+        with self._lock:
+            return self._sessions.get(user_email)
+
+    def remove_session(self, user_email: str):
+        """Remove session for a user."""
+        with self._lock:
+            if user_email in self._sessions:
+                # Get session IDs to clean up mappings
+                session_info = self._sessions.get(user_email, {})
+                mcp_session_id = session_info.get("mcp_session_id")
+                session_id = session_info.get("session_id")
+
+                # Remove from sessions
+                del self._sessions[user_email]
+
+                # Remove from MCP mapping if exists
+                if mcp_session_id and mcp_session_id in self._mcp_session_mapping:
+                    del self._mcp_session_mapping[mcp_session_id]
+                    # Also remove from auth binding
+                    if mcp_session_id in self._session_auth_binding:
+                        del self._session_auth_binding[mcp_session_id]
+                    logger.info(
+                        f"Removed OAuth 2.1 session for {user_email} and MCP mapping for {mcp_session_id}"
+                    )
+
+                # Remove OAuth session binding if exists
+                if session_id and session_id in self._session_auth_binding:
+                    del self._session_auth_binding[session_id]
+
+                if not mcp_session_id:
+                    logger.info(f"Removed OAuth 2.1 session for {user_email}")
+
+    def has_session(self, user_email: str) -> bool:
+        """Check if a user has an active session."""
+        with self._lock:
+            return user_email in self._sessions
+
+    def has_mcp_session(self, mcp_session_id: str) -> bool:
+        """Check if an MCP session has an associated user session."""
+        with self._lock:
+            return mcp_session_id in self._mcp_session_mapping
+
+    def get_single_user_email(self) -> Optional[str]:
+        """Return the sole authenticated user email when exactly one session exists."""
+        with self._lock:
+            if len(self._sessions) == 1:
+                return next(iter(self._sessions))
+            return None
+
+    def get_stats(self) -> Dict[str, Any]:
+        """Get store statistics."""
+        with self._lock:
+            return {
+                "total_sessions": len(self._sessions),
+                "users": list(self._sessions.keys()),
+                "mcp_session_mappings": len(self._mcp_session_mapping),
+                "mcp_sessions": list(self._mcp_session_mapping.keys()),
+            }
+
+
+# Global instance
+_global_store = OAuth21SessionStore()
+
+
+def get_oauth21_session_store() -> OAuth21SessionStore:
+    """Get the global OAuth 2.1 session store."""
+    return _global_store
+
+
+# =============================================================================
+# Google Credentials Bridge (absorbed from oauth21_google_bridge.py)
+# =============================================================================
+
+# Global auth provider instance (set during server initialization)
+_auth_provider = None
+
+
+def set_auth_provider(provider):
+    """Set the global auth provider instance."""
+    global _auth_provider
+    _auth_provider = provider
+    logger.debug("OAuth 2.1 session store configured")
+
+
+def get_auth_provider():
+    """Get the global auth provider instance."""
+    return _auth_provider
+
+
+def _resolve_client_credentials() -> Tuple[Optional[str], Optional[str]]:
+    """Resolve OAuth client credentials from the active provider or configuration."""
+    client_id: Optional[str] = None
+    client_secret: Optional[str] = None
+
+    if _auth_provider:
+        client_id = getattr(_auth_provider, "_upstream_client_id", None)
+        secret_obj = getattr(_auth_provider, "_upstream_client_secret", None)
+        if secret_obj is not None:
+            if hasattr(secret_obj, "get_secret_value"):
+                try:
+                    client_secret = secret_obj.get_secret_value()  # type: ignore[call-arg]
+                except Exception as exc:  # pragma: no cover - defensive
+                    logger.debug(
+                        f"Failed to resolve client secret from provider: {exc}"
+                    )
+            elif isinstance(secret_obj, str):
+                client_secret = secret_obj
+
+    if not client_id or not client_secret:
+        try:
+            from auth.oauth_config import get_oauth_config
+
+            cfg = get_oauth_config()
+            client_id = client_id or cfg.client_id
+            client_secret = client_secret or cfg.client_secret
+        except Exception as exc:  # pragma: no cover - defensive
+            logger.debug(f"Failed to resolve client credentials from config: {exc}")
+
+    return client_id, client_secret
+
+
+def _build_credentials_from_provider(
+    access_token: AccessToken,
+) -> Optional[Credentials]:
+    """Construct Google credentials from the provider cache."""
+    if not _auth_provider:
+        return None
+
+    access_entry = getattr(_auth_provider, "_access_tokens", {}).get(access_token.token)
+    if not access_entry:
+        access_entry = access_token
+
+    client_id, client_secret = _resolve_client_credentials()
+
+    refresh_token_value = getattr(_auth_provider, "_access_to_refresh", {}).get(
+        access_token.token
+    )
+    refresh_token_obj = None
+    if refresh_token_value:
+        refresh_token_obj = getattr(_auth_provider, "_refresh_tokens", {}).get(
+            refresh_token_value
+        )
+
+    expiry = None
+    expires_at = getattr(access_entry, "expires_at", None)
+    if expires_at:
+        try:
+            expiry_candidate = datetime.fromtimestamp(expires_at, tz=timezone.utc)
+            expiry = _normalize_expiry_to_naive_utc(expiry_candidate)
+        except Exception:  # pragma: no cover - defensive
+            expiry = None
+
+    scopes = getattr(access_entry, "scopes", None)
+
+    return Credentials(
+        token=access_token.token,
+        refresh_token=refresh_token_obj.token if refresh_token_obj else None,
+        token_uri="https://oauth2.googleapis.com/token",
+        client_id=client_id,
+        client_secret=client_secret,
+        scopes=scopes,
+        expiry=expiry,
+    )
+
+
+def ensure_session_from_access_token(
+    access_token: AccessToken,
+    user_email: Optional[str],
+    mcp_session_id: Optional[str] = None,
+) -> Optional[Credentials]:
+    """Ensure credentials derived from an access token are cached and returned."""
+
+    if not access_token:
+        return None
+
+    email = user_email
+    if not email and getattr(access_token, "claims", None):
+        email = access_token.claims.get("email")
+
+    credentials = _build_credentials_from_provider(access_token)
+    store_expiry: Optional[datetime] = None
+
+    if credentials is None:
+        client_id, client_secret = _resolve_client_credentials()
+        expiry = None
+        expires_at = getattr(access_token, "expires_at", None)
+        if expires_at:
+            try:
+                expiry = datetime.fromtimestamp(expires_at, tz=timezone.utc)
+            except Exception:  # pragma: no cover - defensive
+                expiry = None
+
+        normalized_expiry = _normalize_expiry_to_naive_utc(expiry)
+        credentials = Credentials(
+            token=access_token.token,
+            refresh_token=None,
+            token_uri="https://oauth2.googleapis.com/token",
+            client_id=client_id,
+            client_secret=client_secret,
+            scopes=getattr(access_token, "scopes", None),
+            expiry=normalized_expiry,
+        )
+        store_expiry = expiry
+    else:
+        store_expiry = credentials.expiry
+
+    if email:
+        try:
+            store = get_oauth21_session_store()
+            store.store_session(
+                user_email=email,
+                access_token=credentials.token,
+                refresh_token=credentials.refresh_token,
+                token_uri=credentials.token_uri,
+                client_id=credentials.client_id,
+                client_secret=credentials.client_secret,
+                scopes=credentials.scopes,
+                expiry=store_expiry,
+                session_id=f"google_{email}",
+                mcp_session_id=mcp_session_id,
+                issuer="https://accounts.google.com",
+            )
+        except Exception as exc:  # pragma: no cover - defensive
+            logger.debug(f"Failed to cache credentials for {email}: {exc}")
+
+    return credentials
+
+
+def get_credentials_from_token(
+    access_token: str, user_email: Optional[str] = None
+) -> Optional[Credentials]:
+    """
+    Convert a bearer token to Google credentials.
+
+    Args:
+        access_token: The bearer token
+        user_email: Optional user email for session lookup
+
+    Returns:
+        Google Credentials object or None
+    """
+    try:
+        store = get_oauth21_session_store()
+
+        # If we have user_email, try to get credentials from store
+        if user_email:
+            credentials = store.get_credentials(user_email)
+            if credentials and credentials.token == access_token:
+                logger.debug(f"Found matching credentials from store for {user_email}")
+                return credentials
+
+        # If the FastMCP provider is managing tokens, sync from provider storage
+        if _auth_provider:
+            access_record = getattr(_auth_provider, "_access_tokens", {}).get(
+                access_token
+            )
+            if access_record:
+                logger.debug("Building credentials from FastMCP provider cache")
+                return ensure_session_from_access_token(access_record, user_email)
+
+        # Otherwise, create minimal credentials with just the access token
+        # Assume token is valid for 1 hour (typical for Google tokens)
+        expiry = _normalize_expiry_to_naive_utc(
+            datetime.now(timezone.utc) + timedelta(hours=1)
+        )
+        client_id, client_secret = _resolve_client_credentials()
+
+        credentials = Credentials(
+            token=access_token,
+            refresh_token=None,
+            token_uri="https://oauth2.googleapis.com/token",
+            client_id=client_id,
+            client_secret=client_secret,
+            scopes=None,
+            expiry=expiry,
+        )
+
+        logger.debug("Created fallback Google credentials from bearer token")
+        return credentials
+
+    except Exception as e:
+        logger.error(f"Failed to create Google credentials from token: {e}")
+        return None
+
+
+def store_token_session(
+    token_response: dict, user_email: str, mcp_session_id: Optional[str] = None
+) -> str:
+    """
+    Store a token response in the session store.
+
+    Args:
+        token_response: OAuth token response from Google
+        user_email: User's email address
+        mcp_session_id: Optional FastMCP session ID to map to this user
+
+    Returns:
+        Session ID
+    """
+    if not _auth_provider:
+        logger.error("Auth provider not configured")
+        return ""
+
+    try:
+        # Try to get FastMCP session ID from context if not provided
+        if not mcp_session_id:
+            try:
+                from core.context import get_fastmcp_session_id
+
+                mcp_session_id = get_fastmcp_session_id()
+                if mcp_session_id:
+                    logger.debug(
+                        f"Got FastMCP session ID from context: {mcp_session_id}"
+                    )
+            except Exception as e:
+                logger.debug(f"Could not get FastMCP session from context: {e}")
+
+        # Store session in OAuth21SessionStore
+        store = get_oauth21_session_store()
+
+        session_id = f"google_{user_email}"
+        client_id, client_secret = _resolve_client_credentials()
+        scopes = token_response.get("scope", "")
+        scopes_list = scopes.split() if scopes else None
+        expiry = datetime.now(timezone.utc) + timedelta(
+            seconds=token_response.get("expires_in", 3600)
+        )
+
+        store.store_session(
+            user_email=user_email,
+            access_token=token_response.get("access_token"),
+            refresh_token=token_response.get("refresh_token"),
+            token_uri="https://oauth2.googleapis.com/token",
+            client_id=client_id,
+            client_secret=client_secret,
+            scopes=scopes_list,
+            expiry=expiry,
+            session_id=session_id,
+            mcp_session_id=mcp_session_id,
+            issuer="https://accounts.google.com",
+        )
+
+        if mcp_session_id:
+            logger.info(
+                f"Stored token session for {user_email} with MCP session {mcp_session_id}"
+            )
+        else:
+            logger.info(f"Stored token session for {user_email}")
+
+        return session_id
+
+    except Exception as e:
+        logger.error(f"Failed to store token session: {e}")
+        return ""

auth/oauth_callback_server.py

@@ -0,0 +1,288 @@
+"""
+Transport-aware OAuth callback handling.
+
+In streamable-http mode: Uses the existing FastAPI server
+In stdio mode: Starts a minimal HTTP server just for OAuth callbacks
+"""
+
+import asyncio
+import logging
+import threading
+import time
+import socket
+import uvicorn
+
+from fastapi import FastAPI, Request
+from fastapi.responses import FileResponse, JSONResponse
+from typing import Optional
+from urllib.parse import urlparse
+
+from auth.scopes import SCOPES, get_current_scopes  # noqa
+from auth.oauth_responses import (
+    create_error_response,
+    create_success_response,
+    create_server_error_response,
+)
+from auth.google_auth import handle_auth_callback, check_client_secrets
+from auth.oauth_config import get_oauth_redirect_uri
+
+logger = logging.getLogger(__name__)
+
+
+class MinimalOAuthServer:
+    """
+    Minimal HTTP server for OAuth callbacks in stdio mode.
+    Only starts when needed and uses the same port (8000) as streamable-http mode.
+    """
+
+    def __init__(self, port: int = 8000, base_uri: str = "http://localhost"):
+        self.port = port
+        self.base_uri = base_uri
+        self.app = FastAPI()
+        self.server = None
+        self.server_thread = None
+        self.is_running = False
+
+        # Setup the callback route
+        self._setup_callback_route()
+        # Setup attachment serving route
+        self._setup_attachment_route()
+
+    def _setup_callback_route(self):
+        """Setup the OAuth callback route."""
+
+        @self.app.get("/oauth2callback")
+        async def oauth_callback(request: Request):
+            """Handle OAuth callback - same logic as in core/server.py"""
+            state = request.query_params.get("state")
+            code = request.query_params.get("code")
+            error = request.query_params.get("error")
+
+            if error:
+                error_message = f"Authentication failed: Google returned an error: {error}. State: {state}."
+                logger.error(error_message)
+                return create_error_response(error_message)
+
+            if not code:
+                error_message = (
+                    "Authentication failed: No authorization code received from Google."
+                )
+                logger.error(error_message)
+                return create_error_response(error_message)
+
+            try:
+                # Check if we have credentials available (environment variables or file)
+                error_message = check_client_secrets()
+                if error_message:
+                    return create_server_error_response(error_message)
+
+                logger.info(
+                    f"OAuth callback: Received code (state: {state}). Attempting to exchange for tokens."
+                )
+
+                # Session ID tracking removed - not needed
+
+                # Exchange code for credentials
+                redirect_uri = get_oauth_redirect_uri()
+                verified_user_id, credentials = handle_auth_callback(
+                    scopes=get_current_scopes(),
+                    authorization_response=str(request.url),
+                    redirect_uri=redirect_uri,
+                    session_id=None,
+                )
+
+                logger.info(
+                    f"OAuth callback: Successfully authenticated user: {verified_user_id} (state: {state})."
+                )
+
+                # Return success page using shared template
+                return create_success_response(verified_user_id)
+
+            except Exception as e:
+                error_message_detail = (
+                    f"Error processing OAuth callback (state: {state}): {str(e)}"
+                )
+                logger.error(error_message_detail, exc_info=True)
+                return create_server_error_response(str(e))
+
+    def _setup_attachment_route(self):
+        """Setup the attachment serving route."""
+        from core.attachment_storage import get_attachment_storage
+
+        @self.app.get("/attachments/{file_id}")
+        async def serve_attachment(file_id: str, request: Request):
+            """Serve a stored attachment file."""
+            storage = get_attachment_storage()
+            metadata = storage.get_attachment_metadata(file_id)
+
+            if not metadata:
+                return JSONResponse(
+                    {"error": "Attachment not found or expired"}, status_code=404
+                )
+
+            file_path = storage.get_attachment_path(file_id)
+            if not file_path:
+                return JSONResponse(
+                    {"error": "Attachment file not found"}, status_code=404
+                )
+
+            return FileResponse(
+                path=str(file_path),
+                filename=metadata["filename"],
+                media_type=metadata["mime_type"],
+            )
+
+    def start(self) -> tuple[bool, str]:
+        """
+        Start the minimal OAuth server.
+
+        Returns:
+            Tuple of (success: bool, error_message: str)
+        """
+        if self.is_running:
+            logger.info("Minimal OAuth server is already running")
+            return True, ""
+
+        # Check if port is available
+        # Extract hostname from base_uri (e.g., "http://localhost" -> "localhost")
+        try:
+            parsed_uri = urlparse(self.base_uri)
+            hostname = parsed_uri.hostname or "localhost"
+        except Exception:
+            hostname = "localhost"
+
+        try:
+            with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+                s.bind((hostname, self.port))
+        except OSError:
+            error_msg = f"Port {self.port} is already in use on {hostname}. Cannot start minimal OAuth server."
+            logger.error(error_msg)
+            return False, error_msg
+
+        def run_server():
+            """Run the server in a separate thread."""
+            try:
+                config = uvicorn.Config(
+                    self.app,
+                    host=hostname,
+                    port=self.port,
+                    log_level="warning",
+                    access_log=False,
+                )
+                self.server = uvicorn.Server(config)
+                asyncio.run(self.server.serve())
+
+            except Exception as e:
+                logger.error(f"Minimal OAuth server error: {e}", exc_info=True)
+                self.is_running = False
+
+        # Start server in background thread
+        self.server_thread = threading.Thread(target=run_server, daemon=True)
+        self.server_thread.start()
+
+        # Wait for server to start
+        max_wait = 3.0
+        start_time = time.time()
+        while time.time() - start_time < max_wait:
+            try:
+                with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+                    result = s.connect_ex((hostname, self.port))
+                    if result == 0:
+                        self.is_running = True
+                        logger.info(
+                            f"Minimal OAuth server started on {hostname}:{self.port}"
+                        )
+                        return True, ""
+            except Exception:
+                pass
+            time.sleep(0.1)
+
+        error_msg = f"Failed to start minimal OAuth server on {hostname}:{self.port} - server did not respond within {max_wait}s"
+        logger.error(error_msg)
+        return False, error_msg
+
+    def stop(self):
+        """Stop the minimal OAuth server."""
+        if not self.is_running:
+            return
+
+        try:
+            if self.server:
+                if hasattr(self.server, "should_exit"):
+                    self.server.should_exit = True
+
+            if self.server_thread and self.server_thread.is_alive():
+                self.server_thread.join(timeout=3.0)
+
+            self.is_running = False
+            logger.info("Minimal OAuth server stopped")
+
+        except Exception as e:
+            logger.error(f"Error stopping minimal OAuth server: {e}", exc_info=True)
+
+
+# Global instance for stdio mode
+_minimal_oauth_server: Optional[MinimalOAuthServer] = None
+
+
+def ensure_oauth_callback_available(
+    transport_mode: str = "stdio", port: int = 8000, base_uri: str = "http://localhost"
+) -> tuple[bool, str]:
+    """
+    Ensure OAuth callback endpoint is available for the given transport mode.
+
+    For streamable-http: Assumes the main server is already running
+    For stdio: Starts a minimal server if needed
+
+    Args:
+        transport_mode: "stdio" or "streamable-http"
+        port: Port number (default 8000)
+        base_uri: Base URI (default "http://localhost")
+
+    Returns:
+        Tuple of (success: bool, error_message: str)
+    """
+    global _minimal_oauth_server
+
+    if transport_mode == "streamable-http":
+        # In streamable-http mode, the main FastAPI server should handle callbacks
+        logger.debug(
+            "Using existing FastAPI server for OAuth callbacks (streamable-http mode)"
+        )
+        return True, ""
+
+    elif transport_mode == "stdio":
+        # In stdio mode, start minimal server if not already running
+        if _minimal_oauth_server is None:
+            logger.info(f"Creating minimal OAuth server instance for {base_uri}:{port}")
+            _minimal_oauth_server = MinimalOAuthServer(port, base_uri)
+
+        if not _minimal_oauth_server.is_running:
+            logger.info("Starting minimal OAuth server for stdio mode")
+            success, error_msg = _minimal_oauth_server.start()
+            if success:
+                logger.info(
+                    f"Minimal OAuth server successfully started on {base_uri}:{port}"
+                )
+                return True, ""
+            else:
+                logger.error(
+                    f"Failed to start minimal OAuth server on {base_uri}:{port}: {error_msg}"
+                )
+                return False, error_msg
+        else:
+            logger.info("Minimal OAuth server is already running")
+            return True, ""
+
+    else:
+        error_msg = f"Unknown transport mode: {transport_mode}"
+        logger.error(error_msg)
+        return False, error_msg
+
+
+def cleanup_oauth_callback_server():
+    """Clean up the minimal OAuth server if it was started."""
+    global _minimal_oauth_server
+    if _minimal_oauth_server:
+        _minimal_oauth_server.stop()
+        _minimal_oauth_server = None

auth/oauth_config.py

@@ -0,0 +1,438 @@
+"""
+OAuth Configuration Management
+
+This module centralizes OAuth-related configuration to eliminate hardcoded values
+scattered throughout the codebase. It provides environment variable support and
+sensible defaults for all OAuth-related settings.
+
+Supports both OAuth 2.0 and OAuth 2.1 with automatic client capability detection.
+"""
+
+import os
+from urllib.parse import urlparse
+from typing import List, Optional, Dict, Any
+
+
+class OAuthConfig:
+    """
+    Centralized OAuth configuration management.
+
+    This class eliminates the hardcoded configuration anti-pattern identified
+    in the challenge review by providing a single source of truth for all
+    OAuth-related configuration values.
+    """
+
+    def __init__(self):
+        # Base server configuration
+        self.base_uri = os.getenv("WORKSPACE_MCP_BASE_URI", "http://localhost")
+        self.port = int(os.getenv("PORT", os.getenv("WORKSPACE_MCP_PORT", "8000")))
+        self.base_url = f"{self.base_uri}:{self.port}"
+
+        # External URL for reverse proxy scenarios
+        self.external_url = os.getenv("WORKSPACE_EXTERNAL_URL")
+
+        # OAuth client configuration
+        self.client_id = os.getenv("GOOGLE_OAUTH_CLIENT_ID")
+        self.client_secret = os.getenv("GOOGLE_OAUTH_CLIENT_SECRET")
+
+        # OAuth 2.1 configuration
+        self.oauth21_enabled = (
+            os.getenv("MCP_ENABLE_OAUTH21", "false").lower() == "true"
+        )
+        self.pkce_required = self.oauth21_enabled  # PKCE is mandatory in OAuth 2.1
+        self.supported_code_challenge_methods = (
+            ["S256", "plain"] if not self.oauth21_enabled else ["S256"]
+        )
+
+        # External OAuth 2.1 provider configuration
+        self.external_oauth21_provider = (
+            os.getenv("EXTERNAL_OAUTH21_PROVIDER", "false").lower() == "true"
+        )
+        if self.external_oauth21_provider and not self.oauth21_enabled:
+            raise ValueError(
+                "EXTERNAL_OAUTH21_PROVIDER requires MCP_ENABLE_OAUTH21=true"
+            )
+
+        # Stateless mode configuration
+        self.stateless_mode = (
+            os.getenv("WORKSPACE_MCP_STATELESS_MODE", "false").lower() == "true"
+        )
+        if self.stateless_mode and not self.oauth21_enabled:
+            raise ValueError(
+                "WORKSPACE_MCP_STATELESS_MODE requires MCP_ENABLE_OAUTH21=true"
+            )
+
+        # Transport mode (will be set at runtime)
+        self._transport_mode = "stdio"  # Default
+
+        # Redirect URI configuration
+        self.redirect_uri = self._get_redirect_uri()
+        self.redirect_path = self._get_redirect_path(self.redirect_uri)
+
+        # Ensure FastMCP's Google provider picks up our existing configuration
+        self._apply_fastmcp_google_env()
+
+    def _get_redirect_uri(self) -> str:
+        """
+        Get the OAuth redirect URI, supporting reverse proxy configurations.
+
+        Returns:
+            The configured redirect URI
+        """
+        explicit_uri = os.getenv("GOOGLE_OAUTH_REDIRECT_URI")
+        if explicit_uri:
+            return explicit_uri
+        return f"{self.base_url}/oauth2callback"
+
+    @staticmethod
+    def _get_redirect_path(uri: str) -> str:
+        """Extract the redirect path from a full redirect URI."""
+        parsed = urlparse(uri)
+        if parsed.scheme or parsed.netloc:
+            path = parsed.path or "/oauth2callback"
+        else:
+            # If the value was already a path, ensure it starts with '/'
+            path = uri if uri.startswith("/") else f"/{uri}"
+        return path or "/oauth2callback"
+
+    def _apply_fastmcp_google_env(self) -> None:
+        """Mirror legacy GOOGLE_* env vars into FastMCP Google provider settings."""
+        if not self.client_id:
+            return
+
+        def _set_if_absent(key: str, value: Optional[str]) -> None:
+            if value and key not in os.environ:
+                os.environ[key] = value
+
+        # Don't set FASTMCP_SERVER_AUTH if using external OAuth provider
+        # (external OAuth means protocol-level auth is disabled, only tool-level auth)
+        if not self.external_oauth21_provider:
+            _set_if_absent(
+                "FASTMCP_SERVER_AUTH",
+                "fastmcp.server.auth.providers.google.GoogleProvider"
+                if self.oauth21_enabled
+                else None,
+            )
+
+        _set_if_absent("FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_ID", self.client_id)
+        _set_if_absent("FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_SECRET", self.client_secret)
+        _set_if_absent("FASTMCP_SERVER_AUTH_GOOGLE_BASE_URL", self.get_oauth_base_url())
+        _set_if_absent("FASTMCP_SERVER_AUTH_GOOGLE_REDIRECT_PATH", self.redirect_path)
+
+    def get_redirect_uris(self) -> List[str]:
+        """
+        Get all valid OAuth redirect URIs.
+
+        Returns:
+            List of all supported redirect URIs
+        """
+        uris = []
+
+        # Primary redirect URI
+        uris.append(self.redirect_uri)
+
+        # Custom redirect URIs from environment
+        custom_uris = os.getenv("OAUTH_CUSTOM_REDIRECT_URIS")
+        if custom_uris:
+            uris.extend([uri.strip() for uri in custom_uris.split(",")])
+
+        # Remove duplicates while preserving order
+        return list(dict.fromkeys(uris))
+
+    def get_allowed_origins(self) -> List[str]:
+        """
+        Get allowed CORS origins for OAuth endpoints.
+
+        Returns:
+            List of allowed origins for CORS
+        """
+        origins = []
+
+        # Server's own origin
+        origins.append(self.base_url)
+
+        # VS Code and development origins
+        origins.extend(
+            [
+                "vscode-webview://",
+                "https://vscode.dev",
+                "https://github.dev",
+            ]
+        )
+
+        # Custom origins from environment
+        custom_origins = os.getenv("OAUTH_ALLOWED_ORIGINS")
+        if custom_origins:
+            origins.extend([origin.strip() for origin in custom_origins.split(",")])
+
+        return list(dict.fromkeys(origins))
+
+    def is_configured(self) -> bool:
+        """
+        Check if OAuth is properly configured.
+
+        Returns:
+            True if OAuth client credentials are available
+        """
+        return bool(self.client_id and self.client_secret)
+
+    def get_oauth_base_url(self) -> str:
+        """
+        Get OAuth base URL for constructing OAuth endpoints.
+
+        Uses WORKSPACE_EXTERNAL_URL if set (for reverse proxy scenarios),
+        otherwise falls back to constructed base_url with port.
+
+        Returns:
+            Base URL for OAuth endpoints
+        """
+        if self.external_url:
+            return self.external_url
+        return self.base_url
+
+    def validate_redirect_uri(self, uri: str) -> bool:
+        """
+        Validate if a redirect URI is allowed.
+
+        Args:
+            uri: The redirect URI to validate
+
+        Returns:
+            True if the URI is allowed, False otherwise
+        """
+        allowed_uris = self.get_redirect_uris()
+        return uri in allowed_uris
+
+    def get_environment_summary(self) -> dict:
+        """
+        Get a summary of the current OAuth configuration.
+
+        Returns:
+            Dictionary with configuration summary (excluding secrets)
+        """
+        return {
+            "base_url": self.base_url,
+            "external_url": self.external_url,
+            "effective_oauth_url": self.get_oauth_base_url(),
+            "redirect_uri": self.redirect_uri,
+            "redirect_path": self.redirect_path,
+            "client_configured": bool(self.client_id),
+            "oauth21_enabled": self.oauth21_enabled,
+            "external_oauth21_provider": self.external_oauth21_provider,
+            "pkce_required": self.pkce_required,
+            "transport_mode": self._transport_mode,
+            "total_redirect_uris": len(self.get_redirect_uris()),
+            "total_allowed_origins": len(self.get_allowed_origins()),
+        }
+
+    def set_transport_mode(self, mode: str) -> None:
+        """
+        Set the current transport mode for OAuth callback handling.
+
+        Args:
+            mode: Transport mode ("stdio", "streamable-http", etc.)
+        """
+        self._transport_mode = mode
+
+    def get_transport_mode(self) -> str:
+        """
+        Get the current transport mode.
+
+        Returns:
+            Current transport mode
+        """
+        return self._transport_mode
+
+    def is_oauth21_enabled(self) -> bool:
+        """
+        Check if OAuth 2.1 mode is enabled.
+
+        Returns:
+            True if OAuth 2.1 is enabled
+        """
+        return self.oauth21_enabled
+
+    def is_external_oauth21_provider(self) -> bool:
+        """
+        Check if external OAuth 2.1 provider mode is enabled.
+
+        When enabled, the server expects external OAuth flow with bearer tokens
+        in Authorization headers for tool calls. Protocol-level auth is disabled.
+
+        Returns:
+            True if external OAuth 2.1 provider is enabled
+        """
+        return self.external_oauth21_provider
+
+    def detect_oauth_version(self, request_params: Dict[str, Any]) -> str:
+        """
+        Detect OAuth version based on request parameters.
+
+        This method implements a conservative detection strategy:
+        - Only returns "oauth21" when we have clear indicators
+        - Defaults to "oauth20" for backward compatibility
+        - Respects the global oauth21_enabled flag
+
+        Args:
+            request_params: Request parameters from authorization or token request
+
+        Returns:
+            "oauth21" or "oauth20" based on detection
+        """
+        # If OAuth 2.1 is not enabled globally, always return OAuth 2.0
+        if not self.oauth21_enabled:
+            return "oauth20"
+
+        # Use the structured type for cleaner detection logic
+        from auth.oauth_types import OAuthVersionDetectionParams
+
+        params = OAuthVersionDetectionParams.from_request(request_params)
+
+        # Clear OAuth 2.1 indicator: PKCE is present
+        if params.has_pkce:
+            return "oauth21"
+
+        # Additional detection: Check if we have an active OAuth 2.1 session
+        # This is important for tool calls where PKCE params aren't available
+        authenticated_user = request_params.get("authenticated_user")
+        if authenticated_user:
+            try:
+                from auth.oauth21_session_store import get_oauth21_session_store
+
+                store = get_oauth21_session_store()
+                if store.has_session(authenticated_user):
+                    return "oauth21"
+            except (ImportError, AttributeError, RuntimeError):
+                pass  # Fall back to OAuth 2.0 if session check fails
+
+        # For public clients in OAuth 2.1 mode, we require PKCE
+        # But since they didn't send PKCE, fall back to OAuth 2.0
+        # This ensures backward compatibility
+
+        # Default to OAuth 2.0 for maximum compatibility
+        return "oauth20"
+
+    def get_authorization_server_metadata(
+        self, scopes: Optional[List[str]] = None
+    ) -> Dict[str, Any]:
+        """
+        Get OAuth authorization server metadata per RFC 8414.
+
+        Args:
+            scopes: Optional list of supported scopes to include in metadata
+
+        Returns:
+            Authorization server metadata dictionary
+        """
+        oauth_base = self.get_oauth_base_url()
+        metadata = {
+            "issuer": "https://accounts.google.com",
+            "authorization_endpoint": f"{oauth_base}/oauth2/authorize",
+            "token_endpoint": f"{oauth_base}/oauth2/token",
+            "registration_endpoint": f"{oauth_base}/oauth2/register",
+            "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs",
+            "userinfo_endpoint": "https://openidconnect.googleapis.com/v1/userinfo",
+            "response_types_supported": ["code", "token"],
+            "grant_types_supported": ["authorization_code", "refresh_token"],
+            "token_endpoint_auth_methods_supported": [
+                "client_secret_post",
+                "client_secret_basic",
+            ],
+            "code_challenge_methods_supported": self.supported_code_challenge_methods,
+        }
+
+        # Include scopes if provided
+        if scopes is not None:
+            metadata["scopes_supported"] = scopes
+
+        # Add OAuth 2.1 specific metadata
+        if self.oauth21_enabled:
+            metadata["pkce_required"] = True
+            # OAuth 2.1 deprecates implicit flow
+            metadata["response_types_supported"] = ["code"]
+            # OAuth 2.1 requires exact redirect URI matching
+            metadata["require_exact_redirect_uri"] = True
+
+        return metadata
+
+
+# Global configuration instance
+_oauth_config = None
+
+
+def get_oauth_config() -> OAuthConfig:
+    """
+    Get the global OAuth configuration instance.
+
+    Returns:
+        The singleton OAuth configuration instance
+    """
+    global _oauth_config
+    if _oauth_config is None:
+        _oauth_config = OAuthConfig()
+    return _oauth_config
+
+
+def reload_oauth_config() -> OAuthConfig:
+    """
+    Reload the OAuth configuration from environment variables.
+
+    This is useful for testing or when environment variables change.
+
+    Returns:
+        The reloaded OAuth configuration instance
+    """
+    global _oauth_config
+    _oauth_config = OAuthConfig()
+    return _oauth_config
+
+
+# Convenience functions for backward compatibility
+def get_oauth_base_url() -> str:
+    """Get OAuth base URL."""
+    return get_oauth_config().get_oauth_base_url()
+
+
+def get_redirect_uris() -> List[str]:
+    """Get all valid OAuth redirect URIs."""
+    return get_oauth_config().get_redirect_uris()
+
+
+def get_allowed_origins() -> List[str]:
+    """Get allowed CORS origins."""
+    return get_oauth_config().get_allowed_origins()
+
+
+def is_oauth_configured() -> bool:
+    """Check if OAuth is properly configured."""
+    return get_oauth_config().is_configured()
+
+
+def set_transport_mode(mode: str) -> None:
+    """Set the current transport mode."""
+    get_oauth_config().set_transport_mode(mode)
+
+
+def get_transport_mode() -> str:
+    """Get the current transport mode."""
+    return get_oauth_config().get_transport_mode()
+
+
+def is_oauth21_enabled() -> bool:
+    """Check if OAuth 2.1 is enabled."""
+    return get_oauth_config().is_oauth21_enabled()
+
+
+def get_oauth_redirect_uri() -> str:
+    """Get the primary OAuth redirect URI."""
+    return get_oauth_config().redirect_uri
+
+
+def is_stateless_mode() -> bool:
+    """Check if stateless mode is enabled."""
+    return get_oauth_config().stateless_mode
+
+
+def is_external_oauth21_provider() -> bool:
+    """Check if external OAuth 2.1 provider mode is enabled."""
+    return get_oauth_config().is_external_oauth21_provider()

auth/oauth_responses.py

@@ -0,0 +1,223 @@
+"""
+Shared OAuth callback response templates.
+
+Provides reusable HTML response templates for OAuth authentication flows
+to eliminate duplication between server.py and oauth_callback_server.py.
+"""
+
+from fastapi.responses import HTMLResponse
+from typing import Optional
+
+
+def create_error_response(error_message: str, status_code: int = 400) -> HTMLResponse:
+    """
+    Create a standardized error response for OAuth failures.
+
+    Args:
+        error_message: The error message to display
+        status_code: HTTP status code (default 400)
+
+    Returns:
+        HTMLResponse with error page
+    """
+    content = f"""
+        <html>
+        <head><title>Authentication Error</title></head>
+        <body style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; max-width: 600px; margin: 40px auto; padding: 20px; text-align: center;">
+            <h2 style="color: #d32f2f;">Authentication Error</h2>
+            <p>{error_message}</p>
+            <p>Please ensure you grant the requested permissions. You can close this window and try again.</p>
+            <script>setTimeout(function() {{ window.close(); }}, 10000);</script>
+        </body>
+        </html>
+    """
+    return HTMLResponse(content=content, status_code=status_code)
+
+
+def create_success_response(verified_user_id: Optional[str] = None) -> HTMLResponse:
+    """
+    Create a standardized success response for OAuth authentication.
+
+    Args:
+        verified_user_id: The authenticated user's email (optional)
+
+    Returns:
+        HTMLResponse with success page
+    """
+    # Handle the case where no user ID is provided
+    user_display = verified_user_id if verified_user_id else "Google User"
+
+    content = f"""<html>
+<head>
+    <title>Authentication Successful</title>
+    <style>
+        * {{
+            margin: 0;
+            padding: 0;
+            box-sizing: border-box;
+        }}
+
+        body {{
+            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+            background: linear-gradient(135deg,#0f172a,#1e293b,#334155);
+            min-height: 100vh;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            color: #1a1a1a;
+            -webkit-font-smoothing: antialiased;
+            -moz-osx-font-smoothing: grayscale;
+        }}
+
+        .container {{
+            background: rgba(255, 255, 255, 0.95);
+            backdrop-filter: blur(10px);
+            padding: 60px;
+            border-radius: 20px;
+            box-shadow: 0 30px 60px rgba(0, 0, 0, 0.12);
+            text-align: center;
+            max-width: 480px;
+            width: 90%;
+            transform: translateY(-20px);
+            animation: slideUp 0.6s ease-out;
+        }}
+
+        @keyframes slideUp {{
+            from {{
+                opacity: 0;
+                transform: translateY(0);
+            }}
+            to {{
+                opacity: 1;
+                transform: translateY(-20px);
+            }}
+        }}
+
+        .icon {{
+            width: 80px;
+            height: 80px;
+            margin: 0 auto 30px;
+            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+            border-radius: 50%;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            font-size: 40px;
+            color: white;
+            animation: pulse 2s ease-in-out infinite;
+        }}
+
+        @keyframes pulse {{
+            0%, 100% {{
+                transform: scale(1);
+            }}
+            50% {{
+                transform: scale(1.05);
+            }}
+        }}
+
+        h1 {{
+            font-size: 28px;
+            font-weight: 600;
+            margin-bottom: 20px;
+            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+            -webkit-background-clip: text;
+            -webkit-text-fill-color: transparent;
+            background-clip: text;
+        }}
+
+        .message {{
+            font-size: 16px;
+            line-height: 1.6;
+            color: #4a5568;
+            margin-bottom: 20px;
+        }}
+
+        .user-id {{
+            font-weight: 600;
+            color: #667eea;
+            padding: 4px 12px;
+            background: rgba(102, 126, 234, 0.1);
+            border-radius: 6px;
+            display: inline-block;
+            margin: 0 4px;
+        }}
+
+        .button {{
+            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+            color: white;
+            padding: 16px 40px;
+            border: none;
+            border-radius: 30px;
+            font-size: 16px;
+            font-weight: 500;
+            cursor: pointer;
+            transition: all 0.3s ease;
+            margin-top: 30px;
+            display: inline-block;
+            text-decoration: none;
+            box-shadow: 0 4px 15px rgba(102, 126, 234, 0.3);
+        }}
+
+        .button:hover {{
+            transform: translateY(-2px);
+            box-shadow: 0 7px 20px rgba(102, 126, 234, 0.4);
+        }}
+
+        .button:active {{
+            transform: translateY(0);
+        }}
+
+        .auto-close {{
+            font-size: 13px;
+            color: #a0aec0;
+            margin-top: 30px;
+            opacity: 0.8;
+        }}
+    </style>
+    <script>
+        setTimeout(function() {{
+            window.close();
+        }}, 10000);
+    </script>
+</head>
+<body>
+    <div class="container">
+        <div class="icon">✓</div>
+        <h1>Authentication Successful</h1>
+        <div class="message">
+            You've been authenticated as <span class="user-id">{user_display}</span>
+        </div>
+        <div class="message">
+            Your credentials have been securely saved. You can now close this window and retry your original command.
+        </div>
+        <button class="button" onclick="window.close()">Close Window</button>
+        <div class="auto-close">This window will close automatically in 10 seconds</div>
+    </div>
+</body>
+</html>"""
+    return HTMLResponse(content=content)
+
+
+def create_server_error_response(error_detail: str) -> HTMLResponse:
+    """
+    Create a standardized server error response for OAuth processing failures.
+
+    Args:
+        error_detail: The detailed error message
+
+    Returns:
+        HTMLResponse with server error page
+    """
+    content = f"""
+        <html>
+        <head><title>Authentication Processing Error</title></head>
+        <body style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; max-width: 600px; margin: 40px auto; padding: 20px; text-align: center;">
+            <h2 style="color: #d32f2f;">Authentication Processing Error</h2>
+            <p>An unexpected error occurred while processing your authentication: {error_detail}</p>
+            <p>Please try again. You can close this window.</p>
+            <script>setTimeout(function() {{ window.close(); }}, 10000);</script>
+        </body>
+        </html>
+    """
+    return HTMLResponse(content=content, status_code=500)

auth/oauth_types.py

@@ -0,0 +1,82 @@
+"""
+Type definitions for OAuth authentication.
+
+This module provides structured types for OAuth-related parameters,
+improving code maintainability and type safety.
+"""
+
+from dataclasses import dataclass
+from typing import Optional, List, Dict, Any
+
+
+@dataclass
+class OAuth21ServiceRequest:
+    """
+    Encapsulates parameters for OAuth 2.1 service authentication requests.
+
+    This parameter object pattern reduces function complexity and makes
+    it easier to extend authentication parameters in the future.
+    """
+
+    service_name: str
+    version: str
+    tool_name: str
+    user_google_email: str
+    required_scopes: List[str]
+    session_id: Optional[str] = None
+    auth_token_email: Optional[str] = None
+    allow_recent_auth: bool = False
+    context: Optional[Dict[str, Any]] = None
+
+    def to_legacy_params(self) -> dict:
+        """Convert to legacy parameter format for backward compatibility."""
+        return {
+            "service_name": self.service_name,
+            "version": self.version,
+            "tool_name": self.tool_name,
+            "user_google_email": self.user_google_email,
+            "required_scopes": self.required_scopes,
+        }
+
+
+@dataclass
+class OAuthVersionDetectionParams:
+    """
+    Parameters used for OAuth version detection.
+
+    Encapsulates the various signals we use to determine
+    whether a client supports OAuth 2.1 or needs OAuth 2.0.
+    """
+
+    client_id: Optional[str] = None
+    client_secret: Optional[str] = None
+    code_challenge: Optional[str] = None
+    code_challenge_method: Optional[str] = None
+    code_verifier: Optional[str] = None
+    authenticated_user: Optional[str] = None
+    session_id: Optional[str] = None
+
+    @classmethod
+    def from_request(
+        cls, request_params: Dict[str, Any]
+    ) -> "OAuthVersionDetectionParams":
+        """Create from raw request parameters."""
+        return cls(
+            client_id=request_params.get("client_id"),
+            client_secret=request_params.get("client_secret"),
+            code_challenge=request_params.get("code_challenge"),
+            code_challenge_method=request_params.get("code_challenge_method"),
+            code_verifier=request_params.get("code_verifier"),
+            authenticated_user=request_params.get("authenticated_user"),
+            session_id=request_params.get("session_id"),
+        )
+
+    @property
+    def has_pkce(self) -> bool:
+        """Check if PKCE parameters are present."""
+        return bool(self.code_challenge or self.code_verifier)
+
+    @property
+    def is_public_client(self) -> bool:
+        """Check if this appears to be a public client (no secret)."""
+        return bool(self.client_id and not self.client_secret)

auth/scopes.py

@@ -0,0 +1,207 @@
+"""
+Google Workspace OAuth Scopes
+
+This module centralizes OAuth scope definitions for Google Workspace integration.
+Separated from service_decorator.py to avoid circular imports.
+"""
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+# Global variable to store enabled tools (set by main.py)
+_ENABLED_TOOLS = None
+
+# Individual OAuth Scope Constants
+USERINFO_EMAIL_SCOPE = "https://www.googleapis.com/auth/userinfo.email"
+USERINFO_PROFILE_SCOPE = "https://www.googleapis.com/auth/userinfo.profile"
+OPENID_SCOPE = "openid"
+CALENDAR_SCOPE = "https://www.googleapis.com/auth/calendar"
+CALENDAR_READONLY_SCOPE = "https://www.googleapis.com/auth/calendar.readonly"
+CALENDAR_EVENTS_SCOPE = "https://www.googleapis.com/auth/calendar.events"
+
+# Google Drive scopes
+DRIVE_SCOPE = "https://www.googleapis.com/auth/drive"
+DRIVE_READONLY_SCOPE = "https://www.googleapis.com/auth/drive.readonly"
+DRIVE_FILE_SCOPE = "https://www.googleapis.com/auth/drive.file"
+
+# Google Docs scopes
+DOCS_READONLY_SCOPE = "https://www.googleapis.com/auth/documents.readonly"
+DOCS_WRITE_SCOPE = "https://www.googleapis.com/auth/documents"
+
+# Gmail API scopes
+GMAIL_READONLY_SCOPE = "https://www.googleapis.com/auth/gmail.readonly"
+GMAIL_SEND_SCOPE = "https://www.googleapis.com/auth/gmail.send"
+GMAIL_COMPOSE_SCOPE = "https://www.googleapis.com/auth/gmail.compose"
+GMAIL_MODIFY_SCOPE = "https://www.googleapis.com/auth/gmail.modify"
+GMAIL_LABELS_SCOPE = "https://www.googleapis.com/auth/gmail.labels"
+GMAIL_SETTINGS_BASIC_SCOPE = "https://www.googleapis.com/auth/gmail.settings.basic"
+
+# Google Chat API scopes
+CHAT_READONLY_SCOPE = "https://www.googleapis.com/auth/chat.messages.readonly"
+CHAT_WRITE_SCOPE = "https://www.googleapis.com/auth/chat.messages"
+CHAT_SPACES_SCOPE = "https://www.googleapis.com/auth/chat.spaces"
+
+# Google Sheets API scopes
+SHEETS_READONLY_SCOPE = "https://www.googleapis.com/auth/spreadsheets.readonly"
+SHEETS_WRITE_SCOPE = "https://www.googleapis.com/auth/spreadsheets"
+
+# Google Forms API scopes
+FORMS_BODY_SCOPE = "https://www.googleapis.com/auth/forms.body"
+FORMS_BODY_READONLY_SCOPE = "https://www.googleapis.com/auth/forms.body.readonly"
+FORMS_RESPONSES_READONLY_SCOPE = (
+    "https://www.googleapis.com/auth/forms.responses.readonly"
+)
+
+# Google Slides API scopes
+SLIDES_SCOPE = "https://www.googleapis.com/auth/presentations"
+SLIDES_READONLY_SCOPE = "https://www.googleapis.com/auth/presentations.readonly"
+
+# Google Tasks API scopes
+TASKS_SCOPE = "https://www.googleapis.com/auth/tasks"
+TASKS_READONLY_SCOPE = "https://www.googleapis.com/auth/tasks.readonly"
+
+# Google Custom Search API scope
+CUSTOM_SEARCH_SCOPE = "https://www.googleapis.com/auth/cse"
+
+# Google Apps Script API scopes
+SCRIPT_PROJECTS_SCOPE = "https://www.googleapis.com/auth/script.projects"
+SCRIPT_PROJECTS_READONLY_SCOPE = (
+    "https://www.googleapis.com/auth/script.projects.readonly"
+)
+SCRIPT_DEPLOYMENTS_SCOPE = "https://www.googleapis.com/auth/script.deployments"
+SCRIPT_DEPLOYMENTS_READONLY_SCOPE = (
+    "https://www.googleapis.com/auth/script.deployments.readonly"
+)
+SCRIPT_PROCESSES_READONLY_SCOPE = "https://www.googleapis.com/auth/script.processes"
+SCRIPT_METRICS_SCOPE = "https://www.googleapis.com/auth/script.metrics"
+
+# Base OAuth scopes required for user identification
+BASE_SCOPES = [USERINFO_EMAIL_SCOPE, USERINFO_PROFILE_SCOPE, OPENID_SCOPE]
+
+# Service-specific scope groups
+DOCS_SCOPES = [DOCS_READONLY_SCOPE, DOCS_WRITE_SCOPE]
+
+CALENDAR_SCOPES = [CALENDAR_SCOPE, CALENDAR_READONLY_SCOPE, CALENDAR_EVENTS_SCOPE]
+
+DRIVE_SCOPES = [DRIVE_SCOPE, DRIVE_READONLY_SCOPE, DRIVE_FILE_SCOPE]
+
+GMAIL_SCOPES = [
+    GMAIL_READONLY_SCOPE,
+    GMAIL_SEND_SCOPE,
+    GMAIL_COMPOSE_SCOPE,
+    GMAIL_MODIFY_SCOPE,
+    GMAIL_LABELS_SCOPE,
+    GMAIL_SETTINGS_BASIC_SCOPE,
+]
+
+CHAT_SCOPES = [CHAT_READONLY_SCOPE, CHAT_WRITE_SCOPE, CHAT_SPACES_SCOPE]
+
+SHEETS_SCOPES = [SHEETS_READONLY_SCOPE, SHEETS_WRITE_SCOPE]
+
+FORMS_SCOPES = [
+    FORMS_BODY_SCOPE,
+    FORMS_BODY_READONLY_SCOPE,
+    FORMS_RESPONSES_READONLY_SCOPE,
+]
+
+SLIDES_SCOPES = [SLIDES_SCOPE, SLIDES_READONLY_SCOPE]
+
+TASKS_SCOPES = [TASKS_SCOPE, TASKS_READONLY_SCOPE]
+
+CUSTOM_SEARCH_SCOPES = [CUSTOM_SEARCH_SCOPE]
+
+SCRIPT_SCOPES = [
+    SCRIPT_PROJECTS_SCOPE,
+    SCRIPT_PROJECTS_READONLY_SCOPE,
+    SCRIPT_DEPLOYMENTS_SCOPE,
+    SCRIPT_DEPLOYMENTS_READONLY_SCOPE,
+    SCRIPT_PROCESSES_READONLY_SCOPE,  # Required for list_script_processes
+    SCRIPT_METRICS_SCOPE,  # Required for get_script_metrics
+    DRIVE_FILE_SCOPE,  # Required for list/delete script projects (uses Drive API)
+]
+
+# Tool-to-scopes mapping
+TOOL_SCOPES_MAP = {
+    "gmail": GMAIL_SCOPES,
+    "drive": DRIVE_SCOPES,
+    "calendar": CALENDAR_SCOPES,
+    "docs": DOCS_SCOPES,
+    "sheets": SHEETS_SCOPES,
+    "chat": CHAT_SCOPES,
+    "forms": FORMS_SCOPES,
+    "slides": SLIDES_SCOPES,
+    "tasks": TASKS_SCOPES,
+    "search": CUSTOM_SEARCH_SCOPES,
+    "appscript": SCRIPT_SCOPES,
+}
+
+
+def set_enabled_tools(enabled_tools):
+    """
+    Set the globally enabled tools list.
+
+    Args:
+        enabled_tools: List of enabled tool names.
+    """
+    global _ENABLED_TOOLS
+    _ENABLED_TOOLS = enabled_tools
+    logger.info(f"Enabled tools set for scope management: {enabled_tools}")
+
+
+def get_current_scopes():
+    """
+    Returns scopes for currently enabled tools.
+    Uses globally set enabled tools or all tools if not set.
+
+    Returns:
+        List of unique scopes for the enabled tools plus base scopes.
+    """
+    enabled_tools = _ENABLED_TOOLS
+    if enabled_tools is None:
+        # Default behavior - return all scopes
+        enabled_tools = TOOL_SCOPES_MAP.keys()
+
+    # Start with base scopes (always required)
+    scopes = BASE_SCOPES.copy()
+
+    # Add scopes for each enabled tool
+    for tool in enabled_tools:
+        if tool in TOOL_SCOPES_MAP:
+            scopes.extend(TOOL_SCOPES_MAP[tool])
+
+    logger.debug(
+        f"Generated scopes for tools {list(enabled_tools)}: {len(set(scopes))} unique scopes"
+    )
+    # Return unique scopes
+    return list(set(scopes))
+
+
+def get_scopes_for_tools(enabled_tools=None):
+    """
+    Returns scopes for enabled tools only.
+
+    Args:
+        enabled_tools: List of enabled tool names. If None, returns all scopes.
+
+    Returns:
+        List of unique scopes for the enabled tools plus base scopes.
+    """
+    if enabled_tools is None:
+        # Default behavior - return all scopes
+        enabled_tools = TOOL_SCOPES_MAP.keys()
+
+    # Start with base scopes (always required)
+    scopes = BASE_SCOPES.copy()
+
+    # Add scopes for each enabled tool
+    for tool in enabled_tools:
+        if tool in TOOL_SCOPES_MAP:
+            scopes.extend(TOOL_SCOPES_MAP[tool])
+
+    # Return unique scopes
+    return list(set(scopes))
+
+
+# Combined scopes for all supported Google Workspace operations (backwards compatibility)
+SCOPES = get_scopes_for_tools()

auth/service_decorator.py

@@ -0,0 +1,789 @@
+import inspect
+import logging
+
+import re
+from functools import wraps
+from typing import Dict, List, Optional, Any, Callable, Union, Tuple
+
+from google.auth.exceptions import RefreshError
+from googleapiclient.discovery import build
+from fastmcp.server.dependencies import get_access_token, get_context
+from auth.google_auth import get_authenticated_google_service, GoogleAuthenticationError
+from auth.oauth21_session_store import (
+    get_auth_provider,
+    get_oauth21_session_store,
+    ensure_session_from_access_token,
+)
+from auth.oauth_config import is_oauth21_enabled, get_oauth_config
+from core.context import set_fastmcp_session_id
+from auth.scopes import (
+    GMAIL_READONLY_SCOPE,
+    GMAIL_SEND_SCOPE,
+    GMAIL_COMPOSE_SCOPE,
+    GMAIL_MODIFY_SCOPE,
+    GMAIL_LABELS_SCOPE,
+    GMAIL_SETTINGS_BASIC_SCOPE,
+    DRIVE_READONLY_SCOPE,
+    DRIVE_FILE_SCOPE,
+    DOCS_READONLY_SCOPE,
+    DOCS_WRITE_SCOPE,
+    CALENDAR_READONLY_SCOPE,
+    CALENDAR_EVENTS_SCOPE,
+    SHEETS_READONLY_SCOPE,
+    SHEETS_WRITE_SCOPE,
+    CHAT_READONLY_SCOPE,
+    CHAT_WRITE_SCOPE,
+    CHAT_SPACES_SCOPE,
+    FORMS_BODY_SCOPE,
+    FORMS_BODY_READONLY_SCOPE,
+    FORMS_RESPONSES_READONLY_SCOPE,
+    SLIDES_SCOPE,
+    SLIDES_READONLY_SCOPE,
+    TASKS_SCOPE,
+    TASKS_READONLY_SCOPE,
+    CUSTOM_SEARCH_SCOPE,
+    SCRIPT_PROJECTS_SCOPE,
+    SCRIPT_PROJECTS_READONLY_SCOPE,
+    SCRIPT_DEPLOYMENTS_SCOPE,
+    SCRIPT_DEPLOYMENTS_READONLY_SCOPE,
+)
+
+logger = logging.getLogger(__name__)
+
+
+# Authentication helper functions
+def _get_auth_context(
+    tool_name: str,
+) -> Tuple[Optional[str], Optional[str], Optional[str]]:
+    """
+    Get authentication context from FastMCP.
+
+    Returns:
+        Tuple of (authenticated_user, auth_method, mcp_session_id)
+    """
+    try:
+        ctx = get_context()
+        if not ctx:
+            return None, None, None
+
+        authenticated_user = ctx.get_state("authenticated_user_email")
+        auth_method = ctx.get_state("authenticated_via")
+        mcp_session_id = ctx.session_id if hasattr(ctx, "session_id") else None
+
+        if mcp_session_id:
+            set_fastmcp_session_id(mcp_session_id)
+
+        logger.debug(
+            f"[{tool_name}] Auth from middleware: {authenticated_user} via {auth_method}"
+        )
+        return authenticated_user, auth_method, mcp_session_id
+
+    except Exception as e:
+        logger.debug(f"[{tool_name}] Could not get FastMCP context: {e}")
+        return None, None, None
+
+
+def _detect_oauth_version(
+    authenticated_user: Optional[str], mcp_session_id: Optional[str], tool_name: str
+) -> bool:
+    """
+    Detect whether to use OAuth 2.1 based on configuration and context.
+
+    Returns:
+        True if OAuth 2.1 should be used, False otherwise
+    """
+    if not is_oauth21_enabled():
+        return False
+
+    # When OAuth 2.1 is enabled globally, ALWAYS use OAuth 2.1 for authenticated users
+    if authenticated_user:
+        logger.info(
+            f"[{tool_name}] OAuth 2.1 mode: Using OAuth 2.1 for authenticated user '{authenticated_user}'"
+        )
+        return True
+
+    # Only use version detection for unauthenticated requests
+    config = get_oauth_config()
+    request_params = {}
+    if mcp_session_id:
+        request_params["session_id"] = mcp_session_id
+
+    oauth_version = config.detect_oauth_version(request_params)
+    use_oauth21 = oauth_version == "oauth21"
+    logger.info(
+        f"[{tool_name}] OAuth version detected: {oauth_version}, will use OAuth 2.1: {use_oauth21}"
+    )
+    return use_oauth21
+
+
+def _update_email_in_args(args: tuple, index: int, new_email: str) -> tuple:
+    """Update email at specific index in args tuple."""
+    if index < len(args):
+        args_list = list(args)
+        args_list[index] = new_email
+        return tuple(args_list)
+    return args
+
+
+def _override_oauth21_user_email(
+    use_oauth21: bool,
+    authenticated_user: Optional[str],
+    current_user_email: str,
+    args: tuple,
+    kwargs: dict,
+    param_names: List[str],
+    tool_name: str,
+    service_type: str = "",
+) -> Tuple[str, tuple]:
+    """
+    Override user_google_email with authenticated user when using OAuth 2.1.
+
+    Returns:
+        Tuple of (updated_user_email, updated_args)
+    """
+    if not (
+        use_oauth21 and authenticated_user and current_user_email != authenticated_user
+    ):
+        return current_user_email, args
+
+    service_suffix = f" for service '{service_type}'" if service_type else ""
+    logger.info(
+        f"[{tool_name}] OAuth 2.1: Overriding user_google_email from '{current_user_email}' to authenticated user '{authenticated_user}'{service_suffix}"
+    )
+
+    # Update in kwargs if present
+    if "user_google_email" in kwargs:
+        kwargs["user_google_email"] = authenticated_user
+
+    # Update in args if user_google_email is passed positionally
+    try:
+        user_email_index = param_names.index("user_google_email")
+        args = _update_email_in_args(args, user_email_index, authenticated_user)
+    except ValueError:
+        pass  # user_google_email not in positional parameters
+
+    return authenticated_user, args
+
+
+async def _authenticate_service(
+    use_oauth21: bool,
+    service_name: str,
+    service_version: str,
+    tool_name: str,
+    user_google_email: str,
+    resolved_scopes: List[str],
+    mcp_session_id: Optional[str],
+    authenticated_user: Optional[str],
+) -> Tuple[Any, str]:
+    """
+    Authenticate and get Google service using appropriate OAuth version.
+
+    Returns:
+        Tuple of (service, actual_user_email)
+    """
+    if use_oauth21:
+        logger.debug(f"[{tool_name}] Using OAuth 2.1 flow")
+        return await get_authenticated_google_service_oauth21(
+            service_name=service_name,
+            version=service_version,
+            tool_name=tool_name,
+            user_google_email=user_google_email,
+            required_scopes=resolved_scopes,
+            session_id=mcp_session_id,
+            auth_token_email=authenticated_user,
+            allow_recent_auth=False,
+        )
+    else:
+        logger.debug(f"[{tool_name}] Using legacy OAuth 2.0 flow")
+        return await get_authenticated_google_service(
+            service_name=service_name,
+            version=service_version,
+            tool_name=tool_name,
+            user_google_email=user_google_email,
+            required_scopes=resolved_scopes,
+            session_id=mcp_session_id,
+        )
+
+
+async def get_authenticated_google_service_oauth21(
+    service_name: str,
+    version: str,
+    tool_name: str,
+    user_google_email: str,
+    required_scopes: List[str],
+    session_id: Optional[str] = None,
+    auth_token_email: Optional[str] = None,
+    allow_recent_auth: bool = False,
+) -> tuple[Any, str]:
+    """
+    OAuth 2.1 authentication using the session store with security validation.
+    """
+    provider = get_auth_provider()
+    access_token = get_access_token()
+
+    if provider and access_token:
+        token_email = None
+        if getattr(access_token, "claims", None):
+            token_email = access_token.claims.get("email")
+
+        resolved_email = token_email or auth_token_email or user_google_email
+        if not resolved_email:
+            raise GoogleAuthenticationError(
+                "Authenticated user email could not be determined from access token."
+            )
+
+        if auth_token_email and token_email and token_email != auth_token_email:
+            raise GoogleAuthenticationError(
+                "Access token email does not match authenticated session context."
+            )
+
+        if token_email and user_google_email and token_email != user_google_email:
+            raise GoogleAuthenticationError(
+                f"Authenticated account {token_email} does not match requested user {user_google_email}."
+            )
+
+        credentials = ensure_session_from_access_token(
+            access_token, resolved_email, session_id
+        )
+        if not credentials:
+            raise GoogleAuthenticationError(
+                "Unable to build Google credentials from authenticated access token."
+            )
+
+        scopes_available = set(credentials.scopes or [])
+        if not scopes_available and getattr(access_token, "scopes", None):
+            scopes_available = set(access_token.scopes)
+
+        if not all(scope in scopes_available for scope in required_scopes):
+            raise GoogleAuthenticationError(
+                f"OAuth credentials lack required scopes. Need: {required_scopes}, Have: {sorted(scopes_available)}"
+            )
+
+        service = build(service_name, version, credentials=credentials)
+        logger.info(f"[{tool_name}] Authenticated {service_name} for {resolved_email}")
+        return service, resolved_email
+
+    store = get_oauth21_session_store()
+
+    # Use the validation method to ensure session can only access its own credentials
+    credentials = store.get_credentials_with_validation(
+        requested_user_email=user_google_email,
+        session_id=session_id,
+        auth_token_email=auth_token_email,
+        allow_recent_auth=allow_recent_auth,
+    )
+
+    if not credentials:
+        raise GoogleAuthenticationError(
+            f"Access denied: Cannot retrieve credentials for {user_google_email}. "
+            f"You can only access credentials for your authenticated account."
+        )
+
+    if not credentials.scopes:
+        scopes_available = set(required_scopes)
+    else:
+        scopes_available = set(credentials.scopes)
+
+    if not all(scope in scopes_available for scope in required_scopes):
+        raise GoogleAuthenticationError(
+            f"OAuth 2.1 credentials lack required scopes. Need: {required_scopes}, Have: {sorted(scopes_available)}"
+        )
+
+    service = build(service_name, version, credentials=credentials)
+    logger.info(f"[{tool_name}] Authenticated {service_name} for {user_google_email}")
+
+    return service, user_google_email
+
+
+def _extract_oauth21_user_email(
+    authenticated_user: Optional[str], func_name: str
+) -> str:
+    """
+    Extract user email for OAuth 2.1 mode.
+
+    Args:
+        authenticated_user: The authenticated user from context
+        func_name: Name of the function being decorated (for error messages)
+
+    Returns:
+        User email string
+
+    Raises:
+        Exception: If no authenticated user found in OAuth 2.1 mode
+    """
+    if not authenticated_user:
+        raise Exception(
+            f"OAuth 2.1 mode requires an authenticated user for {func_name}, but none was found."
+        )
+    return authenticated_user
+
+
+def _extract_oauth20_user_email(
+    args: tuple, kwargs: dict, wrapper_sig: inspect.Signature
+) -> str:
+    """
+    Extract user email for OAuth 2.0 mode from function arguments.
+
+    Args:
+        args: Positional arguments passed to wrapper
+        kwargs: Keyword arguments passed to wrapper
+        wrapper_sig: Function signature for parameter binding
+
+    Returns:
+        User email string
+
+    Raises:
+        Exception: If user_google_email parameter not found
+    """
+    bound_args = wrapper_sig.bind(*args, **kwargs)
+    bound_args.apply_defaults()
+
+    user_google_email = bound_args.arguments.get("user_google_email")
+    if not user_google_email:
+        raise Exception("'user_google_email' parameter is required but was not found.")
+    return user_google_email
+
+
+def _remove_user_email_arg_from_docstring(docstring: str) -> str:
+    """
+    Remove user_google_email parameter documentation from docstring.
+
+    Args:
+        docstring: The original function docstring
+
+    Returns:
+        Modified docstring with user_google_email parameter removed
+    """
+    if not docstring:
+        return docstring
+
+    # Pattern to match user_google_email parameter documentation
+    # Handles various formats like:
+    # - user_google_email (str): The user's Google email address. Required.
+    # - user_google_email: Description
+    # - user_google_email (str) - Description
+    patterns = [
+        r"^\s*user_google_email\s*\([^)]*\)\s*:\s*[^\n]*\.?\s*(?:Required\.?)?\s*\n",
+        r"^\s*user_google_email\s*:\s*[^\n]*\n",
+        r"^\s*user_google_email\s*\([^)]*\)\s*-\s*[^\n]*\n",
+    ]
+
+    modified_docstring = docstring
+    for pattern in patterns:
+        modified_docstring = re.sub(pattern, "", modified_docstring, flags=re.MULTILINE)
+
+    # Clean up any sequence of 3 or more newlines that might have been created
+    modified_docstring = re.sub(r"\n{3,}", "\n\n", modified_docstring)
+    return modified_docstring
+
+
+# Service configuration mapping
+SERVICE_CONFIGS = {
+    "gmail": {"service": "gmail", "version": "v1"},
+    "drive": {"service": "drive", "version": "v3"},
+    "calendar": {"service": "calendar", "version": "v3"},
+    "docs": {"service": "docs", "version": "v1"},
+    "sheets": {"service": "sheets", "version": "v4"},
+    "chat": {"service": "chat", "version": "v1"},
+    "forms": {"service": "forms", "version": "v1"},
+    "slides": {"service": "slides", "version": "v1"},
+    "tasks": {"service": "tasks", "version": "v1"},
+    "customsearch": {"service": "customsearch", "version": "v1"},
+    "script": {"service": "script", "version": "v1"},
+}
+
+
+# Scope group definitions for easy reference
+SCOPE_GROUPS = {
+    # Gmail scopes
+    "gmail_read": GMAIL_READONLY_SCOPE,
+    "gmail_send": GMAIL_SEND_SCOPE,
+    "gmail_compose": GMAIL_COMPOSE_SCOPE,
+    "gmail_modify": GMAIL_MODIFY_SCOPE,
+    "gmail_labels": GMAIL_LABELS_SCOPE,
+    "gmail_settings_basic": GMAIL_SETTINGS_BASIC_SCOPE,
+    # Drive scopes
+    "drive_read": DRIVE_READONLY_SCOPE,
+    "drive_file": DRIVE_FILE_SCOPE,
+    # Docs scopes
+    "docs_read": DOCS_READONLY_SCOPE,
+    "docs_write": DOCS_WRITE_SCOPE,
+    # Calendar scopes
+    "calendar_read": CALENDAR_READONLY_SCOPE,
+    "calendar_events": CALENDAR_EVENTS_SCOPE,
+    # Sheets scopes
+    "sheets_read": SHEETS_READONLY_SCOPE,
+    "sheets_write": SHEETS_WRITE_SCOPE,
+    # Chat scopes
+    "chat_read": CHAT_READONLY_SCOPE,
+    "chat_write": CHAT_WRITE_SCOPE,
+    "chat_spaces": CHAT_SPACES_SCOPE,
+    # Forms scopes
+    "forms": FORMS_BODY_SCOPE,
+    "forms_read": FORMS_BODY_READONLY_SCOPE,
+    "forms_responses_read": FORMS_RESPONSES_READONLY_SCOPE,
+    # Slides scopes
+    "slides": SLIDES_SCOPE,
+    "slides_read": SLIDES_READONLY_SCOPE,
+    # Tasks scopes
+    "tasks": TASKS_SCOPE,
+    "tasks_read": TASKS_READONLY_SCOPE,
+    # Custom Search scope
+    "customsearch": CUSTOM_SEARCH_SCOPE,
+    # Apps Script scopes
+    "script_readonly": SCRIPT_PROJECTS_READONLY_SCOPE,
+    "script_projects": SCRIPT_PROJECTS_SCOPE,
+    "script_deployments": SCRIPT_DEPLOYMENTS_SCOPE,
+    "script_deployments_readonly": SCRIPT_DEPLOYMENTS_READONLY_SCOPE,
+}
+
+
+def _resolve_scopes(scopes: Union[str, List[str]]) -> List[str]:
+    """Resolve scope names to actual scope URLs."""
+    if isinstance(scopes, str):
+        if scopes in SCOPE_GROUPS:
+            return [SCOPE_GROUPS[scopes]]
+        else:
+            return [scopes]
+
+    resolved = []
+    for scope in scopes:
+        if scope in SCOPE_GROUPS:
+            resolved.append(SCOPE_GROUPS[scope])
+        else:
+            resolved.append(scope)
+    return resolved
+
+
+def _handle_token_refresh_error(
+    error: RefreshError, user_email: str, service_name: str
+) -> str:
+    """
+    Handle token refresh errors gracefully, particularly expired/revoked tokens.
+
+    Args:
+        error: The RefreshError that occurred
+        user_email: User's email address
+        service_name: Name of the Google service
+
+    Returns:
+        A user-friendly error message with instructions for reauthentication
+    """
+    error_str = str(error)
+
+    if (
+        "invalid_grant" in error_str.lower()
+        or "expired or revoked" in error_str.lower()
+    ):
+        logger.warning(
+            f"Token expired or revoked for user {user_email} accessing {service_name}"
+        )
+
+        service_display_name = f"Google {service_name.title()}"
+
+        return (
+            f"**Authentication Required: Token Expired/Revoked for {service_display_name}**\n\n"
+            f"Your Google authentication token for {user_email} has expired or been revoked. "
+            f"This commonly happens when:\n"
+            f"- The token has been unused for an extended period\n"
+            f"- You've changed your Google account password\n"
+            f"- You've revoked access to the application\n\n"
+            f"**To resolve this, please:**\n"
+            f"1. Run `start_google_auth` with your email ({user_email}) and service_name='{service_display_name}'\n"
+            f"2. Complete the authentication flow in your browser\n"
+            f"3. Retry your original command\n\n"
+            f"The application will automatically use the new credentials once authentication is complete."
+        )
+    else:
+        # Handle other types of refresh errors
+        logger.error(f"Unexpected refresh error for user {user_email}: {error}")
+        return (
+            f"Authentication error occurred for {user_email}. "
+            f"Please try running `start_google_auth` with your email and the appropriate service name to reauthenticate."
+        )
+
+
+def require_google_service(
+    service_type: str,
+    scopes: Union[str, List[str]],
+    version: Optional[str] = None,
+):
+    """
+    Decorator that automatically handles Google service authentication and injection.
+
+    Args:
+        service_type: Type of Google service ("gmail", "drive", "calendar", etc.)
+        scopes: Required scopes (can be scope group names or actual URLs)
+        version: Service version (defaults to standard version for service type)
+
+    Usage:
+        @require_google_service("gmail", "gmail_read")
+        async def search_messages(service, user_google_email: str, query: str):
+            # service parameter is automatically injected
+            # Original authentication logic is handled automatically
+    """
+
+    def decorator(func: Callable) -> Callable:
+        original_sig = inspect.signature(func)
+        params = list(original_sig.parameters.values())
+
+        # The decorated function must have 'service' as its first parameter.
+        if not params or params[0].name != "service":
+            raise TypeError(
+                f"Function '{func.__name__}' decorated with @require_google_service "
+                "must have 'service' as its first parameter."
+            )
+
+        # Create a new signature for the wrapper that excludes the 'service' parameter.
+        # In OAuth 2.1 mode, also exclude 'user_google_email' since it's automatically determined.
+        if is_oauth21_enabled():
+            # Remove both 'service' and 'user_google_email' parameters
+            filtered_params = [p for p in params[1:] if p.name != "user_google_email"]
+            wrapper_sig = original_sig.replace(parameters=filtered_params)
+        else:
+            # Only remove 'service' parameter for OAuth 2.0 mode
+            wrapper_sig = original_sig.replace(parameters=params[1:])
+
+        @wraps(func)
+        async def wrapper(*args, **kwargs):
+            # Note: `args` and `kwargs` are now the arguments for the *wrapper*,
+            # which does not include 'service'.
+
+            # Get authentication context early to determine OAuth mode
+            authenticated_user, auth_method, mcp_session_id = _get_auth_context(
+                func.__name__
+            )
+
+            # Extract user_google_email based on OAuth mode
+            if is_oauth21_enabled():
+                user_google_email = _extract_oauth21_user_email(
+                    authenticated_user, func.__name__
+                )
+            else:
+                user_google_email = _extract_oauth20_user_email(
+                    args, kwargs, wrapper_sig
+                )
+
+            # Get service configuration from the decorator's arguments
+            if service_type not in SERVICE_CONFIGS:
+                raise Exception(f"Unknown service type: {service_type}")
+
+            config = SERVICE_CONFIGS[service_type]
+            service_name = config["service"]
+            service_version = version or config["version"]
+
+            # Resolve scopes
+            resolved_scopes = _resolve_scopes(scopes)
+
+            try:
+                tool_name = func.__name__
+
+                # Log authentication status
+                logger.debug(
+                    f"[{tool_name}] Auth: {authenticated_user or 'none'} via {auth_method or 'none'} (session: {mcp_session_id[:8] if mcp_session_id else 'none'})"
+                )
+
+                # Detect OAuth version
+                use_oauth21 = _detect_oauth_version(
+                    authenticated_user, mcp_session_id, tool_name
+                )
+
+                # In OAuth 2.1 mode, user_google_email is already set to authenticated_user
+                # In OAuth 2.0 mode, we may need to override it
+                if not is_oauth21_enabled():
+                    wrapper_params = list(wrapper_sig.parameters.keys())
+                    user_google_email, args = _override_oauth21_user_email(
+                        use_oauth21,
+                        authenticated_user,
+                        user_google_email,
+                        args,
+                        kwargs,
+                        wrapper_params,
+                        tool_name,
+                    )
+
+                # Authenticate service
+                service, actual_user_email = await _authenticate_service(
+                    use_oauth21,
+                    service_name,
+                    service_version,
+                    tool_name,
+                    user_google_email,
+                    resolved_scopes,
+                    mcp_session_id,
+                    authenticated_user,
+                )
+            except GoogleAuthenticationError as e:
+                logger.error(
+                    f"[{tool_name}] GoogleAuthenticationError during authentication. "
+                    f"Method={auth_method or 'none'}, User={authenticated_user or 'none'}, "
+                    f"Service={service_name} v{service_version}, MCPSessionID={mcp_session_id or 'none'}: {e}"
+                )
+                # Re-raise the original error without wrapping it
+                raise
+
+            try:
+                # In OAuth 2.1 mode, we need to add user_google_email to kwargs since it was removed from signature
+                if is_oauth21_enabled():
+                    kwargs["user_google_email"] = user_google_email
+
+                # Prepend the fetched service object to the original arguments
+                return await func(service, *args, **kwargs)
+            except RefreshError as e:
+                error_message = _handle_token_refresh_error(
+                    e, actual_user_email, service_name
+                )
+                raise Exception(error_message)
+
+        # Set the wrapper's signature to the one without 'service'
+        wrapper.__signature__ = wrapper_sig
+
+        # Conditionally modify docstring to remove user_google_email parameter documentation
+        if is_oauth21_enabled():
+            logger.debug(
+                "OAuth 2.1 mode enabled, removing user_google_email from docstring"
+            )
+            if func.__doc__:
+                wrapper.__doc__ = _remove_user_email_arg_from_docstring(func.__doc__)
+
+        return wrapper
+
+    return decorator
+
+
+def require_multiple_services(service_configs: List[Dict[str, Any]]):
+    """
+    Decorator for functions that need multiple Google services.
+
+    Args:
+        service_configs: List of service configurations, each containing:
+            - service_type: Type of service
+            - scopes: Required scopes
+            - param_name: Name to inject service as (e.g., 'drive_service', 'docs_service')
+            - version: Optional version override
+
+    Usage:
+        @require_multiple_services([
+            {"service_type": "drive", "scopes": "drive_read", "param_name": "drive_service"},
+            {"service_type": "docs", "scopes": "docs_read", "param_name": "docs_service"}
+        ])
+        async def get_doc_with_metadata(drive_service, docs_service, user_google_email: str, doc_id: str):
+            # Both services are automatically injected
+    """
+
+    def decorator(func: Callable) -> Callable:
+        original_sig = inspect.signature(func)
+
+        service_param_names = {config["param_name"] for config in service_configs}
+        params = list(original_sig.parameters.values())
+
+        # Remove injected service params from the wrapper signature; drop user_google_email only for OAuth 2.1.
+        filtered_params = [p for p in params if p.name not in service_param_names]
+        if is_oauth21_enabled():
+            filtered_params = [
+                p for p in filtered_params if p.name != "user_google_email"
+            ]
+
+        wrapper_sig = original_sig.replace(parameters=filtered_params)
+        wrapper_param_names = [p.name for p in filtered_params]
+
+        @wraps(func)
+        async def wrapper(*args, **kwargs):
+            # Get authentication context early
+            tool_name = func.__name__
+            authenticated_user, _, mcp_session_id = _get_auth_context(tool_name)
+
+            # Extract user_google_email based on OAuth mode
+            if is_oauth21_enabled():
+                user_google_email = _extract_oauth21_user_email(
+                    authenticated_user, tool_name
+                )
+            else:
+                user_google_email = _extract_oauth20_user_email(
+                    args, kwargs, wrapper_sig
+                )
+
+            # Authenticate all services
+            for config in service_configs:
+                service_type = config["service_type"]
+                scopes = config["scopes"]
+                param_name = config["param_name"]
+                version = config.get("version")
+
+                if service_type not in SERVICE_CONFIGS:
+                    raise Exception(f"Unknown service type: {service_type}")
+
+                service_config = SERVICE_CONFIGS[service_type]
+                service_name = service_config["service"]
+                service_version = version or service_config["version"]
+                resolved_scopes = _resolve_scopes(scopes)
+
+                try:
+                    # Detect OAuth version (simplified for multiple services)
+                    use_oauth21 = (
+                        is_oauth21_enabled() and authenticated_user is not None
+                    )
+
+                    # In OAuth 2.0 mode, we may need to override user_google_email
+                    if not is_oauth21_enabled():
+                        user_google_email, args = _override_oauth21_user_email(
+                            use_oauth21,
+                            authenticated_user,
+                            user_google_email,
+                            args,
+                            kwargs,
+                            wrapper_param_names,
+                            tool_name,
+                            service_type,
+                        )
+
+                    # Authenticate service
+                    service, _ = await _authenticate_service(
+                        use_oauth21,
+                        service_name,
+                        service_version,
+                        tool_name,
+                        user_google_email,
+                        resolved_scopes,
+                        mcp_session_id,
+                        authenticated_user,
+                    )
+
+                    # Inject service with specified parameter name
+                    kwargs[param_name] = service
+
+                except GoogleAuthenticationError as e:
+                    logger.error(
+                        f"[{tool_name}] GoogleAuthenticationError for service '{service_type}' (user: {user_google_email}): {e}"
+                    )
+                    # Re-raise the original error without wrapping it
+                    raise
+
+            # Call the original function with refresh error handling
+            try:
+                # In OAuth 2.1 mode, we need to add user_google_email to kwargs since it was removed from signature
+                if is_oauth21_enabled():
+                    kwargs["user_google_email"] = user_google_email
+
+                return await func(*args, **kwargs)
+            except RefreshError as e:
+                # Handle token refresh errors gracefully
+                error_message = _handle_token_refresh_error(
+                    e, user_google_email, "Multiple Services"
+                )
+                raise Exception(error_message)
+
+        # Set the wrapper's signature
+        wrapper.__signature__ = wrapper_sig
+
+        # Conditionally modify docstring to remove user_google_email parameter documentation
+        if is_oauth21_enabled():
+            logger.debug(
+                "OAuth 2.1 mode enabled, removing user_google_email from docstring"
+            )
+            if func.__doc__:
+                wrapper.__doc__ = _remove_user_email_arg_from_docstring(func.__doc__)
+
+        return wrapper
+
+    return decorator

commands.rxt

@@ -0,0 +1,2 @@
+
+Start-Process -FilePath "powershell" -ArgumentList "-NoExit", "-Command", "cd D:\flutter_assignment\backend; python .\google_workspace_mcp\main.py --transport streamable-http"

core/__init__.py

@@ -0,0 +1 @@
+# Make the core directory a Python package

core/api_enablement.py

@@ -0,0 +1,108 @@
+import re
+from typing import Dict, Optional, Tuple
+
+
+API_ENABLEMENT_LINKS: Dict[str, str] = {
+    "calendar-json.googleapis.com": "https://console.cloud.google.com/flows/enableapi?apiid=calendar-json.googleapis.com",
+    "drive.googleapis.com": "https://console.cloud.google.com/flows/enableapi?apiid=drive.googleapis.com",
+    "gmail.googleapis.com": "https://console.cloud.google.com/flows/enableapi?apiid=gmail.googleapis.com",
+    "docs.googleapis.com": "https://console.cloud.google.com/flows/enableapi?apiid=docs.googleapis.com",
+    "sheets.googleapis.com": "https://console.cloud.google.com/flows/enableapi?apiid=sheets.googleapis.com",
+    "slides.googleapis.com": "https://console.cloud.google.com/flows/enableapi?apiid=slides.googleapis.com",
+    "forms.googleapis.com": "https://console.cloud.google.com/flows/enableapi?apiid=forms.googleapis.com",
+    "tasks.googleapis.com": "https://console.cloud.google.com/flows/enableapi?apiid=tasks.googleapis.com",
+    "chat.googleapis.com": "https://console.cloud.google.com/flows/enableapi?apiid=chat.googleapis.com",
+    "customsearch.googleapis.com": "https://console.cloud.google.com/flows/enableapi?apiid=customsearch.googleapis.com",
+}
+
+
+SERVICE_NAME_TO_API: Dict[str, str] = {
+    "Google Calendar": "calendar-json.googleapis.com",
+    "Google Drive": "drive.googleapis.com",
+    "Gmail": "gmail.googleapis.com",
+    "Google Docs": "docs.googleapis.com",
+    "Google Sheets": "sheets.googleapis.com",
+    "Google Slides": "slides.googleapis.com",
+    "Google Forms": "forms.googleapis.com",
+    "Google Tasks": "tasks.googleapis.com",
+    "Google Chat": "chat.googleapis.com",
+    "Google Custom Search": "customsearch.googleapis.com",
+}
+
+
+INTERNAL_SERVICE_TO_API: Dict[str, str] = {
+    "calendar": "calendar-json.googleapis.com",
+    "drive": "drive.googleapis.com",
+    "gmail": "gmail.googleapis.com",
+    "docs": "docs.googleapis.com",
+    "sheets": "sheets.googleapis.com",
+    "slides": "slides.googleapis.com",
+    "forms": "forms.googleapis.com",
+    "tasks": "tasks.googleapis.com",
+    "chat": "chat.googleapis.com",
+    "customsearch": "customsearch.googleapis.com",
+    "search": "customsearch.googleapis.com",
+}
+
+
+def extract_api_info_from_error(
+    error_details: str,
+) -> Tuple[Optional[str], Optional[str]]:
+    """
+    Extract API service and project ID from error details.
+
+    Returns:
+        Tuple of (api_service, project_id) or (None, None) if not found
+    """
+    api_pattern = r"https://console\.developers\.google\.com/apis/api/([^/]+)/overview"
+    project_pattern = r"project[=\s]+([a-zA-Z0-9-]+)"
+
+    api_match = re.search(api_pattern, error_details)
+    project_match = re.search(project_pattern, error_details)
+
+    api_service = api_match.group(1) if api_match else None
+    project_id = project_match.group(1) if project_match else None
+
+    return api_service, project_id
+
+
+def get_api_enablement_message(
+    error_details: str, service_type: Optional[str] = None
+) -> str:
+    """
+    Generate a helpful error message with direct API enablement link.
+
+    Args:
+        error_details: The error details string from the HttpError
+        service_type: Optional service type (e.g., "calendar", "gmail", or "Google Calendar")
+
+    Returns:
+        Formatted error message with enablement link
+    """
+    api_service, project_id = extract_api_info_from_error(error_details)
+
+    if not api_service and service_type:
+        # Check internal service names first (e.g., "calendar", "gmail")
+        api_service = INTERNAL_SERVICE_TO_API.get(service_type)
+        if not api_service:
+            # Check display names (e.g., "Google Calendar")
+            api_service = SERVICE_NAME_TO_API.get(service_type)
+
+    if api_service and api_service in API_ENABLEMENT_LINKS:
+        enable_link = API_ENABLEMENT_LINKS[api_service]
+        service_display_name = next(
+            (name for name, api in SERVICE_NAME_TO_API.items() if api == api_service),
+            api_service,
+        )
+
+        message = (
+            f"{service_display_name} API is not enabled for your project"
+            f"{f' ({project_id})' if project_id else ''}.\n\n"
+            f"Enable it here: {enable_link}\n\n"
+            f"After enabling, wait 1-2 minutes for the change to propagate, then try again."
+            f"IMPORTANT - LLM: share the link provided as a clickable hyperlink and instruct the user to enable the required API."
+        )
+
+        return message
+
+    return ""

core/attachment_storage.py

@@ -0,0 +1,217 @@
+"""
+Temporary attachment storage for Gmail attachments.
+
+Stores attachments in ./tmp directory and provides HTTP URLs for access.
+Files are automatically cleaned up after expiration (default 1 hour).
+"""
+
+import base64
+import logging
+import uuid
+from pathlib import Path
+from typing import Optional, Dict
+from datetime import datetime, timedelta
+
+logger = logging.getLogger(__name__)
+
+# Default expiration: 1 hour
+DEFAULT_EXPIRATION_SECONDS = 3600
+
+# Storage directory
+STORAGE_DIR = Path("./tmp/attachments")
+STORAGE_DIR.mkdir(parents=True, exist_ok=True)
+
+
+class AttachmentStorage:
+    """Manages temporary storage of email attachments."""
+
+    def __init__(self, expiration_seconds: int = DEFAULT_EXPIRATION_SECONDS):
+        self.expiration_seconds = expiration_seconds
+        self._metadata: Dict[str, Dict] = {}
+
+    def save_attachment(
+        self,
+        base64_data: str,
+        filename: Optional[str] = None,
+        mime_type: Optional[str] = None,
+    ) -> str:
+        """
+        Save an attachment and return a unique file ID.
+
+        Args:
+            base64_data: Base64-encoded attachment data
+            filename: Original filename (optional)
+            mime_type: MIME type (optional)
+
+        Returns:
+            Unique file ID (UUID string)
+        """
+        # Generate unique file ID
+        file_id = str(uuid.uuid4())
+
+        # Decode base64 data
+        try:
+            file_bytes = base64.urlsafe_b64decode(base64_data)
+        except Exception as e:
+            logger.error(f"Failed to decode base64 attachment data: {e}")
+            raise ValueError(f"Invalid base64 data: {e}")
+
+        # Determine file extension from filename or mime type
+        extension = ""
+        if filename:
+            extension = Path(filename).suffix
+        elif mime_type:
+            # Basic mime type to extension mapping
+            mime_to_ext = {
+                "image/jpeg": ".jpg",
+                "image/png": ".png",
+                "image/gif": ".gif",
+                "application/pdf": ".pdf",
+                "application/zip": ".zip",
+                "text/plain": ".txt",
+                "text/html": ".html",
+            }
+            extension = mime_to_ext.get(mime_type, "")
+
+        # Save file
+        file_path = STORAGE_DIR / f"{file_id}{extension}"
+        try:
+            file_path.write_bytes(file_bytes)
+            logger.info(
+                f"Saved attachment {file_id} ({len(file_bytes)} bytes) to {file_path}"
+            )
+        except Exception as e:
+            logger.error(f"Failed to save attachment to {file_path}: {e}")
+            raise
+
+        # Store metadata
+        expires_at = datetime.now() + timedelta(seconds=self.expiration_seconds)
+        self._metadata[file_id] = {
+            "file_path": str(file_path),
+            "filename": filename or f"attachment{extension}",
+            "mime_type": mime_type or "application/octet-stream",
+            "size": len(file_bytes),
+            "created_at": datetime.now(),
+            "expires_at": expires_at,
+        }
+
+        return file_id
+
+    def get_attachment_path(self, file_id: str) -> Optional[Path]:
+        """
+        Get the file path for an attachment ID.
+
+        Args:
+            file_id: Unique file ID
+
+        Returns:
+            Path object if file exists and not expired, None otherwise
+        """
+        if file_id not in self._metadata:
+            logger.warning(f"Attachment {file_id} not found in metadata")
+            return None
+
+        metadata = self._metadata[file_id]
+        file_path = Path(metadata["file_path"])
+
+        # Check if expired
+        if datetime.now() > metadata["expires_at"]:
+            logger.info(f"Attachment {file_id} has expired, cleaning up")
+            self._cleanup_file(file_id)
+            return None
+
+        # Check if file exists
+        if not file_path.exists():
+            logger.warning(f"Attachment file {file_path} does not exist")
+            del self._metadata[file_id]
+            return None
+
+        return file_path
+
+    def get_attachment_metadata(self, file_id: str) -> Optional[Dict]:
+        """
+        Get metadata for an attachment.
+
+        Args:
+            file_id: Unique file ID
+
+        Returns:
+            Metadata dict if exists and not expired, None otherwise
+        """
+        if file_id not in self._metadata:
+            return None
+
+        metadata = self._metadata[file_id].copy()
+
+        # Check if expired
+        if datetime.now() > metadata["expires_at"]:
+            self._cleanup_file(file_id)
+            return None
+
+        return metadata
+
+    def _cleanup_file(self, file_id: str) -> None:
+        """Remove file and metadata."""
+        if file_id in self._metadata:
+            file_path = Path(self._metadata[file_id]["file_path"])
+            try:
+                if file_path.exists():
+                    file_path.unlink()
+                    logger.debug(f"Deleted expired attachment file: {file_path}")
+            except Exception as e:
+                logger.warning(f"Failed to delete attachment file {file_path}: {e}")
+            del self._metadata[file_id]
+
+    def cleanup_expired(self) -> int:
+        """
+        Clean up expired attachments.
+
+        Returns:
+            Number of files cleaned up
+        """
+        now = datetime.now()
+        expired_ids = [
+            file_id
+            for file_id, metadata in self._metadata.items()
+            if now > metadata["expires_at"]
+        ]
+
+        for file_id in expired_ids:
+            self._cleanup_file(file_id)
+
+        return len(expired_ids)
+
+
+# Global instance
+_attachment_storage: Optional[AttachmentStorage] = None
+
+
+def get_attachment_storage() -> AttachmentStorage:
+    """Get the global attachment storage instance."""
+    global _attachment_storage
+    if _attachment_storage is None:
+        _attachment_storage = AttachmentStorage()
+    return _attachment_storage
+
+
+def get_attachment_url(file_id: str) -> str:
+    """
+    Generate a URL for accessing an attachment.
+
+    Args:
+        file_id: Unique file ID
+
+    Returns:
+        Full URL to access the attachment
+    """
+    import os
+    from core.config import WORKSPACE_MCP_PORT, WORKSPACE_MCP_BASE_URI
+
+    # Use external URL if set (for reverse proxy scenarios)
+    external_url = os.getenv("WORKSPACE_EXTERNAL_URL")
+    if external_url:
+        base_url = external_url.rstrip("/")
+    else:
+        base_url = f"{WORKSPACE_MCP_BASE_URI}:{WORKSPACE_MCP_PORT}"
+
+    return f"{base_url}/attachments/{file_id}"

core/comments.py

@@ -0,0 +1,320 @@
+"""
+Core Comments Module
+
+This module provides reusable comment management functions for Google Workspace applications.
+All Google Workspace apps (Docs, Sheets, Slides) use the Drive API for comment operations.
+"""
+
+import logging
+import asyncio
+
+
+from auth.service_decorator import require_google_service
+from core.server import server
+from core.utils import handle_http_errors
+
+logger = logging.getLogger(__name__)
+
+
+def create_comment_tools(app_name: str, file_id_param: str):
+    """
+    Factory function to create comment management tools for a specific Google Workspace app.
+
+    Args:
+        app_name: Name of the app (e.g., "document", "spreadsheet", "presentation")
+        file_id_param: Parameter name for the file ID (e.g., "document_id", "spreadsheet_id", "presentation_id")
+
+    Returns:
+        Dict containing the four comment management functions with unique names
+    """
+
+    # Create unique function names based on the app type
+    read_func_name = f"read_{app_name}_comments"
+    create_func_name = f"create_{app_name}_comment"
+    reply_func_name = f"reply_to_{app_name}_comment"
+    resolve_func_name = f"resolve_{app_name}_comment"
+
+    # Create functions without decorators first, then apply decorators with proper names
+    if file_id_param == "document_id":
+
+        @require_google_service("drive", "drive_read")
+        @handle_http_errors(read_func_name, service_type="drive")
+        async def read_comments(
+            service, user_google_email: str, document_id: str
+        ) -> str:
+            """Read all comments from a Google Document."""
+            return await _read_comments_impl(service, app_name, document_id)
+
+        @require_google_service("drive", "drive_file")
+        @handle_http_errors(create_func_name, service_type="drive")
+        async def create_comment(
+            service, user_google_email: str, document_id: str, comment_content: str
+        ) -> str:
+            """Create a new comment on a Google Document."""
+            return await _create_comment_impl(
+                service, app_name, document_id, comment_content
+            )
+
+        @require_google_service("drive", "drive_file")
+        @handle_http_errors(reply_func_name, service_type="drive")
+        async def reply_to_comment(
+            service,
+            user_google_email: str,
+            document_id: str,
+            comment_id: str,
+            reply_content: str,
+        ) -> str:
+            """Reply to a specific comment in a Google Document."""
+            return await _reply_to_comment_impl(
+                service, app_name, document_id, comment_id, reply_content
+            )
+
+        @require_google_service("drive", "drive_file")
+        @handle_http_errors(resolve_func_name, service_type="drive")
+        async def resolve_comment(
+            service, user_google_email: str, document_id: str, comment_id: str
+        ) -> str:
+            """Resolve a comment in a Google Document."""
+            return await _resolve_comment_impl(
+                service, app_name, document_id, comment_id
+            )
+
+    elif file_id_param == "spreadsheet_id":
+
+        @require_google_service("drive", "drive_read")
+        @handle_http_errors(read_func_name, service_type="drive")
+        async def read_comments(
+            service, user_google_email: str, spreadsheet_id: str
+        ) -> str:
+            """Read all comments from a Google Spreadsheet."""
+            return await _read_comments_impl(service, app_name, spreadsheet_id)
+
+        @require_google_service("drive", "drive_file")
+        @handle_http_errors(create_func_name, service_type="drive")
+        async def create_comment(
+            service, user_google_email: str, spreadsheet_id: str, comment_content: str
+        ) -> str:
+            """Create a new comment on a Google Spreadsheet."""
+            return await _create_comment_impl(
+                service, app_name, spreadsheet_id, comment_content
+            )
+
+        @require_google_service("drive", "drive_file")
+        @handle_http_errors(reply_func_name, service_type="drive")
+        async def reply_to_comment(
+            service,
+            user_google_email: str,
+            spreadsheet_id: str,
+            comment_id: str,
+            reply_content: str,
+        ) -> str:
+            """Reply to a specific comment in a Google Spreadsheet."""
+            return await _reply_to_comment_impl(
+                service, app_name, spreadsheet_id, comment_id, reply_content
+            )
+
+        @require_google_service("drive", "drive_file")
+        @handle_http_errors(resolve_func_name, service_type="drive")
+        async def resolve_comment(
+            service, user_google_email: str, spreadsheet_id: str, comment_id: str
+        ) -> str:
+            """Resolve a comment in a Google Spreadsheet."""
+            return await _resolve_comment_impl(
+                service, app_name, spreadsheet_id, comment_id
+            )
+
+    elif file_id_param == "presentation_id":
+
+        @require_google_service("drive", "drive_read")
+        @handle_http_errors(read_func_name, service_type="drive")
+        async def read_comments(
+            service, user_google_email: str, presentation_id: str
+        ) -> str:
+            """Read all comments from a Google Presentation."""
+            return await _read_comments_impl(service, app_name, presentation_id)
+
+        @require_google_service("drive", "drive_file")
+        @handle_http_errors(create_func_name, service_type="drive")
+        async def create_comment(
+            service, user_google_email: str, presentation_id: str, comment_content: str
+        ) -> str:
+            """Create a new comment on a Google Presentation."""
+            return await _create_comment_impl(
+                service, app_name, presentation_id, comment_content
+            )
+
+        @require_google_service("drive", "drive_file")
+        @handle_http_errors(reply_func_name, service_type="drive")
+        async def reply_to_comment(
+            service,
+            user_google_email: str,
+            presentation_id: str,
+            comment_id: str,
+            reply_content: str,
+        ) -> str:
+            """Reply to a specific comment in a Google Presentation."""
+            return await _reply_to_comment_impl(
+                service, app_name, presentation_id, comment_id, reply_content
+            )
+
+        @require_google_service("drive", "drive_file")
+        @handle_http_errors(resolve_func_name, service_type="drive")
+        async def resolve_comment(
+            service, user_google_email: str, presentation_id: str, comment_id: str
+        ) -> str:
+            """Resolve a comment in a Google Presentation."""
+            return await _resolve_comment_impl(
+                service, app_name, presentation_id, comment_id
+            )
+
+    # Set the proper function names and register with server
+    read_comments.__name__ = read_func_name
+    create_comment.__name__ = create_func_name
+    reply_to_comment.__name__ = reply_func_name
+    resolve_comment.__name__ = resolve_func_name
+
+    # Register tools with the server using the proper names
+    server.tool()(read_comments)
+    server.tool()(create_comment)
+    server.tool()(reply_to_comment)
+    server.tool()(resolve_comment)
+
+    return {
+        "read_comments": read_comments,
+        "create_comment": create_comment,
+        "reply_to_comment": reply_to_comment,
+        "resolve_comment": resolve_comment,
+    }
+
+
+async def _read_comments_impl(service, app_name: str, file_id: str) -> str:
+    """Implementation for reading comments from any Google Workspace file."""
+    logger.info(f"[read_{app_name}_comments] Reading comments for {app_name} {file_id}")
+
+    response = await asyncio.to_thread(
+        service.comments()
+        .list(
+            fileId=file_id,
+            fields="comments(id,content,author,createdTime,modifiedTime,resolved,replies(content,author,id,createdTime,modifiedTime))",
+        )
+        .execute
+    )
+
+    comments = response.get("comments", [])
+
+    if not comments:
+        return f"No comments found in {app_name} {file_id}"
+
+    output = [f"Found {len(comments)} comments in {app_name} {file_id}:\\n"]
+
+    for comment in comments:
+        author = comment.get("author", {}).get("displayName", "Unknown")
+        content = comment.get("content", "")
+        created = comment.get("createdTime", "")
+        resolved = comment.get("resolved", False)
+        comment_id = comment.get("id", "")
+        status = " [RESOLVED]" if resolved else ""
+
+        output.append(f"Comment ID: {comment_id}")
+        output.append(f"Author: {author}")
+        output.append(f"Created: {created}{status}")
+        output.append(f"Content: {content}")
+
+        # Add replies if any
+        replies = comment.get("replies", [])
+        if replies:
+            output.append(f"  Replies ({len(replies)}):")
+            for reply in replies:
+                reply_author = reply.get("author", {}).get("displayName", "Unknown")
+                reply_content = reply.get("content", "")
+                reply_created = reply.get("createdTime", "")
+                reply_id = reply.get("id", "")
+                output.append(f"    Reply ID: {reply_id}")
+                output.append(f"    Author: {reply_author}")
+                output.append(f"    Created: {reply_created}")
+                output.append(f"    Content: {reply_content}")
+
+        output.append("")  # Empty line between comments
+
+    return "\\n".join(output)
+
+
+async def _create_comment_impl(
+    service, app_name: str, file_id: str, comment_content: str
+) -> str:
+    """Implementation for creating a comment on any Google Workspace file."""
+    logger.info(f"[create_{app_name}_comment] Creating comment in {app_name} {file_id}")
+
+    body = {"content": comment_content}
+
+    comment = await asyncio.to_thread(
+        service.comments()
+        .create(
+            fileId=file_id,
+            body=body,
+            fields="id,content,author,createdTime,modifiedTime",
+        )
+        .execute
+    )
+
+    comment_id = comment.get("id", "")
+    author = comment.get("author", {}).get("displayName", "Unknown")
+    created = comment.get("createdTime", "")
+
+    return f"Comment created successfully!\\nComment ID: {comment_id}\\nAuthor: {author}\\nCreated: {created}\\nContent: {comment_content}"
+
+
+async def _reply_to_comment_impl(
+    service, app_name: str, file_id: str, comment_id: str, reply_content: str
+) -> str:
+    """Implementation for replying to a comment on any Google Workspace file."""
+    logger.info(
+        f"[reply_to_{app_name}_comment] Replying to comment {comment_id} in {app_name} {file_id}"
+    )
+
+    body = {"content": reply_content}
+
+    reply = await asyncio.to_thread(
+        service.replies()
+        .create(
+            fileId=file_id,
+            commentId=comment_id,
+            body=body,
+            fields="id,content,author,createdTime,modifiedTime",
+        )
+        .execute
+    )
+
+    reply_id = reply.get("id", "")
+    author = reply.get("author", {}).get("displayName", "Unknown")
+    created = reply.get("createdTime", "")
+
+    return f"Reply posted successfully!\\nReply ID: {reply_id}\\nAuthor: {author}\\nCreated: {created}\\nContent: {reply_content}"
+
+
+async def _resolve_comment_impl(
+    service, app_name: str, file_id: str, comment_id: str
+) -> str:
+    """Implementation for resolving a comment on any Google Workspace file."""
+    logger.info(
+        f"[resolve_{app_name}_comment] Resolving comment {comment_id} in {app_name} {file_id}"
+    )
+
+    body = {"content": "This comment has been resolved.", "action": "resolve"}
+
+    reply = await asyncio.to_thread(
+        service.replies()
+        .create(
+            fileId=file_id,
+            commentId=comment_id,
+            body=body,
+            fields="id,content,author,createdTime,modifiedTime",
+        )
+        .execute
+    )
+
+    reply_id = reply.get("id", "")
+    author = reply.get("author", {}).get("displayName", "Unknown")
+    created = reply.get("createdTime", "")
+
+    return f"Comment {comment_id} has been resolved successfully.\\nResolve reply ID: {reply_id}\\nAuthor: {author}\\nCreated: {created}"

core/config.py

@@ -0,0 +1,37 @@
+"""
+Shared configuration for Google Workspace MCP server.
+This module holds configuration values that need to be shared across modules
+to avoid circular imports.
+
+NOTE: OAuth configuration has been moved to auth.oauth_config for centralization.
+This module now imports from there for backward compatibility.
+"""
+
+import os
+from auth.oauth_config import (
+    get_oauth_base_url,
+    get_oauth_redirect_uri,
+    set_transport_mode,
+    get_transport_mode,
+    is_oauth21_enabled,
+)
+
+# Server configuration
+WORKSPACE_MCP_PORT = int(os.getenv("PORT", os.getenv("WORKSPACE_MCP_PORT", 8000)))
+WORKSPACE_MCP_BASE_URI = os.getenv("WORKSPACE_MCP_BASE_URI", "http://localhost")
+
+# Disable USER_GOOGLE_EMAIL in OAuth 2.1 multi-user mode
+USER_GOOGLE_EMAIL = (
+    None if is_oauth21_enabled() else os.getenv("USER_GOOGLE_EMAIL", None)
+)
+
+# Re-export OAuth functions for backward compatibility
+__all__ = [
+    "WORKSPACE_MCP_PORT",
+    "WORKSPACE_MCP_BASE_URI",
+    "USER_GOOGLE_EMAIL",
+    "get_oauth_base_url",
+    "get_oauth_redirect_uri",
+    "set_transport_mode",
+    "get_transport_mode",
+]

core/context.py

@@ -0,0 +1,43 @@
+# core/context.py
+import contextvars
+from typing import Optional
+
+# Context variable to hold injected credentials for the life of a single request.
+_injected_oauth_credentials = contextvars.ContextVar(
+    "injected_oauth_credentials", default=None
+)
+
+# Context variable to hold FastMCP session ID for the life of a single request.
+_fastmcp_session_id = contextvars.ContextVar("fastmcp_session_id", default=None)
+
+
+def get_injected_oauth_credentials():
+    """
+    Retrieve injected OAuth credentials for the current request context.
+    This is called by the authentication layer to check for request-scoped credentials.
+    """
+    return _injected_oauth_credentials.get()
+
+
+def set_injected_oauth_credentials(credentials: Optional[dict]):
+    """
+    Set or clear the injected OAuth credentials for the current request context.
+    This is called by the service decorator.
+    """
+    _injected_oauth_credentials.set(credentials)
+
+
+def get_fastmcp_session_id() -> Optional[str]:
+    """
+    Retrieve the FastMCP session ID for the current request context.
+    This is called by authentication layer to get the current session.
+    """
+    return _fastmcp_session_id.get()
+
+
+def set_fastmcp_session_id(session_id: Optional[str]):
+    """
+    Set or clear the FastMCP session ID for the current request context.
+    This is called when a FastMCP request starts.
+    """
+    _fastmcp_session_id.set(session_id)

core/log_formatter.py

@@ -0,0 +1,207 @@
+"""
+Enhanced Log Formatter for Google Workspace MCP
+
+Provides visually appealing log formatting with emojis and consistent styling
+to match the safe_print output format.
+"""
+
+import logging
+import os
+import re
+import sys
+
+
+class EnhancedLogFormatter(logging.Formatter):
+    """Custom log formatter that adds ASCII prefixes and visual enhancements to log messages."""
+
+    # Color codes for terminals that support ANSI colors
+    COLORS = {
+        "DEBUG": "\033[36m",  # Cyan
+        "INFO": "\033[32m",  # Green
+        "WARNING": "\033[33m",  # Yellow
+        "ERROR": "\033[31m",  # Red
+        "CRITICAL": "\033[35m",  # Magenta
+        "RESET": "\033[0m",  # Reset
+    }
+
+    def __init__(self, use_colors: bool = True, *args, **kwargs):
+        """
+        Initialize the emoji log formatter.
+
+        Args:
+            use_colors: Whether to use ANSI color codes (default: True)
+        """
+        super().__init__(*args, **kwargs)
+        self.use_colors = use_colors
+
+    def format(self, record: logging.LogRecord) -> str:
+        """Format the log record with ASCII prefixes and enhanced styling."""
+        # Get the appropriate ASCII prefix for the service
+        service_prefix = self._get_ascii_prefix(record.name, record.levelname)
+
+        # Format the message with enhanced styling
+        formatted_msg = self._enhance_message(record.getMessage())
+
+        # Build the formatted log entry
+        if self.use_colors:
+            color = self.COLORS.get(record.levelname, "")
+            reset = self.COLORS["RESET"]
+            return f"{service_prefix} {color}{formatted_msg}{reset}"
+        else:
+            return f"{service_prefix} {formatted_msg}"
+
+    def _get_ascii_prefix(self, logger_name: str, level_name: str) -> str:
+        """Get ASCII-safe prefix for Windows compatibility."""
+        # ASCII-safe prefixes for different services
+        ascii_prefixes = {
+            "core.tool_tier_loader": "[TOOLS]",
+            "core.tool_registry": "[REGISTRY]",
+            "auth.scopes": "[AUTH]",
+            "core.utils": "[UTILS]",
+            "auth.google_auth": "[OAUTH]",
+            "auth.credential_store": "[CREDS]",
+            "gcalendar.calendar_tools": "[CALENDAR]",
+            "gdrive.drive_tools": "[DRIVE]",
+            "gmail.gmail_tools": "[GMAIL]",
+            "gdocs.docs_tools": "[DOCS]",
+            "gsheets.sheets_tools": "[SHEETS]",
+            "gchat.chat_tools": "[CHAT]",
+            "gforms.forms_tools": "[FORMS]",
+            "gslides.slides_tools": "[SLIDES]",
+            "gtasks.tasks_tools": "[TASKS]",
+            "gsearch.search_tools": "[SEARCH]",
+        }
+
+        return ascii_prefixes.get(logger_name, f"[{level_name}]")
+
+    def _enhance_message(self, message: str) -> str:
+        """Enhance the log message with better formatting."""
+        # Handle common patterns for better visual appeal
+
+        # Tool tier loading messages
+        if "resolved to" in message and "tools across" in message:
+            # Extract numbers and service names for better formatting
+            pattern = (
+                r"Tier '(\w+)' resolved to (\d+) tools across (\d+) services: (.+)"
+            )
+            match = re.search(pattern, message)
+            if match:
+                tier, tool_count, service_count, services = match.groups()
+                return f"Tool tier '{tier}' loaded: {tool_count} tools across {service_count} services [{services}]"
+
+        # Configuration loading messages
+        if "Loaded tool tiers configuration from" in message:
+            path = message.split("from ")[-1]
+            return f"Configuration loaded from {path}"
+
+        # Tool filtering messages
+        if "Tool tier filtering" in message:
+            pattern = r"removed (\d+) tools, (\d+) enabled"
+            match = re.search(pattern, message)
+            if match:
+                removed, enabled = match.groups()
+                return f"Tool filtering complete: {enabled} tools enabled ({removed} filtered out)"
+
+        # Enabled tools messages
+        if "Enabled tools set for scope management" in message:
+            tools = message.split(": ")[-1]
+            return f"Scope management configured for tools: {tools}"
+
+        # Credentials directory messages
+        if "Credentials directory permissions check passed" in message:
+            path = message.split(": ")[-1]
+            return f"Credentials directory verified: {path}"
+
+        # If no specific pattern matches, return the original message
+        return message
+
+
+def setup_enhanced_logging(
+    log_level: int = logging.INFO, use_colors: bool = True
+) -> None:
+    """
+    Set up enhanced logging with ASCII prefix formatter for the entire application.
+
+    Args:
+        log_level: The logging level to use (default: INFO)
+        use_colors: Whether to use ANSI colors (default: True)
+    """
+    # Create the enhanced formatter
+    formatter = EnhancedLogFormatter(use_colors=use_colors)
+
+    # Get the root logger
+    root_logger = logging.getLogger()
+
+    # Update existing console handlers
+    for handler in root_logger.handlers:
+        if isinstance(handler, logging.StreamHandler) and handler.stream.name in [
+            "<stderr>",
+            "<stdout>",
+        ]:
+            handler.setFormatter(formatter)
+
+    # If no console handler exists, create one
+    console_handlers = [
+        h
+        for h in root_logger.handlers
+        if isinstance(h, logging.StreamHandler)
+        and h.stream.name in ["<stderr>", "<stdout>"]
+    ]
+
+    if not console_handlers:
+        console_handler = logging.StreamHandler()
+        console_handler.setFormatter(formatter)
+        console_handler.setLevel(log_level)
+        root_logger.addHandler(console_handler)
+
+
+def configure_file_logging(logger_name: str = None) -> bool:
+    """
+    Configure file logging based on stateless mode setting.
+
+    In stateless mode, file logging is completely disabled to avoid filesystem writes.
+    In normal mode, sets up detailed file logging to 'mcp_server_debug.log'.
+
+    Args:
+        logger_name: Optional name for the logger (defaults to root logger)
+
+    Returns:
+        bool: True if file logging was configured, False if skipped (stateless mode)
+    """
+    # Check if stateless mode is enabled
+    stateless_mode = (
+        os.getenv("WORKSPACE_MCP_STATELESS_MODE", "false").lower() == "true"
+    )
+
+    if stateless_mode:
+        logger = logging.getLogger(logger_name)
+        logger.debug("File logging disabled in stateless mode")
+        return False
+
+    # Configure file logging for normal mode
+    try:
+        target_logger = logging.getLogger(logger_name)
+        log_file_dir = os.path.dirname(os.path.abspath(__file__))
+        # Go up one level since we're in core/ subdirectory
+        log_file_dir = os.path.dirname(log_file_dir)
+        log_file_path = os.path.join(log_file_dir, "mcp_server_debug.log")
+
+        file_handler = logging.FileHandler(log_file_path, mode="a")
+        file_handler.setLevel(logging.DEBUG)
+
+        file_formatter = logging.Formatter(
+            "%(asctime)s - %(name)s - %(levelname)s - %(process)d - %(threadName)s "
+            "[%(module)s.%(funcName)s:%(lineno)d] - %(message)s"
+        )
+        file_handler.setFormatter(file_formatter)
+        target_logger.addHandler(file_handler)
+
+        logger = logging.getLogger(logger_name)
+        logger.debug(f"Detailed file logging configured to: {log_file_path}")
+        return True
+
+    except Exception as e:
+        sys.stderr.write(
+            f"CRITICAL: Failed to set up file logging to '{log_file_path}': {e}\n"
+        )
+        return False

core/server.py

@@ -0,0 +1,563 @@
+import logging
+import os
+from typing import List, Optional
+from importlib import metadata
+
+from fastapi.responses import HTMLResponse, JSONResponse, FileResponse
+from starlette.applications import Starlette
+from starlette.requests import Request
+from starlette.middleware import Middleware
+from starlette.middleware.cors import CORSMiddleware
+
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.google import GoogleProvider
+
+from auth.oauth21_session_store import get_oauth21_session_store, set_auth_provider
+from auth.google_auth import handle_auth_callback, start_auth_flow, check_client_secrets
+from auth.mcp_session_middleware import MCPSessionMiddleware
+from auth.oauth_responses import (
+    create_error_response,
+    create_success_response,
+    create_server_error_response,
+)
+from auth.auth_info_middleware import AuthInfoMiddleware
+from auth.scopes import SCOPES, get_current_scopes  # noqa
+from core.config import (
+    USER_GOOGLE_EMAIL,
+    get_transport_mode,
+    set_transport_mode as _set_transport_mode,
+    get_oauth_redirect_uri as get_oauth_redirect_uri_for_current_mode,
+)
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+_auth_provider: Optional[GoogleProvider] = None
+_legacy_callback_registered = False
+
+
+def get_cors_middleware() -> Middleware:
+    """Create CORS middleware with configured origins."""
+    cors_origins_env = os.getenv("WORKSPACE_MCP_CORS_ORIGINS", "*").strip()
+    cors_origins = (
+        [origin.strip() for origin in cors_origins_env.split(",") if origin.strip()]
+        if cors_origins_env != "*"
+        else ["*"]
+    )
+    logger.info("CORS configured with origins: %s", ",".join(cors_origins))
+    return Middleware(
+        CORSMiddleware,
+        allow_origins=cors_origins,
+        allow_methods=["GET", "POST", "PUT", "DELETE", "OPTIONS", "HEAD", "PATCH"],
+        allow_headers=[
+            "*",
+            "mcp-protocol-version",
+            "mcp-session-id",
+            "Authorization",
+            "Content-Type",
+        ],
+        expose_headers=["mcp-session-id", "*"],
+        allow_credentials=True,
+    )
+
+
+def get_http_middleware() -> list:
+    """Get the list of middleware for HTTP transport."""
+    return [
+        get_cors_middleware(),
+        Middleware(MCPSessionMiddleware),
+    ]
+
+
+server = FastMCP(
+    name="google_workspace",
+    auth=None,
+)
+
+# Add the AuthInfo middleware to inject authentication into FastMCP context
+auth_info_middleware = AuthInfoMiddleware()
+server.add_middleware(auth_info_middleware)
+
+
+def _parse_bool_env(value: str) -> bool:
+    """Parse environment variable string to boolean."""
+    return value.lower() in ("1", "true", "yes", "on")
+
+
+def set_transport_mode(mode: str):
+    """Sets the transport mode for the server."""
+    _set_transport_mode(mode)
+    logger.info(f"Transport: {mode}")
+
+
+def _ensure_legacy_callback_route() -> None:
+    global _legacy_callback_registered
+    if _legacy_callback_registered:
+        return
+    server.custom_route("/oauth2callback", methods=["GET"])(legacy_oauth2_callback)
+    _legacy_callback_registered = True
+
+
+def configure_server_for_http():
+    """
+    Configures the authentication provider for HTTP transport.
+    This must be called BEFORE server.run().
+    """
+    global _auth_provider
+
+    transport_mode = get_transport_mode()
+
+    if transport_mode != "streamable-http":
+        return
+
+    # Use centralized OAuth configuration
+    from auth.oauth_config import get_oauth_config
+
+    config = get_oauth_config()
+
+    # Check if OAuth 2.1 is enabled via centralized config
+    oauth21_enabled = config.is_oauth21_enabled()
+
+    if oauth21_enabled:
+        if not config.is_configured():
+            logger.warning("OAuth 2.1 enabled but OAuth credentials not configured")
+            return
+
+        def validate_and_derive_jwt_key(
+            jwt_signing_key_override: str | None, client_secret: str
+        ) -> bytes:
+            """Validate JWT signing key override and derive the final JWT key."""
+            if jwt_signing_key_override:
+                if len(jwt_signing_key_override) < 12:
+                    logger.warning(
+                        "OAuth 2.1: FASTMCP_SERVER_AUTH_GOOGLE_JWT_SIGNING_KEY is less than 12 characters; "
+                        "use a longer secret to improve key derivation strength."
+                    )
+                return derive_jwt_key(
+                    low_entropy_material=jwt_signing_key_override,
+                    salt="fastmcp-jwt-signing-key",
+                )
+            else:
+                return derive_jwt_key(
+                    high_entropy_material=client_secret,
+                    salt="fastmcp-jwt-signing-key",
+                )
+
+        try:
+            # Import common dependencies for storage backends
+            from key_value.aio.wrappers.encryption import FernetEncryptionWrapper
+            from cryptography.fernet import Fernet
+            from fastmcp.server.auth.jwt_issuer import derive_jwt_key
+
+            required_scopes: List[str] = sorted(get_current_scopes())
+
+            client_storage = None
+            jwt_signing_key_override = (
+                os.getenv("FASTMCP_SERVER_AUTH_GOOGLE_JWT_SIGNING_KEY", "").strip()
+                or None
+            )
+            storage_backend = (
+                os.getenv("WORKSPACE_MCP_OAUTH_PROXY_STORAGE_BACKEND", "")
+                .strip()
+                .lower()
+            )
+            valkey_host = os.getenv("WORKSPACE_MCP_OAUTH_PROXY_VALKEY_HOST", "").strip()
+
+            # Determine storage backend: valkey, disk, memory (default)
+            use_valkey = storage_backend == "valkey" or bool(valkey_host)
+            use_disk = storage_backend == "disk"
+
+            if use_valkey:
+                try:
+                    from key_value.aio.stores.valkey import ValkeyStore
+
+                    valkey_port_raw = os.getenv(
+                        "WORKSPACE_MCP_OAUTH_PROXY_VALKEY_PORT", "6379"
+                    ).strip()
+                    valkey_db_raw = os.getenv(
+                        "WORKSPACE_MCP_OAUTH_PROXY_VALKEY_DB", "0"
+                    ).strip()
+
+                    valkey_port = int(valkey_port_raw)
+                    valkey_db = int(valkey_db_raw)
+                    valkey_use_tls_raw = os.getenv(
+                        "WORKSPACE_MCP_OAUTH_PROXY_VALKEY_USE_TLS", ""
+                    ).strip()
+                    valkey_use_tls = (
+                        _parse_bool_env(valkey_use_tls_raw)
+                        if valkey_use_tls_raw
+                        else valkey_port == 6380
+                    )
+
+                    valkey_request_timeout_ms_raw = os.getenv(
+                        "WORKSPACE_MCP_OAUTH_PROXY_VALKEY_REQUEST_TIMEOUT_MS", ""
+                    ).strip()
+                    valkey_connection_timeout_ms_raw = os.getenv(
+                        "WORKSPACE_MCP_OAUTH_PROXY_VALKEY_CONNECTION_TIMEOUT_MS", ""
+                    ).strip()
+
+                    valkey_request_timeout_ms = (
+                        int(valkey_request_timeout_ms_raw)
+                        if valkey_request_timeout_ms_raw
+                        else None
+                    )
+                    valkey_connection_timeout_ms = (
+                        int(valkey_connection_timeout_ms_raw)
+                        if valkey_connection_timeout_ms_raw
+                        else None
+                    )
+
+                    valkey_username = (
+                        os.getenv(
+                            "WORKSPACE_MCP_OAUTH_PROXY_VALKEY_USERNAME", ""
+                        ).strip()
+                        or None
+                    )
+                    valkey_password = (
+                        os.getenv(
+                            "WORKSPACE_MCP_OAUTH_PROXY_VALKEY_PASSWORD", ""
+                        ).strip()
+                        or None
+                    )
+
+                    if not valkey_host:
+                        valkey_host = "localhost"
+
+                    client_storage = ValkeyStore(
+                        host=valkey_host,
+                        port=valkey_port,
+                        db=valkey_db,
+                        username=valkey_username,
+                        password=valkey_password,
+                    )
+
+                    # Configure TLS and timeouts on the underlying Glide client config.
+                    # ValkeyStore currently doesn't expose these settings directly.
+                    glide_config = getattr(client_storage, "_client_config", None)
+                    if glide_config is not None:
+                        glide_config.use_tls = valkey_use_tls
+
+                        is_remote_host = valkey_host not in {"localhost", "127.0.0.1"}
+                        if valkey_request_timeout_ms is None and (
+                            valkey_use_tls or is_remote_host
+                        ):
+                            # Glide defaults to 250ms if unset; increase for remote/TLS endpoints.
+                            valkey_request_timeout_ms = 5000
+                        if valkey_request_timeout_ms is not None:
+                            glide_config.request_timeout = valkey_request_timeout_ms
+
+                        if valkey_connection_timeout_ms is None and (
+                            valkey_use_tls or is_remote_host
+                        ):
+                            valkey_connection_timeout_ms = 10000
+                        if valkey_connection_timeout_ms is not None:
+                            from glide_shared.config import (
+                                AdvancedGlideClientConfiguration,
+                            )
+
+                            glide_config.advanced_config = (
+                                AdvancedGlideClientConfiguration(
+                                    connection_timeout=valkey_connection_timeout_ms
+                                )
+                            )
+
+                    jwt_signing_key = validate_and_derive_jwt_key(
+                        jwt_signing_key_override, config.client_secret
+                    )
+
+                    storage_encryption_key = derive_jwt_key(
+                        high_entropy_material=jwt_signing_key.decode(),
+                        salt="fastmcp-storage-encryption-key",
+                    )
+
+                    client_storage = FernetEncryptionWrapper(
+                        key_value=client_storage,
+                        fernet=Fernet(key=storage_encryption_key),
+                    )
+                    logger.info(
+                        "OAuth 2.1: Using ValkeyStore for FastMCP OAuth proxy client_storage (host=%s, port=%s, db=%s, tls=%s)",
+                        valkey_host,
+                        valkey_port,
+                        valkey_db,
+                        valkey_use_tls,
+                    )
+                    if valkey_request_timeout_ms is not None:
+                        logger.info(
+                            "OAuth 2.1: Valkey request timeout set to %sms",
+                            valkey_request_timeout_ms,
+                        )
+                    if valkey_connection_timeout_ms is not None:
+                        logger.info(
+                            "OAuth 2.1: Valkey connection timeout set to %sms",
+                            valkey_connection_timeout_ms,
+                        )
+                    logger.info(
+                        "OAuth 2.1: Applied Fernet encryption wrapper to Valkey client_storage (key derived from FASTMCP_SERVER_AUTH_GOOGLE_JWT_SIGNING_KEY or GOOGLE_OAUTH_CLIENT_SECRET)."
+                    )
+                except ImportError as exc:
+                    logger.warning(
+                        "OAuth 2.1: Valkey client_storage requested but Valkey dependencies are not installed (%s). "
+                        "Install 'workspace-mcp[valkey]' (or 'py-key-value-aio[valkey]', which includes 'valkey-glide') "
+                        "or unset WORKSPACE_MCP_OAUTH_PROXY_STORAGE_BACKEND/WORKSPACE_MCP_OAUTH_PROXY_VALKEY_HOST.",
+                        exc,
+                    )
+                except ValueError as exc:
+                    logger.warning(
+                        "OAuth 2.1: Invalid Valkey configuration; falling back to default storage (%s).",
+                        exc,
+                    )
+            elif use_disk:
+                try:
+                    from key_value.aio.stores.disk import DiskStore
+
+                    disk_directory = os.getenv(
+                        "WORKSPACE_MCP_OAUTH_PROXY_DISK_DIRECTORY", ""
+                    ).strip()
+                    if not disk_directory:
+                        # Default to FASTMCP_HOME/oauth-proxy or ~/.fastmcp/oauth-proxy
+                        fastmcp_home = os.getenv("FASTMCP_HOME", "").strip()
+                        if fastmcp_home:
+                            disk_directory = os.path.join(fastmcp_home, "oauth-proxy")
+                        else:
+                            disk_directory = os.path.expanduser(
+                                "~/.fastmcp/oauth-proxy"
+                            )
+
+                    client_storage = DiskStore(directory=disk_directory)
+
+                    jwt_signing_key = validate_and_derive_jwt_key(
+                        jwt_signing_key_override, config.client_secret
+                    )
+
+                    storage_encryption_key = derive_jwt_key(
+                        high_entropy_material=jwt_signing_key.decode(),
+                        salt="fastmcp-storage-encryption-key",
+                    )
+
+                    client_storage = FernetEncryptionWrapper(
+                        key_value=client_storage,
+                        fernet=Fernet(key=storage_encryption_key),
+                    )
+                    logger.info(
+                        "OAuth 2.1: Using DiskStore for FastMCP OAuth proxy client_storage (directory=%s)",
+                        disk_directory,
+                    )
+                except ImportError as exc:
+                    logger.warning(
+                        "OAuth 2.1: Disk storage requested but dependencies not available (%s). "
+                        "Falling back to default storage.",
+                        exc,
+                    )
+            elif storage_backend == "memory":
+                from key_value.aio.stores.memory import MemoryStore
+
+                client_storage = MemoryStore()
+                logger.info(
+                    "OAuth 2.1: Using MemoryStore for FastMCP OAuth proxy client_storage"
+                )
+            # else: client_storage remains None, FastMCP uses its default
+
+            # Ensure JWT signing key is always derived for all storage backends
+            if "jwt_signing_key" not in locals():
+                jwt_signing_key = validate_and_derive_jwt_key(
+                    jwt_signing_key_override, config.client_secret
+                )
+
+            # Check if external OAuth provider is configured
+            if config.is_external_oauth21_provider():
+                # External OAuth mode: use custom provider that handles ya29.* access tokens
+                from auth.external_oauth_provider import ExternalOAuthProvider
+
+                provider = ExternalOAuthProvider(
+                    client_id=config.client_id,
+                    client_secret=config.client_secret,
+                    base_url=config.get_oauth_base_url(),
+                    redirect_path=config.redirect_path,
+                    required_scopes=required_scopes,
+                )
+                # Disable protocol-level auth, expect bearer tokens in tool calls
+                server.auth = None
+                logger.info(
+                    "OAuth 2.1 enabled with EXTERNAL provider mode - protocol-level auth disabled"
+                )
+                logger.info(
+                    "Expecting Authorization bearer tokens in tool call headers"
+                )
+            else:
+                # Standard OAuth 2.1 mode: use FastMCP's GoogleProvider
+                provider = GoogleProvider(
+                    client_id=config.client_id,
+                    client_secret=config.client_secret,
+                    base_url=config.get_oauth_base_url(),
+                    redirect_path=config.redirect_path,
+                    required_scopes=required_scopes,
+                    client_storage=client_storage,
+                    jwt_signing_key=jwt_signing_key,
+                )
+                # Enable protocol-level auth
+                server.auth = provider
+                logger.info(
+                    "OAuth 2.1 enabled using FastMCP GoogleProvider with protocol-level auth"
+                )
+
+            # Always set auth provider for token validation in middleware
+            set_auth_provider(provider)
+            _auth_provider = provider
+        except Exception as exc:
+            logger.error(
+                "Failed to initialize FastMCP GoogleProvider: %s", exc, exc_info=True
+            )
+            raise
+    else:
+        logger.info("OAuth 2.0 mode - Server will use legacy authentication.")
+        server.auth = None
+        _auth_provider = None
+        set_auth_provider(None)
+        _ensure_legacy_callback_route()
+
+
+def get_auth_provider() -> Optional[GoogleProvider]:
+    """Gets the global authentication provider instance."""
+    return _auth_provider
+
+
+@server.custom_route("/health", methods=["GET"])
+async def health_check(request: Request):
+    try:
+        version = metadata.version("workspace-mcp")
+    except metadata.PackageNotFoundError:
+        version = "dev"
+    return JSONResponse(
+        {
+            "status": "healthy",
+            "service": "workspace-mcp",
+            "version": version,
+            "transport": get_transport_mode(),
+        }
+    )
+
+
+@server.custom_route("/attachments/{file_id}", methods=["GET"])
+async def serve_attachment(file_id: str):
+    """Serve a stored attachment file."""
+    from core.attachment_storage import get_attachment_storage
+
+    storage = get_attachment_storage()
+    metadata = storage.get_attachment_metadata(file_id)
+
+    if not metadata:
+        return JSONResponse(
+            {"error": "Attachment not found or expired"}, status_code=404
+        )
+
+    file_path = storage.get_attachment_path(file_id)
+    if not file_path:
+        return JSONResponse({"error": "Attachment file not found"}, status_code=404)
+
+    return FileResponse(
+        path=str(file_path),
+        filename=metadata["filename"],
+        media_type=metadata["mime_type"],
+    )
+
+
+async def legacy_oauth2_callback(request: Request) -> HTMLResponse:
+    state = request.query_params.get("state")
+    code = request.query_params.get("code")
+    error = request.query_params.get("error")
+
+    if error:
+        msg = (
+            f"Authentication failed: Google returned an error: {error}. State: {state}."
+        )
+        logger.error(msg)
+        return create_error_response(msg)
+
+    if not code:
+        msg = "Authentication failed: No authorization code received from Google."
+        logger.error(msg)
+        return create_error_response(msg)
+
+    try:
+        error_message = check_client_secrets()
+        if error_message:
+            return create_server_error_response(error_message)
+
+        logger.info(f"OAuth callback: Received code (state: {state}).")
+
+        mcp_session_id = None
+        if hasattr(request, "state") and hasattr(request.state, "session_id"):
+            mcp_session_id = request.state.session_id
+
+        verified_user_id, credentials = handle_auth_callback(
+            scopes=get_current_scopes(),
+            authorization_response=str(request.url),
+            redirect_uri=get_oauth_redirect_uri_for_current_mode(),
+            session_id=mcp_session_id,
+        )
+
+        logger.info(
+            f"OAuth callback: Successfully authenticated user: {verified_user_id}."
+        )
+
+        try:
+            store = get_oauth21_session_store()
+
+            store.store_session(
+                user_email=verified_user_id,
+                access_token=credentials.token,
+                refresh_token=credentials.refresh_token,
+                token_uri=credentials.token_uri,
+                client_id=credentials.client_id,
+                client_secret=credentials.client_secret,
+                scopes=credentials.scopes,
+                expiry=credentials.expiry,
+                session_id=f"google-{state}",
+                mcp_session_id=mcp_session_id,
+            )
+            logger.info(
+                f"Stored Google credentials in OAuth 2.1 session store for {verified_user_id}"
+            )
+        except Exception as e:
+            logger.error(f"Failed to store credentials in OAuth 2.1 store: {e}")
+
+        return create_success_response(verified_user_id)
+    except Exception as e:
+        logger.error(f"Error processing OAuth callback: {str(e)}", exc_info=True)
+        return create_server_error_response(str(e))
+
+
+@server.tool()
+async def start_google_auth(
+    service_name: str, user_google_email: str = USER_GOOGLE_EMAIL
+) -> str:
+    """
+    Manually initiate Google OAuth authentication flow.
+
+    NOTE: This tool should typically NOT be called directly. The authentication system
+    automatically handles credential checks and prompts for authentication when needed.
+    Only use this tool if:
+    1. You need to re-authenticate with different credentials
+    2. You want to proactively authenticate before using other tools
+    3. The automatic authentication flow failed and you need to retry
+
+    In most cases, simply try calling the Google Workspace tool you need - it will
+    automatically handle authentication if required.
+    """
+    if not user_google_email:
+        raise ValueError("user_google_email must be provided.")
+
+    error_message = check_client_secrets()
+    if error_message:
+        return f"**Authentication Error:** {error_message}"
+
+    try:
+        auth_message = await start_auth_flow(
+            user_google_email=user_google_email,
+            service_name=service_name,
+            redirect_uri=get_oauth_redirect_uri_for_current_mode(),
+        )
+        return auth_message
+    except Exception as e:
+        logger.error(f"Failed to start Google authentication flow: {e}", exc_info=True)
+        return f"**Error:** An unexpected error occurred: {e}"

core/tool_registry.py

@@ -0,0 +1,105 @@
+"""
+Tool Registry for Conditional Tool Registration
+
+This module provides a registry system that allows tools to be conditionally registered
+based on tier configuration, replacing direct @server.tool() decorators.
+"""
+
+import logging
+from typing import Set, Optional, Callable
+
+logger = logging.getLogger(__name__)
+
+# Global registry of enabled tools
+_enabled_tools: Optional[Set[str]] = None
+
+
+def set_enabled_tools(tool_names: Optional[Set[str]]):
+    """Set the globally enabled tools."""
+    global _enabled_tools
+    _enabled_tools = tool_names
+
+
+def get_enabled_tools() -> Optional[Set[str]]:
+    """Get the set of enabled tools, or None if all tools are enabled."""
+    return _enabled_tools
+
+
+def is_tool_enabled(tool_name: str) -> bool:
+    """Check if a specific tool is enabled."""
+    if _enabled_tools is None:
+        return True  # All tools enabled by default
+    return tool_name in _enabled_tools
+
+
+def conditional_tool(server, tool_name: str):
+    """
+    Decorator that conditionally registers a tool based on the enabled tools set.
+
+    Args:
+        server: The FastMCP server instance
+        tool_name: The name of the tool to register
+
+    Returns:
+        Either the registered tool decorator or a no-op decorator
+    """
+
+    def decorator(func: Callable) -> Callable:
+        if is_tool_enabled(tool_name):
+            logger.debug(f"Registering tool: {tool_name}")
+            return server.tool()(func)
+        else:
+            logger.debug(f"Skipping tool registration: {tool_name}")
+            return func
+
+    return decorator
+
+
+def wrap_server_tool_method(server):
+    """
+    Track tool registrations and filter them post-registration.
+    """
+    original_tool = server.tool
+    server._tracked_tools = []
+
+    def tracking_tool(*args, **kwargs):
+        original_decorator = original_tool(*args, **kwargs)
+
+        def wrapper_decorator(func: Callable) -> Callable:
+            tool_name = func.__name__
+            server._tracked_tools.append(tool_name)
+            # Always apply the original decorator to register the tool
+            return original_decorator(func)
+
+        return wrapper_decorator
+
+    server.tool = tracking_tool
+
+
+def filter_server_tools(server):
+    """Remove disabled tools from the server after registration."""
+    enabled_tools = get_enabled_tools()
+    if enabled_tools is None:
+        return
+
+    tools_removed = 0
+
+    # Access FastMCP's tool registry via _tool_manager._tools
+    if hasattr(server, "_tool_manager"):
+        tool_manager = server._tool_manager
+        if hasattr(tool_manager, "_tools"):
+            tool_registry = tool_manager._tools
+
+            tools_to_remove = []
+            for tool_name in list(tool_registry.keys()):
+                if not is_tool_enabled(tool_name):
+                    tools_to_remove.append(tool_name)
+
+            for tool_name in tools_to_remove:
+                del tool_registry[tool_name]
+                tools_removed += 1
+
+    if tools_removed > 0:
+        logger.info(
+            f"Tool tier filtering: removed {tools_removed} tools, {len(enabled_tools)} enabled"
+        )

core/tool_tier_loader.py

@@ -0,0 +1,196 @@
+"""
+Tool Tier Loader Module
+
+This module provides functionality to load and resolve tool tiers from the YAML configuration.
+It integrates with the existing tool enablement workflow to support tiered tool loading.
+"""
+
+import logging
+from pathlib import Path
+from typing import Dict, List, Set, Literal, Optional
+
+import yaml
+
+logger = logging.getLogger(__name__)
+
+TierLevel = Literal["core", "extended", "complete"]
+
+
+class ToolTierLoader:
+    """Loads and manages tool tiers from configuration."""
+
+    def __init__(self, config_path: Optional[str] = None):
+        """
+        Initialize the tool tier loader.
+
+        Args:
+            config_path: Path to the tool_tiers.yaml file. If None, uses default location.
+        """
+        if config_path is None:
+            # Default to core/tool_tiers.yaml relative to this file
+            config_path = Path(__file__).parent / "tool_tiers.yaml"
+
+        self.config_path = Path(config_path)
+        self._tiers_config: Optional[Dict] = None
+
+    def _load_config(self) -> Dict:
+        """Load the tool tiers configuration from YAML file."""
+        if self._tiers_config is not None:
+            return self._tiers_config
+
+        if not self.config_path.exists():
+            raise FileNotFoundError(
+                f"Tool tiers configuration not found: {self.config_path}"
+            )
+
+        try:
+            with open(self.config_path, "r", encoding="utf-8") as f:
+                self._tiers_config = yaml.safe_load(f)
+            logger.info(f"Loaded tool tiers configuration from {self.config_path}")
+            return self._tiers_config
+        except yaml.YAMLError as e:
+            raise ValueError(f"Invalid YAML in tool tiers configuration: {e}")
+        except Exception as e:
+            raise RuntimeError(f"Failed to load tool tiers configuration: {e}")
+
+    def get_available_services(self) -> List[str]:
+        """Get list of all available services defined in the configuration."""
+        config = self._load_config()
+        return list(config.keys())
+
+    def get_tools_for_tier(
+        self, tier: TierLevel, services: Optional[List[str]] = None
+    ) -> List[str]:
+        """
+        Get all tools for a specific tier level.
+
+        Args:
+            tier: The tier level (core, extended, complete)
+            services: Optional list of services to filter by. If None, includes all services.
+
+        Returns:
+            List of tool names for the specified tier level
+        """
+        config = self._load_config()
+        tools = []
+
+        # If no services specified, use all available services
+        if services is None:
+            services = self.get_available_services()
+
+        for service in services:
+            if service not in config:
+                logger.warning(
+                    f"Service '{service}' not found in tool tiers configuration"
+                )
+                continue
+
+            service_config = config[service]
+            if tier not in service_config:
+                logger.debug(f"Tier '{tier}' not defined for service '{service}'")
+                continue
+
+            tier_tools = service_config[tier]
+            if tier_tools:  # Handle empty lists
+                tools.extend(tier_tools)
+
+        return tools
+
+    def get_tools_up_to_tier(
+        self, tier: TierLevel, services: Optional[List[str]] = None
+    ) -> List[str]:
+        """
+        Get all tools up to and including the specified tier level.
+
+        Args:
+            tier: The maximum tier level to include
+            services: Optional list of services to filter by. If None, includes all services.
+
+        Returns:
+            List of tool names up to the specified tier level
+        """
+        tier_order = ["core", "extended", "complete"]
+        max_tier_index = tier_order.index(tier)
+
+        tools = []
+        for i in range(max_tier_index + 1):
+            current_tier = tier_order[i]
+            tools.extend(self.get_tools_for_tier(current_tier, services))
+
+        # Remove duplicates while preserving order
+        seen = set()
+        unique_tools = []
+        for tool in tools:
+            if tool not in seen:
+                seen.add(tool)
+                unique_tools.append(tool)
+
+        return unique_tools
+
+    def get_services_for_tools(self, tool_names: List[str]) -> Set[str]:
+        """
+        Get the service names that provide the specified tools.
+
+        Args:
+            tool_names: List of tool names to lookup
+
+        Returns:
+            Set of service names that provide any of the specified tools
+        """
+        config = self._load_config()
+        services = set()
+
+        for service, service_config in config.items():
+            for tier_name, tier_tools in service_config.items():
+                if tier_tools and any(tool in tier_tools for tool in tool_names):
+                    services.add(service)
+                    break
+
+        return services
+
+
+def get_tools_for_tier(
+    tier: TierLevel, services: Optional[List[str]] = None
+) -> List[str]:
+    """
+    Convenience function to get tools for a specific tier.
+
+    Args:
+        tier: The tier level (core, extended, complete)
+        services: Optional list of services to filter by
+
+    Returns:
+        List of tool names for the specified tier level
+    """
+    loader = ToolTierLoader()
+    return loader.get_tools_up_to_tier(tier, services)
+
+
+def resolve_tools_from_tier(
+    tier: TierLevel, services: Optional[List[str]] = None
+) -> tuple[List[str], List[str]]:
+    """
+    Resolve tool names and service names for the specified tier.
+
+    Args:
+        tier: The tier level (core, extended, complete)
+        services: Optional list of services to filter by
+
+    Returns:
+        Tuple of (tool_names, service_names) where:
+        - tool_names: List of specific tool names for the tier
+        - service_names: List of service names that should be imported
+    """
+    loader = ToolTierLoader()
+
+    # Get all tools for the tier
+    tools = loader.get_tools_up_to_tier(tier, services)
+
+    # Map back to service names
+    service_names = loader.get_services_for_tools(tools)
+
+    logger.info(
+        f"Tier '{tier}' resolved to {len(tools)} tools across {len(service_names)} services: {sorted(service_names)}"
+    )
+
+    return tools, sorted(service_names)

core/tool_tiers.yaml

@@ -0,0 +1,166 @@
+gmail:
+  core:
+    - search_gmail_messages
+    - get_gmail_message_content
+    - get_gmail_messages_content_batch
+    - send_gmail_message
+
+  extended:
+    - get_gmail_attachment_content
+    - get_gmail_thread_content
+    - modify_gmail_message_labels
+    - list_gmail_labels
+    - manage_gmail_label
+    - draft_gmail_message
+
+  complete:
+    - get_gmail_threads_content_batch
+    - batch_modify_gmail_message_labels
+    - start_google_auth
+
+drive:
+  core:
+    - search_drive_files
+    - get_drive_file_content
+    - get_drive_file_download_url
+    - create_drive_file
+    - share_drive_file
+    - get_drive_shareable_link
+  extended:
+    - list_drive_items
+    - update_drive_file
+    - update_drive_permission
+    - remove_drive_permission
+    - transfer_drive_ownership
+    - batch_share_drive_file
+  complete:
+    - get_drive_file_permissions
+    - check_drive_file_public_access
+
+calendar:
+  core:
+    - list_calendars
+    - get_events
+    - create_event
+    - modify_event
+  extended:
+    - delete_event
+  complete: []
+
+docs:
+  core:
+    - get_doc_content
+    - create_doc
+    - modify_doc_text
+  extended:
+    - export_doc_to_pdf
+    - search_docs
+    - find_and_replace_doc
+    - list_docs_in_folder
+    - insert_doc_elements
+  complete:
+    - insert_doc_image
+    - update_doc_headers_footers
+    - batch_update_doc
+    - inspect_doc_structure
+    - create_table_with_data
+    - debug_table_structure
+    - read_document_comments
+    - create_document_comment
+    - reply_to_document_comment
+    - resolve_document_comment
+
+sheets:
+  core:
+    - create_spreadsheet
+    - read_sheet_values
+    - modify_sheet_values
+  extended:
+    - list_spreadsheets
+    - get_spreadsheet_info
+  complete:
+    - create_sheet
+    - read_spreadsheet_comments
+    - create_spreadsheet_comment
+    - reply_to_spreadsheet_comment
+    - resolve_spreadsheet_comment
+
+chat:
+  core:
+    - send_message
+    - get_messages
+    - search_messages
+  extended:
+    - list_spaces
+  complete: []
+
+forms:
+  core:
+    - create_form
+    - get_form
+  extended:
+    - list_form_responses
+  complete:
+    - set_publish_settings
+    - get_form_response
+
+slides:
+  core:
+    - create_presentation
+    - get_presentation
+  extended:
+    - batch_update_presentation
+    - get_page
+    - get_page_thumbnail
+  complete:
+    - read_presentation_comments
+    - create_presentation_comment
+    - reply_to_presentation_comment
+    - resolve_presentation_comment
+
+tasks:
+  core:
+    - get_task
+    - list_tasks
+    - create_task
+    - update_task
+  extended:
+    - delete_task
+  complete:
+    - list_task_lists
+    - get_task_list
+    - create_task_list
+    - update_task_list
+    - delete_task_list
+    - move_task
+    - clear_completed_tasks
+
+search:
+  core:
+    - search_custom
+  extended:
+    - search_custom_siterestrict
+  complete:
+    - get_search_engine_info
+
+appscript:
+  core:
+    - list_script_projects
+    - get_script_project
+    - get_script_content
+    - create_script_project
+    - update_script_content
+    - run_script_function
+    - generate_trigger_code
+  extended:
+    - create_deployment
+    - list_deployments
+    - update_deployment
+    - delete_deployment
+    - delete_script_project
+    - list_versions
+    - create_version
+    - get_version
+    - list_script_processes
+    - get_script_metrics
+  complete: []

core/utils.py

@@ -0,0 +1,341 @@
+import io
+import logging
+import os
+import zipfile
+import xml.etree.ElementTree as ET
+import ssl
+import asyncio
+import functools
+
+from typing import List, Optional
+
+from googleapiclient.errors import HttpError
+from .api_enablement import get_api_enablement_message
+from auth.google_auth import GoogleAuthenticationError
+
+logger = logging.getLogger(__name__)
+
+
+class TransientNetworkError(Exception):
+    """Custom exception for transient network errors after retries."""
+
+    pass
+
+
+class UserInputError(Exception):
+    """Raised for user-facing input/validation errors that shouldn't be retried."""
+
+    pass
+
+
+def check_credentials_directory_permissions(credentials_dir: str = None) -> None:
+    """
+    Check if the service has appropriate permissions to create and write to the .credentials directory.
+
+    Args:
+        credentials_dir: Path to the credentials directory (default: uses get_default_credentials_dir())
+
+    Raises:
+        PermissionError: If the service lacks necessary permissions
+        OSError: If there are other file system issues
+    """
+    if credentials_dir is None:
+        from auth.google_auth import get_default_credentials_dir
+
+        credentials_dir = get_default_credentials_dir()
+
+    try:
+        # Check if directory exists
+        if os.path.exists(credentials_dir):
+            # Directory exists, check if we can write to it
+            test_file = os.path.join(credentials_dir, ".permission_test")
+            try:
+                with open(test_file, "w") as f:
+                    f.write("test")
+                os.remove(test_file)
+                logger.info(
+                    f"Credentials directory permissions check passed: {os.path.abspath(credentials_dir)}"
+                )
+            except (PermissionError, OSError) as e:
+                raise PermissionError(
+                    f"Cannot write to existing credentials directory '{os.path.abspath(credentials_dir)}': {e}"
+                )
+        else:
+            # Directory doesn't exist, try to create it and its parent directories
+            try:
+                os.makedirs(credentials_dir, exist_ok=True)
+                # Test writing to the new directory
+                test_file = os.path.join(credentials_dir, ".permission_test")
+                with open(test_file, "w") as f:
+                    f.write("test")
+                os.remove(test_file)
+                logger.info(
+                    f"Created credentials directory with proper permissions: {os.path.abspath(credentials_dir)}"
+                )
+            except (PermissionError, OSError) as e:
+                # Clean up if we created the directory but can't write to it
+                try:
+                    if os.path.exists(credentials_dir):
+                        os.rmdir(credentials_dir)
+                except (PermissionError, OSError):
+                    pass
+                raise PermissionError(
+                    f"Cannot create or write to credentials directory '{os.path.abspath(credentials_dir)}': {e}"
+                )
+
+    except PermissionError:
+        raise
+    except Exception as e:
+        raise OSError(
+            f"Unexpected error checking credentials directory permissions: {e}"
+        )
+
+
+def extract_office_xml_text(file_bytes: bytes, mime_type: str) -> Optional[str]:
+    """
+    Very light-weight XML scraper for Word, Excel, PowerPoint files.
+    Returns plain-text if something readable is found, else None.
+    No external deps – just std-lib zipfile + ElementTree.
+    """
+    shared_strings: List[str] = []
+    ns_excel_main = "http://schemas.openxmlformats.org/spreadsheetml/2006/main"
+
+    try:
+        with zipfile.ZipFile(io.BytesIO(file_bytes)) as zf:
+            targets: List[str] = []
+            # Map MIME → iterable of XML files to inspect
+            if (
+                mime_type
+                == "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+            ):
+                targets = ["word/document.xml"]
+            elif (
+                mime_type
+                == "application/vnd.openxmlformats-officedocument.presentationml.presentation"
+            ):
+                targets = [n for n in zf.namelist() if n.startswith("ppt/slides/slide")]
+            elif (
+                mime_type
+                == "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+            ):
+                targets = [
+                    n
+                    for n in zf.namelist()
+                    if n.startswith("xl/worksheets/sheet") and "drawing" not in n
+                ]
+                # Attempt to parse sharedStrings.xml for Excel files
+                try:
+                    shared_strings_xml = zf.read("xl/sharedStrings.xml")
+                    shared_strings_root = ET.fromstring(shared_strings_xml)
+                    for si_element in shared_strings_root.findall(
+                        f"{{{ns_excel_main}}}si"
+                    ):
+                        text_parts = []
+                        # Find all <t> elements, simple or within <r> runs, and concatenate their text
+                        for t_element in si_element.findall(f".//{{{ns_excel_main}}}t"):
+                            if t_element.text:
+                                text_parts.append(t_element.text)
+                        shared_strings.append("".join(text_parts))
+                except KeyError:
+                    logger.info(
+                        "No sharedStrings.xml found in Excel file (this is optional)."
+                    )
+                except ET.ParseError as e:
+                    logger.error(f"Error parsing sharedStrings.xml: {e}")
+                except (
+                    Exception
+                ) as e:  # Catch any other unexpected error during sharedStrings parsing
+                    logger.error(
+                        f"Unexpected error processing sharedStrings.xml: {e}",
+                        exc_info=True,
+                    )
+            else:
+                return None
+
+            pieces: List[str] = []
+            for member in targets:
+                try:
+                    xml_content = zf.read(member)
+                    xml_root = ET.fromstring(xml_content)
+                    member_texts: List[str] = []
+
+                    if (
+                        mime_type
+                        == "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+                    ):
+                        for cell_element in xml_root.findall(
+                            f".//{{{ns_excel_main}}}c"
+                        ):  # Find all <c> elements
+                            value_element = cell_element.find(
+                                f"{{{ns_excel_main}}}v"
+                            )  # Find <v> under <c>
+
+                            # Skip if cell has no value element or value element has no text
+                            if value_element is None or value_element.text is None:
+                                continue
+
+                            cell_type = cell_element.get("t")
+                            if cell_type == "s":  # Shared string
+                                try:
+                                    ss_idx = int(value_element.text)
+                                    if 0 <= ss_idx < len(shared_strings):
+                                        member_texts.append(shared_strings[ss_idx])
+                                    else:
+                                        logger.warning(
+                                            f"Invalid shared string index {ss_idx} in {member}. Max index: {len(shared_strings) - 1}"
+                                        )
+                                except ValueError:
+                                    logger.warning(
+                                        f"Non-integer shared string index: '{value_element.text}' in {member}."
+                                    )
+                            else:  # Direct value (number, boolean, inline string if not 's')
+                                member_texts.append(value_element.text)
+                    else:  # Word or PowerPoint
+                        for elem in xml_root.iter():
+                            # For Word: <w:t> where w is "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
+                            # For PowerPoint: <a:t> where a is "http://schemas.openxmlformats.org/drawingml/2006/main"
+                            if (
+                                elem.tag.endswith("}t") and elem.text
+                            ):  # Check for any namespaced tag ending with 't'
+                                cleaned_text = elem.text.strip()
+                                if (
+                                    cleaned_text
+                                ):  # Add only if there's non-whitespace text
+                                    member_texts.append(cleaned_text)
+
+                    if member_texts:
+                        pieces.append(
+                            " ".join(member_texts)
+                        )  # Join texts from one member with spaces
+
+                except ET.ParseError as e:
+                    logger.warning(
+                        f"Could not parse XML in member '{member}' for {mime_type} file: {e}"
+                    )
+                except Exception as e:
+                    logger.error(
+                        f"Error processing member '{member}' for {mime_type}: {e}",
+                        exc_info=True,
+                    )
+                    # continue processing other members
+
+            if not pieces:  # If no text was extracted at all
+                return None
+
+            # Join content from different members (sheets/slides) with double newlines for separation
+            text = "\n\n".join(pieces).strip()
+            return text or None  # Ensure None is returned if text is empty after strip
+
+    except zipfile.BadZipFile:
+        logger.warning(f"File is not a valid ZIP archive (mime_type: {mime_type}).")
+        return None
+    except (
+        ET.ParseError
+    ) as e:  # Catch parsing errors at the top level if zipfile itself is XML-like
+        logger.error(f"XML parsing error at a high level for {mime_type}: {e}")
+        return None
+    except Exception as e:
+        logger.error(
+            f"Failed to extract office XML text for {mime_type}: {e}", exc_info=True
+        )
+        return None
+
+
+def handle_http_errors(
+    tool_name: str, is_read_only: bool = False, service_type: Optional[str] = None
+):
+    """
+    A decorator to handle Google API HttpErrors and transient SSL errors in a standardized way.
+
+    It wraps a tool function, catches HttpError, logs a detailed error message,
+    and raises a generic Exception with a user-friendly message.
+
+    If is_read_only is True, it will also catch ssl.SSLError and retry with
+    exponential backoff. After exhausting retries, it raises a TransientNetworkError.
+
+    Args:
+        tool_name (str): The name of the tool being decorated (e.g., 'list_calendars').
+        is_read_only (bool): If True, the operation is considered safe to retry on
+                             transient network errors. Defaults to False.
+        service_type (str): Optional. The Google service type (e.g., 'calendar', 'gmail').
+    """
+
+    def decorator(func):
+        @functools.wraps(func)
+        async def wrapper(*args, **kwargs):
+            max_retries = 3
+            base_delay = 1
+
+            for attempt in range(max_retries):
+                try:
+                    return await func(*args, **kwargs)
+                except ssl.SSLError as e:
+                    if is_read_only and attempt < max_retries - 1:
+                        delay = base_delay * (2**attempt)
+                        logger.warning(
+                            f"SSL error in {tool_name} on attempt {attempt + 1}: {e}. Retrying in {delay} seconds..."
+                        )
+                        await asyncio.sleep(delay)
+                    else:
+                        logger.error(
+                            f"SSL error in {tool_name} on final attempt: {e}. Raising exception."
+                        )
+                        raise TransientNetworkError(
+                            f"A transient SSL error occurred in '{tool_name}' after {max_retries} attempts. "
+                            "This is likely a temporary network or certificate issue. Please try again shortly."
+                        ) from e
+                except UserInputError as e:
+                    message = f"Input error in {tool_name}: {e}"
+                    logger.warning(message)
+                    raise e
+                except HttpError as error:
+                    user_google_email = kwargs.get("user_google_email", "N/A")
+                    error_details = str(error)
+
+                    # Check if this is an API not enabled error
+                    if (
+                        error.resp.status == 403
+                        and ("accessNotConfigured" in error_details or "SERVICE_DISABLED" in error_details)
+                    ):
+                        enablement_msg = get_api_enablement_message(
+                            error_details, service_type
+                        )
+
+                        if enablement_msg:
+                            message = (
+                                f"API error in {tool_name}: {enablement_msg}\n\n"
+                                f"User: {user_google_email}"
+                            )
+                        else:
+                            message = (
+                                f"API error in {tool_name}: {error}. "
+                                f"The required API is not enabled for your project. "
+                                f"Please check the Google Cloud Console to enable it."
+                            )
+                    elif error.resp.status in [401, 403]:
+                        # Authentication/authorization errors
+                        message = (
+                            f"API error in {tool_name}: {error}. "
+                            f"You might need to re-authenticate for user '{user_google_email}'. "
+                            f"LLM: Try 'start_google_auth' with the user's email and the appropriate service_name."
+                        )
+                    else:
+                        # Other HTTP errors (400 Bad Request, etc.) - don't suggest re-auth
+                        message = f"API error in {tool_name}: {error}"
+
+                    logger.error(f"API error in {tool_name}: {error}", exc_info=True)
+                    raise Exception(message) from error
+                except TransientNetworkError:
+                    # Re-raise without wrapping to preserve the specific error type
+                    raise
+                except GoogleAuthenticationError:
+                    # Re-raise authentication errors without wrapping
+                    raise
+                except Exception as e:
+                    message = f"An unexpected error occurred in {tool_name}: {e}"
+                    logger.exception(message)
+                    raise Exception(message) from e
+
+        return wrapper
+
+    return decorator

docker-compose.yml

@@ -0,0 +1,16 @@
+services:
+  gws_mcp:
+    build: .
+    container_name: gws_mcp
+    ports:
+      - "8000:8000"
+    environment:
+      - GOOGLE_MCP_CREDENTIALS_DIR=/app/store_creds
+    volumes:
+      - ./client_secret.json:/app/client_secret.json:ro
+      - store_creds:/app/store_creds:rw
+    env_file:
+      - .env
+
+volumes:
+  store_creds:

fastmcp.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+  "source": {
+    "path": "fastmcp_server.py",
+    "entrypoint": "mcp"
+  },
+  "environment": {
+    "python": ">=3.10",
+    "project": "."
+  },
+  "deployment": {
+    "transport": "http",
+    "host": "0.0.0.0",
+    "port": 8000,
+    "log_level": "INFO",
+    "env": {
+      "MCP_ENABLE_OAUTH21": "true",
+      "OAUTHLIB_INSECURE_TRANSPORT": "1"
+    }
+  }
+}

fastmcp_server.py

@@ -0,0 +1,175 @@
+# ruff: noqa
+"""
+FastMCP Cloud entrypoint for the Google Workspace MCP server.
+Enforces OAuth 2.1 + stateless defaults required by FastMCP-hosted deployments.
+"""
+
+import logging
+import os
+import sys
+from dotenv import load_dotenv
+
+# Load environment variables BEFORE any other imports that might read them
+dotenv_path = os.path.join(os.path.dirname(os.path.abspath(__file__)), ".env")
+load_dotenv(dotenv_path=dotenv_path)
+
+from auth.oauth_config import reload_oauth_config, is_stateless_mode
+from core.log_formatter import EnhancedLogFormatter, configure_file_logging
+from core.utils import check_credentials_directory_permissions
+from core.server import server, set_transport_mode, configure_server_for_http
+from core.tool_registry import (
+    set_enabled_tools as set_enabled_tool_names,
+    wrap_server_tool_method,
+    filter_server_tools,
+)
+from auth.scopes import set_enabled_tools
+
+
+def enforce_fastmcp_cloud_defaults():
+    """Force FastMCP Cloud-compatible OAuth settings before initializing the server."""
+    enforced = []
+
+    required = {
+        "MCP_ENABLE_OAUTH21": "true",
+        "WORKSPACE_MCP_STATELESS_MODE": "true",
+    }
+    defaults = {
+        "MCP_SINGLE_USER_MODE": "false",
+    }
+
+    for key, target in required.items():
+        current = os.environ.get(key)
+        normalized = (current or "").lower()
+        if normalized != target:
+            os.environ[key] = target
+            enforced.append((key, current, target))
+
+    for key, target in defaults.items():
+        current = os.environ.get(key)
+        if current != target:
+            os.environ[key] = target
+            enforced.append((key, current, target))
+
+    return enforced
+
+
+_fastmcp_cloud_overrides = enforce_fastmcp_cloud_defaults()
+
+# Suppress googleapiclient discovery cache warning
+logging.getLogger("googleapiclient.discovery_cache").setLevel(logging.ERROR)
+
+# Reload OAuth configuration after env vars loaded
+reload_oauth_config()
+
+# Configure basic logging
+logging.basicConfig(
+    level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+)
+logger = logging.getLogger(__name__)
+
+if _fastmcp_cloud_overrides:
+    for key, previous, new_value in _fastmcp_cloud_overrides:
+        if previous is None:
+            logger.info("FastMCP Cloud: set %s=%s", key, new_value)
+        else:
+            logger.warning(
+                "FastMCP Cloud: overriding %s from %s to %s", key, previous, new_value
+            )
+else:
+    logger.info("FastMCP Cloud: OAuth 2.1 stateless defaults already satisfied")
+
+# Configure file logging based on stateless mode
+configure_file_logging()
+
+
+def configure_safe_logging():
+    """Configure safe Unicode handling for logging."""
+
+    class SafeEnhancedFormatter(EnhancedLogFormatter):
+        """Enhanced ASCII formatter with additional Windows safety."""
+
+        def format(self, record):
+            try:
+                return super().format(record)
+            except UnicodeEncodeError:
+                # Fallback to ASCII-safe formatting
+                service_prefix = self._get_ascii_prefix(record.name, record.levelname)
+                safe_msg = (
+                    str(record.getMessage())
+                    .encode("ascii", errors="replace")
+                    .decode("ascii")
+                )
+                return f"{service_prefix} {safe_msg}"
+
+    # Replace all console handlers' formatters with safe enhanced ones
+    for handler in logging.root.handlers:
+        # Only apply to console/stream handlers, keep file handlers as-is
+        if isinstance(handler, logging.StreamHandler) and handler.stream.name in [
+            "<stderr>",
+            "<stdout>",
+        ]:
+            safe_formatter = SafeEnhancedFormatter(use_colors=True)
+            handler.setFormatter(safe_formatter)
+
+
+# Configure safe logging
+configure_safe_logging()
+
+# Check credentials directory permissions (skip in stateless mode)
+if not is_stateless_mode():
+    try:
+        logger.info("Checking credentials directory permissions...")
+        check_credentials_directory_permissions()
+        logger.info("Credentials directory permissions verified")
+    except (PermissionError, OSError) as e:
+        logger.error(f"Credentials directory permission check failed: {e}")
+        logger.error(
+            "   Please ensure the service has write permissions to create/access the credentials directory"
+        )
+        sys.exit(1)
+else:
+    logger.info("🔍 Skipping credentials directory check (stateless mode)")
+
+# Set transport mode for HTTP (FastMCP CLI defaults to streamable-http)
+set_transport_mode("streamable-http")
+
+# Import all tool modules to register their @server.tool() decorators
+import gmail.gmail_tools
+import gdrive.drive_tools
+import gcalendar.calendar_tools
+import gdocs.docs_tools
+import gsheets.sheets_tools
+import gchat.chat_tools
+import gforms.forms_tools
+import gslides.slides_tools
+import gtasks.tasks_tools
+import gsearch.search_tools
+
+# Configure tool registration
+wrap_server_tool_method(server)
+
+# Enable all tools and services by default
+all_services = [
+    "gmail",
+    "drive",
+    "calendar",
+    "docs",
+    "sheets",
+    "chat",
+    "forms",
+    "slides",
+    "tasks",
+    "search",
+]
+set_enabled_tools(all_services)  # Set enabled services for scopes
+set_enabled_tool_names(None)  # Don't filter individual tools - enable all
+
+# Filter tools based on configuration
+filter_server_tools(server)
+
+# Configure authentication after scopes are known
+configure_server_for_http()
+
+# Export server instance for FastMCP CLI (looks for 'mcp', 'server', or 'app')
+mcp = server
+app = server

gappsscript/README.md

@@ -0,0 +1,514 @@
+# Google Apps Script MCP Tools
+
+This module provides Model Context Protocol (MCP) tools for interacting with Google Apps Script API, enabling AI agents to create, manage, and execute Apps Script projects programmatically.
+
+## Overview
+
+Google Apps Script allows automation and extension of Google Workspace applications. This MCP integration provides 17 tools across core and extended tiers for complete Apps Script lifecycle management.
+
+## Why Apps Script?
+
+Apps Script is the automation glue of Google Workspace. While individual service APIs (Docs, Sheets, Gmail) operate on single resources, Apps Script enables:
+
+- **Cross-app automation** - Orchestrate workflows across Sheets, Gmail, Calendar, Forms, and Drive
+- **Persistent logic** - Host custom business rules inside Google's environment
+- **Scheduled execution** - Run automations on time-based or event-driven triggers
+- **Advanced integration** - Access functionality not available through standard APIs
+
+This MCP integration allows AI agents to author, debug, deploy, and operate these automations end-to-end - something not possible with individual Workspace APIs alone.
+
+### What This Enables
+
+| Without Apps Script MCP | With Apps Script MCP |
+|------------------------|---------------------|
+| Read/update Sheets, Docs, Gmail individually | Create long-lived automations across services |
+| No persistent automation logic | Host business logic that executes repeatedly |
+| Manual workflow orchestration | Automated multi-step workflows |
+| No execution history | Debug via execution logs and status |
+| No deployment versioning | Manage deployments and roll back versions |
+
+### Complete Workflow Example
+
+**Scenario:** Automated weekly report system
+
+```
+User: "Create a script that runs every Monday at 9 AM. It should:
+1. Read data from the 'Sales' spreadsheet
+2. Calculate weekly totals and growth percentages
+3. Generate a summary with the top 5 performers
+4. Email the report to team@company.com
+5. Log any errors to a monitoring sheet"
+```
+
+The AI agent:
+1. Creates a new Apps Script project
+2. Generates the complete automation code
+3. Deploys the script
+4. Sets up the time-based trigger
+5. Tests execution and monitors results
+
+All through natural language - no JavaScript knowledge required.
+
+### AI Agent Workflow Pattern
+
+The MCP client typically follows this pattern when working with Apps Script:
+
+1. **Inspect** - Read existing script code and project structure
+2. **Analyze** - Understand current functionality and identify issues
+3. **Propose** - Generate code changes or new functionality
+4. **Update** - Modify files atomically with complete version control
+5. **Execute** - Run functions to test changes
+6. **Deploy** - Create versioned deployments for production use
+7. **Monitor** - Check execution logs and debug failures
+
+This ensures safe, auditable automation management.
+
+## Features
+
+### Project Management
+- List all Apps Script projects
+- Get complete project details including all files
+- Create new standalone or bound script projects
+- Update script content (add/modify JavaScript files)
+- Delete script projects
+
+### Execution
+- Execute functions with parameters
+- Development mode for testing latest code
+- Production deployment execution
+- View execution history and status
+
+### Deployment Management
+- Create new deployments
+- List all deployments for a project
+- Update deployment configurations
+- Delete outdated deployments
+
+### Version Management
+- List all versions of a script
+- Create immutable version snapshots
+- Get details of specific versions
+
+### Monitoring & Analytics
+- View recent script executions
+- Check execution status and results
+- Monitor for errors and failures
+- Get execution metrics (active users, total executions, failures)
+
+### Trigger Code Generation
+- Generate Apps Script code for time-based triggers (minutes, hours, daily, weekly)
+- Generate code for event triggers (onOpen, onEdit, onFormSubmit, onChange)
+- Provides ready-to-use code snippets with setup instructions
+
+## Limitations & Non-Goals
+
+**Current Limitations**
+- Direct trigger management via API is not supported (use `generate_trigger_code` instead)
+- Real-time debugging and breakpoints are not available
+- Advanced service enablement must be done manually in the script editor
+
+**Non-Goals**
+- This integration does not replace the Apps Script editor UI
+- Does not execute arbitrary JavaScript outside defined script functions
+- Does not provide IDE features like autocomplete or syntax highlighting
+
+**Workarounds**
+- Triggers: Use `generate_trigger_code` to get ready-to-use Apps Script code for any trigger type
+- Advanced services can be enabled via the manifest file (appsscript.json)
+- Debugging is supported through execution logs, metrics, and error monitoring
+
+## Prerequisites
+
+### 1. Google Cloud Project Setup
+
+Before using the Apps Script MCP tools, configure your Google Cloud project:
+
+**Step 1: Enable Required APIs**
+
+Enable these APIs in your Google Cloud Console:
+
+1. [Apps Script API](https://console.cloud.google.com/flows/enableapi?apiid=script.googleapis.com) (required for all operations)
+2. [Google Drive API](https://console.cloud.google.com/flows/enableapi?apiid=drive.googleapis.com) (required for listing projects)
+
+**Step 2: Create OAuth Credentials**
+
+1. Go to [APIs & Services > Credentials](https://console.cloud.google.com/apis/credentials)
+2. Click "Create Credentials" > "OAuth client ID"
+3. Select "Desktop application" as the application type
+4. Download the JSON file and save as `client_secret.json`
+
+**Step 3: Configure OAuth Consent Screen**
+
+1. Go to [OAuth consent screen](https://console.cloud.google.com/apis/credentials/consent)
+2. Add yourself as a test user (required for unverified apps)
+3. Add the required scopes (see below)
+
+### 2. OAuth Scopes
+
+The following OAuth scopes are required:
+
+```
+https://www.googleapis.com/auth/script.projects
+https://www.googleapis.com/auth/script.projects.readonly
+https://www.googleapis.com/auth/script.deployments
+https://www.googleapis.com/auth/script.deployments.readonly
+https://www.googleapis.com/auth/script.processes
+https://www.googleapis.com/auth/script.metrics
+https://www.googleapis.com/auth/drive.file
+```
+
+These are automatically requested when using the appscript tool tier.
+
+### 3. Running the MCP Server
+
+Start the server with Apps Script tools enabled:
+
+```bash
+uv run main.py --tools appscript --single-user
+```
+
+Or include with other tools:
+
+```bash
+uv run main.py --tools appscript drive sheets
+```
+
+On first use, you will be prompted to authorize the application. Complete the OAuth flow in your browser.
+
+## Tool Tiers
+
+### Core Tier
+Essential operations for reading, writing, and executing scripts:
+
+- `list_script_projects`: List accessible projects
+- `get_script_project`: Get full project with all files
+- `get_script_content`: Get specific file content
+- `create_script_project`: Create new project
+- `update_script_content`: Modify project files
+- `run_script_function`: Execute functions
+- `generate_trigger_code`: Generate trigger setup code
+
+### Extended Tier
+Advanced deployment, versioning, and monitoring:
+
+- `create_deployment`: Create new deployment
+- `list_deployments`: List all deployments
+- `update_deployment`: Update deployment config
+- `delete_deployment`: Remove deployment
+- `delete_script_project`: Delete a project permanently
+- `list_versions`: List all versions
+- `create_version`: Create immutable version snapshot
+- `get_version`: Get version details
+- `list_script_processes`: View execution history
+- `get_script_metrics`: Get execution analytics
+
+## Usage Examples
+
+### List Projects
+
+```python
+# List all Apps Script projects
+uv run main.py --tools appscript
+# In MCP client: "Show me my Apps Script projects"
+```
+
+Example output:
+```
+Found 3 Apps Script projects:
+- Email Automation (ID: abc123) Created: 2025-01-10 Modified: 2026-01-12
+- Sheet Processor (ID: def456) Created: 2025-06-15 Modified: 2025-12-20
+- Form Handler (ID: ghi789) Created: 2024-11-03 Modified: 2025-08-14
+```
+
+### Create New Project
+
+```python
+# Create a new Apps Script project
+# In MCP client: "Create a new Apps Script project called 'Data Sync'"
+```
+
+Example output:
+```
+Created Apps Script project: Data Sync
+Script ID: new123
+Edit URL: https://script.google.com/d/new123/edit
+```
+
+### Get Project Details
+
+```python
+# Get complete project with all files
+# In MCP client: "Show me the code for script abc123"
+```
+
+Example output:
+```
+Project: Email Automation (ID: abc123)
+Creator: user@example.com
+Created: 2025-01-10
+Modified: 2026-01-12
+
+Files:
+1. Code.gs (SERVER_JS)
+   function sendDailyEmail() {
+     var sheet = SpreadsheetApp.getActiveSpreadsheet();
+     // ... email logic
+   }
+
+2. appsscript.json (JSON)
+   {"timeZone": "America/New_York", "dependencies": {}}
+```
+
+### Update Script Content
+
+```python
+# Update script files
+# In MCP client: "Update my email script to add error handling"
+```
+
+The AI will:
+1. Read current code
+2. Generate improved version
+3. Call `update_script_content` with new files
+
+### Run Script Function
+
+```python
+# Execute a function
+# In MCP client: "Run the sendDailyEmail function in script abc123"
+```
+
+Example output:
+```
+Execution successful
+Function: sendDailyEmail
+Result: Emails sent to 5 recipients
+```
+
+### Create Deployment
+
+```python
+# Deploy script for production
+# In MCP client: "Deploy my email automation to production"
+```
+
+Example output:
+```
+Created deployment for script: abc123
+Deployment ID: AKfy...xyz
+Description: Production release
+```
+
+## Common Workflows
+
+### 1. Create Automated Workflow (Complete Example)
+
+**Scenario:** Form submission handler that sends customized emails
+
+```
+User: "When someone submits the Contact Form:
+1. Get their email and department from the form response
+2. Look up their manager in the Team Directory spreadsheet
+3. Send a welcome email to the submitter
+4. Send a notification to their manager
+5. Log the interaction in the Onboarding Tracker sheet"
+```
+
+**AI Agent Steps:**
+```
+1. "Create a new Apps Script bound to the Contact Form"
+2. "Add a function that reads form submissions"
+3. "Connect to the Team Directory spreadsheet to look up managers"
+4. "Generate personalized email templates for both messages"
+5. "Add logging to the Onboarding Tracker"
+6. "Run the function to test it with sample data"
+7. "Create a production deployment"
+```
+
+Result: Complete automation created and deployed without writing code.
+
+### 2. Debug Existing Script
+
+```
+User: "My expense tracker script is failing"
+AI: "Show me the code for the expense tracker script"
+AI: "What errors occurred in recent executions?"
+AI: "The calculateTotal function has a division by zero error on line 23"
+AI: "Fix the error by adding a check for zero values"
+AI: "Run calculateTotal to verify the fix"
+User: "Create a new deployment with the bug fix"
+```
+
+### 3. Modify and Extend Automation
+
+```
+User: "Update my weekly report script to include sales data from the Q1 sheet"
+AI: "Read the current report generation script"
+AI: "Add Q1 data fetching to the generateReport function"
+AI: "Test the updated function"
+User: "Looks good, deploy it"
+AI: "Create a new deployment with description 'Added Q1 sales data'"
+```
+
+### 4. Run Existing Business Logic
+
+```
+User: "Run the monthlyCleanup function in my Data Management script"
+User: "What does the calculateCommission function do?"
+User: "Execute reconcileAccounts with parameters: ['2024', 'January']"
+```
+
+## File Types
+
+Apps Script projects support three file types:
+
+- **SERVER_JS**: Google Apps Script code (.gs files)
+- **HTML**: HTML files for custom UIs
+- **JSON**: Manifest file (appsscript.json)
+
+## API Limitations
+
+### Execution Timeouts
+- Simple triggers: 30 seconds
+- Custom functions: 30 seconds
+- Script execution via API: 6 minutes
+
+### Quota Limits
+- Script executions per day: varies by account type
+- URL Fetch calls: 20,000 per day (consumer accounts)
+
+See [Apps Script Quotas](https://developers.google.com/apps-script/guides/services/quotas) for details.
+
+### Cannot Execute Arbitrary Code
+The `run_script_function` tool can only execute functions that are defined in the script. You cannot run arbitrary JavaScript code directly. To run new code:
+
+1. Add function to script via `update_script_content`
+2. Execute the function via `run_script_function`
+3. Optionally remove the function after execution
+
+### run_script_function Requires API Executable Deployment
+
+The `run_script_function` tool requires additional manual configuration in the Apps Script editor:
+
+**Why this limitation exists:**
+Google requires scripts to be explicitly deployed as "API Executable" before they can be invoked via the Apps Script API. This is a security measure to prevent unauthorized code execution.
+
+**To enable API execution:**
+
+1. Open the script in the Apps Script editor
+2. Go to Project Settings (gear icon)
+3. Under "Google Cloud Platform (GCP) Project", click "Change project"
+4. Enter your GCP project number (found in Cloud Console dashboard)
+5. Click "Deploy" > "New deployment"
+6. Select type: "API Executable"
+7. Set "Who has access" to "Anyone" or "Anyone with Google account"
+8. Click "Deploy"
+
+After completing these steps, the `run_script_function` tool will work for that script.
+
+**Note:** All other tools (create, update, list, deploy) work without this manual step. Only function execution via API requires the API Executable deployment.
+
+## Error Handling
+
+Common errors and solutions:
+
+### 404: Script not found
+- Verify script ID is correct
+- Ensure you have access to the project
+
+### 403: Permission denied
+- Check OAuth scopes are authorized
+- Verify you own or have access to the project
+
+### Execution timeout
+- Script exceeded 6-minute limit
+- Optimize code or split into smaller functions
+
+### Script authorization required
+- Function needs additional permissions
+- User must manually authorize in script editor
+
+## Security Considerations
+
+### OAuth Scopes
+Scripts inherit the OAuth scopes of the MCP server. Functions that access other Google services (Gmail, Drive, etc.) will only work if those scopes are authorized.
+
+### Script Permissions
+Scripts run with the permissions of the script owner, not the user executing them. Be cautious when:
+- Running scripts you did not create
+- Granting additional permissions to scripts
+- Executing functions that modify data
+
+### Code Review
+Always review code before executing, especially for:
+- Scripts from unknown sources
+- Functions that access sensitive data
+- Operations that modify or delete data
+
+## Testing
+
+### Unit Tests
+Run unit tests with mocked API responses:
+
+```bash
+uv run pytest tests/gappsscript/test_apps_script_tools.py
+```
+
+### Manual Testing
+Test against real Apps Script API:
+
+```bash
+python tests/gappsscript/manual_test.py
+```
+
+Note: Manual tests create real projects in your account. Delete test projects after running.
+
+## References
+
+### Apps Script Documentation
+- [Apps Script Overview](https://developers.google.com/apps-script/overview) - Introduction and capabilities
+- [Apps Script Guides](https://developers.google.com/apps-script/guides/services) - Service-specific guides
+- [Apps Script Reference](https://developers.google.com/apps-script/reference) - Complete API reference
+
+### Apps Script API (for this MCP integration)
+- [Apps Script API Overview](https://developers.google.com/apps-script/api) - API features and concepts
+- [REST API Reference](https://developers.google.com/apps-script/api/reference/rest) - Endpoint documentation
+- [OAuth Scopes](https://developers.google.com/apps-script/api/how-tos/authorization) - Required permissions
+
+### Useful Resources
+- [Apps Script Quotas](https://developers.google.com/apps-script/guides/services/quotas) - Usage limits and restrictions
+- [Best Practices](https://developers.google.com/apps-script/guides/support/best-practices) - Performance and optimization
+- [Troubleshooting](https://developers.google.com/apps-script/guides/support/troubleshooting) - Common issues and solutions
+
+## Troubleshooting
+
+### "Apps Script API has not been used in project"
+Enable the API in Google Cloud Console
+
+### "Insufficient Permission"
+- Verify OAuth scopes are authorized
+- Re-authenticate if needed
+
+### "Function not found"
+- Check function name spelling
+- Verify function exists in the script
+- Ensure function is not private
+
+### "Invalid project structure"
+- Ensure at least one .gs file exists
+- Verify JSON files are valid JSON
+- Check file names don't contain invalid characters
+
+## Contributing
+
+When adding new Apps Script tools:
+
+1. Follow existing patterns in `apps_script_tools.py`
+2. Add comprehensive docstrings
+3. Include unit tests
+4. Update this README with examples
+5. Test against real API before submitting
+
+## License
+
+MIT License - see project root LICENSE file

gappsscript/TESTING.md

@@ -0,0 +1,254 @@
+# Apps Script MCP Testing Guide
+
+This document provides instructions for running unit tests and end-to-end (E2E) tests for the Apps Script MCP feature.
+
+## Test Structure
+
+```
+tests/gappsscript/
+    __init__.py
+    test_apps_script_tools.py   # Unit tests with mocked API
+    manual_test.py              # E2E tests against real API
+```
+
+## Unit Tests
+
+Unit tests use mocked API responses and do not require Google credentials.
+
+### Running Unit Tests
+
+```bash
+# Run all Apps Script unit tests
+uv run pytest tests/gappsscript/test_apps_script_tools.py -v
+
+# Run specific test
+uv run pytest tests/gappsscript/test_apps_script_tools.py::test_list_script_projects -v
+
+# Run with coverage
+uv run pytest tests/gappsscript/test_apps_script_tools.py --cov=gappsscript
+```
+
+### Test Coverage
+
+Unit tests cover:
+- list_script_projects (uses Drive API)
+- get_script_project
+- get_script_content
+- create_script_project
+- update_script_content
+- run_script_function
+- create_deployment
+- list_deployments
+- update_deployment
+- delete_deployment
+- list_script_processes
+
+## E2E Tests
+
+E2E tests interact with the real Google Apps Script API. They require valid OAuth credentials and will create real resources in your Google account.
+
+### Prerequisites
+
+1. **Google Cloud Project** with Apps Script API and Drive API enabled
+2. **OAuth credentials** (Desktop application type)
+3. **Test user** added to OAuth consent screen
+
+### Setup
+
+**Option 1: Default paths (recommended for CI)**
+
+Place credentials in the project root:
+```bash
+# Place your OAuth client credentials here
+cp /path/to/your/client_secret.json ./client_secret.json
+```
+
+**Option 2: Custom paths via environment variables**
+
+```bash
+export GOOGLE_CLIENT_SECRET_PATH=/path/to/client_secret.json
+export GOOGLE_TOKEN_PATH=/path/to/token.pickle
+```
+
+### Running E2E Tests
+
+```bash
+# Interactive mode (prompts for confirmation)
+uv run python tests/gappsscript/manual_test.py
+
+# Non-interactive mode (for CI)
+uv run python tests/gappsscript/manual_test.py --yes
+```
+
+### E2E Test Flow
+
+The test script performs the following operations:
+
+1. **List Projects** - Lists existing Apps Script projects via Drive API
+2. **Create Project** - Creates a new test project
+3. **Get Project** - Retrieves project details
+4. **Update Content** - Adds code to the project
+5. **Run Function** - Attempts to execute a function (see note below)
+6. **Create Deployment** - Creates a versioned deployment
+7. **List Deployments** - Lists all deployments
+8. **List Processes** - Lists recent script executions
+
+### Cleanup
+
+The test script does not automatically delete created projects. After running tests:
+
+1. Go to [Google Apps Script](https://script.google.com/)
+2. Find projects named "MCP Test Project"
+3. Delete them manually via the menu (three dots) > Remove
+
+## Headless Linux Testing
+
+For headless environments (servers, CI/CD, WSL without GUI):
+
+### OAuth Authentication Flow
+
+The test script uses a headless-compatible OAuth flow:
+
+1. Script prints an authorization URL
+2. Open the URL in any browser (can be on a different machine)
+3. Complete Google sign-in and authorization
+4. Browser redirects to `http://localhost/?code=...` (page will not load)
+5. Copy the full URL from the browser address bar
+6. Paste it into the terminal when prompted
+
+### Example Session
+
+```
+$ python tests/gappsscript/manual_test.py --yes
+
+============================================================
+HEADLESS AUTH
+============================================================
+
+1. Open this URL in any browser:
+
+https://accounts.google.com/o/oauth2/auth?response_type=code&client_id=...
+
+2. Sign in and authorize the app
+3. You'll be redirected to http://localhost (won't load)
+4. Copy the FULL URL from browser address bar
+   (looks like: http://localhost/?code=4/0A...&scope=...)
+5. Paste it below:
+
+Paste full redirect URL: http://localhost/?code=4/0AQSTgQ...&scope=...
+
+Building API services...
+
+=== Test: List Projects ===
+Found 3 Apps Script projects:
+...
+```
+
+### Credential Storage
+
+OAuth tokens are stored as pickle files:
+- Default: `./test_token.pickle` in project root
+- Custom: Set via `GOOGLE_TOKEN_PATH` environment variable
+
+Tokens are reused on subsequent runs until they expire or are revoked.
+
+## Known Limitations and Caveats
+
+### run_script_function Test Failure
+
+The "Run Function" test will fail with a 404 error unless you manually configure the script as an API Executable. This is a Google platform requirement, not a bug.
+
+To make run_script_function work:
+
+1. Open the created test script in Apps Script editor
+2. Go to Project Settings > Change GCP project
+3. Enter your GCP project number
+4. Deploy as "API Executable"
+
+For E2E testing purposes, it is acceptable for this test to fail. All other tests should pass.
+
+### Drive API Requirement
+
+The `list_script_projects` function uses the Google Drive API (not the Apps Script API) because the Apps Script API does not provide a projects.list endpoint. Ensure the Drive API is enabled in your GCP project.
+
+### Scope Requirements
+
+The E2E tests require these scopes:
+- `script.projects` and `script.projects.readonly`
+- `script.deployments` and `script.deployments.readonly`
+- `script.processes`
+- `drive.readonly`
+
+If you encounter "insufficient scopes" errors, delete the stored token file and re-authenticate.
+
+### Rate Limits
+
+Google enforces rate limits on the Apps Script API. If running tests repeatedly, you may encounter quota errors. Wait a few minutes before retrying.
+
+## CI/CD Integration
+
+For automated testing in CI/CD pipelines:
+
+### Unit Tests Only (Recommended)
+
+```yaml
+# GitHub Actions example
+- name: Run unit tests
+  run: uv run pytest tests/gappsscript/test_apps_script_tools.py -v
+```
+
+### E2E Tests in CI
+
+E2E tests require OAuth credentials. Options:
+
+1. **Skip E2E in CI** - Run only unit tests in CI, run E2E locally
+2. **Service Account** - Not supported (Apps Script API requires user OAuth)
+3. **Pre-authenticated Token** - Store encrypted token in CI secrets
+
+To use a pre-authenticated token:
+```bash
+# Generate token locally
+python tests/gappsscript/manual_test.py
+
+# Store test_token.pickle contents as base64 in CI secret
+base64 test_token.pickle > token.b64
+
+# In CI, restore and set path
+echo $TOKEN_SECRET | base64 -d > test_token.pickle
+export GOOGLE_TOKEN_PATH=./test_token.pickle
+python tests/gappsscript/manual_test.py --yes
+```
+
+Note: Tokens expire and must be refreshed periodically.
+
+## Troubleshooting
+
+### "Apps Script API has not been used in project"
+
+Enable the Apps Script API in your GCP project:
+https://console.cloud.google.com/flows/enableapi?apiid=script.googleapis.com
+
+### "Access Not Configured. Drive API has not been used"
+
+Enable the Drive API in your GCP project:
+https://console.cloud.google.com/flows/enableapi?apiid=drive.googleapis.com
+
+### "Request had insufficient authentication scopes"
+
+Delete the token file and re-authenticate:
+```bash
+rm test_token.pickle
+python tests/gappsscript/manual_test.py
+```
+
+### "User is not authorized to access this resource"
+
+Ensure your email is added as a test user in the OAuth consent screen configuration.
+
+### "Requested entity was not found" (404 on run)
+
+The script needs to be deployed as "API Executable". See the run_script_function section above.
+
+### OAuth redirect fails on headless machine
+
+The redirect to `http://localhost` is expected to fail. Copy the URL from the browser address bar (including the error page URL) and paste it into the terminal.

gappsscript/apps_script_tools.py

@@ -0,0 +1,1309 @@
+"""
+Google Apps Script MCP Tools
+
+This module provides MCP tools for interacting with Google Apps Script API.
+"""
+
+import logging
+import asyncio
+from typing import List, Dict, Any, Optional
+
+from auth.service_decorator import require_google_service
+from core.server import server
+from core.utils import handle_http_errors
+
+logger = logging.getLogger(__name__)
+
+
+# Internal implementation functions for testing
+async def _list_script_projects_impl(
+    service: Any,
+    user_google_email: str,
+    page_size: int = 50,
+    page_token: Optional[str] = None,
+) -> str:
+    """Internal implementation for list_script_projects.
+
+    Uses Drive API to find Apps Script files since the Script API
+    does not have a projects.list method.
+    """
+    logger.info(
+        f"[list_script_projects] Email: {user_google_email}, PageSize: {page_size}"
+    )
+
+    # Search for Apps Script files using Drive API
+    query = "mimeType='application/vnd.google-apps.script' and trashed=false"
+    request_params = {
+        "q": query,
+        "pageSize": page_size,
+        "fields": "nextPageToken, files(id, name, createdTime, modifiedTime)",
+        "orderBy": "modifiedTime desc",
+    }
+    if page_token:
+        request_params["pageToken"] = page_token
+
+    response = await asyncio.to_thread(service.files().list(**request_params).execute)
+
+    files = response.get("files", [])
+
+    if not files:
+        return "No Apps Script projects found."
+
+    output = [f"Found {len(files)} Apps Script projects:"]
+    for file in files:
+        title = file.get("name", "Untitled")
+        script_id = file.get("id", "Unknown ID")
+        create_time = file.get("createdTime", "Unknown")
+        update_time = file.get("modifiedTime", "Unknown")
+
+        output.append(
+            f"- {title} (ID: {script_id}) Created: {create_time} Modified: {update_time}"
+        )
+
+    if "nextPageToken" in response:
+        output.append(f"\nNext page token: {response['nextPageToken']}")
+
+    logger.info(
+        f"[list_script_projects] Found {len(files)} projects for {user_google_email}"
+    )
+    return "\n".join(output)
+
+
+@server.tool()
+@handle_http_errors("list_script_projects", is_read_only=True, service_type="drive")
+@require_google_service("drive", "drive_read")
+async def list_script_projects(
+    service: Any,
+    user_google_email: str,
+    page_size: int = 50,
+    page_token: Optional[str] = None,
+) -> str:
+    """
+    Lists Google Apps Script projects accessible to the user.
+
+    Uses Drive API to find Apps Script files.
+
+    Args:
+        service: Injected Google API service client
+        user_google_email: User's email address
+        page_size: Number of results per page (default: 50)
+        page_token: Token for pagination (optional)
+
+    Returns:
+        str: Formatted list of script projects
+    """
+    return await _list_script_projects_impl(
+        service, user_google_email, page_size, page_token
+    )
+
+
+async def _get_script_project_impl(
+    service: Any,
+    user_google_email: str,
+    script_id: str,
+) -> str:
+    """Internal implementation for get_script_project."""
+    logger.info(f"[get_script_project] Email: {user_google_email}, ID: {script_id}")
+
+    project = await asyncio.to_thread(
+        service.projects().get(scriptId=script_id).execute
+    )
+
+    title = project.get("title", "Untitled")
+    project_script_id = project.get("scriptId", "Unknown")
+    creator = project.get("creator", {}).get("email", "Unknown")
+    create_time = project.get("createTime", "Unknown")
+    update_time = project.get("updateTime", "Unknown")
+
+    output = [
+        f"Project: {title} (ID: {project_script_id})",
+        f"Creator: {creator}",
+        f"Created: {create_time}",
+        f"Modified: {update_time}",
+        "",
+        "Files:",
+    ]
+
+    files = project.get("files", [])
+    for i, file in enumerate(files, 1):
+        file_name = file.get("name", "Untitled")
+        file_type = file.get("type", "Unknown")
+        source = file.get("source", "")
+
+        output.append(f"{i}. {file_name} ({file_type})")
+        if source:
+            output.append(f"   {source[:200]}{'...' if len(source) > 200 else ''}")
+            output.append("")
+
+    logger.info(f"[get_script_project] Retrieved project {script_id}")
+    return "\n".join(output)
+
+
+@server.tool()
+@handle_http_errors("get_script_project", is_read_only=True, service_type="script")
+@require_google_service("script", "script_readonly")
+async def get_script_project(
+    service: Any,
+    user_google_email: str,
+    script_id: str,
+) -> str:
+    """
+    Retrieves complete project details including all source files.
+
+    Args:
+        service: Injected Google API service client
+        user_google_email: User's email address
+        script_id: The script project ID
+
+    Returns:
+        str: Formatted project details with all file contents
+    """
+    return await _get_script_project_impl(service, user_google_email, script_id)
+
+
+async def _get_script_content_impl(
+    service: Any,
+    user_google_email: str,
+    script_id: str,
+    file_name: str,
+) -> str:
+    """Internal implementation for get_script_content."""
+    logger.info(
+        f"[get_script_content] Email: {user_google_email}, ID: {script_id}, File: {file_name}"
+    )
+
+    project = await asyncio.to_thread(
+        service.projects().get(scriptId=script_id).execute
+    )
+
+    files = project.get("files", [])
+    target_file = None
+
+    for file in files:
+        if file.get("name") == file_name:
+            target_file = file
+            break
+
+    if not target_file:
+        return f"File '{file_name}' not found in project {script_id}"
+
+    source = target_file.get("source", "")
+    file_type = target_file.get("type", "Unknown")
+
+    output = [f"File: {file_name} ({file_type})", "", source]
+
+    logger.info(f"[get_script_content] Retrieved file {file_name} from {script_id}")
+    return "\n".join(output)
+
+
+@server.tool()
+@handle_http_errors("get_script_content", is_read_only=True, service_type="script")
+@require_google_service("script", "script_readonly")
+async def get_script_content(
+    service: Any,
+    user_google_email: str,
+    script_id: str,
+    file_name: str,
+) -> str:
+    """
+    Retrieves content of a specific file within a project.
+
+    Args:
+        service: Injected Google API service client
+        user_google_email: User's email address
+        script_id: The script project ID
+        file_name: Name of the file to retrieve
+
+    Returns:
+        str: File content as string
+    """
+    return await _get_script_content_impl(
+        service, user_google_email, script_id, file_name
+    )
+
+
+async def _create_script_project_impl(
+    service: Any,
+    user_google_email: str,
+    title: str,
+    parent_id: Optional[str] = None,
+) -> str:
+    """Internal implementation for create_script_project."""
+    logger.info(f"[create_script_project] Email: {user_google_email}, Title: {title}")
+
+    request_body = {"title": title}
+
+    if parent_id:
+        request_body["parentId"] = parent_id
+
+    project = await asyncio.to_thread(
+        service.projects().create(body=request_body).execute
+    )
+
+    script_id = project.get("scriptId", "Unknown")
+    edit_url = f"https://script.google.com/d/{script_id}/edit"
+
+    output = [
+        f"Created Apps Script project: {title}",
+        f"Script ID: {script_id}",
+        f"Edit URL: {edit_url}",
+    ]
+
+    logger.info(f"[create_script_project] Created project {script_id}")
+    return "\n".join(output)
+
+
+@server.tool()
+@handle_http_errors("create_script_project", service_type="script")
+@require_google_service("script", "script_projects")
+async def create_script_project(
+    service: Any,
+    user_google_email: str,
+    title: str,
+    parent_id: Optional[str] = None,
+) -> str:
+    """
+    Creates a new Apps Script project.
+
+    Args:
+        service: Injected Google API service client
+        user_google_email: User's email address
+        title: Project title
+        parent_id: Optional Drive folder ID or bound container ID
+
+    Returns:
+        str: Formatted string with new project details
+    """
+    return await _create_script_project_impl(
+        service, user_google_email, title, parent_id
+    )
+
+
+async def _update_script_content_impl(
+    service: Any,
+    user_google_email: str,
+    script_id: str,
+    files: List[Dict[str, str]],
+) -> str:
+    """Internal implementation for update_script_content."""
+    logger.info(
+        f"[update_script_content] Email: {user_google_email}, ID: {script_id}, Files: {len(files)}"
+    )
+
+    request_body = {"files": files}
+
+    updated_content = await asyncio.to_thread(
+        service.projects().updateContent(scriptId=script_id, body=request_body).execute
+    )
+
+    output = [f"Updated script project: {script_id}", "", "Modified files:"]
+
+    for file in updated_content.get("files", []):
+        file_name = file.get("name", "Untitled")
+        file_type = file.get("type", "Unknown")
+        output.append(f"- {file_name} ({file_type})")
+
+    logger.info(f"[update_script_content] Updated {len(files)} files in {script_id}")
+    return "\n".join(output)
+
+
+@server.tool()
+@handle_http_errors("update_script_content", service_type="script")
+@require_google_service("script", "script_projects")
+async def update_script_content(
+    service: Any,
+    user_google_email: str,
+    script_id: str,
+    files: List[Dict[str, str]],
+) -> str:
+    """
+    Updates or creates files in a script project.
+
+    Args:
+        service: Injected Google API service client
+        user_google_email: User's email address
+        script_id: The script project ID
+        files: List of file objects with name, type, and source
+
+    Returns:
+        str: Formatted string confirming update with file list
+    """
+    return await _update_script_content_impl(
+        service, user_google_email, script_id, files
+    )
+
+
+async def _run_script_function_impl(
+    service: Any,
+    user_google_email: str,
+    script_id: str,
+    function_name: str,
+    parameters: Optional[List[Any]] = None,
+    dev_mode: bool = False,
+) -> str:
+    """Internal implementation for run_script_function."""
+    logger.info(
+        f"[run_script_function] Email: {user_google_email}, ID: {script_id}, Function: {function_name}"
+    )
+
+    request_body = {"function": function_name, "devMode": dev_mode}
+
+    if parameters:
+        request_body["parameters"] = parameters
+
+    try:
+        response = await asyncio.to_thread(
+            service.scripts().run(scriptId=script_id, body=request_body).execute
+        )
+
+        if "error" in response:
+            error_details = response["error"]
+            error_message = error_details.get("message", "Unknown error")
+            return (
+                f"Execution failed\nFunction: {function_name}\nError: {error_message}"
+            )
+
+        result = response.get("response", {}).get("result")
+        output = [
+            "Execution successful",
+            f"Function: {function_name}",
+            f"Result: {result}",
+        ]
+
+        logger.info(f"[run_script_function] Successfully executed {function_name}")
+        return "\n".join(output)
+
+    except Exception as e:
+        logger.error(f"[run_script_function] Execution error: {str(e)}")
+        return f"Execution failed\nFunction: {function_name}\nError: {str(e)}"
+
+
+@server.tool()
+@handle_http_errors("run_script_function", service_type="script")
+@require_google_service("script", "script_projects")
+async def run_script_function(
+    service: Any,
+    user_google_email: str,
+    script_id: str,
+    function_name: str,
+    parameters: Optional[List[Any]] = None,
+    dev_mode: bool = False,
+) -> str:
+    """
+    Executes a function in a deployed script.
+
+    Args:
+        service: Injected Google API service client
+        user_google_email: User's email address
+        script_id: The script project ID
+        function_name: Name of function to execute
+        parameters: Optional list of parameters to pass
+        dev_mode: Whether to run latest code vs deployed version
+
+    Returns:
+        str: Formatted string with execution result or error
+    """
+    return await _run_script_function_impl(
+        service, user_google_email, script_id, function_name, parameters, dev_mode
+    )
+
+
+async def _create_deployment_impl(
+    service: Any,
+    user_google_email: str,
+    script_id: str,
+    description: str,
+    version_description: Optional[str] = None,
+) -> str:
+    """Internal implementation for create_deployment.
+
+    Creates a new version first, then creates a deployment using that version.
+    """
+    logger.info(
+        f"[create_deployment] Email: {user_google_email}, ID: {script_id}, Desc: {description}"
+    )
+
+    # First, create a new version
+    version_body = {"description": version_description or description}
+    version = await asyncio.to_thread(
+        service.projects()
+        .versions()
+        .create(scriptId=script_id, body=version_body)
+        .execute
+    )
+    version_number = version.get("versionNumber")
+    logger.info(f"[create_deployment] Created version {version_number}")
+
+    # Now create the deployment with the version number
+    deployment_body = {
+        "versionNumber": version_number,
+        "description": description,
+    }
+
+    deployment = await asyncio.to_thread(
+        service.projects()
+        .deployments()
+        .create(scriptId=script_id, body=deployment_body)
+        .execute
+    )
+
+    deployment_id = deployment.get("deploymentId", "Unknown")
+
+    output = [
+        f"Created deployment for script: {script_id}",
+        f"Deployment ID: {deployment_id}",
+        f"Version: {version_number}",
+        f"Description: {description}",
+    ]
+
+    logger.info(f"[create_deployment] Created deployment {deployment_id}")
+    return "\n".join(output)
+
+
+@server.tool()
+@handle_http_errors("create_deployment", service_type="script")
+@require_google_service("script", "script_deployments")
+async def create_deployment(
+    service: Any,
+    user_google_email: str,
+    script_id: str,
+    description: str,
+    version_description: Optional[str] = None,
+) -> str:
+    """
+    Creates a new deployment of the script.
+
+    Args:
+        service: Injected Google API service client
+        user_google_email: User's email address
+        script_id: The script project ID
+        description: Deployment description
+        version_description: Optional version description
+
+    Returns:
+        str: Formatted string with deployment details
+    """
+    return await _create_deployment_impl(
+        service, user_google_email, script_id, description, version_description
+    )
+
+
+async def _list_deployments_impl(
+    service: Any,
+    user_google_email: str,
+    script_id: str,
+) -> str:
+    """Internal implementation for list_deployments."""
+    logger.info(f"[list_deployments] Email: {user_google_email}, ID: {script_id}")
+
+    response = await asyncio.to_thread(
+        service.projects().deployments().list(scriptId=script_id).execute
+    )
+
+    deployments = response.get("deployments", [])
+
+    if not deployments:
+        return f"No deployments found for script: {script_id}"
+
+    output = [f"Deployments for script: {script_id}", ""]
+
+    for i, deployment in enumerate(deployments, 1):
+        deployment_id = deployment.get("deploymentId", "Unknown")
+        description = deployment.get("description", "No description")
+        update_time = deployment.get("updateTime", "Unknown")
+
+        output.append(f"{i}. {description} ({deployment_id})")
+        output.append(f"   Updated: {update_time}")
+        output.append("")
+
+    logger.info(f"[list_deployments] Found {len(deployments)} deployments")
+    return "\n".join(output)
+
+
+@server.tool()
+@handle_http_errors("list_deployments", is_read_only=True, service_type="script")
+@require_google_service("script", "script_deployments_readonly")
+async def list_deployments(
+    service: Any,
+    user_google_email: str,
+    script_id: str,
+) -> str:
+    """
+    Lists all deployments for a script project.
+
+    Args:
+        service: Injected Google API service client
+        user_google_email: User's email address
+        script_id: The script project ID
+
+    Returns:
+        str: Formatted string with deployment list
+    """
+    return await _list_deployments_impl(service, user_google_email, script_id)
+
+
+async def _update_deployment_impl(
+    service: Any,
+    user_google_email: str,
+    script_id: str,
+    deployment_id: str,
+    description: Optional[str] = None,
+) -> str:
+    """Internal implementation for update_deployment."""
+    logger.info(
+        f"[update_deployment] Email: {user_google_email}, Script: {script_id}, Deployment: {deployment_id}"
+    )
+
+    request_body = {}
+    if description:
+        request_body["description"] = description
+
+    deployment = await asyncio.to_thread(
+        service.projects()
+        .deployments()
+        .update(scriptId=script_id, deploymentId=deployment_id, body=request_body)
+        .execute
+    )
+
+    output = [
+        f"Updated deployment: {deployment_id}",
+        f"Script: {script_id}",
+        f"Description: {deployment.get('description', 'No description')}",
+    ]
+
+    logger.info(f"[update_deployment] Updated deployment {deployment_id}")
+    return "\n".join(output)
+
+
+@server.tool()
+@handle_http_errors("update_deployment", service_type="script")
+@require_google_service("script", "script_deployments")
+async def update_deployment(
+    service: Any,
+    user_google_email: str,
+    script_id: str,
+    deployment_id: str,
+    description: Optional[str] = None,
+) -> str:
+    """
+    Updates an existing deployment configuration.
+
+    Args:
+        service: Injected Google API service client
+        user_google_email: User's email address
+        script_id: The script project ID
+        deployment_id: The deployment ID to update
+        description: Optional new description
+
+    Returns:
+        str: Formatted string confirming update
+    """
+    return await _update_deployment_impl(
+        service, user_google_email, script_id, deployment_id, description
+    )
+
+
+async def _delete_deployment_impl(
+    service: Any,
+    user_google_email: str,
+    script_id: str,
+    deployment_id: str,
+) -> str:
+    """Internal implementation for delete_deployment."""
+    logger.info(
+        f"[delete_deployment] Email: {user_google_email}, Script: {script_id}, Deployment: {deployment_id}"
+    )
+
+    await asyncio.to_thread(
+        service.projects()
+        .deployments()
+        .delete(scriptId=script_id, deploymentId=deployment_id)
+        .execute
+    )
+
+    output = f"Deleted deployment: {deployment_id} from script: {script_id}"
+
+    logger.info(f"[delete_deployment] Deleted deployment {deployment_id}")
+    return output
+
+
+@server.tool()
+@handle_http_errors("delete_deployment", service_type="script")
+@require_google_service("script", "script_deployments")
+async def delete_deployment(
+    service: Any,
+    user_google_email: str,
+    script_id: str,
+    deployment_id: str,
+) -> str:
+    """
+    Deletes a deployment.
+
+    Args:
+        service: Injected Google API service client
+        user_google_email: User's email address
+        script_id: The script project ID
+        deployment_id: The deployment ID to delete
+
+    Returns:
+        str: Confirmation message
+    """
+    return await _delete_deployment_impl(
+        service, user_google_email, script_id, deployment_id
+    )
+
+
+async def _list_script_processes_impl(
+    service: Any,
+    user_google_email: str,
+    page_size: int = 50,
+    script_id: Optional[str] = None,
+) -> str:
+    """Internal implementation for list_script_processes."""
+    logger.info(
+        f"[list_script_processes] Email: {user_google_email}, PageSize: {page_size}"
+    )
+
+    request_params = {"pageSize": page_size}
+    if script_id:
+        request_params["scriptId"] = script_id
+
+    response = await asyncio.to_thread(
+        service.processes().list(**request_params).execute
+    )
+
+    processes = response.get("processes", [])
+
+    if not processes:
+        return "No recent script executions found."
+
+    output = ["Recent script executions:", ""]
+
+    for i, process in enumerate(processes, 1):
+        function_name = process.get("functionName", "Unknown")
+        process_status = process.get("processStatus", "Unknown")
+        start_time = process.get("startTime", "Unknown")
+        duration = process.get("duration", "Unknown")
+
+        output.append(f"{i}. {function_name}")
+        output.append(f"   Status: {process_status}")
+        output.append(f"   Started: {start_time}")
+        output.append(f"   Duration: {duration}")
+        output.append("")
+
+    logger.info(f"[list_script_processes] Found {len(processes)} processes")
+    return "\n".join(output)
+
+
+@server.tool()
+@handle_http_errors("list_script_processes", is_read_only=True, service_type="script")
+@require_google_service("script", "script_readonly")
+async def list_script_processes(
+    service: Any,
+    user_google_email: str,
+    page_size: int = 50,
+    script_id: Optional[str] = None,
+) -> str:
+    """
+    Lists recent execution processes for user's scripts.
+
+    Args:
+        service: Injected Google API service client
+        user_google_email: User's email address
+        page_size: Number of results (default: 50)
+        script_id: Optional filter by script ID
+
+    Returns:
+        str: Formatted string with process list
+    """
+    return await _list_script_processes_impl(
+        service, user_google_email, page_size, script_id
+    )
+
+
+# ============================================================================
+# Delete Script Project
+# ============================================================================
+
+
+async def _delete_script_project_impl(
+    service: Any,
+    user_google_email: str,
+    script_id: str,
+) -> str:
+    """Internal implementation for delete_script_project."""
+    logger.info(
+        f"[delete_script_project] Email: {user_google_email}, ScriptID: {script_id}"
+    )
+
+    # Apps Script projects are stored as Drive files
+    await asyncio.to_thread(service.files().delete(fileId=script_id).execute)
+
+    logger.info(f"[delete_script_project] Deleted script {script_id}")
+    return f"Deleted Apps Script project: {script_id}"
+
+
+@server.tool()
+@handle_http_errors("delete_script_project", is_read_only=False, service_type="drive")
+@require_google_service("drive", "drive_full")
+async def delete_script_project(
+    service: Any,
+    user_google_email: str,
+    script_id: str,
+) -> str:
+    """
+    Deletes an Apps Script project.
+
+    This permanently deletes the script project. The action cannot be undone.
+
+    Args:
+        service: Injected Google API service client
+        user_google_email: User's email address
+        script_id: The script project ID to delete
+
+    Returns:
+        str: Confirmation message
+    """
+    return await _delete_script_project_impl(service, user_google_email, script_id)
+
+
+# ============================================================================
+# Version Management
+# ============================================================================
+
+
+async def _list_versions_impl(
+    service: Any,
+    user_google_email: str,
+    script_id: str,
+) -> str:
+    """Internal implementation for list_versions."""
+    logger.info(f"[list_versions] Email: {user_google_email}, ScriptID: {script_id}")
+
+    response = await asyncio.to_thread(
+        service.projects().versions().list(scriptId=script_id).execute
+    )
+
+    versions = response.get("versions", [])
+
+    if not versions:
+        return f"No versions found for script: {script_id}"
+
+    output = [f"Versions for script: {script_id}", ""]
+
+    for version in versions:
+        version_number = version.get("versionNumber", "Unknown")
+        description = version.get("description", "No description")
+        create_time = version.get("createTime", "Unknown")
+
+        output.append(f"Version {version_number}: {description}")
+        output.append(f"   Created: {create_time}")
+        output.append("")
+
+    logger.info(f"[list_versions] Found {len(versions)} versions")
+    return "\n".join(output)
+
+
+@server.tool()
+@handle_http_errors("list_versions", is_read_only=True, service_type="script")
+@require_google_service("script", "script_readonly")
+async def list_versions(
+    service: Any,
+    user_google_email: str,
+    script_id: str,
+) -> str:
+    """
+    Lists all versions of a script project.
+
+    Versions are immutable snapshots of your script code.
+    They are created when you deploy or explicitly create a version.
+
+    Args:
+        service: Injected Google API service client
+        user_google_email: User's email address
+        script_id: The script project ID
+
+    Returns:
+        str: Formatted string with version list
+    """
+    return await _list_versions_impl(service, user_google_email, script_id)
+
+
+async def _create_version_impl(
+    service: Any,
+    user_google_email: str,
+    script_id: str,
+    description: Optional[str] = None,
+) -> str:
+    """Internal implementation for create_version."""
+    logger.info(f"[create_version] Email: {user_google_email}, ScriptID: {script_id}")
+
+    request_body = {}
+    if description:
+        request_body["description"] = description
+
+    version = await asyncio.to_thread(
+        service.projects()
+        .versions()
+        .create(scriptId=script_id, body=request_body)
+        .execute
+    )
+
+    version_number = version.get("versionNumber", "Unknown")
+    create_time = version.get("createTime", "Unknown")
+
+    output = [
+        f"Created version {version_number} for script: {script_id}",
+        f"Description: {description or 'No description'}",
+        f"Created: {create_time}",
+    ]
+
+    logger.info(f"[create_version] Created version {version_number}")
+    return "\n".join(output)
+
+
+@server.tool()
+@handle_http_errors("create_version", is_read_only=False, service_type="script")
+@require_google_service("script", "script_full")
+async def create_version(
+    service: Any,
+    user_google_email: str,
+    script_id: str,
+    description: Optional[str] = None,
+) -> str:
+    """
+    Creates a new immutable version of a script project.
+
+    Versions capture a snapshot of the current script code.
+    Once created, versions cannot be modified.
+
+    Args:
+        service: Injected Google API service client
+        user_google_email: User's email address
+        script_id: The script project ID
+        description: Optional description for this version
+
+    Returns:
+        str: Formatted string with new version details
+    """
+    return await _create_version_impl(
+        service, user_google_email, script_id, description
+    )
+
+
+async def _get_version_impl(
+    service: Any,
+    user_google_email: str,
+    script_id: str,
+    version_number: int,
+) -> str:
+    """Internal implementation for get_version."""
+    logger.info(
+        f"[get_version] Email: {user_google_email}, ScriptID: {script_id}, Version: {version_number}"
+    )
+
+    version = await asyncio.to_thread(
+        service.projects()
+        .versions()
+        .get(scriptId=script_id, versionNumber=version_number)
+        .execute
+    )
+
+    ver_num = version.get("versionNumber", "Unknown")
+    description = version.get("description", "No description")
+    create_time = version.get("createTime", "Unknown")
+
+    output = [
+        f"Version {ver_num} of script: {script_id}",
+        f"Description: {description}",
+        f"Created: {create_time}",
+    ]
+
+    logger.info(f"[get_version] Retrieved version {ver_num}")
+    return "\n".join(output)
+
+
+@server.tool()
+@handle_http_errors("get_version", is_read_only=True, service_type="script")
+@require_google_service("script", "script_readonly")
+async def get_version(
+    service: Any,
+    user_google_email: str,
+    script_id: str,
+    version_number: int,
+) -> str:
+    """
+    Gets details of a specific version.
+
+    Args:
+        service: Injected Google API service client
+        user_google_email: User's email address
+        script_id: The script project ID
+        version_number: The version number to retrieve (1, 2, 3, etc.)
+
+    Returns:
+        str: Formatted string with version details
+    """
+    return await _get_version_impl(
+        service, user_google_email, script_id, version_number
+    )
+
+
+# ============================================================================
+# Metrics
+# ============================================================================
+
+
+async def _get_script_metrics_impl(
+    service: Any,
+    user_google_email: str,
+    script_id: str,
+    metrics_granularity: str = "DAILY",
+) -> str:
+    """Internal implementation for get_script_metrics."""
+    logger.info(
+        f"[get_script_metrics] Email: {user_google_email}, ScriptID: {script_id}, Granularity: {metrics_granularity}"
+    )
+
+    request_params = {
+        "scriptId": script_id,
+        "metricsGranularity": metrics_granularity,
+    }
+
+    response = await asyncio.to_thread(
+        service.projects().getMetrics(**request_params).execute
+    )
+
+    output = [
+        f"Metrics for script: {script_id}",
+        f"Granularity: {metrics_granularity}",
+        "",
+    ]
+
+    # Active users
+    active_users = response.get("activeUsers", [])
+    if active_users:
+        output.append("Active Users:")
+        for metric in active_users:
+            start_time = metric.get("startTime", "Unknown")
+            end_time = metric.get("endTime", "Unknown")
+            value = metric.get("value", "0")
+            output.append(f"  {start_time} to {end_time}: {value} users")
+        output.append("")
+
+    # Total executions
+    total_executions = response.get("totalExecutions", [])
+    if total_executions:
+        output.append("Total Executions:")
+        for metric in total_executions:
+            start_time = metric.get("startTime", "Unknown")
+            end_time = metric.get("endTime", "Unknown")
+            value = metric.get("value", "0")
+            output.append(f"  {start_time} to {end_time}: {value} executions")
+        output.append("")
+
+    # Failed executions
+    failed_executions = response.get("failedExecutions", [])
+    if failed_executions:
+        output.append("Failed Executions:")
+        for metric in failed_executions:
+            start_time = metric.get("startTime", "Unknown")
+            end_time = metric.get("endTime", "Unknown")
+            value = metric.get("value", "0")
+            output.append(f"  {start_time} to {end_time}: {value} failures")
+        output.append("")
+
+    if not active_users and not total_executions and not failed_executions:
+        output.append("No metrics data available for this script.")
+
+    logger.info(f"[get_script_metrics] Retrieved metrics for {script_id}")
+    return "\n".join(output)
+
+
+@server.tool()
+@handle_http_errors("get_script_metrics", is_read_only=True, service_type="script")
+@require_google_service("script", "script_readonly")
+async def get_script_metrics(
+    service: Any,
+    user_google_email: str,
+    script_id: str,
+    metrics_granularity: str = "DAILY",
+) -> str:
+    """
+    Gets execution metrics for a script project.
+
+    Returns analytics data including active users, total executions,
+    and failed executions over time.
+
+    Args:
+        service: Injected Google API service client
+        user_google_email: User's email address
+        script_id: The script project ID
+        metrics_granularity: Granularity of metrics - "DAILY" or "WEEKLY"
+
+    Returns:
+        str: Formatted string with metrics data
+    """
+    return await _get_script_metrics_impl(
+        service, user_google_email, script_id, metrics_granularity
+    )
+
+
+# ============================================================================
+# Trigger Code Generation
+# ============================================================================
+
+
+def _generate_trigger_code_impl(
+    trigger_type: str,
+    function_name: str,
+    schedule: str = "",
+) -> str:
+    """Internal implementation for generate_trigger_code."""
+    code_lines = []
+
+    if trigger_type == "on_open":
+        code_lines = [
+            "// Simple trigger - just rename your function to 'onOpen'",
+            "// This runs automatically when the document is opened",
+            "function onOpen(e) {",
+            f"  {function_name}();",
+            "}",
+        ]
+    elif trigger_type == "on_edit":
+        code_lines = [
+            "// Simple trigger - just rename your function to 'onEdit'",
+            "// This runs automatically when a user edits the spreadsheet",
+            "function onEdit(e) {",
+            f"  {function_name}();",
+            "}",
+        ]
+    elif trigger_type == "time_minutes":
+        interval = schedule or "5"
+        code_lines = [
+            "// Run this function ONCE to install the trigger",
+            f"function createTimeTrigger_{function_name}() {{",
+            "  // Delete existing triggers for this function first",
+            "  const triggers = ScriptApp.getProjectTriggers();",
+            "  triggers.forEach(trigger => {",
+            f"    if (trigger.getHandlerFunction() === '{function_name}') {{",
+            "      ScriptApp.deleteTrigger(trigger);",
+            "    }",
+            "  });",
+            "",
+            f"  // Create new trigger - runs every {interval} minutes",
+            f"  ScriptApp.newTrigger('{function_name}')",
+            "    .timeBased()",
+            f"    .everyMinutes({interval})",
+            "    .create();",
+            "",
+            f"  Logger.log('Trigger created: {function_name} will run every {interval} minutes');",
+            "}",
+        ]
+    elif trigger_type == "time_hours":
+        interval = schedule or "1"
+        code_lines = [
+            "// Run this function ONCE to install the trigger",
+            f"function createTimeTrigger_{function_name}() {{",
+            "  // Delete existing triggers for this function first",
+            "  const triggers = ScriptApp.getProjectTriggers();",
+            "  triggers.forEach(trigger => {",
+            f"    if (trigger.getHandlerFunction() === '{function_name}') {{",
+            "      ScriptApp.deleteTrigger(trigger);",
+            "    }",
+            "  });",
+            "",
+            f"  // Create new trigger - runs every {interval} hour(s)",
+            f"  ScriptApp.newTrigger('{function_name}')",
+            "    .timeBased()",
+            f"    .everyHours({interval})",
+            "    .create();",
+            "",
+            f"  Logger.log('Trigger created: {function_name} will run every {interval} hour(s)');",
+            "}",
+        ]
+    elif trigger_type == "time_daily":
+        hour = schedule or "9"
+        code_lines = [
+            "// Run this function ONCE to install the trigger",
+            f"function createDailyTrigger_{function_name}() {{",
+            "  // Delete existing triggers for this function first",
+            "  const triggers = ScriptApp.getProjectTriggers();",
+            "  triggers.forEach(trigger => {",
+            f"    if (trigger.getHandlerFunction() === '{function_name}') {{",
+            "      ScriptApp.deleteTrigger(trigger);",
+            "    }",
+            "  });",
+            "",
+            f"  // Create new trigger - runs daily at {hour}:00",
+            f"  ScriptApp.newTrigger('{function_name}')",
+            "    .timeBased()",
+            f"    .atHour({hour})",
+            "    .everyDays(1)",
+            "    .create();",
+            "",
+            f"  Logger.log('Trigger created: {function_name} will run daily at {hour}:00');",
+            "}",
+        ]
+    elif trigger_type == "time_weekly":
+        day = schedule.upper() if schedule else "MONDAY"
+        code_lines = [
+            "// Run this function ONCE to install the trigger",
+            f"function createWeeklyTrigger_{function_name}() {{",
+            "  // Delete existing triggers for this function first",
+            "  const triggers = ScriptApp.getProjectTriggers();",
+            "  triggers.forEach(trigger => {",
+            f"    if (trigger.getHandlerFunction() === '{function_name}') {{",
+            "      ScriptApp.deleteTrigger(trigger);",
+            "    }",
+            "  });",
+            "",
+            f"  // Create new trigger - runs weekly on {day}",
+            f"  ScriptApp.newTrigger('{function_name}')",
+            "    .timeBased()",
+            f"    .onWeekDay(ScriptApp.WeekDay.{day})",
+            "    .atHour(9)",
+            "    .create();",
+            "",
+            f"  Logger.log('Trigger created: {function_name} will run every {day} at 9:00');",
+            "}",
+        ]
+    elif trigger_type == "on_form_submit":
+        code_lines = [
+            "// Run this function ONCE to install the trigger",
+            "// This must be run from a script BOUND to the Google Form",
+            f"function createFormSubmitTrigger_{function_name}() {{",
+            "  // Delete existing triggers for this function first",
+            "  const triggers = ScriptApp.getProjectTriggers();",
+            "  triggers.forEach(trigger => {",
+            f"    if (trigger.getHandlerFunction() === '{function_name}') {{",
+            "      ScriptApp.deleteTrigger(trigger);",
+            "    }",
+            "  });",
+            "",
+            "  // Create new trigger - runs when form is submitted",
+            f"  ScriptApp.newTrigger('{function_name}')",
+            "    .forForm(FormApp.getActiveForm())",
+            "    .onFormSubmit()",
+            "    .create();",
+            "",
+            f"  Logger.log('Trigger created: {function_name} will run on form submit');",
+            "}",
+        ]
+    elif trigger_type == "on_change":
+        code_lines = [
+            "// Run this function ONCE to install the trigger",
+            "// This must be run from a script BOUND to a Google Sheet",
+            f"function createChangeTrigger_{function_name}() {{",
+            "  // Delete existing triggers for this function first",
+            "  const triggers = ScriptApp.getProjectTriggers();",
+            "  triggers.forEach(trigger => {",
+            f"    if (trigger.getHandlerFunction() === '{function_name}') {{",
+            "      ScriptApp.deleteTrigger(trigger);",
+            "    }",
+            "  });",
+            "",
+            "  // Create new trigger - runs when spreadsheet changes",
+            f"  ScriptApp.newTrigger('{function_name}')",
+            "    .forSpreadsheet(SpreadsheetApp.getActive())",
+            "    .onChange()",
+            "    .create();",
+            "",
+            f"  Logger.log('Trigger created: {function_name} will run on spreadsheet change');",
+            "}",
+        ]
+    else:
+        return (
+            f"Unknown trigger type: {trigger_type}\n\n"
+            "Valid types: time_minutes, time_hours, time_daily, time_weekly, "
+            "on_open, on_edit, on_form_submit, on_change"
+        )
+
+    code = "\n".join(code_lines)
+
+    instructions = []
+    if trigger_type.startswith("on_"):
+        if trigger_type in ("on_open", "on_edit"):
+            instructions = [
+                "SIMPLE TRIGGER",
+                "=" * 50,
+                "",
+                "Add this code to your script. Simple triggers run automatically",
+                "when the event occurs - no setup function needed.",
+                "",
+                "Note: Simple triggers have limitations:",
+                "- Cannot access services that require authorization",
+                "- Cannot run longer than 30 seconds",
+                "- Cannot make external HTTP requests",
+                "",
+                "For more capabilities, use an installable trigger instead.",
+                "",
+                "CODE TO ADD:",
+                "-" * 50,
+            ]
+        else:
+            instructions = [
+                "INSTALLABLE TRIGGER",
+                "=" * 50,
+                "",
+                "1. Add this code to your script",
+                f"2. Run the setup function once: createFormSubmitTrigger_{function_name}() or similar",
+                "3. The trigger will then run automatically",
+                "",
+                "CODE TO ADD:",
+                "-" * 50,
+            ]
+    else:
+        instructions = [
+            "INSTALLABLE TRIGGER",
+            "=" * 50,
+            "",
+            "1. Add this code to your script using update_script_content",
+            "2. Run the setup function ONCE (manually in Apps Script editor or via run_script_function)",
+            "3. The trigger will then run automatically on schedule",
+            "",
+            "To check installed triggers: Apps Script editor > Triggers (clock icon)",
+            "",
+            "CODE TO ADD:",
+            "-" * 50,
+        ]
+
+    return "\n".join(instructions) + "\n\n" + code
+
+
+@server.tool()
+async def generate_trigger_code(
+    trigger_type: str,
+    function_name: str,
+    schedule: str = "",
+) -> str:
+    """
+    Generates Apps Script code for creating triggers.
+
+    The Apps Script API cannot create triggers directly - they must be created
+    from within Apps Script itself. This tool generates the code you need.
+
+    Args:
+        trigger_type: Type of trigger. One of:
+                      - "time_minutes" (run every N minutes: 1, 5, 10, 15, 30)
+                      - "time_hours" (run every N hours: 1, 2, 4, 6, 8, 12)
+                      - "time_daily" (run daily at a specific hour: 0-23)
+                      - "time_weekly" (run weekly on a specific day)
+                      - "on_open" (simple trigger - runs when document opens)
+                      - "on_edit" (simple trigger - runs when user edits)
+                      - "on_form_submit" (runs when form is submitted)
+                      - "on_change" (runs when content changes)
+
+        function_name: The function to run when trigger fires (e.g., "sendDailyReport")
+
+        schedule: Schedule details (depends on trigger_type):
+                  - For time_minutes: "1", "5", "10", "15", or "30"
+                  - For time_hours: "1", "2", "4", "6", "8", or "12"
+                  - For time_daily: hour as "0"-"23" (e.g., "9" for 9am)
+                  - For time_weekly: "MONDAY", "TUESDAY", etc.
+                  - For simple triggers (on_open, on_edit): not needed
+
+    Returns:
+        str: Apps Script code to create the trigger
+    """
+    return _generate_trigger_code_impl(trigger_type, function_name, schedule)

gcalendar/__init__.py

@@ -0,0 +1 @@
+# Make the calendar directory a Python package

gcalendar/calendar_tools.py

@@ -0,0 +1,1075 @@
+"""
+Google Calendar MCP Tools
+
+This module provides MCP tools for interacting with Google Calendar API.
+"""
+
+import datetime
+import logging
+import asyncio
+import re
+import uuid
+import json
+from typing import List, Optional, Dict, Any, Union
+
+from googleapiclient.errors import HttpError
+from googleapiclient.discovery import build
+
+from auth.service_decorator import require_google_service
+from core.utils import handle_http_errors
+
+from core.server import server
+
+
+# Configure module logger
+logger = logging.getLogger(__name__)
+
+
+def _parse_reminders_json(
+    reminders_input: Optional[Union[str, List[Dict[str, Any]]]], function_name: str
+) -> List[Dict[str, Any]]:
+    """
+    Parse reminders from JSON string or list object and validate them.
+
+    Args:
+        reminders_input: JSON string containing reminder objects or list of reminder objects
+        function_name: Name of calling function for logging
+
+    Returns:
+        List of validated reminder objects
+    """
+    if not reminders_input:
+        return []
+
+    # Handle both string (JSON) and list inputs
+    if isinstance(reminders_input, str):
+        try:
+            reminders = json.loads(reminders_input)
+            if not isinstance(reminders, list):
+                logger.warning(
+                    f"[{function_name}] Reminders must be a JSON array, got {type(reminders).__name__}"
+                )
+                return []
+        except json.JSONDecodeError as e:
+            logger.warning(f"[{function_name}] Invalid JSON for reminders: {e}")
+            return []
+    elif isinstance(reminders_input, list):
+        reminders = reminders_input
+    else:
+        logger.warning(
+            f"[{function_name}] Reminders must be a JSON string or list, got {type(reminders_input).__name__}"
+        )
+        return []
+
+    # Validate reminders
+    if len(reminders) > 5:
+        logger.warning(
+            f"[{function_name}] More than 5 reminders provided, truncating to first 5"
+        )
+        reminders = reminders[:5]
+
+    validated_reminders = []
+    for reminder in reminders:
+        if (
+            not isinstance(reminder, dict)
+            or "method" not in reminder
+            or "minutes" not in reminder
+        ):
+            logger.warning(
+                f"[{function_name}] Invalid reminder format: {reminder}, skipping"
+            )
+            continue
+
+        method = reminder["method"].lower()
+        if method not in ["popup", "email"]:
+            logger.warning(
+                f"[{function_name}] Invalid reminder method '{method}', must be 'popup' or 'email', skipping"
+            )
+            continue
+
+        minutes = reminder["minutes"]
+        if not isinstance(minutes, int) or minutes < 0 or minutes > 40320:
+            logger.warning(
+                f"[{function_name}] Invalid reminder minutes '{minutes}', must be integer 0-40320, skipping"
+            )
+            continue
+
+        validated_reminders.append({"method": method, "minutes": minutes})
+
+    return validated_reminders
+
+
+def _apply_transparency_if_valid(
+    event_body: Dict[str, Any],
+    transparency: Optional[str],
+    function_name: str,
+) -> None:
+    """
+    Apply transparency to the event body if the provided value is valid.
+
+    Args:
+        event_body: Event payload being constructed.
+        transparency: Provided transparency value.
+        function_name: Name of the calling function for logging context.
+    """
+    if transparency is None:
+        return
+
+    valid_transparency_values = ["opaque", "transparent"]
+    if transparency in valid_transparency_values:
+        event_body["transparency"] = transparency
+        logger.info(f"[{function_name}] Set transparency to '{transparency}'")
+    else:
+        logger.warning(
+            f"[{function_name}] Invalid transparency value '{transparency}', must be 'opaque' or 'transparent', skipping"
+        )
+
+
+def _apply_visibility_if_valid(
+    event_body: Dict[str, Any],
+    visibility: Optional[str],
+    function_name: str,
+) -> None:
+    """
+    Apply visibility to the event body if the provided value is valid.
+
+    Args:
+        event_body: Event payload being constructed.
+        visibility: Provided visibility value.
+        function_name: Name of the calling function for logging context.
+    """
+    if visibility is None:
+        return
+
+    valid_visibility_values = ["default", "public", "private", "confidential"]
+    if visibility in valid_visibility_values:
+        event_body["visibility"] = visibility
+        logger.info(f"[{function_name}] Set visibility to '{visibility}'")
+    else:
+        logger.warning(
+            f"[{function_name}] Invalid visibility value '{visibility}', must be 'default', 'public', 'private', or 'confidential', skipping"
+        )
+
+
+def _preserve_existing_fields(
+    event_body: Dict[str, Any],
+    existing_event: Dict[str, Any],
+    field_mappings: Dict[str, Any],
+) -> None:
+    """
+    Helper function to preserve existing event fields when not explicitly provided.
+
+    Args:
+        event_body: The event body being built for the API call
+        existing_event: The existing event data from the API
+        field_mappings: Dict mapping field names to their new values (None means preserve existing)
+    """
+    for field_name, new_value in field_mappings.items():
+        if new_value is None and field_name in existing_event:
+            event_body[field_name] = existing_event[field_name]
+            logger.info(f"[modify_event] Preserving existing {field_name}")
+        elif new_value is not None:
+            event_body[field_name] = new_value
+
+
+def _format_attendee_details(
+    attendees: List[Dict[str, Any]], indent: str = "  "
+) -> str:
+    """
+      Format attendee details including response status, organizer, and optional flags.
+
+      Example output format:
+      "  user@example.com: accepted
+    manager@example.com: declined (organizer)
+    optional-person@example.com: tentative (optional)"
+
+      Args:
+          attendees: List of attendee dictionaries from Google Calendar API
+          indent: Indentation to use for newline-separated attendees (default: "  ")
+
+      Returns:
+          Formatted string with attendee details, or "None" if no attendees
+    """
+    if not attendees:
+        return "None"
+
+    attendee_details_list = []
+    for a in attendees:
+        email = a.get("email", "unknown")
+        response_status = a.get("responseStatus", "unknown")
+        optional = a.get("optional", False)
+        organizer = a.get("organizer", False)
+
+        detail_parts = [f"{email}: {response_status}"]
+        if organizer:
+            detail_parts.append("(organizer)")
+        if optional:
+            detail_parts.append("(optional)")
+
+        attendee_details_list.append(" ".join(detail_parts))
+
+    return f"\n{indent}".join(attendee_details_list)
+
+
+def _format_attachment_details(
+    attachments: List[Dict[str, Any]], indent: str = "  "
+) -> str:
+    """
+    Format attachment details including file information.
+
+
+    Args:
+        attachments: List of attachment dictionaries from Google Calendar API
+        indent: Indentation to use for newline-separated attachments (default: "  ")
+
+    Returns:
+        Formatted string with attachment details, or "None" if no attachments
+    """
+    if not attachments:
+        return "None"
+
+    attachment_details_list = []
+    for att in attachments:
+        title = att.get("title", "Untitled")
+        file_url = att.get("fileUrl", "No URL")
+        file_id = att.get("fileId", "No ID")
+        mime_type = att.get("mimeType", "Unknown")
+
+        attachment_info = (
+            f"{title}\n"
+            f"{indent}File URL: {file_url}\n"
+            f"{indent}File ID: {file_id}\n"
+            f"{indent}MIME Type: {mime_type}"
+        )
+        attachment_details_list.append(attachment_info)
+
+    return f"\n{indent}".join(attachment_details_list)
+
+
+# Helper function to ensure time strings for API calls are correctly formatted
+def _correct_time_format_for_api(
+    time_str: Optional[str], param_name: str
+) -> Optional[str]:
+    if not time_str:
+        return None
+
+    logger.info(
+        f"_correct_time_format_for_api: Processing {param_name} with value '{time_str}'"
+    )
+
+    # Handle date-only format (YYYY-MM-DD)
+    if len(time_str) == 10 and time_str.count("-") == 2:
+        try:
+            # Validate it's a proper date
+            datetime.datetime.strptime(time_str, "%Y-%m-%d")
+            # For date-only, append T00:00:00Z to make it RFC3339 compliant
+            formatted = f"{time_str}T00:00:00Z"
+            logger.info(
+                f"Formatting date-only {param_name} '{time_str}' to RFC3339: '{formatted}'"
+            )
+            return formatted
+        except ValueError:
+            logger.warning(
+                f"{param_name} '{time_str}' looks like a date but is not valid YYYY-MM-DD. Using as is."
+            )
+            return time_str
+
+    # Specifically address YYYY-MM-DDTHH:MM:SS by appending 'Z'
+    if (
+        len(time_str) == 19
+        and time_str[10] == "T"
+        and time_str.count(":") == 2
+        and not (
+            time_str.endswith("Z") or ("+" in time_str[10:]) or ("-" in time_str[10:])
+        )
+    ):
+        try:
+            # Validate the format before appending 'Z'
+            datetime.datetime.strptime(time_str, "%Y-%m-%dT%H:%M:%S")
+            logger.info(
+                f"Formatting {param_name} '{time_str}' by appending 'Z' for UTC."
+            )
+            return time_str + "Z"
+        except ValueError:
+            logger.warning(
+                f"{param_name} '{time_str}' looks like it needs 'Z' but is not valid YYYY-MM-DDTHH:MM:SS. Using as is."
+            )
+            return time_str
+
+    # If it already has timezone info or doesn't match our patterns, return as is
+    logger.info(f"{param_name} '{time_str}' doesn't need formatting, using as is.")
+    return time_str
+
+
+@server.tool()
+@handle_http_errors("list_calendars", is_read_only=True, service_type="calendar")
+@require_google_service("calendar", "calendar_read")
+async def list_calendars(service, user_google_email: str) -> str:
+    """
+    Retrieves a list of calendars accessible to the authenticated user.
+
+    Args:
+        user_google_email (str): The user's Google email address. Required.
+
+    Returns:
+        str: A formatted list of the user's calendars (summary, ID, primary status).
+    """
+    logger.info(f"[list_calendars] Invoked. Email: '{user_google_email}'")
+
+    calendar_list_response = await asyncio.to_thread(
+        lambda: service.calendarList().list().execute()
+    )
+    items = calendar_list_response.get("items", [])
+    if not items:
+        return f"No calendars found for {user_google_email}."
+
+    calendars_summary_list = [
+        f'- "{cal.get("summary", "No Summary")}"{" (Primary)" if cal.get("primary") else ""} (ID: {cal["id"]})'
+        for cal in items
+    ]
+    text_output = (
+        f"Successfully listed {len(items)} calendars for {user_google_email}:\n"
+        + "\n".join(calendars_summary_list)
+    )
+    logger.info(f"Successfully listed {len(items)} calendars for {user_google_email}.")
+    return text_output
+
+
+@server.tool()
+@handle_http_errors("get_events", is_read_only=True, service_type="calendar")
+@require_google_service("calendar", "calendar_read")
+async def get_events(
+    service,
+    user_google_email: str,
+    calendar_id: str = "primary",
+    event_id: Optional[str] = None,
+    time_min: Optional[str] = None,
+    time_max: Optional[str] = None,
+    max_results: int = 25,
+    query: Optional[str] = None,
+    detailed: bool = False,
+    include_attachments: bool = False,
+) -> str:
+    """
+    Retrieves events from a specified Google Calendar. Can retrieve a single event by ID or multiple events within a time range.
+    You can also search for events by keyword by supplying the optional "query" param.
+
+    Args:
+        user_google_email (str): The user's Google email address. Required.
+        calendar_id (str): The ID of the calendar to query. Use 'primary' for the user's primary calendar. Defaults to 'primary'. Calendar IDs can be obtained using `list_calendars`.
+        event_id (Optional[str]): The ID of a specific event to retrieve. If provided, retrieves only this event and ignores time filtering parameters.
+        time_min (Optional[str]): The start of the time range (inclusive) in RFC3339 format (e.g., '2024-05-12T10:00:00Z' or '2024-05-12'). If omitted, defaults to the current time. Ignored if event_id is provided.
+        time_max (Optional[str]): The end of the time range (exclusive) in RFC3339 format. If omitted, events starting from `time_min` onwards are considered (up to `max_results`). Ignored if event_id is provided.
+        max_results (int): The maximum number of events to return. Defaults to 25. Ignored if event_id is provided.
+        query (Optional[str]): A keyword to search for within event fields (summary, description, location). Ignored if event_id is provided.
+        detailed (bool): Whether to return detailed event information including description, location, attendees, and attendee details (response status, organizer, optional flags). Defaults to False.
+        include_attachments (bool): Whether to include attachment information in detailed event output. When True, shows attachment details (fileId, fileUrl, mimeType, title) for events that have attachments. Only applies when detailed=True. Set this to True when you need to view or access files that have been attached to calendar events, such as meeting documents, presentations, or other shared files. Defaults to False.
+
+    Returns:
+        str: A formatted list of events (summary, start and end times, link) within the specified range, or detailed information for a single event if event_id is provided.
+    """
+    logger.info(
+        f"[get_events] Raw parameters - event_id: '{event_id}', time_min: '{time_min}', time_max: '{time_max}', query: '{query}', detailed: {detailed}, include_attachments: {include_attachments}"
+    )
+
+    # Handle single event retrieval
+    if event_id:
+        logger.info(f"[get_events] Retrieving single event with ID: {event_id}")
+        event = await asyncio.to_thread(
+            lambda: service.events()
+            .get(calendarId=calendar_id, eventId=event_id)
+            .execute()
+        )
+        items = [event]
+    else:
+        # Handle multiple events retrieval with time filtering
+        # Ensure time_min and time_max are correctly formatted for the API
+        formatted_time_min = _correct_time_format_for_api(time_min, "time_min")
+        if formatted_time_min:
+            effective_time_min = formatted_time_min
+        else:
+            utc_now = datetime.datetime.now(datetime.timezone.utc)
+            effective_time_min = utc_now.isoformat().replace("+00:00", "Z")
+        if time_min is None:
+            logger.info(
+                f"time_min not provided, defaulting to current UTC time: {effective_time_min}"
+            )
+        else:
+            logger.info(
+                f"time_min processing: original='{time_min}', formatted='{formatted_time_min}', effective='{effective_time_min}'"
+            )
+
+        effective_time_max = _correct_time_format_for_api(time_max, "time_max")
+        if time_max:
+            logger.info(
+                f"time_max processing: original='{time_max}', formatted='{effective_time_max}'"
+            )
+
+        logger.info(
+            f"[get_events] Final API parameters - calendarId: '{calendar_id}', timeMin: '{effective_time_min}', timeMax: '{effective_time_max}', maxResults: {max_results}, query: '{query}'"
+        )
+
+        # Build the request parameters dynamically
+        request_params = {
+            "calendarId": calendar_id,
+            "timeMin": effective_time_min,
+            "timeMax": effective_time_max,
+            "maxResults": max_results,
+            "singleEvents": True,
+            "orderBy": "startTime",
+        }
+
+        if query:
+            request_params["q"] = query
+
+        events_result = await asyncio.to_thread(
+            lambda: service.events().list(**request_params).execute()
+        )
+        items = events_result.get("items", [])
+    if not items:
+        if event_id:
+            return f"Event with ID '{event_id}' not found in calendar '{calendar_id}' for {user_google_email}."
+        else:
+            return f"No events found in calendar '{calendar_id}' for {user_google_email} for the specified time range."
+
+    # Handle returning detailed output for a single event when requested
+    if event_id and detailed:
+        item = items[0]
+        summary = item.get("summary", "No Title")
+        start = item["start"].get("dateTime", item["start"].get("date"))
+        end = item["end"].get("dateTime", item["end"].get("date"))
+        link = item.get("htmlLink", "No Link")
+        description = item.get("description", "No Description")
+        location = item.get("location", "No Location")
+        color_id = item.get("colorId", "None")
+        attendees = item.get("attendees", [])
+        attendee_emails = (
+            ", ".join([a.get("email", "") for a in attendees]) if attendees else "None"
+        )
+        attendee_details_str = _format_attendee_details(attendees, indent="  ")
+
+        event_details = (
+            f"Event Details:\n"
+            f"- Title: {summary}\n"
+            f"- Starts: {start}\n"
+            f"- Ends: {end}\n"
+            f"- Description: {description}\n"
+            f"- Location: {location}\n"
+            f"- Color ID: {color_id}\n"
+            f"- Attendees: {attendee_emails}\n"
+            f"- Attendee Details: {attendee_details_str}\n"
+        )
+
+        if include_attachments:
+            attachments = item.get("attachments", [])
+            attachment_details_str = _format_attachment_details(
+                attachments, indent="  "
+            )
+            event_details += f"- Attachments: {attachment_details_str}\n"
+
+        event_details += f"- Event ID: {event_id}\n- Link: {link}"
+        logger.info(
+            f"[get_events] Successfully retrieved detailed event {event_id} for {user_google_email}."
+        )
+        return event_details
+
+    # Handle multiple events or single event with basic output
+    event_details_list = []
+    for item in items:
+        summary = item.get("summary", "No Title")
+        start_time = item["start"].get("dateTime", item["start"].get("date"))
+        end_time = item["end"].get("dateTime", item["end"].get("date"))
+        link = item.get("htmlLink", "No Link")
+        item_event_id = item.get("id", "No ID")
+
+        if detailed:
+            # Add detailed information for multiple events
+            description = item.get("description", "No Description")
+            location = item.get("location", "No Location")
+            attendees = item.get("attendees", [])
+            attendee_emails = (
+                ", ".join([a.get("email", "") for a in attendees])
+                if attendees
+                else "None"
+            )
+            attendee_details_str = _format_attendee_details(attendees, indent="    ")
+
+            event_detail_parts = (
+                f'- "{summary}" (Starts: {start_time}, Ends: {end_time})\n'
+                f"  Description: {description}\n"
+                f"  Location: {location}\n"
+                f"  Attendees: {attendee_emails}\n"
+                f"  Attendee Details: {attendee_details_str}\n"
+            )
+
+            if include_attachments:
+                attachments = item.get("attachments", [])
+                attachment_details_str = _format_attachment_details(
+                    attachments, indent="    "
+                )
+                event_detail_parts += f"  Attachments: {attachment_details_str}\n"
+
+            event_detail_parts += f"  ID: {item_event_id} | Link: {link}"
+            event_details_list.append(event_detail_parts)
+        else:
+            # Basic output format
+            event_details_list.append(
+                f'- "{summary}" (Starts: {start_time}, Ends: {end_time}) ID: {item_event_id} | Link: {link}'
+            )
+
+    if event_id:
+        # Single event basic output
+        text_output = (
+            f"Successfully retrieved event from calendar '{calendar_id}' for {user_google_email}:\n"
+            + "\n".join(event_details_list)
+        )
+    else:
+        # Multiple events output
+        text_output = (
+            f"Successfully retrieved {len(items)} events from calendar '{calendar_id}' for {user_google_email}:\n"
+            + "\n".join(event_details_list)
+        )
+
+    logger.info(f"Successfully retrieved {len(items)} events for {user_google_email}.")
+    return text_output
+
+
+@server.tool()
+@handle_http_errors("create_event", service_type="calendar")
+@require_google_service("calendar", "calendar_events")
+async def create_event(
+    service,
+    user_google_email: str,
+    summary: str,
+    start_time: str,
+    end_time: str,
+    calendar_id: str = "primary",
+    description: Optional[str] = None,
+    location: Optional[str] = None,
+    attendees: Optional[List[str]] = None,
+    timezone: Optional[str] = None,
+    attachments: Optional[List[str]] = None,
+    add_google_meet: bool = False,
+    reminders: Optional[Union[str, List[Dict[str, Any]]]] = None,
+    use_default_reminders: bool = True,
+    transparency: Optional[str] = None,
+    visibility: Optional[str] = None,
+) -> str:
+    """
+    Creates a new event.
+
+    Args:
+        user_google_email (str): The user's Google email address. Required.
+        summary (str): Event title.
+        start_time (str): Start time (RFC3339, e.g., "2023-10-27T10:00:00-07:00" or "2023-10-27" for all-day).
+        end_time (str): End time (RFC3339, e.g., "2023-10-27T11:00:00-07:00" or "2023-10-28" for all-day).
+        calendar_id (str): Calendar ID (default: 'primary').
+        description (Optional[str]): Event description.
+        location (Optional[str]): Event location.
+        attendees (Optional[List[str]]): Attendee email addresses.
+        timezone (Optional[str]): Timezone (e.g., "America/New_York").
+        attachments (Optional[List[str]]): List of Google Drive file URLs or IDs to attach to the event.
+        add_google_meet (bool): Whether to add a Google Meet video conference to the event. Defaults to False.
+        reminders (Optional[Union[str, List[Dict[str, Any]]]]): JSON string or list of reminder objects. Each should have 'method' ("popup" or "email") and 'minutes' (0-40320). Max 5 reminders. Example: '[{"method": "popup", "minutes": 15}]' or [{"method": "popup", "minutes": 15}]
+        use_default_reminders (bool): Whether to use calendar's default reminders. If False, uses custom reminders. Defaults to True.
+        transparency (Optional[str]): Event transparency for busy/free status. "opaque" shows as Busy (default), "transparent" shows as Available/Free. Defaults to None (uses Google Calendar default).
+        visibility (Optional[str]): Event visibility. "default" uses calendar default, "public" is visible to all, "private" is visible only to attendees, "confidential" is same as private (legacy). Defaults to None (uses Google Calendar default).
+
+    Returns:
+        str: Confirmation message of the successful event creation with event link.
+    """
+    logger.info(
+        f"[create_event] Invoked. Email: '{user_google_email}', Summary: {summary}"
+    )
+    logger.info(f"[create_event] Incoming attachments param: {attachments}")
+    # If attachments value is a string, split by comma and strip whitespace
+    if attachments and isinstance(attachments, str):
+        attachments = [a.strip() for a in attachments.split(",") if a.strip()]
+        logger.info(
+            f"[create_event] Parsed attachments list from string: {attachments}"
+        )
+    event_body: Dict[str, Any] = {
+        "summary": summary,
+        "start": (
+            {"date": start_time} if "T" not in start_time else {"dateTime": start_time}
+        ),
+        "end": ({"date": end_time} if "T" not in end_time else {"dateTime": end_time}),
+    }
+    if location:
+        event_body["location"] = location
+    if description:
+        event_body["description"] = description
+    if timezone:
+        if "dateTime" in event_body["start"]:
+            event_body["start"]["timeZone"] = timezone
+        if "dateTime" in event_body["end"]:
+            event_body["end"]["timeZone"] = timezone
+    if attendees:
+        event_body["attendees"] = [{"email": email} for email in attendees]
+
+    # Handle reminders
+    if reminders is not None or not use_default_reminders:
+        # If custom reminders are provided, automatically disable default reminders
+        effective_use_default = use_default_reminders and reminders is None
+
+        reminder_data = {"useDefault": effective_use_default}
+        if reminders is not None:
+            validated_reminders = _parse_reminders_json(reminders, "create_event")
+            if validated_reminders:
+                reminder_data["overrides"] = validated_reminders
+                logger.info(
+                    f"[create_event] Added {len(validated_reminders)} custom reminders"
+                )
+                if use_default_reminders:
+                    logger.info(
+                        "[create_event] Custom reminders provided - disabling default reminders"
+                    )
+
+        event_body["reminders"] = reminder_data
+
+    # Handle transparency validation
+    _apply_transparency_if_valid(event_body, transparency, "create_event")
+
+    # Handle visibility validation
+    _apply_visibility_if_valid(event_body, visibility, "create_event")
+
+    if add_google_meet:
+        request_id = str(uuid.uuid4())
+        event_body["conferenceData"] = {
+            "createRequest": {
+                "requestId": request_id,
+                "conferenceSolutionKey": {"type": "hangoutsMeet"},
+            }
+        }
+        logger.info(
+            f"[create_event] Adding Google Meet conference with request ID: {request_id}"
+        )
+
+    if attachments:
+        # Accept both file URLs and file IDs. If a URL, extract the fileId.
+        event_body["attachments"] = []
+        drive_service = None
+        try:
+            drive_service = service._http and build("drive", "v3", http=service._http)
+        except Exception as e:
+            logger.warning(f"Could not build Drive service for MIME type lookup: {e}")
+        for att in attachments:
+            file_id = None
+            if att.startswith("https://"):
+                # Match /d/<id>, /file/d/<id>, ?id=<id>
+                match = re.search(r"(?:/d/|/file/d/|id=)([\w-]+)", att)
+                file_id = match.group(1) if match else None
+                logger.info(
+                    f"[create_event] Extracted file_id '{file_id}' from attachment URL '{att}'"
+                )
+            else:
+                file_id = att
+                logger.info(
+                    f"[create_event] Using direct file_id '{file_id}' for attachment"
+                )
+            if file_id:
+                file_url = f"https://drive.google.com/open?id={file_id}"
+                mime_type = "application/vnd.google-apps.drive-sdk"
+                title = "Drive Attachment"
+                # Try to get the actual MIME type and filename from Drive
+                if drive_service:
+                    try:
+                        file_metadata = await asyncio.to_thread(
+                            lambda: drive_service.files()
+                            .get(
+                                fileId=file_id,
+                                fields="mimeType,name",
+                                supportsAllDrives=True,
+                            )
+                            .execute()
+                        )
+                        mime_type = file_metadata.get("mimeType", mime_type)
+                        filename = file_metadata.get("name")
+                        if filename:
+                            title = filename
+                            logger.info(
+                                f"[create_event] Using filename '{filename}' as attachment title"
+                            )
+                        else:
+                            logger.info(
+                                "[create_event] No filename found, using generic title"
+                            )
+                    except Exception as e:
+                        logger.warning(
+                            f"Could not fetch metadata for file {file_id}: {e}"
+                        )
+                event_body["attachments"].append(
+                    {
+                        "fileUrl": file_url,
+                        "title": title,
+                        "mimeType": mime_type,
+                    }
+                )
+        created_event = await asyncio.to_thread(
+            lambda: service.events()
+            .insert(
+                calendarId=calendar_id,
+                body=event_body,
+                supportsAttachments=True,
+                conferenceDataVersion=1 if add_google_meet else 0,
+            )
+            .execute()
+        )
+    else:
+        created_event = await asyncio.to_thread(
+            lambda: service.events()
+            .insert(
+                calendarId=calendar_id,
+                body=event_body,
+                conferenceDataVersion=1 if add_google_meet else 0,
+            )
+            .execute()
+        )
+    link = created_event.get("htmlLink", "No link available")
+    confirmation_message = f"Successfully created event '{created_event.get('summary', summary)}' for {user_google_email}. Link: {link}"
+
+    # Add Google Meet information if conference was created
+    if add_google_meet and "conferenceData" in created_event:
+        conference_data = created_event["conferenceData"]
+        if "entryPoints" in conference_data:
+            for entry_point in conference_data["entryPoints"]:
+                if entry_point.get("entryPointType") == "video":
+                    meet_link = entry_point.get("uri", "")
+                    if meet_link:
+                        confirmation_message += f" Google Meet: {meet_link}"
+                        break
+
+    logger.info(
+        f"Event created successfully for {user_google_email}. ID: {created_event.get('id')}, Link: {link}"
+    )
+    return confirmation_message
+
+
+def _normalize_attendees(
+    attendees: Optional[Union[List[str], List[Dict[str, Any]]]],
+) -> Optional[List[Dict[str, Any]]]:
+    """
+    Normalize attendees input to list of attendee objects.
+
+    Accepts either:
+    - List of email strings: ["user@example.com", "other@example.com"]
+    - List of attendee objects: [{"email": "user@example.com", "responseStatus": "accepted"}]
+    - Mixed list of both formats
+
+    Returns list of attendee dicts with at minimum 'email' key.
+    """
+    if attendees is None:
+        return None
+
+    normalized = []
+    for att in attendees:
+        if isinstance(att, str):
+            normalized.append({"email": att})
+        elif isinstance(att, dict) and "email" in att:
+            normalized.append(att)
+        else:
+            logger.warning(
+                f"[_normalize_attendees] Invalid attendee format: {att}, skipping"
+            )
+    return normalized if normalized else None
+
+
+@server.tool()
+@handle_http_errors("modify_event", service_type="calendar")
+@require_google_service("calendar", "calendar_events")
+async def modify_event(
+    service,
+    user_google_email: str,
+    event_id: str,
+    calendar_id: str = "primary",
+    summary: Optional[str] = None,
+    start_time: Optional[str] = None,
+    end_time: Optional[str] = None,
+    description: Optional[str] = None,
+    location: Optional[str] = None,
+    attendees: Optional[Union[List[str], List[Dict[str, Any]]]] = None,
+    timezone: Optional[str] = None,
+    add_google_meet: Optional[bool] = None,
+    reminders: Optional[Union[str, List[Dict[str, Any]]]] = None,
+    use_default_reminders: Optional[bool] = None,
+    transparency: Optional[str] = None,
+    visibility: Optional[str] = None,
+    color_id: Optional[str] = None,
+) -> str:
+    """
+    Modifies an existing event.
+
+    Args:
+        user_google_email (str): The user's Google email address. Required.
+        event_id (str): The ID of the event to modify.
+        calendar_id (str): Calendar ID (default: 'primary').
+        summary (Optional[str]): New event title.
+        start_time (Optional[str]): New start time (RFC3339, e.g., "2023-10-27T10:00:00-07:00" or "2023-10-27" for all-day).
+        end_time (Optional[str]): New end time (RFC3339, e.g., "2023-10-27T11:00:00-07:00" or "2023-10-28" for all-day).
+        description (Optional[str]): New event description.
+        location (Optional[str]): New event location.
+        attendees (Optional[Union[List[str], List[Dict[str, Any]]]]): Attendees as email strings or objects with metadata. Supports: ["email@example.com"] or [{"email": "email@example.com", "responseStatus": "accepted", "organizer": true, "optional": true}]. When using objects, existing metadata (responseStatus, organizer, optional) is preserved. New attendees default to responseStatus="needsAction".
+        timezone (Optional[str]): New timezone (e.g., "America/New_York").
+        add_google_meet (Optional[bool]): Whether to add or remove Google Meet video conference. If True, adds Google Meet; if False, removes it; if None, leaves unchanged.
+        reminders (Optional[Union[str, List[Dict[str, Any]]]]): JSON string or list of reminder objects to replace existing reminders. Each should have 'method' ("popup" or "email") and 'minutes' (0-40320). Max 5 reminders. Example: '[{"method": "popup", "minutes": 15}]' or [{"method": "popup", "minutes": 15}]
+        use_default_reminders (Optional[bool]): Whether to use calendar's default reminders. If specified, overrides current reminder settings.
+        transparency (Optional[str]): Event transparency for busy/free status. "opaque" shows as Busy, "transparent" shows as Available/Free. If None, preserves existing transparency setting.
+        visibility (Optional[str]): Event visibility. "default" uses calendar default, "public" is visible to all, "private" is visible only to attendees, "confidential" is same as private (legacy). If None, preserves existing visibility setting.
+        color_id (Optional[str]): Event color ID (1-11). If None, preserves existing color.
+
+    Returns:
+        str: Confirmation message of the successful event modification with event link.
+    """
+    logger.info(
+        f"[modify_event] Invoked. Email: '{user_google_email}', Event ID: {event_id}"
+    )
+
+    # Build the event body with only the fields that are provided
+    event_body: Dict[str, Any] = {}
+    if summary is not None:
+        event_body["summary"] = summary
+    if start_time is not None:
+        event_body["start"] = (
+            {"date": start_time} if "T" not in start_time else {"dateTime": start_time}
+        )
+        if timezone is not None and "dateTime" in event_body["start"]:
+            event_body["start"]["timeZone"] = timezone
+    if end_time is not None:
+        event_body["end"] = (
+            {"date": end_time} if "T" not in end_time else {"dateTime": end_time}
+        )
+        if timezone is not None and "dateTime" in event_body["end"]:
+            event_body["end"]["timeZone"] = timezone
+    if description is not None:
+        event_body["description"] = description
+    if location is not None:
+        event_body["location"] = location
+
+    # Normalize attendees - accepts both email strings and full attendee objects
+    normalized_attendees = _normalize_attendees(attendees)
+    if normalized_attendees is not None:
+        event_body["attendees"] = normalized_attendees
+
+    if color_id is not None:
+        event_body["colorId"] = color_id
+
+    # Handle reminders
+    if reminders is not None or use_default_reminders is not None:
+        reminder_data = {}
+        if use_default_reminders is not None:
+            reminder_data["useDefault"] = use_default_reminders
+        else:
+            # Preserve existing event's useDefault value if not explicitly specified
+            try:
+                existing_event = (
+                    service.events()
+                    .get(calendarId=calendar_id, eventId=event_id)
+                    .execute()
+                )
+                reminder_data["useDefault"] = existing_event.get("reminders", {}).get(
+                    "useDefault", True
+                )
+            except Exception as e:
+                logger.warning(
+                    f"[modify_event] Could not fetch existing event for reminders: {e}"
+                )
+                reminder_data["useDefault"] = (
+                    True  # Fallback to True if unable to fetch
+                )
+
+        # If custom reminders are provided, automatically disable default reminders
+        if reminders is not None:
+            if reminder_data.get("useDefault", False):
+                reminder_data["useDefault"] = False
+                logger.info(
+                    "[modify_event] Custom reminders provided - disabling default reminders"
+                )
+
+            validated_reminders = _parse_reminders_json(reminders, "modify_event")
+            if reminders and not validated_reminders:
+                logger.warning(
+                    "[modify_event] Reminders provided but failed validation. No custom reminders will be set."
+                )
+            elif validated_reminders:
+                reminder_data["overrides"] = validated_reminders
+                logger.info(
+                    f"[modify_event] Updated reminders with {len(validated_reminders)} custom reminders"
+                )
+
+        event_body["reminders"] = reminder_data
+
+    # Handle transparency validation
+    _apply_transparency_if_valid(event_body, transparency, "modify_event")
+
+    # Handle visibility validation
+    _apply_visibility_if_valid(event_body, visibility, "modify_event")
+
+    if timezone is not None and "start" not in event_body and "end" not in event_body:
+        # If timezone is provided but start/end times are not, we need to fetch the existing event
+        # to apply the timezone correctly. This is a simplification; a full implementation
+        # might handle this more robustly or require start/end with timezone.
+        # For now, we'll log a warning and skip applying timezone if start/end are missing.
+        logger.warning(
+            "[modify_event] Timezone provided but start_time and end_time are missing. Timezone will not be applied unless start/end times are also provided."
+        )
+
+    if not event_body:
+        message = "No fields provided to modify the event."
+        logger.warning(f"[modify_event] {message}")
+        raise Exception(message)
+
+    # Log the event ID for debugging
+    logger.info(
+        f"[modify_event] Attempting to update event with ID: '{event_id}' in calendar '{calendar_id}'"
+    )
+
+    # Get the existing event to preserve fields that aren't being updated
+    try:
+        existing_event = await asyncio.to_thread(
+            lambda: service.events()
+            .get(calendarId=calendar_id, eventId=event_id)
+            .execute()
+        )
+        logger.info(
+            "[modify_event] Successfully retrieved existing event before update"
+        )
+
+        # Preserve existing fields if not provided in the update
+        _preserve_existing_fields(
+            event_body,
+            existing_event,
+            {
+                "summary": summary,
+                "description": description,
+                "location": location,
+                # Use the already-normalized attendee objects (if provided); otherwise preserve existing
+                "attendees": event_body.get("attendees"),
+                "colorId": event_body.get("colorId"),
+            },
+        )
+
+        # Handle Google Meet conference data
+        if add_google_meet is not None:
+            if add_google_meet:
+                # Add Google Meet
+                request_id = str(uuid.uuid4())
+                event_body["conferenceData"] = {
+                    "createRequest": {
+                        "requestId": request_id,
+                        "conferenceSolutionKey": {"type": "hangoutsMeet"},
+                    }
+                }
+                logger.info(
+                    f"[modify_event] Adding Google Meet conference with request ID: {request_id}"
+                )
+            else:
+                # Remove Google Meet by setting conferenceData to empty
+                event_body["conferenceData"] = {}
+                logger.info("[modify_event] Removing Google Meet conference")
+        elif "conferenceData" in existing_event:
+            # Preserve existing conference data if not specified
+            event_body["conferenceData"] = existing_event["conferenceData"]
+            logger.info("[modify_event] Preserving existing conference data")
+
+    except HttpError as get_error:
+        if get_error.resp.status == 404:
+            logger.error(
+                f"[modify_event] Event not found during pre-update verification: {get_error}"
+            )
+            message = f"Event not found during verification. The event with ID '{event_id}' could not be found in calendar '{calendar_id}'. This may be due to incorrect ID format or the event no longer exists."
+            raise Exception(message)
+        else:
+            logger.warning(
+                f"[modify_event] Error during pre-update verification, but proceeding with update: {get_error}"
+            )
+
+    # Proceed with the update
+    updated_event = await asyncio.to_thread(
+        lambda: service.events()
+        .update(
+            calendarId=calendar_id,
+            eventId=event_id,
+            body=event_body,
+            conferenceDataVersion=1,
+        )
+        .execute()
+    )
+
+    link = updated_event.get("htmlLink", "No link available")
+    confirmation_message = f"Successfully modified event '{updated_event.get('summary', summary)}' (ID: {event_id}) for {user_google_email}. Link: {link}"
+
+    # Add Google Meet information if conference was added
+    if add_google_meet is True and "conferenceData" in updated_event:
+        conference_data = updated_event["conferenceData"]
+        if "entryPoints" in conference_data:
+            for entry_point in conference_data["entryPoints"]:
+                if entry_point.get("entryPointType") == "video":
+                    meet_link = entry_point.get("uri", "")
+                    if meet_link:
+                        confirmation_message += f" Google Meet: {meet_link}"
+                        break
+    elif add_google_meet is False:
+        confirmation_message += " (Google Meet removed)"
+
+    logger.info(
+        f"Event modified successfully for {user_google_email}. ID: {updated_event.get('id')}, Link: {link}"
+    )
+    return confirmation_message
+
+
+@server.tool()
+@handle_http_errors("delete_event", service_type="calendar")
+@require_google_service("calendar", "calendar_events")
+async def delete_event(
+    service, user_google_email: str, event_id: str, calendar_id: str = "primary"
+) -> str:
+    """
+    Deletes an existing event.
+
+    Args:
+        user_google_email (str): The user's Google email address. Required.
+        event_id (str): The ID of the event to delete.
+        calendar_id (str): Calendar ID (default: 'primary').
+
+    Returns:
+        str: Confirmation message of the successful event deletion.
+    """
+    logger.info(
+        f"[delete_event] Invoked. Email: '{user_google_email}', Event ID: {event_id}"
+    )
+
+    # Log the event ID for debugging
+    logger.info(
+        f"[delete_event] Attempting to delete event with ID: '{event_id}' in calendar '{calendar_id}'"
+    )
+
+    # Try to get the event first to verify it exists
+    try:
+        await asyncio.to_thread(
+            lambda: service.events()
+            .get(calendarId=calendar_id, eventId=event_id)
+            .execute()
+        )
+        logger.info("[delete_event] Successfully verified event exists before deletion")
+    except HttpError as get_error:
+        if get_error.resp.status == 404:
+            logger.error(
+                f"[delete_event] Event not found during pre-delete verification: {get_error}"
+            )
+            message = f"Event not found during verification. The event with ID '{event_id}' could not be found in calendar '{calendar_id}'. This may be due to incorrect ID format or the event no longer exists."
+            raise Exception(message)
+        else:
+            logger.warning(
+                f"[delete_event] Error during pre-delete verification, but proceeding with deletion: {get_error}"
+            )
+
+    # Proceed with the deletion
+    await asyncio.to_thread(
+        lambda: service.events()
+        .delete(calendarId=calendar_id, eventId=event_id)
+        .execute()
+    )
+
+    confirmation_message = f"Successfully deleted event (ID: {event_id}) from calendar '{calendar_id}' for {user_google_email}."
+    logger.info(f"Event deleted successfully for {user_google_email}. ID: {event_id}")
+    return confirmation_message

gchat/__init__.py

@@ -0,0 +1,7 @@
+"""
+Google Chat MCP Tools Package
+"""
+
+from . import chat_tools
+
+__all__ = ["chat_tools"]

gchat/chat_tools.py

@@ -0,0 +1,223 @@
+"""
+Google Chat MCP Tools
+
+This module provides MCP tools for interacting with Google Chat API.
+"""
+
+import logging
+import asyncio
+from typing import Optional
+
+from googleapiclient.errors import HttpError
+
+# Auth & server utilities
+from auth.service_decorator import require_google_service
+from core.server import server
+from core.utils import handle_http_errors
+
+logger = logging.getLogger(__name__)
+
+
+@server.tool()
+@require_google_service("chat", "chat_read")
+@handle_http_errors("list_spaces", service_type="chat")
+async def list_spaces(
+    service,
+    user_google_email: str,
+    page_size: int = 100,
+    space_type: str = "all",  # "all", "room", "dm"
+) -> str:
+    """
+    Lists Google Chat spaces (rooms and direct messages) accessible to the user.
+
+    Returns:
+        str: A formatted list of Google Chat spaces accessible to the user.
+    """
+    logger.info(f"[list_spaces] Email={user_google_email}, Type={space_type}")
+
+    # Build filter based on space_type
+    filter_param = None
+    if space_type == "room":
+        filter_param = "spaceType = SPACE"
+    elif space_type == "dm":
+        filter_param = "spaceType = DIRECT_MESSAGE"
+
+    request_params = {"pageSize": page_size}
+    if filter_param:
+        request_params["filter"] = filter_param
+
+    response = await asyncio.to_thread(service.spaces().list(**request_params).execute)
+
+    spaces = response.get("spaces", [])
+    if not spaces:
+        return f"No Chat spaces found for type '{space_type}'."
+
+    output = [f"Found {len(spaces)} Chat spaces (type: {space_type}):"]
+    for space in spaces:
+        space_name = space.get("displayName", "Unnamed Space")
+        space_id = space.get("name", "")
+        space_type_actual = space.get("spaceType", "UNKNOWN")
+        output.append(f"- {space_name} (ID: {space_id}, Type: {space_type_actual})")
+
+    return "\n".join(output)
+
+
+@server.tool()
+@require_google_service("chat", "chat_read")
+@handle_http_errors("get_messages", service_type="chat")
+async def get_messages(
+    service,
+    user_google_email: str,
+    space_id: str,
+    page_size: int = 50,
+    order_by: str = "createTime desc",
+) -> str:
+    """
+    Retrieves messages from a Google Chat space.
+
+    Returns:
+        str: Formatted messages from the specified space.
+    """
+    logger.info(f"[get_messages] Space ID: '{space_id}' for user '{user_google_email}'")
+
+    # Get space info first
+    space_info = await asyncio.to_thread(service.spaces().get(name=space_id).execute)
+    space_name = space_info.get("displayName", "Unknown Space")
+
+    # Get messages
+    response = await asyncio.to_thread(
+        service.spaces()
+        .messages()
+        .list(parent=space_id, pageSize=page_size, orderBy=order_by)
+        .execute
+    )
+
+    messages = response.get("messages", [])
+    if not messages:
+        return f"No messages found in space '{space_name}' (ID: {space_id})."
+
+    output = [f"Messages from '{space_name}' (ID: {space_id}):\n"]
+    for msg in messages:
+        sender = msg.get("sender", {}).get("displayName", "Unknown Sender")
+        create_time = msg.get("createTime", "Unknown Time")
+        text_content = msg.get("text", "No text content")
+        msg_name = msg.get("name", "")
+
+        output.append(f"[{create_time}] {sender}:")
+        output.append(f"  {text_content}")
+        output.append(f"  (Message ID: {msg_name})\n")
+
+    return "\n".join(output)
+
+
+@server.tool()
+@require_google_service("chat", "chat_write")
+@handle_http_errors("send_message", service_type="chat")
+async def send_message(
+    service,
+    user_google_email: str,
+    space_id: str,
+    message_text: str,
+    thread_key: Optional[str] = None,
+) -> str:
+    """
+    Sends a message to a Google Chat space.
+
+    Returns:
+        str: Confirmation message with sent message details.
+    """
+    logger.info(f"[send_message] Email: '{user_google_email}', Space: '{space_id}'")
+
+    message_body = {"text": message_text}
+
+    # Add thread key if provided (for threaded replies)
+    request_params = {"parent": space_id, "body": message_body}
+    if thread_key:
+        request_params["threadKey"] = thread_key
+
+    message = await asyncio.to_thread(
+        service.spaces().messages().create(**request_params).execute
+    )
+
+    message_name = message.get("name", "")
+    create_time = message.get("createTime", "")
+
+    msg = f"Message sent to space '{space_id}' by {user_google_email}. Message ID: {message_name}, Time: {create_time}"
+    logger.info(
+        f"Successfully sent message to space '{space_id}' by {user_google_email}"
+    )
+    return msg
+
+
+@server.tool()
+@require_google_service("chat", "chat_read")
+@handle_http_errors("search_messages", service_type="chat")
+async def search_messages(
+    service,
+    user_google_email: str,
+    query: str,
+    space_id: Optional[str] = None,
+    page_size: int = 25,
+) -> str:
+    """
+    Searches for messages in Google Chat spaces by text content.
+
+    Returns:
+        str: A formatted list of messages matching the search query.
+    """
+    logger.info(f"[search_messages] Email={user_google_email}, Query='{query}'")
+
+    # If specific space provided, search within that space
+    if space_id:
+        response = await asyncio.to_thread(
+            service.spaces()
+            .messages()
+            .list(parent=space_id, pageSize=page_size, filter=f'text:"{query}"')
+            .execute
+        )
+        messages = response.get("messages", [])
+        context = f"space '{space_id}'"
+    else:
+        # Search across all accessible spaces (this may require iterating through spaces)
+        # For simplicity, we'll search the user's spaces first
+        spaces_response = await asyncio.to_thread(
+            service.spaces().list(pageSize=100).execute
+        )
+        spaces = spaces_response.get("spaces", [])
+
+        messages = []
+        for space in spaces[:10]:  # Limit to first 10 spaces to avoid timeout
+            try:
+                space_messages = await asyncio.to_thread(
+                    service.spaces()
+                    .messages()
+                    .list(
+                        parent=space.get("name"), pageSize=5, filter=f'text:"{query}"'
+                    )
+                    .execute
+                )
+                space_msgs = space_messages.get("messages", [])
+                for msg in space_msgs:
+                    msg["_space_name"] = space.get("displayName", "Unknown")
+                messages.extend(space_msgs)
+            except HttpError:
+                continue  # Skip spaces we can't access
+        context = "all accessible spaces"
+
+    if not messages:
+        return f"No messages found matching '{query}' in {context}."
+
+    output = [f"Found {len(messages)} messages matching '{query}' in {context}:"]
+    for msg in messages:
+        sender = msg.get("sender", {}).get("displayName", "Unknown Sender")
+        create_time = msg.get("createTime", "Unknown Time")
+        text_content = msg.get("text", "No text content")
+        space_name = msg.get("_space_name", "Unknown Space")
+
+        # Truncate long messages
+        if len(text_content) > 100:
+            text_content = text_content[:100] + "..."
+
+        output.append(f"- [{create_time}] {sender} in '{space_name}': {text_content}")
+
+    return "\n".join(output)