workspace-mcp 1.0.2__tar.gz → 1.0.3__tar.gz

{workspace_mcp-1.0.2 → workspace_mcp-1.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: workspace-mcp
-Version: 1.0.2
+Version: 1.0.3
 Summary: Comprehensive, highly performant Google Workspace Streamable HTTP & SSE MCP Server for Calendar, Gmail, Docs, Sheets, Slides & Drive
 Author-email: Taylor Wilsdon <taylor@taylorwilsdon.com>
 License: MIT
@@ -76,6 +76,20 @@ Dynamic: license-file
 
 ---
 
+## AI-Enhanced Documentation
+
+> **This README was crafted with AI assistance, and here's why that matters**
+> 
+> When people dismiss documentation as "AI-generated," they're missing the bigger picture
+
+As a solo developer building open source tools that may only ever serve my own needs, comprehensive documentation often wouldn't happen without AI help. When done right—using agents like **Roo** or **Claude Code** that understand the entire codebase, AI doesn't just regurgitate generic content - it extracts real implementation details and creates accurate, specific documentation.
+
+**The alternative? No docs at all.** 
+
+I hope the community can appreciate these tools for what they enable: solo developers maintaining professional documentation standards while focusing on building great software.
+
+---
+*This documentation was enhanced by AI with full codebase context. The result? You're reading docs that otherwise might not exist.*
 
 ## 🌐 Overview
 
@@ -102,9 +116,13 @@ A production-ready MCP server that integrates all major Google Workspace service
 
 ### Simplest Start (uvx - Recommended)
 
-Run instantly without installation:
+> Run instantly without manual installation - you must configure OAuth credentials when using uvx. You can use either environment variables (recommended for production) or set the `GOOGLE_CLIENT_SECRET_PATH` (or legacy `GOOGLE_CLIENT_SECRETS`) environment variable to point to your `client_secret.json` file.
 
 ```bash
+# Set OAuth credentials via environment variables (recommended)
+export GOOGLE_OAUTH_CLIENT_ID="your-client-id.apps.googleusercontent.com"
+export GOOGLE_OAUTH_CLIENT_SECRET="your-client-secret"
+
 # Start the server with all Google Workspace tools
 uvx workspace-mcp
 
@@ -138,9 +156,31 @@ uv run main.py
 1. **Google Cloud Setup**:
    - Create OAuth 2.0 credentials (web application) in [Google Cloud Console](https://console.cloud.google.com/)
    - Enable APIs: Calendar, Drive, Gmail, Docs, Sheets, Slides, Forms, Chat
-   - Download credentials as `client_secret.json` in project root
-     - To use a different location for `client_secret.json`, you can set the `GOOGLE_CLIENT_SECRETS` environment variable with that path
    - Add redirect URI: `http://localhost:8000/oauth2callback`
+   - Configure credentials using one of these methods:
+
+     **Option A: Environment Variables (Recommended for Production)**
+     ```bash
+     export GOOGLE_OAUTH_CLIENT_ID="your-client-id.apps.googleusercontent.com"
+     export GOOGLE_OAUTH_CLIENT_SECRET="your-client-secret"
+     export GOOGLE_OAUTH_REDIRECT_URI="http://localhost:8000/oauth2callback"  # Optional
+     ```
+
+     **Option B: File-based (Traditional)**
+     - Download credentials as `client_secret.json` in project root
+     - To use a different location, set `GOOGLE_CLIENT_SECRET_PATH` (or legacy `GOOGLE_CLIENT_SECRETS`) environment variable with the file path
+
+   **Credential Loading Priority**:
+   1. Environment variables (`GOOGLE_OAUTH_CLIENT_ID`, `GOOGLE_OAUTH_CLIENT_SECRET`)
+   2. File specified by `GOOGLE_CLIENT_SECRET_PATH` or `GOOGLE_CLIENT_SECRETS` environment variable
+   3. Default file (`client_secret.json` in project root)
+
+   **Why Environment Variables?**
+   - ✅ Containerized deployments (Docker, Kubernetes)
+   - ✅ Cloud platforms (Heroku, Railway, etc.)
+   - ✅ CI/CD pipelines
+   - ✅ No secrets in version control
+   - ✅ Easy credential rotation
 
 2. **Environment**:
    ```bash
@@ -198,7 +238,11 @@ python install_claude.py
   "mcpServers": {
     "google_workspace": {
       "command": "uvx",
-      "args": ["workspace-mcp"]
+      "args": ["workspace-mcp"],
+      "env": {
+        "GOOGLE_OAUTH_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
+        "GOOGLE_OAUTH_CLIENT_SECRET": "your-client-secret"
+      }
     }
   }
 }
@@ -211,7 +255,11 @@ python install_claude.py
     "google_workspace": {
       "command": "uv",
       "args": ["run", "main.py"],
-      "cwd": "/path/to/google_workspace_mcp"
+      "cwd": "/path/to/google_workspace_mcp",
+      "env": {
+        "GOOGLE_OAUTH_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
+        "GOOGLE_OAUTH_CLIENT_SECRET": "your-client-secret"
+      }
     }
   }
 }
@@ -259,7 +307,8 @@ When calling a tool:
 |------|-------------|
 | `list_calendars` | List accessible calendars |
 | `get_events` | Retrieve events with time range filtering |
-| `create_event` | Create events (all-day or timed) |
+| `get_event` | Fetch detailed information of a single event by ID |
+| `create_event` | Create events (all-day or timed) with optional Drive file attachments |
 | `modify_event` | Update existing events |
 | `delete_event` | Remove events |
 
@@ -270,7 +319,7 @@ When calling a tool:
 | `search_drive_files` | Search files with query syntax |
 | `get_drive_file_content` | Read file content (supports Office formats) |
 | `list_drive_items` | List folder contents |
-| `create_drive_file` | Create new files |
+| `create_drive_file` | Create new files or fetch content from public URLs |
 
 ### 📧 Gmail ([`gmail_tools.py`](gmail/gmail_tools.py))
 

{workspace_mcp-1.0.2 → workspace_mcp-1.0.3}/README.md

@@ -34,6 +34,20 @@
 
 ---
 
+## AI-Enhanced Documentation
+
+> **This README was crafted with AI assistance, and here's why that matters**
+> 
+> When people dismiss documentation as "AI-generated," they're missing the bigger picture
+
+As a solo developer building open source tools that may only ever serve my own needs, comprehensive documentation often wouldn't happen without AI help. When done right—using agents like **Roo** or **Claude Code** that understand the entire codebase, AI doesn't just regurgitate generic content - it extracts real implementation details and creates accurate, specific documentation.
+
+**The alternative? No docs at all.** 
+
+I hope the community can appreciate these tools for what they enable: solo developers maintaining professional documentation standards while focusing on building great software.
+
+---
+*This documentation was enhanced by AI with full codebase context. The result? You're reading docs that otherwise might not exist.*
 
 ## 🌐 Overview
 
@@ -60,9 +74,13 @@ A production-ready MCP server that integrates all major Google Workspace service
 
 ### Simplest Start (uvx - Recommended)
 
-Run instantly without installation:
+> Run instantly without manual installation - you must configure OAuth credentials when using uvx. You can use either environment variables (recommended for production) or set the `GOOGLE_CLIENT_SECRET_PATH` (or legacy `GOOGLE_CLIENT_SECRETS`) environment variable to point to your `client_secret.json` file.
 
 ```bash
+# Set OAuth credentials via environment variables (recommended)
+export GOOGLE_OAUTH_CLIENT_ID="your-client-id.apps.googleusercontent.com"
+export GOOGLE_OAUTH_CLIENT_SECRET="your-client-secret"
+
 # Start the server with all Google Workspace tools
 uvx workspace-mcp
 
@@ -96,9 +114,31 @@ uv run main.py
 1. **Google Cloud Setup**:
    - Create OAuth 2.0 credentials (web application) in [Google Cloud Console](https://console.cloud.google.com/)
    - Enable APIs: Calendar, Drive, Gmail, Docs, Sheets, Slides, Forms, Chat
-   - Download credentials as `client_secret.json` in project root
-     - To use a different location for `client_secret.json`, you can set the `GOOGLE_CLIENT_SECRETS` environment variable with that path
    - Add redirect URI: `http://localhost:8000/oauth2callback`
+   - Configure credentials using one of these methods:
+
+     **Option A: Environment Variables (Recommended for Production)**
+     ```bash
+     export GOOGLE_OAUTH_CLIENT_ID="your-client-id.apps.googleusercontent.com"
+     export GOOGLE_OAUTH_CLIENT_SECRET="your-client-secret"
+     export GOOGLE_OAUTH_REDIRECT_URI="http://localhost:8000/oauth2callback"  # Optional
+     ```
+
+     **Option B: File-based (Traditional)**
+     - Download credentials as `client_secret.json` in project root
+     - To use a different location, set `GOOGLE_CLIENT_SECRET_PATH` (or legacy `GOOGLE_CLIENT_SECRETS`) environment variable with the file path
+
+   **Credential Loading Priority**:
+   1. Environment variables (`GOOGLE_OAUTH_CLIENT_ID`, `GOOGLE_OAUTH_CLIENT_SECRET`)
+   2. File specified by `GOOGLE_CLIENT_SECRET_PATH` or `GOOGLE_CLIENT_SECRETS` environment variable
+   3. Default file (`client_secret.json` in project root)
+
+   **Why Environment Variables?**
+   - ✅ Containerized deployments (Docker, Kubernetes)
+   - ✅ Cloud platforms (Heroku, Railway, etc.)
+   - ✅ CI/CD pipelines
+   - ✅ No secrets in version control
+   - ✅ Easy credential rotation
 
 2. **Environment**:
    ```bash
@@ -156,7 +196,11 @@ python install_claude.py
   "mcpServers": {
     "google_workspace": {
       "command": "uvx",
-      "args": ["workspace-mcp"]
+      "args": ["workspace-mcp"],
+      "env": {
+        "GOOGLE_OAUTH_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
+        "GOOGLE_OAUTH_CLIENT_SECRET": "your-client-secret"
+      }
     }
   }
 }
@@ -169,7 +213,11 @@ python install_claude.py
     "google_workspace": {
       "command": "uv",
       "args": ["run", "main.py"],
-      "cwd": "/path/to/google_workspace_mcp"
+      "cwd": "/path/to/google_workspace_mcp",
+      "env": {
+        "GOOGLE_OAUTH_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
+        "GOOGLE_OAUTH_CLIENT_SECRET": "your-client-secret"
+      }
     }
   }
 }
@@ -217,7 +265,8 @@ When calling a tool:
 |------|-------------|
 | `list_calendars` | List accessible calendars |
 | `get_events` | Retrieve events with time range filtering |
-| `create_event` | Create events (all-day or timed) |
+| `get_event` | Fetch detailed information of a single event by ID |
+| `create_event` | Create events (all-day or timed) with optional Drive file attachments |
 | `modify_event` | Update existing events |
 | `delete_event` | Remove events |
 
@@ -228,7 +277,7 @@ When calling a tool:
 | `search_drive_files` | Search files with query syntax |
 | `get_drive_file_content` | Read file content (supports Office formats) |
 | `list_drive_items` | List folder contents |
-| `create_drive_file` | Create new files |
+| `create_drive_file` | Create new files or fetch content from public URLs |
 
 ### 📧 Gmail ([`gmail_tools.py`](gmail/gmail_tools.py))
 

{workspace_mcp-1.0.2 → workspace_mcp-1.0.3}/auth/google_auth.py

@@ -27,7 +27,7 @@ DEFAULT_CREDENTIALS_DIR = ".credentials"
 # This should be more robust in a production system once OAuth2.1 is implemented in client.
 _SESSION_CREDENTIALS_CACHE: Dict[str, Credentials] = {}
 # Centralized Client Secrets Path Logic
-_client_secrets_env = os.getenv("GOOGLE_CLIENT_SECRETS")
+_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:
@@ -151,22 +151,128 @@ def load_credentials_from_session(session_id: str) -> Optional[Credentials]:
         logger.debug(f"No credentials found in session cache 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 file."""
+    """
+    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:
-                 return client_config["installed"]
+                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 ---
 
@@ -206,8 +312,7 @@ async def start_auth_flow(
             OAUTH_STATE_TO_SESSION_ID_MAP[oauth_state] = mcp_session_id
             logger.info(f"[start_auth_flow] Stored mcp_session_id '{mcp_session_id}' for oauth_state '{oauth_state}'.")
 
-        flow = Flow.from_client_secrets_file(
-            CONFIG_CLIENT_SECRETS_PATH, # Use module constant
+        flow = create_oauth_flow(
             scopes=SCOPES, # Use global SCOPES
             redirect_uri=redirect_uri, # Use passed redirect_uri
             state=oauth_state
@@ -240,7 +345,7 @@ async def start_auth_flow(
         return "\n".join(message_lines)
 
     except FileNotFoundError as e:
-        error_text = f"OAuth client secrets file not found: {e}. Please ensure '{CONFIG_CLIENT_SECRETS_PATH}' is correctly configured."
+        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:
@@ -249,12 +354,12 @@ async def start_auth_flow(
         raise Exception(error_text)
 
 def handle_auth_callback(
-    client_secrets_path: str,
     scopes: List[str],
     authorization_response: str,
-    redirect_uri: str, # Made redirect_uri a required parameter
+    redirect_uri: str,
     credentials_base_dir: str = DEFAULT_CREDENTIALS_DIR,
-    session_id: Optional[str] = None
+    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,
@@ -262,12 +367,12 @@ def handle_auth_callback(
     and returns them.
 
     Args:
-        client_secrets_path: Path to the Google client secrets JSON file.
         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.
@@ -278,13 +383,16 @@ def handle_auth_callback(
         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'
 
-        flow = Flow.from_client_secrets_file(
-            client_secrets_path,
+        flow = create_oauth_flow(
             scopes=scopes,
             redirect_uri=redirect_uri
         )

{workspace_mcp-1.0.2 → workspace_mcp-1.0.3}/auth/oauth_callback_server.py

@@ -15,7 +15,7 @@ import socket
 from fastapi import FastAPI, Request
 import uvicorn
 
-from auth.google_auth import handle_auth_callback, CONFIG_CLIENT_SECRETS_PATH
+from auth.google_auth import handle_auth_callback, check_client_secrets
 from auth.scopes import OAUTH_STATE_TO_SESSION_ID_MAP, SCOPES
 from auth.oauth_responses import create_error_response, create_success_response, create_server_error_response
 
@@ -59,6 +59,11 @@ class MinimalOAuthServer:
                 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.")
 
                 mcp_session_id: Optional[str] = OAUTH_STATE_TO_SESSION_ID_MAP.pop(state, None)
@@ -69,7 +74,6 @@ class MinimalOAuthServer:
 
                 # Exchange code for credentials
                 verified_user_id, credentials = handle_auth_callback(
-                    client_secrets_path=CONFIG_CLIENT_SECRETS_PATH,
                     scopes=SCOPES,
                     authorization_response=str(request.url),
                     redirect_uri=f"{self.base_uri}:{self.port}/oauth2callback",
@@ -106,7 +110,7 @@ class MinimalOAuthServer:
             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))

workspace_mcp-1.0.3/core/context.py

@@ -0,0 +1,22 @@
+# 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
+)
+
+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)

{workspace_mcp-1.0.2 → workspace_mcp-1.0.3}/core/server.py

@@ -11,7 +11,7 @@ from mcp import types
 from mcp.server.fastmcp import FastMCP
 from starlette.requests import Request
 
-from auth.google_auth import handle_auth_callback, start_auth_flow, CONFIG_CLIENT_SECRETS_PATH
+from auth.google_auth import handle_auth_callback, start_auth_flow, check_client_secrets
 from auth.oauth_callback_server import get_oauth_redirect_uri, ensure_oauth_callback_available
 from auth.oauth_responses import create_error_response, create_success_response, create_server_error_response
 
@@ -119,11 +119,10 @@ async def oauth2_callback(request: Request) -> HTMLResponse:
         return create_error_response(error_message)
 
     try:
-        client_secrets_path = CONFIG_CLIENT_SECRETS_PATH
-        if not os.path.exists(client_secrets_path):
-            logger.error(f"OAuth client secrets file not found at {client_secrets_path}")
-            # This is a server configuration error, should not happen in a deployed environment.
-            return HTMLResponse(content="Server Configuration Error: Client secrets not found.", status_code=500)
+        # 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.")
 
@@ -136,7 +135,6 @@ async def oauth2_callback(request: Request) -> HTMLResponse:
         # Exchange code for credentials. handle_auth_callback will save them.
         # The user_id returned here is the Google-verified email.
         verified_user_id, credentials = handle_auth_callback(
-            client_secrets_path=client_secrets_path,
             scopes=SCOPES, # Ensure all necessary scopes are requested
             authorization_response=str(request.url),
             redirect_uri=get_oauth_redirect_uri_for_current_mode(),

{workspace_mcp-1.0.2 → workspace_mcp-1.0.3}/gdocs/docs_tools.py

@@ -214,3 +214,181 @@ async def create_doc(
     msg = f"Created Google Doc '{title}' (ID: {doc_id}) for {user_google_email}. Link: {link}"
     logger.info(f"Successfully created Google Doc '{title}' (ID: {doc_id}) for {user_google_email}. Link: {link}")
     return msg
+
+
+@server.tool()
+@require_google_service("drive", "drive_read")
+@handle_http_errors("read_doc_comments")
+async def read_doc_comments(
+    service,
+    user_google_email: str,
+    document_id: str,
+) -> str:
+    """
+    Read all comments from a Google Doc.
+
+    Args:
+        document_id: The ID of the Google Document
+
+    Returns:
+        str: A formatted list of all comments and replies in the document.
+    """
+    logger.info(f"[read_doc_comments] Reading comments for document {document_id}")
+
+    response = await asyncio.to_thread(
+        service.comments().list(
+            fileId=document_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 document {document_id}"
+    
+    output = [f"Found {len(comments)} comments in document {document_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)
+
+
+@server.tool()
+@require_google_service("drive", "drive_file")
+@handle_http_errors("reply_to_comment")
+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 Doc.
+
+    Args:
+        document_id: The ID of the Google Document
+        comment_id: The ID of the comment to reply to
+        reply_content: The content of the reply
+
+    Returns:
+        str: Confirmation message with reply details.
+    """
+    logger.info(f"[reply_to_comment] Replying to comment {comment_id} in document {document_id}")
+
+    body = {'content': reply_content}
+    
+    reply = await asyncio.to_thread(
+        service.replies().create(
+            fileId=document_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}"
+
+
+@server.tool()
+@require_google_service("drive", "drive_file")
+@handle_http_errors("create_doc_comment")
+async def create_doc_comment(
+    service,
+    user_google_email: str,
+    document_id: str,
+    comment_content: str,
+) -> str:
+    """
+    Create a new comment on a Google Doc.
+
+    Args:
+        document_id: The ID of the Google Document
+        comment_content: The content of the comment
+
+    Returns:
+        str: Confirmation message with comment details.
+    """
+    logger.info(f"[create_doc_comment] Creating comment in document {document_id}")
+
+    body = {"content": comment_content}
+    
+    comment = await asyncio.to_thread(
+        service.comments().create(
+            fileId=document_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}"
+
+
+@server.tool()
+@require_google_service("drive", "drive_file")
+@handle_http_errors("resolve_comment")
+async def resolve_comment(
+    service,
+    user_google_email: str,
+    document_id: str,
+    comment_id: str,
+) -> str:
+    """
+    Resolve a comment in a Google Doc.
+
+    Args:
+        document_id: The ID of the Google Document
+        comment_id: The ID of the comment to resolve
+
+    Returns:
+        str: Confirmation message.
+    """
+    logger.info(f"[resolve_comment] Resolving comment {comment_id} in document {document_id}")
+
+    body = {"resolved": True}
+    
+    await asyncio.to_thread(
+        service.comments().update(
+            fileId=document_id,
+            commentId=comment_id,
+            body=body
+        ).execute
+    )
+    
+    return f"Comment {comment_id} has been resolved successfully."

{workspace_mcp-1.0.2 → workspace_mcp-1.0.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "workspace-mcp"
-version = "1.0.2"
+version = "1.0.3"
 description = "Comprehensive, highly performant Google Workspace Streamable HTTP & SSE MCP Server for Calendar, Gmail, Docs, Sheets, Slides & Drive"
 readme = "README.md"
 keywords = [ "mcp", "google", "workspace", "llm", "ai", "claude", "model", "context", "protocol", "server"]

workspace_mcp-1.0.3/tests/test_auth.py

@@ -0,0 +1,115 @@
+import os
+import json
+from unittest.mock import patch, mock_open
+import pytest
+from auth.google_auth import load_client_secrets_from_env, create_oauth_flow, load_client_secrets
+from google_auth_oauthlib.flow import Flow
+
+# -- Mocks and Fixtures --
+
+@pytest.fixture
+def mock_env_vars(monkeypatch):
+    """Fixture to mock environment variables for OAuth."""
+    monkeypatch.setenv("GOOGLE_OAUTH_CLIENT_ID", "test_client_id_from_env")
+    monkeypatch.setenv("GOOGLE_OAUTH_CLIENT_SECRET", "test_client_secret_from_env")
+    monkeypatch.setenv("GOOGLE_OAUTH_REDIRECT_URI", "http://localhost:8000/callback")
+    return monkeypatch
+
+@pytest.fixture
+def mock_client_secrets_file(tmp_path):
+    """Fixture to create a mock client_secret.json file."""
+    secrets_content = {
+        "web": {
+            "client_id": "test_client_id_from_file",
+            "client_secret": "test_client_secret_from_file",
+            "redirect_uris": ["http://localhost:8000/oauth2callback"],
+            "auth_uri": "https://accounts.google.com/o/oauth2/auth",
+            "token_uri": "https://oauth2.googleapis.com/token"
+        }
+    }
+    secrets_file = tmp_path / "client_secret.json"
+    secrets_file.write_text(json.dumps(secrets_content))
+    return str(secrets_file)
+
+# -- Tests for load_client_secrets_from_env --
+
+def test_load_client_secrets_from_env_success(mock_env_vars):
+    """Test loading client secrets from environment variables successfully."""
+    config = load_client_secrets_from_env()
+    assert config is not None
+    assert config["web"]["client_id"] == "test_client_id_from_env"
+    assert config["web"]["client_secret"] == "test_client_secret_from_env"
+    assert config["web"]["redirect_uris"] == ["http://localhost:8000/callback"]
+
+def test_load_client_secrets_from_env_missing_vars():
+    """Test that None is returned when environment variables are missing."""
+    # Ensure variables are not set
+    if "GOOGLE_OAUTH_CLIENT_ID" in os.environ:
+        del os.environ["GOOGLE_OAUTH_CLIENT_ID"]
+    config = load_client_secrets_from_env()
+    assert config is None
+
+# -- Tests for load_client_secrets (the combined function) --
+
+def test_load_client_secrets_prioritizes_env_vars(mock_env_vars, mock_client_secrets_file):
+    """Test that environment variables are prioritized over the file."""
+    # Pass a file path, but env vars should be used
+    config = load_client_secrets(mock_client_secrets_file)
+    assert config["client_id"] == "test_client_id_from_env"
+    assert config["client_secret"] == "test_client_secret_from_env"
+
+def test_load_client_secrets_falls_back_to_file(mock_client_secrets_file):
+    """Test that the file is used when no environment variables are set."""
+    # Ensure env vars are not present
+    if "GOOGLE_OAUTH_CLIENT_ID" in os.environ:
+        del os.environ["GOOGLE_OAUTH_CLIENT_ID"]
+
+    config = load_client_secrets(mock_client_secrets_file)
+    assert config["client_id"] == "test_client_id_from_file"
+    assert config["client_secret"] == "test_client_secret_from_file"
+
+def test_load_client_secrets_file_not_found():
+    """Test that an error is raised if no file is found and no env vars are set."""
+    with pytest.raises(IOError):
+        load_client_secrets("non_existent_file.json")
+
+# -- Tests for create_oauth_flow --
+
+@patch('auth.google_auth.Flow')
+def test_create_oauth_flow_from_env(mock_flow, mock_env_vars):
+    """Test creating an OAuth flow using environment variables."""
+    create_oauth_flow(scopes=["test_scope"], redirect_uri="http://localhost:8000/callback")
+
+    # Check that Flow.from_client_config was called with the correct config
+    mock_flow.from_client_config.assert_called_once()
+    call_args = mock_flow.from_client_config.call_args[0][0]
+    assert call_args["web"]["client_id"] == "test_client_id_from_env"
+
+@patch('auth.google_auth.Flow')
+@patch('os.path.exists', return_value=True)
+def test_create_oauth_flow_from_file(mock_path_exists, mock_flow, mock_client_secrets_file):
+    """Test creating an OAuth flow using a client secrets file."""
+    # Ensure env vars are not present
+    if "GOOGLE_OAUTH_CLIENT_ID" in os.environ:
+        del os.environ["GOOGLE_OAUTH_CLIENT_ID"]
+
+    with patch('auth.google_auth.CONFIG_CLIENT_SECRETS_PATH', mock_client_secrets_file):
+        create_oauth_flow(scopes=["test_scope"], redirect_uri="http://localhost:8000/callback")
+
+    # Check that Flow.from_client_secrets_file was called
+    mock_flow.from_client_secrets_file.assert_called_once_with(
+        mock_client_secrets_file,
+        scopes=["test_scope"],
+        redirect_uri="http://localhost:8000/callback",
+        state=None
+    )
+
+@patch('os.path.exists', return_value=False)
+def test_create_oauth_flow_no_config_found(mock_path_exists):
+    """Test that an error is raised if no configuration is found."""
+    # Ensure env vars are not present
+    if "GOOGLE_OAUTH_CLIENT_ID" in os.environ:
+        del os.environ["GOOGLE_OAUTH_CLIENT_ID"]
+
+    with pytest.raises(FileNotFoundError):
+        create_oauth_flow(scopes=["test_scope"], redirect_uri="http://localhost:8000/callback")

{workspace_mcp-1.0.2 → workspace_mcp-1.0.3}/workspace_mcp.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: workspace-mcp
-Version: 1.0.2
+Version: 1.0.3
 Summary: Comprehensive, highly performant Google Workspace Streamable HTTP & SSE MCP Server for Calendar, Gmail, Docs, Sheets, Slides & Drive
 Author-email: Taylor Wilsdon <taylor@taylorwilsdon.com>
 License: MIT
@@ -76,6 +76,20 @@ Dynamic: license-file
 
 ---
 
+## AI-Enhanced Documentation
+
+> **This README was crafted with AI assistance, and here's why that matters**
+> 
+> When people dismiss documentation as "AI-generated," they're missing the bigger picture
+
+As a solo developer building open source tools that may only ever serve my own needs, comprehensive documentation often wouldn't happen without AI help. When done right—using agents like **Roo** or **Claude Code** that understand the entire codebase, AI doesn't just regurgitate generic content - it extracts real implementation details and creates accurate, specific documentation.
+
+**The alternative? No docs at all.** 
+
+I hope the community can appreciate these tools for what they enable: solo developers maintaining professional documentation standards while focusing on building great software.
+
+---
+*This documentation was enhanced by AI with full codebase context. The result? You're reading docs that otherwise might not exist.*
 
 ## 🌐 Overview
 
@@ -102,9 +116,13 @@ A production-ready MCP server that integrates all major Google Workspace service
 
 ### Simplest Start (uvx - Recommended)
 
-Run instantly without installation:
+> Run instantly without manual installation - you must configure OAuth credentials when using uvx. You can use either environment variables (recommended for production) or set the `GOOGLE_CLIENT_SECRET_PATH` (or legacy `GOOGLE_CLIENT_SECRETS`) environment variable to point to your `client_secret.json` file.
 
 ```bash
+# Set OAuth credentials via environment variables (recommended)
+export GOOGLE_OAUTH_CLIENT_ID="your-client-id.apps.googleusercontent.com"
+export GOOGLE_OAUTH_CLIENT_SECRET="your-client-secret"
+
 # Start the server with all Google Workspace tools
 uvx workspace-mcp
 
@@ -138,9 +156,31 @@ uv run main.py
 1. **Google Cloud Setup**:
    - Create OAuth 2.0 credentials (web application) in [Google Cloud Console](https://console.cloud.google.com/)
    - Enable APIs: Calendar, Drive, Gmail, Docs, Sheets, Slides, Forms, Chat
-   - Download credentials as `client_secret.json` in project root
-     - To use a different location for `client_secret.json`, you can set the `GOOGLE_CLIENT_SECRETS` environment variable with that path
    - Add redirect URI: `http://localhost:8000/oauth2callback`
+   - Configure credentials using one of these methods:
+
+     **Option A: Environment Variables (Recommended for Production)**
+     ```bash
+     export GOOGLE_OAUTH_CLIENT_ID="your-client-id.apps.googleusercontent.com"
+     export GOOGLE_OAUTH_CLIENT_SECRET="your-client-secret"
+     export GOOGLE_OAUTH_REDIRECT_URI="http://localhost:8000/oauth2callback"  # Optional
+     ```
+
+     **Option B: File-based (Traditional)**
+     - Download credentials as `client_secret.json` in project root
+     - To use a different location, set `GOOGLE_CLIENT_SECRET_PATH` (or legacy `GOOGLE_CLIENT_SECRETS`) environment variable with the file path
+
+   **Credential Loading Priority**:
+   1. Environment variables (`GOOGLE_OAUTH_CLIENT_ID`, `GOOGLE_OAUTH_CLIENT_SECRET`)
+   2. File specified by `GOOGLE_CLIENT_SECRET_PATH` or `GOOGLE_CLIENT_SECRETS` environment variable
+   3. Default file (`client_secret.json` in project root)
+
+   **Why Environment Variables?**
+   - ✅ Containerized deployments (Docker, Kubernetes)
+   - ✅ Cloud platforms (Heroku, Railway, etc.)
+   - ✅ CI/CD pipelines
+   - ✅ No secrets in version control
+   - ✅ Easy credential rotation
 
 2. **Environment**:
    ```bash
@@ -198,7 +238,11 @@ python install_claude.py
   "mcpServers": {
     "google_workspace": {
       "command": "uvx",
-      "args": ["workspace-mcp"]
+      "args": ["workspace-mcp"],
+      "env": {
+        "GOOGLE_OAUTH_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
+        "GOOGLE_OAUTH_CLIENT_SECRET": "your-client-secret"
+      }
     }
   }
 }
@@ -211,7 +255,11 @@ python install_claude.py
     "google_workspace": {
       "command": "uv",
       "args": ["run", "main.py"],
-      "cwd": "/path/to/google_workspace_mcp"
+      "cwd": "/path/to/google_workspace_mcp",
+      "env": {
+        "GOOGLE_OAUTH_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
+        "GOOGLE_OAUTH_CLIENT_SECRET": "your-client-secret"
+      }
     }
   }
 }
@@ -259,7 +307,8 @@ When calling a tool:
 |------|-------------|
 | `list_calendars` | List accessible calendars |
 | `get_events` | Retrieve events with time range filtering |
-| `create_event` | Create events (all-day or timed) |
+| `get_event` | Fetch detailed information of a single event by ID |
+| `create_event` | Create events (all-day or timed) with optional Drive file attachments |
 | `modify_event` | Update existing events |
 | `delete_event` | Remove events |
 
@@ -270,7 +319,7 @@ When calling a tool:
 | `search_drive_files` | Search files with query syntax |
 | `get_drive_file_content` | Read file content (supports Office formats) |
 | `list_drive_items` | List folder contents |
-| `create_drive_file` | Create new files |
+| `create_drive_file` | Create new files or fetch content from public URLs |
 
 ### 📧 Gmail ([`gmail_tools.py`](gmail/gmail_tools.py))
 

{workspace_mcp-1.0.2 → workspace_mcp-1.0.3}/workspace_mcp.egg-info/SOURCES.txt

@@ -9,6 +9,7 @@ auth/oauth_responses.py
 auth/scopes.py
 auth/service_decorator.py
 core/__init__.py
+core/context.py
 core/server.py
 core/utils.py
 gcalendar/__init__.py
@@ -27,6 +28,7 @@ gsheets/__init__.py
 gsheets/sheets_tools.py
 gslides/__init__.py
 gslides/slides_tools.py
+tests/test_auth.py
 workspace_mcp.egg-info/PKG-INFO
 workspace_mcp.egg-info/SOURCES.txt
 workspace_mcp.egg-info/dependency_links.txt