Merge branch 'main' into dev

Author: cfdude

.gitignore

@@ -2,8 +2,6 @@
 __pycache__/
 *.py[cod]
 *.so
-.mcp.json
-claude.md
 
 # ---- Packaging ---------------------------------------------------------
 *.egg-info/
@@ -22,6 +20,7 @@ venv/
 
 # ---- Secrets -----------------------------------------------------------
 client_secret.json
+.mcp.json
 
 # ---- Logs --------------------------------------------------------------
 mcp_server_debug.log

CLAUDE.md

@@ -0,0 +1,92 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Common Commands
+
+### Development
+- `uv run main.py` - Start server in stdio mode (default for MCP clients)
+- `uv run main.py --transport streamable-http` - Start server in HTTP mode for debugging
+- `uv run main.py --single-user` - Run in single-user mode (bypass session mapping)
+- `uv run main.py --tools gmail drive calendar` - Start with specific tools only
+
+### Installation & Setup
+- `python install_claude.py` - Auto-install MCP server configuration in Claude Desktop
+- `uvx workspace-mcp` - Run directly via uvx without local installation
+
+### Docker
+- `docker build -t workspace-mcp .`
+- `docker run -p 8000:8000 -v $(pwd):/app workspace-mcp --transport streamable-http`
+
+## Architecture Overview
+
+This is a comprehensive Google Workspace MCP server built with FastMCP. The architecture follows a modular design pattern:
+
+### Core Components
+- **`main.py`** - Entry point with argument parsing and tool module loading
+- **`core/server.py`** - FastMCP server configuration with OAuth callback handling  
+- **`core/utils.py`** - Shared utilities and credential directory management
+
+### Authentication System (`auth/`)
+- **Service Decorator Pattern**: Uses `@require_google_service()` decorators for automatic authentication
+- **OAuth 2.0 Flow**: Transport-aware callback handling (stdio mode starts minimal HTTP server on port 8000)
+- **Service Caching**: 30-minute TTL to reduce authentication overhead
+- **Session Management**: Maps OAuth state to MCP session IDs for multi-user support
+- **Scope Management**: Centralized scope definitions in `auth/scopes.py` with predefined scope groups
+
+### Service Modules
+Each Google service has its own module in `g{service}/` format:
+- `gcalendar/` - Google Calendar API integration
+- `gdrive/` - Google Drive API with Office format support  
+- `gmail/` - Gmail API for email management
+- `gdocs/` - Google Docs API operations with full editing support
+- `gsheets/` - Google Sheets API with cell operations
+- `gforms/` - Google Forms creation and response management
+- `gchat/` - Google Chat/Spaces messaging
+- `gslides/` - Google Slides presentation management
+
+### Key Patterns
+- **Service Injection**: The `@require_google_service(service_name, scope_group)` decorator automatically injects authenticated Google API service objects
+- **Multi-Service Support**: Use `@require_multiple_services()` for tools needing multiple Google services
+- **Error Handling**: Native Python exceptions are automatically converted to MCP errors
+- **Transport Modes**: Supports both stdio (for MCP clients) and streamable-http (for debugging/web interfaces)
+
+### Configuration
+- Environment variables: `WORKSPACE_MCP_PORT` (default: 8000), `WORKSPACE_MCP_BASE_URI` (default: http://localhost)
+- OAuth credentials: `client_secret.json` in project root or set `GOOGLE_CLIENT_SECRETS` env var
+- Single-user mode: Set `MCP_SINGLE_USER_MODE=1` or use `--single-user` flag
+
+### Tool Development
+When adding new tools:
+1. Use appropriate service decorator: `@require_google_service("service_name", "scope_group")`
+2. Service object is automatically injected as first parameter
+3. Return native Python objects (automatic JSON serialization)
+4. Follow existing naming patterns in scope groups from `auth/scopes.py`
+5. Add service configuration to `SERVICE_CONFIGS` in `auth/service_decorator.py`
+
+## Google Docs Editing Capabilities
+
+The Google Docs integration now supports comprehensive document editing through these tools:
+
+### Core Text Operations
+- `update_doc_text` - Insert or replace text at specific positions
+- `find_and_replace_doc` - Find and replace text throughout the document
+- `format_doc_text` - Apply text formatting (bold, italic, underline, font size/family)
+
+### Structural Elements
+- `insert_doc_elements` - Add tables, lists, or page breaks
+- `insert_doc_image` - Insert images from Google Drive or URLs
+- `update_doc_headers_footers` - Modify document headers and footers
+
+### Advanced Operations
+- `batch_update_doc` - Execute multiple document operations atomically
+
+### Helper Functions
+The `gdocs/docs_helpers.py` module provides utility functions for:
+- Building text style objects
+- Creating API request structures
+- Validating batch operations
+- Extracting document text
+- Calculating text indices
+
+These tools use the Google Docs API's batchUpdate method for efficient, atomic document modifications. All editing operations require the `docs_write` scope which is already configured in the authentication system.

auth/service_decorator.py

@@ -552,18 +552,29 @@ async def get_doc_with_metadata(drive_service, docs_service, user_google_email:
     """
 
     def decorator(func: Callable) -> Callable:
+        # Inspect the original function signature
+        original_sig = inspect.signature(func)
+        params = list(original_sig.parameters.values())
+        
+        # Create list of service parameter names that will be injected
+        service_param_names = [config["param_name"] for config in service_configs]
+        
+        # Filter out the service parameters from the original signature
+        # to create the wrapper signature that MCP will see
+        wrapper_params = [p for p in params if p.name not in service_param_names]
+        wrapper_sig = original_sig.replace(parameters=wrapper_params)
+        
         @wraps(func)
         async def wrapper(*args, **kwargs):
-            # Extract user_google_email
-            sig = inspect.signature(func)
-            param_names = list(sig.parameters.keys())
-
+            # Extract user_google_email - use robust approach that works with injected services
+            original_param_names = list(original_sig.parameters.keys())
             user_google_email = None
             if "user_google_email" in kwargs:
                 user_google_email = kwargs["user_google_email"]
             else:
+                # Look for user_google_email in positional args using original function signature
                 try:
-                    user_email_index = param_names.index("user_google_email")
+                    user_email_index = original_param_names.index('user_google_email')
                     if user_email_index < len(args):
                         user_google_email = args[user_email_index]
                 except ValueError:
@@ -605,7 +616,7 @@ async def wrapper(*args, **kwargs):
                         user_google_email,
                         args,
                         kwargs,
-                        param_names,
+                        original_param_names,
                         tool_name,
                         service_type,
                     )
@@ -642,6 +653,9 @@ async def wrapper(*args, **kwargs):
                 )
                 raise Exception(error_message)
 
+        # Set the wrapper's signature to the one without service parameters
+        # This is critical for MCP compatibility
+        wrapper.__signature__ = wrapper_sig
         return wrapper
 
     return decorator

core/tool_tiers.yaml

@@ -50,6 +50,8 @@ docs:
     - insert_doc_elements
   complete:
     - insert_doc_image
+    - insert_doc_image_from_drive
+    - insert_doc_image_url
     - update_doc_headers_footers
     - batch_update_doc
     - inspect_doc_structure

gdocs/docs_tools.py

@@ -295,7 +295,7 @@ async def create_doc(
     doc = await asyncio.to_thread(service.documents().create(body={'title': title}).execute)
     doc_id = doc.get('documentId')
     if content:
-        requests = [{'insertText': {'location': {'index': 1}, 'text': content}}]
+        requests = [create_insert_text_request(1, content)]
         await asyncio.to_thread(service.documents().batchUpdate(documentId=doc_id, body={'requests': requests}).execute)
     link = f"https://docs.google.com/document/d/{doc_id}/edit"
     msg = f"Created Google Doc '{title}' (ID: {doc_id}) for {user_google_email}. Link: {link}"
@@ -626,10 +626,8 @@ async def insert_doc_image(
     else:
         image_uri = image_source
         source_description = "URL image"
-
     # Use helper to create image request
     requests = [create_insert_image_request(index, image_uri, width, height)]
-
     await asyncio.to_thread(
         docs_service.documents().batchUpdate(
             documentId=document_id,
@@ -644,6 +642,160 @@ async def insert_doc_image(
     link = f"https://docs.google.com/document/d/{document_id}/edit"
     return f"Inserted {source_description}{size_info} at index {index} in document {document_id}. Link: {link}"
 
+@server.tool()
+@handle_http_errors("insert_doc_image_from_drive", service_type="docs")
+@require_multiple_services([
+    {"service_type": "drive", "scopes": "drive_read", "param_name": "drive_service"},
+    {"service_type": "docs", "scopes": "docs_write", "param_name": "docs_service"}
+])
+async def insert_doc_image_from_drive(
+    drive_service,
+    docs_service,
+    user_google_email: str,
+    document_id: str,
+    drive_file_name: str,
+    index: int,
+    width: int = None,
+    height: int = None,
+) -> str:
+    """
+    Searches for an image in Google Drive by name and inserts it into a Google Doc.
+    Checks permissions first and provides helpful error messages if the image isn't publicly shared.
+    
+    Args:
+        user_google_email: User's Google email address
+        document_id: ID of the document to update
+        drive_file_name: Name of the image file in Google Drive (e.g., "product_roadmap_2025.png")
+        index: Position to insert image (0-based)
+        width: Image width in points (optional)
+        height: Image height in points (optional)
+    
+    Returns:
+        str: Confirmation message with insertion details or error with instructions
+    """
+    logger.info(f"[insert_doc_image_from_drive] Doc={document_id}, file={drive_file_name}, index={index}")
+    
+    # Build search query for the specific file name
+    escaped_name = drive_file_name.replace("'", "\\'")
+    search_query = f"name = '{escaped_name}'"
+    
+    # Search for the file in Drive with permission information
+    list_params = {
+        "q": search_query,
+        "pageSize": 5,
+        "fields": "files(id, name, mimeType, webViewLink, permissions, shared)",
+        "supportsAllDrives": True,
+        "includeItemsFromAllDrives": True,
+    }
+    
+    search_results = await asyncio.to_thread(
+        drive_service.files().list(**list_params).execute
+    )
+    
+    files = search_results.get('files', [])
+    if not files:
+        return f"❌ Error: File '{drive_file_name}' not found in Google Drive"
+    
+    # Use the first matching file
+    file_info = files[0]
+    file_id = file_info.get('id')
+    file_name = file_info.get('name')
+    mime_type = file_info.get('mimeType', '')
+    
+    # Check if it's an image file
+    if not mime_type.startswith('image/'):
+        logger.warning(f"File '{drive_file_name}' has MIME type '{mime_type}' which may not be an image")
+    
+    # Check permissions to see if file has "anyone with link" permission
+    from gdrive.drive_helpers import check_public_link_permission
+    permissions = file_info.get('permissions', [])
+    has_public_link = check_public_link_permission(permissions)
+    
+    if not has_public_link:
+        from gdrive.drive_helpers import format_public_sharing_error
+        return format_public_sharing_error(file_name, file_id)
+    
+    # File has public access - proceed with insertion
+    from gdrive.drive_helpers import get_drive_image_url
+    image_uri = get_drive_image_url(file_id)
+    
+    # Use helper function to create request
+    request = create_insert_image_request(index, image_uri, width, height)
+    requests = [request]
+    
+    try:
+        await asyncio.to_thread(
+            docs_service.documents().batchUpdate(
+                documentId=document_id,
+                body={'requests': requests}
+            ).execute
+        )
+        
+        size_info = ""
+        if width or height:
+            size_info = f" (size: {width or 'auto'}x{height or 'auto'} points)"
+        
+        link = f"https://docs.google.com/document/d/{document_id}/edit"
+        return f"✅ Successfully inserted Drive image '{file_name}' (ID: {file_id}){size_info} at index {index} in document {document_id}. Link: {link}"
+        
+    except Exception as e:
+        error_str = str(e)
+        if "publicly accessible" in error_str or "forbidden" in error_str.lower():
+            return f"❌ API Error: Drive image '{file_name}' access denied despite public sharing. May need propagation time or use insert_doc_image_url with: {get_drive_image_url(file_id)}"
+        else:
+            # Some other error occurred
+            return f"❌ Error inserting image '{file_name}': {e}"
+
+@server.tool()
+@handle_http_errors("insert_doc_image_url", service_type="docs")
+@require_google_service("docs", "docs_write")
+async def insert_doc_image_url(
+    service,
+    user_google_email: str,
+    document_id: str,
+    image_url: str,
+    index: int,
+    width: int = None,
+    height: int = None,
+) -> str:
+    """
+    Inserts an image from a URL into a Google Doc.
+    Simplified version that only works with URLs, not Drive files.
+    
+    Args:
+        user_google_email: User's Google email address
+        document_id: ID of the document to update
+        image_url: Public image URL (must start with http:// or https://)
+        index: Position to insert image (0-based)
+        width: Image width in points (optional)
+        height: Image height in points (optional)
+    
+    Returns:
+        str: Confirmation message with insertion details
+    """
+    logger.info(f"[insert_doc_image_url] Doc={document_id}, url={image_url}, index={index}")
+    
+    if not (image_url.startswith('http://') or image_url.startswith('https://')):
+        return "Error: image_url must be a valid HTTP/HTTPS URL"
+    
+    # Use helper function to create request
+    request = create_insert_image_request(index, image_url, width, height)
+    requests = [request]
+    
+    await asyncio.to_thread(
+        service.documents().batchUpdate(
+            documentId=document_id,
+            body={'requests': requests}
+        ).execute
+    )
+    
+    size_info = ""
+    if width or height:
+        size_info = f" (size: {width or 'auto'}x{height or 'auto'} points)"
+    
+    link = f"https://docs.google.com/document/d/{document_id}/edit"
+    return f"Inserted image from URL{size_info} at index {index} in document {document_id}. Link: {link}"
+
 @server.tool()
 @handle_http_errors("update_doc_headers_footers", service_type="docs")
 @require_google_service("docs", "docs_write")