workspace-mcp 0.2.0__py3-none-any.whl

gmail/gmail_tools.py

@@ -0,0 +1,807 @@
+"""
+Google Gmail MCP Tools
+
+This module provides MCP tools for interacting with the Gmail API.
+"""
+
+import logging
+import asyncio
+import base64
+from typing import Optional, List, Dict, Literal
+
+from email.mime.text import MIMEText
+
+from mcp import types
+from fastapi import Body
+from googleapiclient.errors import HttpError
+
+from auth.service_decorator import require_google_service
+
+from core.server import (
+    GMAIL_READONLY_SCOPE,
+    GMAIL_SEND_SCOPE,
+    GMAIL_COMPOSE_SCOPE,
+    GMAIL_MODIFY_SCOPE,
+    GMAIL_LABELS_SCOPE,
+    server,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def _extract_message_body(payload):
+    """
+    Helper function to extract plain text body from a Gmail message payload.
+
+    Args:
+        payload (dict): The message payload from Gmail API
+
+    Returns:
+        str: The plain text body content, or empty string if not found
+    """
+    body_data = ""
+    parts = [payload] if "parts" not in payload else payload.get("parts", [])
+
+    part_queue = list(parts)  # Use a queue for BFS traversal of parts
+    while part_queue:
+        part = part_queue.pop(0)
+        if part.get("mimeType") == "text/plain" and part.get("body", {}).get("data"):
+            data = base64.urlsafe_b64decode(part["body"]["data"])
+            body_data = data.decode("utf-8", errors="ignore")
+            break  # Found plain text body
+        elif part.get("mimeType", "").startswith("multipart/") and "parts" in part:
+            part_queue.extend(part.get("parts", []))  # Add sub-parts to the queue
+
+    # If no plain text found, check the main payload body if it exists
+    if (
+        not body_data
+        and payload.get("mimeType") == "text/plain"
+        and payload.get("body", {}).get("data")
+    ):
+        data = base64.urlsafe_b64decode(payload["body"]["data"])
+        body_data = data.decode("utf-8", errors="ignore")
+
+    return body_data
+
+
+def _extract_headers(payload: dict, header_names: List[str]) -> Dict[str, str]:
+    """
+    Extract specified headers from a Gmail message payload.
+
+    Args:
+        payload: The message payload from Gmail API
+        header_names: List of header names to extract
+
+    Returns:
+        Dict mapping header names to their values
+    """
+    headers = {}
+    for header in payload.get("headers", []):
+        if header["name"] in header_names:
+            headers[header["name"]] = header["value"]
+    return headers
+
+
+def _generate_gmail_web_url(item_id: str, account_index: int = 0) -> str:
+    """
+    Generate Gmail web interface URL for a message or thread ID.
+    Uses #all to access messages from any Gmail folder/label (not just inbox).
+
+    Args:
+        item_id: Gmail message ID or thread ID
+        account_index: Google account index (default 0 for primary account)
+
+    Returns:
+        Gmail web interface URL that opens the message/thread in Gmail web interface
+    """
+    return f"https://mail.google.com/mail/u/{account_index}/#all/{item_id}"
+
+
+def _format_gmail_results_plain(messages: list, query: str) -> str:
+    """Format Gmail search results in clean, LLM-friendly plain text."""
+    if not messages:
+        return f"No messages found for query: '{query}'"
+
+    lines = [
+        f"Found {len(messages)} messages matching '{query}':",
+        "",
+        "📧 MESSAGES:",
+    ]
+
+    for i, msg in enumerate(messages, 1):
+        message_url = _generate_gmail_web_url(msg["id"])
+        thread_url = _generate_gmail_web_url(msg["threadId"])
+
+        lines.extend([
+            f"  {i}. Message ID: {msg['id']}",
+            f"     Web Link: {message_url}",
+            f"     Thread ID: {msg['threadId']}",
+            f"     Thread Link: {thread_url}",
+            ""
+        ])
+
+    lines.extend([
+        "💡 USAGE:",
+        "  • Pass the Message IDs **as a list** to get_gmail_messages_content_batch()",
+        "    e.g. get_gmail_messages_content_batch(message_ids=[...])",
+        "  • Pass the Thread IDs to get_gmail_thread_content() (single) _or_",
+        "    get_gmail_threads_content_batch() (coming soon)"
+    ])
+
+    return "\n".join(lines)
+
+
+@server.tool()
+@require_google_service("gmail", "gmail_read")
+async def search_gmail_messages(
+    service, query: str, user_google_email: str, page_size: int = 10
+) -> str:
+    """
+    Searches messages in a user's Gmail account based on a query.
+    Returns both Message IDs and Thread IDs for each found message, along with Gmail web interface links for manual verification.
+
+    Args:
+        query (str): The search query. Supports standard Gmail search operators.
+        user_google_email (str): The user's Google email address. Required.
+        page_size (int): The maximum number of messages to return. Defaults to 10.
+
+    Returns:
+        str: LLM-friendly structured results with Message IDs, Thread IDs, and clickable Gmail web interface URLs for each found message.
+    """
+    logger.info(f"[search_gmail_messages] Email: '{user_google_email}', Query: '{query}'")
+
+    try:
+        response = await asyncio.to_thread(
+            service.users()
+            .messages()
+            .list(userId="me", q=query, maxResults=page_size)
+            .execute
+        )
+        messages = response.get("messages", [])
+        formatted_output = _format_gmail_results_plain(messages, query)
+
+        logger.info(f"[search_gmail_messages] Found {len(messages)} messages")
+        return formatted_output
+
+    except HttpError as e:
+        error_msg = f"Gmail API error: {e.reason}" if e.resp.status != 400 else f"Invalid query: '{query}'"
+        logger.error(f"[search_gmail_messages] {error_msg}")
+        raise Exception(error_msg)
+    except Exception as e:
+        error_msg = f"Error searching Gmail: {str(e)}"
+        logger.error(f"[search_gmail_messages] {error_msg}")
+        raise Exception(error_msg)
+
+
+@server.tool()
+@require_google_service("gmail", "gmail_read")
+async def get_gmail_message_content(
+    service, message_id: str, user_google_email: str
+) -> str:
+    """
+    Retrieves the full content (subject, sender, plain text body) of a specific Gmail message.
+
+    Args:
+        message_id (str): The unique ID of the Gmail message to retrieve.
+        user_google_email (str): The user's Google email address. Required.
+
+    Returns:
+        str: The message details including subject, sender, and body content.
+    """
+    logger.info(
+        f"[get_gmail_message_content] Invoked. Message ID: '{message_id}', Email: '{user_google_email}'"
+    )
+
+    try:
+        logger.info(f"[get_gmail_message_content] Using service for: {user_google_email}")
+
+        # Fetch message metadata first to get headers
+        message_metadata = await asyncio.to_thread(
+            service.users()
+            .messages()
+            .get(
+                userId="me",
+                id=message_id,
+                format="metadata",
+                metadataHeaders=["Subject", "From"],
+            )
+            .execute
+        )
+
+        headers = {
+            h["name"]: h["value"]
+            for h in message_metadata.get("payload", {}).get("headers", [])
+        }
+        subject = headers.get("Subject", "(no subject)")
+        sender = headers.get("From", "(unknown sender)")
+
+        # Now fetch the full message to get the body parts
+        message_full = await asyncio.to_thread(
+            service.users()
+            .messages()
+            .get(
+                userId="me",
+                id=message_id,
+                format="full",  # Request full payload for body
+            )
+            .execute
+        )
+
+        # Extract the plain text body using helper function
+        payload = message_full.get("payload", {})
+        body_data = _extract_message_body(payload)
+
+        content_text = "\n".join(
+            [
+                f"Subject: {subject}",
+                f"From:    {sender}",
+                f"\n--- BODY ---\n{body_data or '[No text/plain body found]'}",
+            ]
+        )
+        return content_text
+
+    except HttpError as e:
+        logger.error(
+            f"[get_gmail_message_content] Gmail API error getting message content: {e}", exc_info=True
+        )
+        raise Exception(f"Gmail API error: {e}")
+    except Exception as e:
+        logger.exception(
+            f"[get_gmail_message_content] Unexpected error getting Gmail message content: {e}"
+        )
+        raise Exception(f"Unexpected error: {e}")
+
+
+@server.tool()
+@require_google_service("gmail", "gmail_read")
+async def get_gmail_messages_content_batch(
+    service,
+    message_ids: List[str],
+    user_google_email: str,
+    format: Literal["full", "metadata"] = "full",
+) -> str:
+    """
+    Retrieves the content of multiple Gmail messages in a single batch request.
+    Supports up to 100 messages per request using Google's batch API.
+
+    Args:
+        message_ids (List[str]): List of Gmail message IDs to retrieve (max 100).
+        user_google_email (str): The user's Google email address. Required.
+        format (Literal["full", "metadata"]): Message format. "full" includes body, "metadata" only headers.
+
+    Returns:
+        str: A formatted list of message contents with separators.
+    """
+    logger.info(
+        f"[get_gmail_messages_content_batch] Invoked. Message count: {len(message_ids)}, Email: '{user_google_email}'"
+    )
+
+    if not message_ids:
+        raise Exception("No message IDs provided")
+
+    try:
+        output_messages = []
+
+        # Process in chunks of 100 (Gmail batch limit)
+        for chunk_start in range(0, len(message_ids), 100):
+            chunk_ids = message_ids[chunk_start:chunk_start + 100]
+            results: Dict[str, Dict] = {}
+
+            def _batch_callback(request_id, response, exception):
+                """Callback for batch requests"""
+                results[request_id] = {"data": response, "error": exception}
+
+            # Try to use batch API
+            try:
+                batch = service.new_batch_http_request(callback=_batch_callback)
+
+                for mid in chunk_ids:
+                    if format == "metadata":
+                        req = service.users().messages().get(
+                            userId="me",
+                            id=mid,
+                            format="metadata",
+                            metadataHeaders=["Subject", "From"]
+                        )
+                    else:
+                        req = service.users().messages().get(
+                            userId="me",
+                            id=mid,
+                            format="full"
+                        )
+                    batch.add(req, request_id=mid)
+
+                # Execute batch request
+                await asyncio.to_thread(batch.execute)
+
+            except Exception as batch_error:
+                # Fallback to asyncio.gather if batch API fails
+                logger.warning(
+                    f"[get_gmail_messages_content_batch] Batch API failed, falling back to asyncio.gather: {batch_error}"
+                )
+
+                async def fetch_message(mid: str):
+                    try:
+                        if format == "metadata":
+                            msg = await asyncio.to_thread(
+                                service.users().messages().get(
+                                    userId="me",
+                                    id=mid,
+                                    format="metadata",
+                                    metadataHeaders=["Subject", "From"]
+                                ).execute
+                            )
+                        else:
+                            msg = await asyncio.to_thread(
+                                service.users().messages().get(
+                                    userId="me",
+                                    id=mid,
+                                    format="full"
+                                ).execute
+                            )
+                        return mid, msg, None
+                    except Exception as e:
+                        return mid, None, e
+
+                # Fetch all messages in parallel
+                fetch_results = await asyncio.gather(
+                    *[fetch_message(mid) for mid in chunk_ids],
+                    return_exceptions=False
+                )
+
+                # Convert to results format
+                for mid, msg, error in fetch_results:
+                    results[mid] = {"data": msg, "error": error}
+
+            # Process results for this chunk
+            for mid in chunk_ids:
+                entry = results.get(mid, {"data": None, "error": "No result"})
+
+                if entry["error"]:
+                    output_messages.append(
+                        f"⚠️ Message {mid}: {entry['error']}\n"
+                    )
+                else:
+                    message = entry["data"]
+                    if not message:
+                        output_messages.append(
+                            f"⚠️ Message {mid}: No data returned\n"
+                        )
+                        continue
+
+                    # Extract content based on format
+                    payload = message.get("payload", {})
+
+                    if format == "metadata":
+                        headers = _extract_headers(payload, ["Subject", "From"])
+                        subject = headers.get("Subject", "(no subject)")
+                        sender = headers.get("From", "(unknown sender)")
+
+                        output_messages.append(
+                            f"Message ID: {mid}\n"
+                            f"Subject: {subject}\n"
+                            f"From: {sender}\n"
+                            f"Web Link: {_generate_gmail_web_url(mid)}\n"
+                        )
+                    else:
+                        # Full format - extract body too
+                        headers = _extract_headers(payload, ["Subject", "From"])
+                        subject = headers.get("Subject", "(no subject)")
+                        sender = headers.get("From", "(unknown sender)")
+                        body = _extract_message_body(payload)
+
+                        output_messages.append(
+                            f"Message ID: {mid}\n"
+                            f"Subject: {subject}\n"
+                            f"From: {sender}\n"
+                            f"Web Link: {_generate_gmail_web_url(mid)}\n"
+                            f"\n{body or '[No text/plain body found]'}\n"
+                        )
+
+        # Combine all messages with separators
+        final_output = f"Retrieved {len(message_ids)} messages:\n\n"
+        final_output += "\n---\n\n".join(output_messages)
+
+        return final_output
+
+    except HttpError as e:
+        logger.error(
+            f"[get_gmail_messages_content_batch] Gmail API error in batch retrieval: {e}", exc_info=True
+        )
+        raise Exception(f"Gmail API error: {e}")
+    except Exception as e:
+        logger.exception(
+            f"[get_gmail_messages_content_batch] Unexpected error in batch retrieval: {e}"
+        )
+        raise Exception(f"Unexpected error: {e}")
+
+
+@server.tool()
+@require_google_service("gmail", GMAIL_SEND_SCOPE)
+async def send_gmail_message(
+    service,
+    user_google_email: str,
+    to: str = Body(..., description="Recipient email address."),
+    subject: str = Body(..., description="Email subject."),
+    body: str = Body(..., description="Email body (plain text)."),
+) -> str:
+    """
+    Sends an email using the user's Gmail account.
+
+    Args:
+        to (str): Recipient email address.
+        subject (str): Email subject.
+        body (str): Email body (plain text).
+        user_google_email (str): The user's Google email address. Required.
+
+    Returns:
+        str: Confirmation message with the sent email's message ID.
+    """
+    try:
+        # Prepare the email
+        message = MIMEText(body)
+        message["to"] = to
+        message["subject"] = subject
+        raw_message = base64.urlsafe_b64encode(message.as_bytes()).decode()
+        send_body = {"raw": raw_message}
+
+        # Send the message
+        sent_message = await asyncio.to_thread(
+            service.users().messages().send(userId="me", body=send_body).execute
+        )
+        message_id = sent_message.get("id")
+        return f"Email sent! Message ID: {message_id}"
+
+    except HttpError as e:
+        logger.error(
+            f"[send_gmail_message] Gmail API error sending message: {e}", exc_info=True
+        )
+        raise Exception(f"Gmail API error: {e}")
+    except Exception as e:
+        logger.exception(f"[send_gmail_message] Unexpected error sending Gmail message: {e}")
+        raise Exception(f"Unexpected error: {e}")
+
+
+@server.tool()
+@require_google_service("gmail", GMAIL_COMPOSE_SCOPE)
+async def draft_gmail_message(
+    service,
+    user_google_email: str,
+    subject: str = Body(..., description="Email subject."),
+    body: str = Body(..., description="Email body (plain text)."),
+    to: Optional[str] = Body(None, description="Optional recipient email address."),
+) -> str:
+    """
+    Creates a draft email in the user's Gmail account.
+
+    Args:
+        user_google_email (str): The user's Google email address. Required.
+        subject (str): Email subject.
+        body (str): Email body (plain text).
+        to (Optional[str]): Optional recipient email address. Can be left empty for drafts.
+
+    Returns:
+        str: Confirmation message with the created draft's ID.
+    """
+    logger.info(
+        f"[draft_gmail_message] Invoked. Email: '{user_google_email}', Subject: '{subject}'"
+    )
+
+    try:
+        # Prepare the email
+        message = MIMEText(body)
+        message["subject"] = subject
+
+        # Add recipient if provided
+        if to:
+            message["to"] = to
+
+        raw_message = base64.urlsafe_b64encode(message.as_bytes()).decode()
+
+        # Create a draft instead of sending
+        draft_body = {"message": {"raw": raw_message}}
+
+        # Create the draft
+        created_draft = await asyncio.to_thread(
+            service.users().drafts().create(userId="me", body=draft_body).execute
+        )
+        draft_id = created_draft.get("id")
+        return f"Draft created! Draft ID: {draft_id}"
+
+    except HttpError as e:
+        logger.error(
+            f"[draft_gmail_message] Gmail API error creating draft: {e}", exc_info=True
+        )
+        raise Exception(f"Gmail API error: {e}")
+    except Exception as e:
+        logger.exception(f"[draft_gmail_message] Unexpected error creating Gmail draft: {e}")
+        raise Exception(f"Unexpected error: {e}")
+
+
+@server.tool()
+@require_google_service("gmail", "gmail_read")
+async def get_gmail_thread_content(
+    service, thread_id: str, user_google_email: str
+) -> str:
+    """
+    Retrieves the complete content of a Gmail conversation thread, including all messages.
+
+    Args:
+        thread_id (str): The unique ID of the Gmail thread to retrieve.
+        user_google_email (str): The user's Google email address. Required.
+
+    Returns:
+        str: The complete thread content with all messages formatted for reading.
+    """
+    logger.info(
+        f"[get_gmail_thread_content] Invoked. Thread ID: '{thread_id}', Email: '{user_google_email}'"
+    )
+
+    try:
+        # Fetch the complete thread with all messages
+        thread_response = await asyncio.to_thread(
+            service.users()
+            .threads()
+            .get(userId="me", id=thread_id, format="full")
+            .execute
+        )
+
+        messages = thread_response.get("messages", [])
+        if not messages:
+            return f"No messages found in thread '{thread_id}'."
+
+        # Extract thread subject from the first message
+        first_message = messages[0]
+        first_headers = {
+            h["name"]: h["value"]
+            for h in first_message.get("payload", {}).get("headers", [])
+        }
+        thread_subject = first_headers.get("Subject", "(no subject)")
+
+        # Build the thread content
+        content_lines = [
+            f"Thread ID: {thread_id}",
+            f"Subject: {thread_subject}",
+            f"Messages: {len(messages)}",
+            "",
+        ]
+
+        # Process each message in the thread
+        for i, message in enumerate(messages, 1):
+            # Extract headers
+            headers = {
+                h["name"]: h["value"]
+                for h in message.get("payload", {}).get("headers", [])
+            }
+
+            sender = headers.get("From", "(unknown sender)")
+            date = headers.get("Date", "(unknown date)")
+            subject = headers.get("Subject", "(no subject)")
+
+            # Extract message body
+            payload = message.get("payload", {})
+            body_data = _extract_message_body(payload)
+
+            # Add message to content
+            content_lines.extend(
+                [
+                    f"=== Message {i} ===",
+                    f"From: {sender}",
+                    f"Date: {date}",
+                ]
+            )
+
+            # Only show subject if it's different from thread subject
+            if subject != thread_subject:
+                content_lines.append(f"Subject: {subject}")
+
+            content_lines.extend(
+                [
+                    "",
+                    body_data or "[No text/plain body found]",
+                    "",
+                ]
+            )
+
+        content_text = "\n".join(content_lines)
+        return content_text
+
+    except HttpError as e:
+        logger.error(
+            f"[get_gmail_thread_content] Gmail API error getting thread content: {e}", exc_info=True
+        )
+        raise Exception(f"Gmail API error: {e}")
+    except Exception as e:
+        logger.exception(
+            f"[get_gmail_thread_content] Unexpected error getting Gmail thread content: {e}"
+        )
+        raise Exception(f"Unexpected error: {e}")
+
+
+@server.tool()
+@require_google_service("gmail", "gmail_read")
+async def list_gmail_labels(service, user_google_email: str) -> str:
+    """
+    Lists all labels in the user's Gmail account.
+
+    Args:
+        user_google_email (str): The user's Google email address. Required.
+
+    Returns:
+        str: A formatted list of all labels with their IDs, names, and types.
+    """
+    logger.info(f"[list_gmail_labels] Invoked. Email: '{user_google_email}'")
+
+    try:
+        response = await asyncio.to_thread(
+            service.users().labels().list(userId="me").execute
+        )
+        labels = response.get("labels", [])
+
+        if not labels:
+            return "No labels found."
+
+        lines = [f"Found {len(labels)} labels:", ""]
+
+        system_labels = []
+        user_labels = []
+
+        for label in labels:
+            if label.get("type") == "system":
+                system_labels.append(label)
+            else:
+                user_labels.append(label)
+
+        if system_labels:
+            lines.append("📂 SYSTEM LABELS:")
+            for label in system_labels:
+                lines.append(f"  • {label['name']} (ID: {label['id']})")
+            lines.append("")
+
+        if user_labels:
+            lines.append("🏷️  USER LABELS:")
+            for label in user_labels:
+                lines.append(f"  • {label['name']} (ID: {label['id']})")
+
+        return "\n".join(lines)
+
+    except HttpError as e:
+        logger.error(f"[list_gmail_labels] Gmail API error listing labels: {e}", exc_info=True)
+        raise Exception(f"Gmail API error: {e}")
+    except Exception as e:
+        logger.exception(f"[list_gmail_labels] Unexpected error listing Gmail labels: {e}")
+        raise Exception(f"Unexpected error: {e}")
+
+
+@server.tool()
+@require_google_service("gmail", GMAIL_LABELS_SCOPE)
+async def manage_gmail_label(
+    service,
+    user_google_email: str,
+    action: Literal["create", "update", "delete"],
+    name: Optional[str] = None,
+    label_id: Optional[str] = None,
+    label_list_visibility: Literal["labelShow", "labelHide"] = "labelShow",
+    message_list_visibility: Literal["show", "hide"] = "show",
+) -> str:
+    """
+    Manages Gmail labels: create, update, or delete labels.
+
+    Args:
+        user_google_email (str): The user's Google email address. Required.
+        action (Literal["create", "update", "delete"]): Action to perform on the label.
+        name (Optional[str]): Label name. Required for create, optional for update.
+        label_id (Optional[str]): Label ID. Required for update and delete operations.
+        label_list_visibility (Literal["labelShow", "labelHide"]): Whether the label is shown in the label list.
+        message_list_visibility (Literal["show", "hide"]): Whether the label is shown in the message list.
+
+    Returns:
+        str: Confirmation message of the label operation.
+    """
+    logger.info(f"[manage_gmail_label] Invoked. Email: '{user_google_email}', Action: '{action}'")
+
+    if action == "create" and not name:
+        raise Exception("Label name is required for create action.")
+
+    if action in ["update", "delete"] and not label_id:
+        raise Exception("Label ID is required for update and delete actions.")
+
+    try:
+        if action == "create":
+            label_object = {
+                "name": name,
+                "labelListVisibility": label_list_visibility,
+                "messageListVisibility": message_list_visibility,
+            }
+            created_label = await asyncio.to_thread(
+                service.users().labels().create(userId="me", body=label_object).execute
+            )
+            return f"Label created successfully!\nName: {created_label['name']}\nID: {created_label['id']}"
+
+        elif action == "update":
+            current_label = await asyncio.to_thread(
+                service.users().labels().get(userId="me", id=label_id).execute
+            )
+
+            label_object = {
+                "id": label_id,
+                "name": name if name is not None else current_label["name"],
+                "labelListVisibility": label_list_visibility,
+                "messageListVisibility": message_list_visibility,
+            }
+
+            updated_label = await asyncio.to_thread(
+                service.users().labels().update(userId="me", id=label_id, body=label_object).execute
+            )
+            return f"Label updated successfully!\nName: {updated_label['name']}\nID: {updated_label['id']}"
+
+        elif action == "delete":
+            label = await asyncio.to_thread(
+                service.users().labels().get(userId="me", id=label_id).execute
+            )
+            label_name = label["name"]
+
+            await asyncio.to_thread(
+                service.users().labels().delete(userId="me", id=label_id).execute
+            )
+            return f"Label '{label_name}' (ID: {label_id}) deleted successfully!"
+
+    except HttpError as e:
+        logger.error(f"[manage_gmail_label] Gmail API error: {e}", exc_info=True)
+        raise Exception(f"Gmail API error: {e}")
+    except Exception as e:
+        logger.exception(f"[manage_gmail_label] Unexpected error: {e}")
+        raise Exception(f"Unexpected error: {e}")
+
+
+@server.tool()
+@require_google_service("gmail", GMAIL_MODIFY_SCOPE)
+async def modify_gmail_message_labels(
+    service,
+    user_google_email: str,
+    message_id: str,
+    add_label_ids: Optional[List[str]] = None,
+    remove_label_ids: Optional[List[str]] = None,
+) -> str:
+    """
+    Adds or removes labels from a Gmail message.
+
+    Args:
+        user_google_email (str): The user's Google email address. Required.
+        message_id (str): The ID of the message to modify.
+        add_label_ids (Optional[List[str]]): List of label IDs to add to the message.
+        remove_label_ids (Optional[List[str]]): List of label IDs to remove from the message.
+
+    Returns:
+        str: Confirmation message of the label changes applied to the message.
+    """
+    logger.info(f"[modify_gmail_message_labels] Invoked. Email: '{user_google_email}', Message ID: '{message_id}'")
+
+    if not add_label_ids and not remove_label_ids:
+        raise Exception("At least one of add_label_ids or remove_label_ids must be provided.")
+
+    try:
+        body = {}
+        if add_label_ids:
+            body["addLabelIds"] = add_label_ids
+        if remove_label_ids:
+            body["removeLabelIds"] = remove_label_ids
+
+        await asyncio.to_thread(
+            service.users().messages().modify(userId="me", id=message_id, body=body).execute
+        )
+
+        actions = []
+        if add_label_ids:
+            actions.append(f"Added labels: {', '.join(add_label_ids)}")
+        if remove_label_ids:
+            actions.append(f"Removed labels: {', '.join(remove_label_ids)}")
+
+        return f"Message labels updated successfully!\nMessage ID: {message_id}\n{'; '.join(actions)}"
+
+    except HttpError as e:
+        logger.error(f"[modify_gmail_message_labels] Gmail API error modifying message labels: {e}", exc_info=True)
+        raise Exception(f"Gmail API error: {e}")
+    except Exception as e:
+        logger.exception(f"[modify_gmail_message_labels] Unexpected error modifying Gmail message labels: {e}")
+        raise Exception(f"Unexpected error: {e}")