workspace-mcp 1.1.4__py3-none-any.whl → 1.1.6__py3-none-any.whl

gforms/forms_tools.py

@@ -6,10 +6,9 @@ This module provides MCP tools for interacting with Google Forms API.
 
 import logging
 import asyncio
-from typing import List, Optional, Dict, Any
+from typing import 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
@@ -19,8 +18,8 @@ logger = logging.getLogger(__name__)
 
 
 @server.tool()
-@require_google_service("forms", "forms")
 @handle_http_errors("create_form")
+@require_google_service("forms", "forms")
 async def create_form(
     service,
     user_google_email: str,
@@ -47,10 +46,10 @@ async def create_form(
             "title": title
         }
     }
-    
+
     if description:
         form_body["info"]["description"] = description
-        
+
     if document_title:
         form_body["info"]["document_title"] = document_title
 
@@ -61,15 +60,15 @@ async def create_form(
     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
 
 
 @server.tool()
+@handle_http_errors("get_form", is_read_only=True)
 @require_google_service("forms", "forms")
-@handle_http_errors("get_form")
 async def get_form(
     service,
     user_google_email: str,
@@ -95,10 +94,10 @@ async def get_form(
     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):
@@ -106,9 +105,9 @@ async def get_form(
         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}"
@@ -118,14 +117,14 @@ async def get_form(
 - 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
 
 
 @server.tool()
-@require_google_service("forms", "forms")
 @handle_http_errors("set_publish_settings")
+@require_google_service("forms", "forms")
 async def set_publish_settings(
     service,
     user_google_email: str,
@@ -162,8 +161,8 @@ async def set_publish_settings(
 
 
 @server.tool()
+@handle_http_errors("get_form_response", is_read_only=True)
 @require_google_service("forms", "forms")
-@handle_http_errors("get_form_response")
 async def get_form_response(
     service,
     user_google_email: str,
@@ -190,7 +189,7 @@ async def get_form_response(
     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():
@@ -200,9 +199,9 @@ async def get_form_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}
@@ -210,14 +209,14 @@ async def get_form_response(
 - Last Submitted: {last_submitted_time}
 - Answers:
 {answers_text}"""
-    
+
     logger.info(f"Successfully retrieved response for {user_google_email}. Response ID: {response_id}")
     return result
 
 
 @server.tool()
+@handle_http_errors("list_form_responses", is_read_only=True)
 @require_google_service("forms", "forms")
-@handle_http_errors("list_form_responses")
 async def list_form_responses(
     service,
     user_google_email: str,
@@ -252,7 +251,7 @@ async def list_form_responses(
 
     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}."
 
@@ -261,19 +260,19 @@ async def list_form_responses(
         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

gmail/gmail_tools.py

@@ -13,7 +13,6 @@ 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.utils import handle_http_errors
@@ -112,28 +111,31 @@ def _format_gmail_results_plain(messages: list, query: str) -> str:
         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)"
-    ])
+        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() (batch)",
+        ]
+    )
 
     return "\n".join(lines)
 
 
 @server.tool()
+@handle_http_errors("search_gmail_messages", is_read_only=True)
 @require_google_service("gmail", "gmail_read")
-@handle_http_errors("search_gmail_messages")
 async def search_gmail_messages(
     service, query: str, user_google_email: str, page_size: int = 10
 ) -> str:
@@ -149,7 +151,9 @@ async def search_gmail_messages(
     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}'")
+    logger.info(
+        f"[search_gmail_messages] Email: '{user_google_email}', Query: '{query}'"
+    )
 
     response = await asyncio.to_thread(
         service.users()
@@ -165,8 +169,8 @@ async def search_gmail_messages(
 
 
 @server.tool()
+@handle_http_errors("get_gmail_message_content", is_read_only=True)
 @require_google_service("gmail", "gmail_read")
-@handle_http_errors("get_gmail_message_content")
 async def get_gmail_message_content(
     service, message_id: str, user_google_email: str
 ) -> str:
@@ -233,8 +237,8 @@ async def get_gmail_message_content(
 
 
 @server.tool()
+@handle_http_errors("get_gmail_messages_content_batch", is_read_only=True)
 @require_google_service("gmail", "gmail_read")
-@handle_http_errors("get_gmail_messages_content_batch")
 async def get_gmail_messages_content_batch(
     service,
     message_ids: List[str],
@@ -264,7 +268,7 @@ async def get_gmail_messages_content_batch(
 
     # 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]
+        chunk_ids = message_ids[chunk_start : chunk_start + 100]
         results: Dict[str, Dict] = {}
 
         def _batch_callback(request_id, response, exception):
@@ -277,17 +281,21 @@ async def get_gmail_messages_content_batch(
 
             for mid in chunk_ids:
                 if format == "metadata":
-                    req = service.users().messages().get(
-                        userId="me",
-                        id=mid,
-                        format="metadata",
-                        metadataHeaders=["Subject", "From"]
+                    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"
+                    req = (
+                        service.users()
+                        .messages()
+                        .get(userId="me", id=mid, format="full")
                     )
                 batch.add(req, request_id=mid)
 
@@ -304,20 +312,22 @@ async def get_gmail_messages_content_batch(
                 try:
                     if format == "metadata":
                         msg = await asyncio.to_thread(
-                            service.users().messages().get(
+                            service.users()
+                            .messages()
+                            .get(
                                 userId="me",
                                 id=mid,
                                 format="metadata",
-                                metadataHeaders=["Subject", "From"]
-                            ).execute
+                                metadataHeaders=["Subject", "From"],
+                            )
+                            .execute
                         )
                     else:
                         msg = await asyncio.to_thread(
-                            service.users().messages().get(
-                                userId="me",
-                                id=mid,
-                                format="full"
-                            ).execute
+                            service.users()
+                            .messages()
+                            .get(userId="me", id=mid, format="full")
+                            .execute
                         )
                     return mid, msg, None
                 except Exception as e:
@@ -325,8 +335,7 @@ async def get_gmail_messages_content_batch(
 
             # Fetch all messages in parallel
             fetch_results = await asyncio.gather(
-                *[fetch_message(mid) for mid in chunk_ids],
-                return_exceptions=False
+                *[fetch_message(mid) for mid in chunk_ids], return_exceptions=False
             )
 
             # Convert to results format
@@ -338,15 +347,11 @@ async def get_gmail_messages_content_batch(
             entry = results.get(mid, {"data": None, "error": "No result"})
 
             if entry["error"]:
-                output_messages.append(
-                    f"⚠️ Message {mid}: {entry['error']}\n"
-                )
+                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"
-                    )
+                    output_messages.append(f"⚠️ Message {mid}: No data returned\n")
                     continue
 
                 # Extract content based on format
@@ -386,8 +391,8 @@ async def get_gmail_messages_content_batch(
 
 
 @server.tool()
-@require_google_service("gmail", GMAIL_SEND_SCOPE)
 @handle_http_errors("send_gmail_message")
+@require_google_service("gmail", GMAIL_SEND_SCOPE)
 async def send_gmail_message(
     service,
     user_google_email: str,
@@ -423,8 +428,8 @@ async def send_gmail_message(
 
 
 @server.tool()
-@require_google_service("gmail", GMAIL_COMPOSE_SCOPE)
 @handle_http_errors("draft_gmail_message")
+@require_google_service("gmail", GMAIL_COMPOSE_SCOPE)
 async def draft_gmail_message(
     service,
     user_google_email: str,
@@ -469,35 +474,18 @@ async def draft_gmail_message(
     return f"Draft created! Draft ID: {draft_id}"
 
 
-@server.tool()
-@require_google_service("gmail", "gmail_read")
-@handle_http_errors("get_gmail_thread_content")
-async def get_gmail_thread_content(
-    service, thread_id: str, user_google_email: str
-) -> str:
+def _format_thread_content(thread_data: dict, thread_id: str) -> str:
     """
-    Retrieves the complete content of a Gmail conversation thread, including all messages.
+    Helper function to format thread content from Gmail API response.
 
     Args:
-        thread_id (str): The unique ID of the Gmail thread to retrieve.
-        user_google_email (str): The user's Google email address. Required.
+        thread_data (dict): Thread data from Gmail API
+        thread_id (str): Thread ID for display
 
     Returns:
-        str: The complete thread content with all messages formatted for reading.
+        str: Formatted thread content
     """
-    logger.info(
-        f"[get_gmail_thread_content] Invoked. Thread ID: '{thread_id}', Email: '{user_google_email}'"
-    )
-
-    # 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", [])
+    messages = thread_data.get("messages", [])
     if not messages:
         return f"No messages found in thread '{thread_id}'."
 
@@ -521,8 +509,7 @@ async def get_gmail_thread_content(
     for i, message in enumerate(messages, 1):
         # Extract headers
         headers = {
-            h["name"]: h["value"]
-            for h in message.get("payload", {}).get("headers", [])
+            h["name"]: h["value"] for h in message.get("payload", {}).get("headers", [])
         }
 
         sender = headers.get("From", "(unknown sender)")
@@ -554,13 +541,134 @@ async def get_gmail_thread_content(
             ]
         )
 
-    content_text = "\n".join(content_lines)
-    return content_text
+    return "\n".join(content_lines)
 
 
 @server.tool()
 @require_google_service("gmail", "gmail_read")
-@handle_http_errors("list_gmail_labels")
+@handle_http_errors("get_gmail_thread_content", is_read_only=True)
+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}'"
+    )
+
+    # 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
+    )
+
+    return _format_thread_content(thread_response, thread_id)
+
+
+@server.tool()
+@require_google_service("gmail", "gmail_read")
+@handle_http_errors("get_gmail_threads_content_batch", is_read_only=True)
+async def get_gmail_threads_content_batch(
+    service,
+    thread_ids: List[str],
+    user_google_email: str,
+) -> str:
+    """
+    Retrieves the content of multiple Gmail threads in a single batch request.
+    Supports up to 100 threads per request using Google's batch API.
+
+    Args:
+        thread_ids (List[str]): A list of Gmail thread IDs to retrieve. The function will automatically batch requests in chunks of 100.
+        user_google_email (str): The user's Google email address. Required.
+
+    Returns:
+        str: A formatted list of thread contents with separators.
+    """
+    logger.info(
+        f"[get_gmail_threads_content_batch] Invoked. Thread count: {len(thread_ids)}, Email: '{user_google_email}'"
+    )
+
+    if not thread_ids:
+        raise ValueError("No thread IDs provided")
+
+    output_threads = []
+
+    def _batch_callback(request_id, response, exception):
+        """Callback for batch requests"""
+        results[request_id] = {"data": response, "error": exception}
+
+    # Process in chunks of 100 (Gmail batch limit)
+    for chunk_start in range(0, len(thread_ids), 100):
+        chunk_ids = thread_ids[chunk_start : chunk_start + 100]
+        results: Dict[str, Dict] = {}
+
+        # Try to use batch API
+        try:
+            batch = service.new_batch_http_request(callback=_batch_callback)
+
+            for tid in chunk_ids:
+                req = service.users().threads().get(userId="me", id=tid, format="full")
+                batch.add(req, request_id=tid)
+
+            # 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_threads_content_batch] Batch API failed, falling back to asyncio.gather: {batch_error}"
+            )
+
+            async def fetch_thread(tid: str):
+                try:
+                    thread = await asyncio.to_thread(
+                        service.users()
+                        .threads()
+                        .get(userId="me", id=tid, format="full")
+                        .execute
+                    )
+                    return tid, thread, None
+                except Exception as e:
+                    return tid, None, e
+
+            # Fetch all threads in parallel
+            fetch_results = await asyncio.gather(
+                *[fetch_thread(tid) for tid in chunk_ids], return_exceptions=False
+            )
+
+            # Convert to results format
+            for tid, thread, error in fetch_results:
+                results[tid] = {"data": thread, "error": error}
+
+        # Process results for this chunk
+        for tid in chunk_ids:
+            entry = results.get(tid, {"data": None, "error": "No result"})
+
+            if entry["error"]:
+                output_threads.append(f"⚠️ Thread {tid}: {entry['error']}\n")
+            else:
+                thread = entry["data"]
+                if not thread:
+                    output_threads.append(f"⚠️ Thread {tid}: No data returned\n")
+                    continue
+
+                output_threads.append(_format_thread_content(thread, tid))
+
+    # Combine all threads with separators
+    header = f"Retrieved {len(thread_ids)} threads:"
+    return header + "\n\n" + "\n---\n\n".join(output_threads)
+
+
+@server.tool()
+@handle_http_errors("list_gmail_labels", is_read_only=True)
+@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.
@@ -607,8 +715,8 @@ async def list_gmail_labels(service, user_google_email: str) -> str:
 
 
 @server.tool()
-@require_google_service("gmail", GMAIL_LABELS_SCOPE)
 @handle_http_errors("manage_gmail_label")
+@require_google_service("gmail", GMAIL_LABELS_SCOPE)
 async def manage_gmail_label(
     service,
     user_google_email: str,
@@ -632,7 +740,9 @@ async def manage_gmail_label(
     Returns:
         str: Confirmation message of the label operation.
     """
-    logger.info(f"[manage_gmail_label] Invoked. Email: '{user_google_email}', Action: '{action}'")
+    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.")
@@ -664,7 +774,10 @@ async def manage_gmail_label(
         }
 
         updated_label = await asyncio.to_thread(
-            service.users().labels().update(userId="me", id=label_id, body=label_object).execute
+            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']}"
 
@@ -681,8 +794,8 @@ async def manage_gmail_label(
 
 
 @server.tool()
-@require_google_service("gmail", GMAIL_MODIFY_SCOPE)
 @handle_http_errors("modify_gmail_message_labels")
+@require_google_service("gmail", GMAIL_MODIFY_SCOPE)
 async def modify_gmail_message_labels(
     service,
     user_google_email: str,
@@ -702,10 +815,14 @@ async def modify_gmail_message_labels(
     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}'")
+    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.")
+        raise Exception(
+            "At least one of add_label_ids or remove_label_ids must be provided."
+        )
 
     body = {}
     if add_label_ids:

gsheets/sheets_tools.py

@@ -21,8 +21,8 @@ logger = logging.getLogger(__name__)
 
 
 @server.tool()
+@handle_http_errors("list_spreadsheets", is_read_only=True)
 @require_google_service("drive", "drive_read")
-@handle_http_errors("list_spreadsheets")
 async def list_spreadsheets(
     service,
     user_google_email: str,
@@ -70,8 +70,8 @@ async def list_spreadsheets(
 
 
 @server.tool()
+@handle_http_errors("get_spreadsheet_info", is_read_only=True)
 @require_google_service("sheets", "sheets_read")
-@handle_http_errors("get_spreadsheet_info")
 async def get_spreadsheet_info(
     service,
     user_google_email: str,
@@ -120,8 +120,8 @@ async def get_spreadsheet_info(
 
 
 @server.tool()
+@handle_http_errors("read_sheet_values", is_read_only=True)
 @require_google_service("sheets", "sheets_read")
-@handle_http_errors("read_sheet_values")
 async def read_sheet_values(
     service,
     user_google_email: str,
@@ -170,8 +170,8 @@ async def read_sheet_values(
 
 
 @server.tool()
-@require_google_service("sheets", "sheets_write")
 @handle_http_errors("modify_sheet_values")
+@require_google_service("sheets", "sheets_write")
 async def modify_sheet_values(
     service,
     user_google_email: str,
@@ -241,8 +241,8 @@ async def modify_sheet_values(
 
 
 @server.tool()
-@require_google_service("sheets", "sheets_write")
 @handle_http_errors("create_spreadsheet")
+@require_google_service("sheets", "sheets_write")
 async def create_spreadsheet(
     service,
     user_google_email: str,
@@ -290,8 +290,8 @@ async def create_spreadsheet(
 
 
 @server.tool()
-@require_google_service("sheets", "sheets_write")
 @handle_http_errors("create_sheet")
+@require_google_service("sheets", "sheets_write")
 async def create_sheet(
     service,
     user_google_email: str,
@@ -344,7 +344,7 @@ _comment_tools = create_comment_tools("spreadsheet", "spreadsheet_id")
 
 # Extract and register the functions
 read_sheet_comments = _comment_tools['read_comments']
-create_sheet_comment = _comment_tools['create_comment'] 
+create_sheet_comment = _comment_tools['create_comment']
 reply_to_sheet_comment = _comment_tools['reply_to_comment']
 resolve_sheet_comment = _comment_tools['resolve_comment']