workspace-mcp 0.2.0__py3-none-any.whl

gdrive/drive_tools.py

@@ -0,0 +1,362 @@
+"""
+Google Drive MCP Tools
+
+This module provides MCP tools for interacting with Google Drive API.
+"""
+import logging
+import asyncio
+import re
+from typing import List, Optional, Dict, Any
+
+from mcp import types
+from googleapiclient.errors import HttpError
+from googleapiclient.http import MediaIoBaseDownload, MediaIoBaseUpload
+import io
+
+from auth.service_decorator import require_google_service
+from core.utils import extract_office_xml_text
+from core.server import server
+
+logger = logging.getLogger(__name__)
+
+# Precompiled regex patterns for Drive query detection
+DRIVE_QUERY_PATTERNS = [
+    re.compile(r'\b\w+\s*(=|!=|>|<)\s*[\'"].*?[\'"]', re.IGNORECASE),  # field = 'value'
+    re.compile(r'\b\w+\s*(=|!=|>|<)\s*\d+', re.IGNORECASE),            # field = number
+    re.compile(r'\bcontains\b', re.IGNORECASE),                         # contains operator
+    re.compile(r'\bin\s+parents\b', re.IGNORECASE),                     # in parents
+    re.compile(r'\bhas\s*\{', re.IGNORECASE),                          # has {properties}
+    re.compile(r'\btrashed\s*=\s*(true|false)\b', re.IGNORECASE),      # trashed=true/false
+    re.compile(r'\bstarred\s*=\s*(true|false)\b', re.IGNORECASE),      # starred=true/false
+    re.compile(r'[\'"][^\'"]+[\'"]\s+in\s+parents', re.IGNORECASE),    # 'parentId' in parents
+    re.compile(r'\bfullText\s+contains\b', re.IGNORECASE),             # fullText contains
+    re.compile(r'\bname\s*(=|contains)\b', re.IGNORECASE),             # name = or name contains
+    re.compile(r'\bmimeType\s*(=|!=)\b', re.IGNORECASE),               # mimeType operators
+]
+
+
+def _build_drive_list_params(
+    query: str,
+    page_size: int,
+    drive_id: Optional[str] = None,
+    include_items_from_all_drives: bool = True,
+    corpora: Optional[str] = None,
+) -> Dict[str, Any]:
+    """
+    Helper function to build common list parameters for Drive API calls.
+
+    Args:
+        query: The search query string
+        page_size: Maximum number of items to return
+        drive_id: Optional shared drive ID
+        include_items_from_all_drives: Whether to include items from all drives
+        corpora: Optional corpus specification
+
+    Returns:
+        Dictionary of parameters for Drive API list calls
+    """
+    list_params = {
+        "q": query,
+        "pageSize": page_size,
+        "fields": "nextPageToken, files(id, name, mimeType, webViewLink, iconLink, modifiedTime, size)",
+        "supportsAllDrives": True,
+        "includeItemsFromAllDrives": include_items_from_all_drives,
+    }
+
+    if drive_id:
+        list_params["driveId"] = drive_id
+        if corpora:
+            list_params["corpora"] = corpora
+        else:
+            list_params["corpora"] = "drive"
+    elif corpora:
+        list_params["corpora"] = corpora
+
+    return list_params
+
+@server.tool()
+@require_google_service("drive", "drive_read")
+async def search_drive_files(
+    service,
+    user_google_email: str,
+    query: str,
+    page_size: int = 10,
+    drive_id: Optional[str] = None,
+    include_items_from_all_drives: bool = True,
+    corpora: Optional[str] = None,
+) -> str:
+    """
+    Searches for files and folders within a user's Google Drive, including shared drives.
+
+    Args:
+        user_google_email (str): The user's Google email address. Required.
+        query (str): The search query string. Supports Google Drive search operators.
+        page_size (int): The maximum number of files to return. Defaults to 10.
+        drive_id (Optional[str]): ID of the shared drive to search. If None, behavior depends on `corpora` and `include_items_from_all_drives`.
+        include_items_from_all_drives (bool): Whether shared drive items should be included in results. Defaults to True. This is effective when not specifying a `drive_id`.
+        corpora (Optional[str]): Bodies of items to query (e.g., 'user', 'domain', 'drive', 'allDrives').
+                                 If 'drive_id' is specified and 'corpora' is None, it defaults to 'drive'.
+                                 Otherwise, Drive API default behavior applies. Prefer 'user' or 'drive' over 'allDrives' for efficiency.
+
+    Returns:
+        str: A formatted list of found files/folders with their details (ID, name, type, size, modified time, link).
+    """
+    logger.info(f"[search_drive_files] Invoked. Email: '{user_google_email}', Query: '{query}'")
+
+    try:
+        # Check if the query looks like a structured Drive query or free text
+        # Look for Drive API operators and structured query patterns
+        is_structured_query = any(pattern.search(query) for pattern in DRIVE_QUERY_PATTERNS)
+
+        if is_structured_query:
+            final_query = query
+            logger.info(f"[search_drive_files] Using structured query as-is: '{final_query}'")
+        else:
+            # For free text queries, wrap in fullText contains
+            escaped_query = query.replace("'", "\\'")
+            final_query = f"fullText contains '{escaped_query}'"
+            logger.info(f"[search_drive_files] Reformatting free text query '{query}' to '{final_query}'")
+
+        list_params = _build_drive_list_params(
+            query=final_query,
+            page_size=page_size,
+            drive_id=drive_id,
+            include_items_from_all_drives=include_items_from_all_drives,
+            corpora=corpora,
+        )
+
+        results = await asyncio.to_thread(
+            service.files().list(**list_params).execute
+        )
+        files = results.get('files', [])
+        if not files:
+            return f"No files found for '{query}'."
+
+        formatted_files_text_parts = [f"Found {len(files)} files for {user_google_email} matching '{query}':"]
+        for item in files:
+            size_str = f", Size: {item.get('size', 'N/A')}" if 'size' in item else ""
+            formatted_files_text_parts.append(
+                f"- Name: \"{item['name']}\" (ID: {item['id']}, Type: {item['mimeType']}{size_str}, Modified: {item.get('modifiedTime', 'N/A')}) Link: {item.get('webViewLink', '#')}"
+            )
+        text_output = "\n".join(formatted_files_text_parts)
+        return text_output
+    except HttpError as error:
+        logger.error(f"API error searching Drive files: {error}", exc_info=True)
+        raise Exception(f"API error: {error}")
+    except Exception as e:
+        logger.exception(f"Unexpected error searching Drive files: {e}")
+        raise Exception(f"Unexpected error: {e}")
+
+@server.tool()
+@require_google_service("drive", "drive_read")
+async def get_drive_file_content(
+    service,
+    user_google_email: str,
+    file_id: str,
+) -> str:
+    """
+    Retrieves the content of a specific Google Drive file by ID, supporting files in shared drives.
+
+    • Native Google Docs, Sheets, Slides → exported as text / CSV.
+    • Office files (.docx, .xlsx, .pptx) → unzipped & parsed with std-lib to
+      extract readable text.
+    • Any other file → downloaded; tries UTF-8 decode, else notes binary.
+
+    Args:
+        user_google_email: The user’s Google email address.
+        file_id: Drive file ID.
+
+    Returns:
+        str: The file content as plain text with metadata header.
+    """
+    logger.info(f"[get_drive_file_content] Invoked. File ID: '{file_id}'")
+
+    try:
+        file_metadata = await asyncio.to_thread(
+            service.files().get(
+                fileId=file_id, fields="id, name, mimeType, webViewLink", supportsAllDrives=True
+            ).execute
+        )
+        mime_type = file_metadata.get("mimeType", "")
+        file_name = file_metadata.get("name", "Unknown File")
+        export_mime_type = {
+            "application/vnd.google-apps.document": "text/plain",
+            "application/vnd.google-apps.spreadsheet": "text/csv",
+            "application/vnd.google-apps.presentation": "text/plain",
+        }.get(mime_type)
+
+        request_obj = (
+            service.files().export_media(fileId=file_id, mimeType=export_mime_type)
+            if export_mime_type
+            else service.files().get_media(fileId=file_id)
+        )
+        fh = io.BytesIO()
+        downloader = MediaIoBaseDownload(fh, request_obj)
+        loop = asyncio.get_event_loop()
+        done = False
+        while not done:
+            status, done = await loop.run_in_executor(None, downloader.next_chunk)
+
+        file_content_bytes = fh.getvalue()
+
+        # Attempt Office XML extraction only for actual Office XML files
+        office_mime_types = {
+            "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+            "application/vnd.openxmlformats-officedocument.presentationml.presentation", 
+            "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+        }
+        
+        if mime_type in office_mime_types:
+            office_text = extract_office_xml_text(file_content_bytes, mime_type)
+            if office_text:
+                body_text = office_text
+            else:
+                # Fallback: try UTF-8; otherwise flag binary
+                try:
+                    body_text = file_content_bytes.decode("utf-8")
+                except UnicodeDecodeError:
+                    body_text = (
+                        f"[Binary or unsupported text encoding for mimeType '{mime_type}' - "
+                        f"{len(file_content_bytes)} bytes]"
+                    )
+        else:
+            # For non-Office files (including Google native files), try UTF-8 decode directly
+            try:
+                body_text = file_content_bytes.decode("utf-8")
+            except UnicodeDecodeError:
+                body_text = (
+                    f"[Binary or unsupported text encoding for mimeType '{mime_type}' - "
+                    f"{len(file_content_bytes)} bytes]"
+                )
+
+        # Assemble response
+        header = (
+            f'File: "{file_name}" (ID: {file_id}, Type: {mime_type})\n'
+            f'Link: {file_metadata.get("webViewLink", "#")}\n\n--- CONTENT ---\n'
+        )
+        return header + body_text
+
+    except HttpError as error:
+        logger.error(
+            f"API error getting Drive file content for {file_id}: {error}",
+            exc_info=True,
+        )
+        raise Exception(f"API error: {error}")
+    except Exception as e:
+        logger.exception(f"Unexpected error getting Drive file content for {file_id}: {e}")
+        raise Exception(f"Unexpected error: {e}")
+
+
+@require_google_service("drive", "drive_read")
+async def list_drive_items(
+    service,
+    user_google_email: str,
+    folder_id: str = 'root',
+    page_size: int = 100,
+    drive_id: Optional[str] = None,
+    include_items_from_all_drives: bool = True,
+    corpora: Optional[str] = None,
+) -> str:
+    """
+    Lists files and folders, supporting shared drives.
+    If `drive_id` is specified, lists items within that shared drive. `folder_id` is then relative to that drive (or use drive_id as folder_id for root).
+    If `drive_id` is not specified, lists items from user's "My Drive" and accessible shared drives (if `include_items_from_all_drives` is True).
+
+    Args:
+        user_google_email (str): The user's Google email address. Required.
+        folder_id (str): The ID of the Google Drive folder. Defaults to 'root'. For a shared drive, this can be the shared drive's ID to list its root, or a folder ID within that shared drive.
+        page_size (int): The maximum number of items to return. Defaults to 100.
+        drive_id (Optional[str]): ID of the shared drive. If provided, the listing is scoped to this drive.
+        include_items_from_all_drives (bool): Whether items from all accessible shared drives should be included if `drive_id` is not set. Defaults to True.
+        corpora (Optional[str]): Corpus to query ('user', 'drive', 'allDrives'). If `drive_id` is set and `corpora` is None, 'drive' is used. If None and no `drive_id`, API defaults apply.
+
+    Returns:
+        str: A formatted list of files/folders in the specified folder.
+    """
+    logger.info(f"[list_drive_items] Invoked. Email: '{user_google_email}', Folder ID: '{folder_id}'")
+
+    try:
+        final_query = f"'{folder_id}' in parents and trashed=false"
+
+        list_params = _build_drive_list_params(
+            query=final_query,
+            page_size=page_size,
+            drive_id=drive_id,
+            include_items_from_all_drives=include_items_from_all_drives,
+            corpora=corpora,
+        )
+
+        results = await asyncio.to_thread(
+            service.files().list(**list_params).execute
+        )
+        files = results.get('files', [])
+        if not files:
+            return f"No items found in folder '{folder_id}'."
+
+        formatted_items_text_parts = [f"Found {len(files)} items in folder '{folder_id}' for {user_google_email}:"]
+        for item in files:
+            size_str = f", Size: {item.get('size', 'N/A')}" if 'size' in item else ""
+            formatted_items_text_parts.append(
+                f"- Name: \"{item['name']}\" (ID: {item['id']}, Type: {item['mimeType']}{size_str}, Modified: {item.get('modifiedTime', 'N/A')}) Link: {item.get('webViewLink', '#')}"
+            )
+        text_output = "\n".join(formatted_items_text_parts)
+        return text_output
+    except HttpError as error:
+        logger.error(f"API error listing Drive items in folder {folder_id}: {error}", exc_info=True)
+        raise Exception(f"API error: {error}")
+    except Exception as e:
+        logger.exception(f"Unexpected error listing Drive items in folder {folder_id}: {e}")
+        raise Exception(f"Unexpected error: {e}")
+
+@require_google_service("drive", "drive_file")
+async def create_drive_file(
+    service,
+    user_google_email: str,
+    file_name: str,
+    content: str,
+    folder_id: str = 'root',
+    mime_type: str = 'text/plain',
+) -> str:
+    """
+    Creates a new file in Google Drive, supporting creation within shared drives.
+
+    Args:
+        user_google_email (str): The user's Google email address. Required.
+        file_name (str): The name for the new file.
+        content (str): The content to write to the file.
+        folder_id (str): The ID of the parent folder. Defaults to 'root'. For shared drives, this must be a folder ID within the shared drive.
+        mime_type (str): The MIME type of the file. Defaults to 'text/plain'.
+
+    Returns:
+        str: Confirmation message of the successful file creation with file link.
+    """
+    logger.info(f"[create_drive_file] Invoked. Email: '{user_google_email}', File Name: {file_name}, Folder ID: {folder_id}")
+
+    try:
+        file_metadata = {
+            'name': file_name,
+            'parents': [folder_id],
+            'mimeType': mime_type
+        }
+        media = io.BytesIO(content.encode('utf-8'))
+
+        created_file = await asyncio.to_thread(
+            service.files().create(
+                body=file_metadata,
+                media_body=MediaIoBaseUpload(media, mimetype=mime_type, resumable=True),
+                fields='id, name, webViewLink',
+                supportsAllDrives=True
+            ).execute
+        )
+
+        link = created_file.get('webViewLink', 'No link available')
+        confirmation_message = f"Successfully created file '{created_file.get('name', file_name)}' (ID: {created_file.get('id', 'N/A')}) in folder '{folder_id}' for {user_google_email}. Link: {link}"
+        logger.info(f"Successfully created file. Link: {link}")
+        return confirmation_message
+
+    except HttpError as error:
+        logger.error(f"API error creating Drive file '{file_name}': {error}", exc_info=True)
+        raise Exception(f"API error: {error}")
+    except Exception as e:
+        logger.exception(f"Unexpected error creating Drive file '{file_name}': {e}")
+        raise Exception(f"Unexpected error: {e}")

gforms/__init__.py

@@ -0,0 +1,3 @@
+"""
+Google Forms MCP Tools module
+"""

gforms/forms_tools.py

@@ -0,0 +1,318 @@
+"""
+Google Forms MCP Tools
+
+This module provides MCP tools for interacting with Google Forms API.
+"""
+
+import logging
+import asyncio
+from typing import List, Optional, Dict, Any
+
+from mcp import types
+from googleapiclient.errors import HttpError
+
+from auth.service_decorator import require_google_service
+from core.server import server
+
+logger = logging.getLogger(__name__)
+
+
+@server.tool()
+@require_google_service("forms", "forms")
+async def create_form(
+    service,
+    user_google_email: str,
+    title: str,
+    description: Optional[str] = None,
+    document_title: Optional[str] = None
+) -> str:
+    """
+    Create a new form using the title given in the provided form message in the request.
+
+    Args:
+        user_google_email (str): The user's Google email address. Required.
+        title (str): The title of the form.
+        description (Optional[str]): The description of the form.
+        document_title (Optional[str]): The document title (shown in browser tab).
+
+    Returns:
+        str: Confirmation message with form ID and edit URL.
+    """
+    logger.info(f"[create_form] Invoked. Email: '{user_google_email}', Title: {title}")
+
+    try:
+        form_body: Dict[str, Any] = {
+            "info": {
+                "title": title
+            }
+        }
+        
+        if description:
+            form_body["info"]["description"] = description
+            
+        if document_title:
+            form_body["info"]["document_title"] = document_title
+
+        created_form = await asyncio.to_thread(
+            service.forms().create(body=form_body).execute
+        )
+
+        form_id = created_form.get("formId")
+        edit_url = f"https://docs.google.com/forms/d/{form_id}/edit"
+        responder_url = created_form.get("responderUri", f"https://docs.google.com/forms/d/{form_id}/viewform")
+        
+        confirmation_message = f"Successfully created form '{created_form.get('info', {}).get('title', title)}' for {user_google_email}. Form ID: {form_id}. Edit URL: {edit_url}. Responder URL: {responder_url}"
+        logger.info(f"Form created successfully for {user_google_email}. ID: {form_id}")
+        return confirmation_message
+    except HttpError as error:
+        message = f"API error creating form: {error}. You might need to re-authenticate. LLM: Try 'start_google_auth' with the user's email ({user_google_email}) and service_name='Google Forms'."
+        logger.error(message, exc_info=True)
+        raise Exception(message)
+    except Exception as e:
+        message = f"Unexpected error creating form: {e}."
+        logger.exception(message)
+        raise Exception(message)
+
+
+@server.tool()
+@require_google_service("forms", "forms")
+async def get_form(
+    service,
+    user_google_email: str,
+    form_id: str
+) -> str:
+    """
+    Get a form.
+
+    Args:
+        user_google_email (str): The user's Google email address. Required.
+        form_id (str): The ID of the form to retrieve.
+
+    Returns:
+        str: Form details including title, description, questions, and URLs.
+    """
+    logger.info(f"[get_form] Invoked. Email: '{user_google_email}', Form ID: {form_id}")
+
+    try:
+        form = await asyncio.to_thread(
+            service.forms().get(formId=form_id).execute
+        )
+
+        form_info = form.get("info", {})
+        title = form_info.get("title", "No Title")
+        description = form_info.get("description", "No Description")
+        document_title = form_info.get("documentTitle", title)
+        
+        edit_url = f"https://docs.google.com/forms/d/{form_id}/edit"
+        responder_url = form.get("responderUri", f"https://docs.google.com/forms/d/{form_id}/viewform")
+        
+        items = form.get("items", [])
+        questions_summary = []
+        for i, item in enumerate(items, 1):
+            item_title = item.get("title", f"Question {i}")
+            item_type = item.get("questionItem", {}).get("question", {}).get("required", False)
+            required_text = " (Required)" if item_type else ""
+            questions_summary.append(f"  {i}. {item_title}{required_text}")
+        
+        questions_text = "\n".join(questions_summary) if questions_summary else "  No questions found"
+        
+        result = f"""Form Details for {user_google_email}:
+- Title: "{title}"
+- Description: "{description}"
+- Document Title: "{document_title}"
+- Form ID: {form_id}
+- Edit URL: {edit_url}
+- Responder URL: {responder_url}
+- Questions ({len(items)} total):
+{questions_text}"""
+        
+        logger.info(f"Successfully retrieved form for {user_google_email}. ID: {form_id}")
+        return result
+    except HttpError as error:
+        message = f"API error getting form: {error}. You might need to re-authenticate. LLM: Try 'start_google_auth' with the user's email ({user_google_email}) and service_name='Google Forms'."
+        logger.error(message, exc_info=True)
+        raise Exception(message)
+    except Exception as e:
+        message = f"Unexpected error getting form: {e}."
+        logger.exception(message)
+        raise Exception(message)
+
+
+@server.tool()
+@require_google_service("forms", "forms")
+async def set_publish_settings(
+    service,
+    user_google_email: str,
+    form_id: str,
+    publish_as_template: bool = False,
+    require_authentication: bool = False
+) -> str:
+    """
+    Updates the publish settings of a form.
+
+    Args:
+        user_google_email (str): The user's Google email address. Required.
+        form_id (str): The ID of the form to update publish settings for.
+        publish_as_template (bool): Whether to publish as a template. Defaults to False.
+        require_authentication (bool): Whether to require authentication to view/submit. Defaults to False.
+
+    Returns:
+        str: Confirmation message of the successful publish settings update.
+    """
+    logger.info(f"[set_publish_settings] Invoked. Email: '{user_google_email}', Form ID: {form_id}")
+
+    try:
+        settings_body = {
+            "publishAsTemplate": publish_as_template,
+            "requireAuthentication": require_authentication
+        }
+
+        await asyncio.to_thread(
+            service.forms().setPublishSettings(formId=form_id, body=settings_body).execute
+        )
+
+        confirmation_message = f"Successfully updated publish settings for form {form_id} for {user_google_email}. Publish as template: {publish_as_template}, Require authentication: {require_authentication}"
+        logger.info(f"Publish settings updated successfully for {user_google_email}. Form ID: {form_id}")
+        return confirmation_message
+    except HttpError as error:
+        message = f"API error updating publish settings: {error}. You might need to re-authenticate. LLM: Try 'start_google_auth' with the user's email ({user_google_email}) and service_name='Google Forms'."
+        logger.error(message, exc_info=True)
+        raise Exception(message)
+    except Exception as e:
+        message = f"Unexpected error updating publish settings: {e}."
+        logger.exception(message)
+        raise Exception(message)
+
+
+@server.tool()
+@require_google_service("forms", "forms")
+async def get_form_response(
+    service,
+    user_google_email: str,
+    form_id: str,
+    response_id: str
+) -> str:
+    """
+    Get one response from the form.
+
+    Args:
+        user_google_email (str): The user's Google email address. Required.
+        form_id (str): The ID of the form.
+        response_id (str): The ID of the response to retrieve.
+
+    Returns:
+        str: Response details including answers and metadata.
+    """
+    logger.info(f"[get_form_response] Invoked. Email: '{user_google_email}', Form ID: {form_id}, Response ID: {response_id}")
+
+    try:
+        response = await asyncio.to_thread(
+            service.forms().responses().get(formId=form_id, responseId=response_id).execute
+        )
+
+        response_id = response.get("responseId", "Unknown")
+        create_time = response.get("createTime", "Unknown")
+        last_submitted_time = response.get("lastSubmittedTime", "Unknown")
+        
+        answers = response.get("answers", {})
+        answer_details = []
+        for question_id, answer_data in answers.items():
+            question_response = answer_data.get("textAnswers", {}).get("answers", [])
+            if question_response:
+                answer_text = ", ".join([ans.get("value", "") for ans in question_response])
+                answer_details.append(f"  Question ID {question_id}: {answer_text}")
+            else:
+                answer_details.append(f"  Question ID {question_id}: No answer provided")
+        
+        answers_text = "\n".join(answer_details) if answer_details else "  No answers found"
+        
+        result = f"""Form Response Details for {user_google_email}:
+- Form ID: {form_id}
+- Response ID: {response_id}
+- Created: {create_time}
+- Last Submitted: {last_submitted_time}
+- Answers:
+{answers_text}"""
+        
+        logger.info(f"Successfully retrieved response for {user_google_email}. Response ID: {response_id}")
+        return result
+    except HttpError as error:
+        message = f"API error getting form response: {error}. You might need to re-authenticate. LLM: Try 'start_google_auth' with the user's email ({user_google_email}) and service_name='Google Forms'."
+        logger.error(message, exc_info=True)
+        raise Exception(message)
+    except Exception as e:
+        message = f"Unexpected error getting form response: {e}."
+        logger.exception(message)
+        raise Exception(message)
+
+
+@server.tool()
+@require_google_service("forms", "forms")
+async def list_form_responses(
+    service,
+    user_google_email: str,
+    form_id: str,
+    page_size: int = 10,
+    page_token: Optional[str] = None
+) -> str:
+    """
+    List a form's responses.
+
+    Args:
+        user_google_email (str): The user's Google email address. Required.
+        form_id (str): The ID of the form.
+        page_size (int): Maximum number of responses to return. Defaults to 10.
+        page_token (Optional[str]): Token for retrieving next page of results.
+
+    Returns:
+        str: List of responses with basic details and pagination info.
+    """
+    logger.info(f"[list_form_responses] Invoked. Email: '{user_google_email}', Form ID: {form_id}")
+
+    try:
+        params = {
+            "formId": form_id,
+            "pageSize": page_size
+        }
+        if page_token:
+            params["pageToken"] = page_token
+
+        responses_result = await asyncio.to_thread(
+            service.forms().responses().list(**params).execute
+        )
+
+        responses = responses_result.get("responses", [])
+        next_page_token = responses_result.get("nextPageToken")
+        
+        if not responses:
+            return f"No responses found for form {form_id} for {user_google_email}."
+
+        response_details = []
+        for i, response in enumerate(responses, 1):
+            response_id = response.get("responseId", "Unknown")
+            create_time = response.get("createTime", "Unknown")
+            last_submitted_time = response.get("lastSubmittedTime", "Unknown")
+            
+            answers_count = len(response.get("answers", {}))
+            response_details.append(
+                f"  {i}. Response ID: {response_id} | Created: {create_time} | Last Submitted: {last_submitted_time} | Answers: {answers_count}"
+            )
+
+        pagination_info = f"\nNext page token: {next_page_token}" if next_page_token else "\nNo more pages."
+        
+        result = f"""Form Responses for {user_google_email}:
+- Form ID: {form_id}
+- Total responses returned: {len(responses)}
+- Responses:
+{chr(10).join(response_details)}{pagination_info}"""
+        
+        logger.info(f"Successfully retrieved {len(responses)} responses for {user_google_email}. Form ID: {form_id}")
+        return result
+    except HttpError as error:
+        message = f"API error listing form responses: {error}. You might need to re-authenticate. LLM: Try 'start_google_auth' with the user's email ({user_google_email}) and service_name='Google Forms'."
+        logger.error(message, exc_info=True)
+        raise Exception(message)
+    except Exception as e:
+        message = f"Unexpected error listing form responses: {e}."
+        logger.exception(message)
+        raise Exception(message)

gmail/__init__.py

@@ -0,0 +1 @@
+# This file marks the 'gmail' directory as a Python package.