google-workspace-mcp 1.0.4__py3-none-any.whl → 1.1.5__py3-none-any.whl

google_workspace_mcp/tools/calendar.py

@@ -16,7 +16,6 @@ logger = logging.getLogger(__name__)
 
 # @mcp.tool(
 #     name="list_calendars",
-#     description="Lists all calendars accessible by the user.",
 # )
 # async def list_calendars() -> dict[str, Any]:
 #     """
@@ -40,10 +39,9 @@ logger = logging.getLogger(__name__)
 #     return {"count": len(calendars), "calendars": calendars}
 
 
-@mcp.tool(
-    name="calendar_get_events",
-    description="Retrieve calendar events within a specified time range.",
-)
+# @mcp.tool(
+#     name="calendar_get_events",
+# )
 async def calendar_get_events(
     time_min: str,
     time_max: str,
@@ -92,10 +90,9 @@ async def calendar_get_events(
     return {"count": len(events), "events": events}
 
 
-@mcp.tool(
-    name="calendar_get_event_details",
-    description="Retrieves detailed information for a specific calendar event by its ID.",
-)
+# @mcp.tool(
+#     name="calendar_get_event_details",
+# )
 async def calendar_get_event_details(event_id: str, calendar_id: str = "primary") -> dict[str, Any]:
     """
     Retrieves details for a specific event in a Google Calendar.
@@ -126,10 +123,9 @@ async def calendar_get_event_details(event_id: str, calendar_id: str = "primary"
     return event_details
 
 
-@mcp.tool(
-    name="create_calendar_event",
-    description="Creates a new event in a specified Google Calendar.",
-)
+# @mcp.tool(
+#     name="create_calendar_event",
+# )
 async def create_calendar_event(
     summary: str,
     start_time: str,
@@ -184,10 +180,9 @@ async def create_calendar_event(
     return result
 
 
-@mcp.tool(
-    name="delete_calendar_event",
-    description="Deletes an event from Google Calendar by its event ID.",
-)
+# @mcp.tool(
+#     name="delete_calendar_event",
+# )
 async def delete_calendar_event(
     event_id: str,
     calendar_id: str = "primary",

google_workspace_mcp/tools/docs_tools.py

@@ -11,10 +11,9 @@ from google_workspace_mcp.services.docs_service import DocsService
 logger = logging.getLogger(__name__)
 
 
-@mcp.tool(
-    name="docs_create_document",
-    description="Creates a new Google Document with a specified title.",
-)
+# @mcp.tool(
+#     name="docs_create_document",
+# )
 async def docs_create_document(title: str) -> dict[str, Any]:
     """
     Creates a new, empty Google Document.
@@ -44,10 +43,9 @@ async def docs_create_document(title: str) -> dict[str, Any]:
     return result
 
 
-@mcp.tool(
-    name="docs_get_document_metadata",
-    description="Retrieves metadata (like title and ID) for a Google Document.",
-)
+# @mcp.tool(
+#     name="docs_get_document_metadata",
+# )
 async def docs_get_document_metadata(document_id: str) -> dict[str, Any]:
     """
     Retrieves metadata for a specific Google Document.
@@ -77,10 +75,9 @@ async def docs_get_document_metadata(document_id: str) -> dict[str, Any]:
     return result
 
 
-@mcp.tool(
-    name="docs_get_content_as_markdown",
-    description="Retrieves the content of a Google Document, attempting to convert it to Markdown. Note: Direct Markdown export from Google Docs via Drive API is not officially guaranteed for all document complexities and may result in errors or suboptimal formatting. For critical conversions, consider exporting as HTML and using a dedicated Markdown conversion library.",
-)
+# @mcp.tool(
+#     name="docs_get_content_as_markdown",
+# )
 async def docs_get_content_as_markdown(document_id: str) -> dict[str, Any]:
     """
     Retrieves the main textual content of a Google Document, converted to Markdown.
@@ -114,10 +111,9 @@ async def docs_get_content_as_markdown(document_id: str) -> dict[str, Any]:
     return result
 
 
-@mcp.tool(
-    name="docs_append_text",
-    description="Appends text to the end of a specified Google Document.",
-)
+# @mcp.tool(
+#     name="docs_append_text",
+# )
 async def docs_append_text(
     document_id: str, text: str, ensure_newline: bool = True
 ) -> dict[str, Any]:
@@ -152,10 +148,9 @@ async def docs_append_text(
     return result
 
 
-@mcp.tool(
-    name="docs_prepend_text",
-    description="Prepends text to the beginning of a specified Google Document.",
-)
+# @mcp.tool(
+#     name="docs_prepend_text",
+# )
 async def docs_prepend_text(
     document_id: str, text: str, ensure_newline: bool = True
 ) -> dict[str, Any]:
@@ -190,10 +185,9 @@ async def docs_prepend_text(
     return result
 
 
-@mcp.tool(
-    name="docs_insert_text",
-    description="Inserts text at a specified location in a Google Document. For simple appends or prepends, use 'docs_append_text' or 'docs_prepend_text'.",
-)
+# @mcp.tool(
+#     name="docs_insert_text",
+# )
 async def docs_insert_text(
     document_id: str, text: str, index: int | None = None, segment_id: str | None = None
 ) -> dict[str, Any]:
@@ -234,10 +228,9 @@ async def docs_insert_text(
     return result
 
 
-@mcp.tool(
-    name="docs_batch_update",
-    description="Applies a list of raw Google Docs API update requests to a document. For advanced users familiar with Docs API request structures.",
-)
+# @mcp.tool(
+#     name="docs_batch_update",
+# )
 async def docs_batch_update(document_id: str, requests: list[dict]) -> dict[str, Any]:
     """
     Applies a list of Google Docs API update requests to the specified document.
@@ -277,10 +270,9 @@ async def docs_batch_update(document_id: str, requests: list[dict]) -> dict[str,
     return result  # Return the full response which includes documentId and replies
 
 
-@mcp.tool(
-    name="docs_insert_image",
-    description="Inserts an image into a Google Document from a URL at a specific index. The image URL must be publicly accessible and in PNG, JPEG, or GIF format.",
-)
+# @mcp.tool(
+#     name="docs_insert_image",
+# )
 async def docs_insert_image(
     document_id: str,
     image_url: str,

google_workspace_mcp/tools/drive.py

@@ -16,34 +16,70 @@ logger = logging.getLogger(__name__)
 
 @mcp.tool(
     name="drive_search_files",
-    description="Search for files in Google Drive with optional shared drive support.",
 )
 async def drive_search_files(
     query: str,
     page_size: int = 10,
     shared_drive_id: str | None = None,
+    include_shared_drives: bool = True,
+    include_trashed: bool = False,
 ) -> dict[str, Any]:
     """
-    Search for files in Google Drive, optionally within a specific shared drive.
+    Search for files in Google Drive with optional shared drive support. Trashed files are excluded by default.
+
+
+    Examples:
+    - "budget report" → works as-is
+    - "John's Documents" → automatically handled
 
     Args:
         query: Search query string. Can be a simple text search or complex query with operators.
+               Apostrophes are automatically escaped for you.
         page_size: Maximum number of files to return (1 to 1000, default 10).
         shared_drive_id: Optional shared drive ID to search within a specific shared drive.
+        include_shared_drives: Whether to include shared drives and folders in search (default True).
+                              Set to False to search only personal files.
+        include_trashed: Whether to include trashed files in search results (default False).
 
     Returns:
         A dictionary containing a list of files or an error message.
     """
     logger.info(
-        f"Executing drive_search_files with query: '{query}', page_size: {page_size}, shared_drive_id: {shared_drive_id}"
+        f"Executing drive_search_files with query: '{query}', page_size: {page_size}, "
+        f"shared_drive_id: {shared_drive_id}, include_shared_drives: {include_shared_drives}, "
+        f"include_trashed: {include_trashed}"
     )
 
     if not query or not query.strip():
         raise ValueError("Query cannot be empty")
 
+    # Logic to build a robust query
+    # If the query looks like a simple term (no spaces, no operators), wrap it.
+    # Otherwise, assume the user has provided a full query expression.
+    clean_query = query.strip()
+    if (
+        " " not in clean_query
+        and ":" not in clean_query
+        and "=" not in clean_query
+        and ">" not in clean_query
+        and "<" not in clean_query
+    ):
+        # This is likely a simple term, wrap it for a full-text search.
+        final_query = f"fullText contains '{clean_query.replace("'", "\\'")}'"
+    else:
+        # Assume it's a complex query and use it as-is.
+        final_query = clean_query.replace("'", "\\'")
+
+    # Append the trashed filter
+    if not include_trashed:
+        final_query = f"{final_query} and trashed=false"
+
     drive_service = DriveService()
     files = drive_service.search_files(
-        query=query, page_size=page_size, shared_drive_id=shared_drive_id
+        query=final_query,
+        page_size=page_size,
+        shared_drive_id=shared_drive_id,
+        include_shared_drives=include_shared_drives,
     )
 
     if isinstance(files, dict) and files.get("error"):
@@ -52,10 +88,9 @@ async def drive_search_files(
     return {"files": files}
 
 
-@mcp.tool(
-    name="drive_read_file_content",
-    description="Read the content of a file from Google Drive.",
-)
+# @mcp.tool(
+#     name="drive_read_file_content",
+# )
 async def drive_read_file_content(file_id: str) -> dict[str, Any]:
     """
     Read the content of a file from Google Drive.
@@ -82,10 +117,9 @@ async def drive_read_file_content(file_id: str) -> dict[str, Any]:
     return result
 
 
-@mcp.tool(
-    name="drive_upload_file",
-    description="Uploads a file to Google Drive by providing its content directly.",
-)
+# @mcp.tool(
+#     name="drive_upload_file",
+# )
 async def drive_upload_file(
     filename: str,
     content_base64: str,
@@ -126,10 +160,9 @@ async def drive_upload_file(
     return result
 
 
-@mcp.tool(
-    name="drive_create_folder",
-    description="Create a new folder in Google Drive.",
-)
+# @mcp.tool(
+#     name="drive_create_folder",
+# )
 async def drive_create_folder(
     folder_name: str,
     parent_folder_id: str | None = None,
@@ -168,10 +201,9 @@ async def drive_create_folder(
     return result
 
 
-@mcp.tool(
-    name="drive_delete_file",
-    description="Delete a file from Google Drive using its file ID.",
-)
+# @mcp.tool(
+#     name="drive_delete_file",
+# )
 async def drive_delete_file(
     file_id: str,
 ) -> dict[str, Any]:
@@ -199,7 +231,6 @@ async def drive_delete_file(
 
 @mcp.tool(
     name="drive_list_shared_drives",
-    description="Lists shared drives accessible by the user.",
 )
 async def drive_list_shared_drives(page_size: int = 100) -> dict[str, Any]:
     """
@@ -224,3 +255,215 @@ async def drive_list_shared_drives(page_size: int = 100) -> dict[str, Any]:
         return {"message": "No shared drives found or accessible."}
 
     return {"count": len(drives), "shared_drives": drives}
+
+
+@mcp.tool(
+    name="drive_search_files_in_folder",
+)
+async def drive_search_files_in_folder(
+    folder_id: str,
+    query: str = "",
+    page_size: int = 10,
+) -> dict[str, Any]:
+    """
+    Search for files or folders within a specific folder ID. Trashed files are excluded.
+    This works for both regular folders and Shared Drives (when using the Shared Drive's ID as the folder_id).
+
+    Args:
+        folder_id: The ID of the folder or Shared Drive to search within.
+        query: Optional search query string, following Google Drive API syntax.
+               If empty, returns all items.
+               Example to find only sub-folders: "mimeType = 'application/vnd.google-apps.folder'"
+        page_size: Maximum number of files to return (1 to 1000, default 10).
+
+    Returns:
+        A dictionary containing a list of files and folders.
+    """
+    logger.info(
+        f"Executing drive_search_files_in_folder with folder_id: '{folder_id}', "
+        f"query: '{query}', page_size: {page_size}"
+    )
+
+    if not folder_id or not folder_id.strip():
+        raise ValueError("Folder ID cannot be empty")
+
+    # Build the search query to search within the specific folder
+    folder_query = f"'{folder_id}' in parents and trashed=false"
+    if query and query.strip():
+        # Automatically escape apostrophes in user query
+        escaped_query = query.strip().replace("'", "\\'")
+        # Combine folder constraint with user query
+        combined_query = f"{escaped_query} and {folder_query}"
+    else:
+        combined_query = folder_query
+
+    drive_service = DriveService()
+    files = drive_service.search_files(
+        query=combined_query,
+        page_size=page_size,
+        include_shared_drives=True,  # Always include shared drives for folder searches
+    )
+
+    if isinstance(files, dict) and files.get("error"):
+        raise ValueError(
+            f"Folder search failed: {files.get('message', 'Unknown error')}"
+        )
+
+    return {"folder_id": folder_id, "files": files}
+
+
+# @mcp.tool(
+#     name="drive_get_folder_info",
+# )
+async def drive_get_folder_info(folder_id: str) -> dict[str, Any]:
+    """
+    Get detailed information about a folder in Google Drive.
+
+    Useful for understanding folder permissions and hierarchy.
+
+    Args:
+        folder_id: The ID of the folder to get information about.
+
+    Returns:
+        A dictionary containing folder metadata or an error message.
+    """
+    logger.info(f"Executing drive_get_folder_info with folder_id: '{folder_id}'")
+
+    if not folder_id or not folder_id.strip():
+        raise ValueError("Folder ID cannot be empty")
+
+    drive_service = DriveService()
+    folder_info = drive_service.get_file_metadata(file_id=folder_id)
+
+    if isinstance(folder_info, dict) and folder_info.get("error"):
+        raise ValueError(
+            f"Failed to get folder info: {folder_info.get('message', 'Unknown error')}"
+        )
+
+    # Verify it's actually a folder
+    if folder_info.get("mimeType") != "application/vnd.google-apps.folder":
+        raise ValueError(
+            f"ID '{folder_id}' is not a folder (mimeType: {folder_info.get('mimeType')})"
+        )
+
+    return folder_info
+
+
+@mcp.tool(
+    name="drive_find_folder_by_name",
+)
+async def drive_find_folder_by_name(
+    folder_name: str,
+    include_files: bool = False,
+    file_query: str = "",
+    page_size: int = 10,
+    shared_drive_id: str | None = None,
+) -> dict[str, Any]:
+    """
+    Finds folders by name using a two-step search: first an exact match, then a partial match.
+    Automatically handles apostrophes in folder names and search queries. Trashed items are excluded.
+
+    Crucial Note: This tool finds **regular folders** within "My Drive" or a Shared Drive.
+    It **does not** find Shared Drives themselves. To list available Shared Drives,
+    use the `drive_list_shared_drives` tool.
+
+    Args:
+        folder_name: The name of the folder to search for.
+        include_files: Whether to also search for files within the found folder (default False).
+        file_query: Optional search query for files within the folder. Only used if include_files=True.
+        page_size: Maximum number of files to return (1 to 1000, default 10).
+        shared_drive_id: Optional shared drive ID to search within a specific shared drive.
+
+    Returns:
+        A dictionary containing folders_found and, if requested, file search results.
+    """
+    logger.info(
+        f"Executing drive_find_folder_by_name with folder_name: '{folder_name}', "
+        f"include_files: {include_files}, file_query: '{file_query}', "
+        f"page_size: {page_size}, shared_drive_id: {shared_drive_id}"
+    )
+
+    if not folder_name or not folder_name.strip():
+        raise ValueError("Folder name cannot be empty")
+
+    drive_service = DriveService()
+    escaped_folder_name = folder_name.strip().replace("'", "\\'")
+
+    # --- Step 1: Attempt Exact Match ---
+    logger.info(f"Step 1: Searching for exact folder name: '{escaped_folder_name}'")
+    exact_query = f"name = '{escaped_folder_name}' and mimeType='application/vnd.google-apps.folder' and trashed=false"
+    folders = drive_service.search_files(
+        query=exact_query,
+        page_size=5,
+        shared_drive_id=shared_drive_id,
+        include_shared_drives=True,
+    )
+
+    # If no exact match, fall back to partial match
+    if not folders:
+        logger.info(
+            f"No exact match found. Step 2: Searching for folder name containing '{escaped_folder_name}'"
+        )
+        contains_query = f"name contains '{escaped_folder_name}' and mimeType='application/vnd.google-apps.folder' and trashed=false"
+        folders = drive_service.search_files(
+            query=contains_query,
+            page_size=5,
+            shared_drive_id=shared_drive_id,
+            include_shared_drives=True,
+        )
+
+    if isinstance(folders, dict) and folders.get("error"):
+        raise ValueError(
+            f"Folder search failed: {folders.get('message', 'Unknown error')}"
+        )
+
+    result = {
+        "folder_name": folder_name,
+        "folders_found": folders,
+        "folder_count": len(folders) if folders else 0,
+    }
+
+    if not include_files:
+        return result
+
+    if not folders:
+        result["message"] = f"No folders found with name matching '{folder_name}'"
+        return result
+
+    target_folder = folders[0]
+    folder_id = target_folder["id"]
+
+    # Build the search query for files within the folder
+    folder_constraint = f"'{folder_id}' in parents and trashed=false"
+
+    if file_query and file_query.strip():
+        # Use the same smart query logic as drive_search_files
+        clean_file_query = file_query.strip()
+        if (
+            " " not in clean_file_query
+            and ":" not in clean_file_query
+            and "=" not in clean_file_query
+        ):
+            wrapped_file_query = (
+                f"fullText contains '{clean_file_query.replace("'", "\\'")}'"
+            )
+        else:
+            wrapped_file_query = clean_file_query.replace("'", "\\'")
+        combined_query = f"{wrapped_file_query} and {folder_constraint}"
+    else:
+        combined_query = folder_constraint
+
+    files = drive_service.search_files(
+        query=combined_query, page_size=page_size, include_shared_drives=True
+    )
+
+    if isinstance(files, dict) and files.get("error"):
+        raise ValueError(
+            f"File search in folder failed: {files.get('message', 'Unknown error')}"
+        )
+
+    result["target_folder"] = target_folder
+    result["files"] = files
+    result["file_count"] = len(files) if files else 0
+
+    return result

google_workspace_mcp/tools/gmail.py

@@ -14,10 +14,9 @@ logger = logging.getLogger(__name__)
 # --- Gmail Tool Functions --- #
 
 
-@mcp.tool(
-    name="query_gmail_emails",
-    description="Query Gmail emails based on a search query.",
-)
+# @mcp.tool(
+#     name="query_gmail_emails",
+# )
 async def query_gmail_emails(query: str, max_results: int = 100) -> dict[str, Any]:
     """
     Searches for Gmail emails using Gmail query syntax.
@@ -45,10 +44,9 @@ async def query_gmail_emails(query: str, max_results: int = 100) -> dict[str, An
     return {"count": len(emails), "emails": emails}
 
 
-@mcp.tool(
-    name="gmail_get_message_details",
-    description="Retrieves a complete Gmail email message by its ID.",
-)
+# @mcp.tool(
+#     name="gmail_get_message_details",
+# )
 async def gmail_get_message_details(email_id: str) -> dict[str, Any]:
     """
     Retrieves a complete Gmail email message by its ID.
@@ -77,10 +75,9 @@ async def gmail_get_message_details(email_id: str) -> dict[str, Any]:
     return result
 
 
-@mcp.tool(
-    name="gmail_get_attachment_content",
-    description="Retrieves a specific attachment from a Gmail message.",
-)
+# @mcp.tool(
+#     name="gmail_get_attachment_content",
+# )
 async def gmail_get_attachment_content(message_id: str, attachment_id: str) -> dict[str, Any]:
     """
     Retrieves a specific attachment from a Gmail message.
@@ -109,10 +106,9 @@ async def gmail_get_attachment_content(message_id: str, attachment_id: str) -> d
     return result
 
 
-@mcp.tool(
-    name="create_gmail_draft",
-    description="Creates a draft email message in Gmail.",
-)
+# @mcp.tool(
+#     name="create_gmail_draft",
+# )
 async def create_gmail_draft(
     to: str,
     subject: str,
@@ -150,10 +146,9 @@ async def create_gmail_draft(
     return result
 
 
-@mcp.tool(
-    name="delete_gmail_draft",
-    description="Deletes a Gmail draft email by its draft ID.",
-)
+# @mcp.tool(
+#     name="delete_gmail_draft",
+# )
 async def delete_gmail_draft(
     draft_id: str,
 ) -> dict[str, Any]:
@@ -189,10 +184,9 @@ async def delete_gmail_draft(
     }
 
 
-@mcp.tool(
-    name="gmail_send_draft",
-    description="Sends an existing draft email from Gmail.",
-)
+# @mcp.tool(
+#     name="gmail_send_draft",
+# )
 async def gmail_send_draft(draft_id: str) -> dict[str, Any]:
     """
     Sends a specific draft email.
@@ -219,10 +213,9 @@ async def gmail_send_draft(draft_id: str) -> dict[str, Any]:
     return result
 
 
-@mcp.tool(
-    name="gmail_reply_to_email",
-    description="Create a reply to an existing email. Can be sent or saved as draft.",
-)
+# @mcp.tool(
+#     name="gmail_reply_to_email",
+# )
 async def gmail_reply_to_email(
     email_id: str,
     reply_body: str,
@@ -262,10 +255,9 @@ async def gmail_reply_to_email(
     return result
 
 
-@mcp.tool(
-    name="gmail_bulk_delete_messages",
-    description="Delete multiple emails at once by providing a list of message IDs.",
-)
+# @mcp.tool(
+#     name="gmail_bulk_delete_messages",
+# )
 async def gmail_bulk_delete_messages(
     message_ids: list[str],
 ) -> dict[str, Any]:
@@ -300,10 +292,9 @@ async def gmail_bulk_delete_messages(
     return result
 
 
-@mcp.tool(
-    name="gmail_send_email",
-    description="Composes and sends an email directly.",
-)
+# @mcp.tool(
+#     name="gmail_send_email",
+# )
 async def gmail_send_email(
     to: list[str],
     subject: str,