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

google_workspace_mcp/tools/calendar.py

@@ -3,9 +3,14 @@ Google Calendar tool handlers for Google Workspace MCP.
 """
 
 import logging
-from typing import Any
 
 from google_workspace_mcp.app import mcp  # Import from central app module
+from google_workspace_mcp.models import (
+    CalendarEventCreationOutput,
+    CalendarEventDeletionOutput,
+    CalendarEventDetailsOutput,
+    CalendarEventsOutput,
+)
 from google_workspace_mcp.services.calendar import CalendarService
 
 logger = logging.getLogger(__name__)
@@ -16,6 +21,7 @@ logger = logging.getLogger(__name__)
 
 # @mcp.tool(
 #     name="list_calendars",
+#     description="Lists all calendars accessible by the user.",
 # )
 # async def list_calendars() -> dict[str, Any]:
 #     """
@@ -39,186 +45,196 @@ logger = logging.getLogger(__name__)
 #     return {"count": len(calendars), "calendars": calendars}
 
 
-# @mcp.tool(
-#     name="calendar_get_events",
-# )
+@mcp.tool(
+    name="calendar_get_events",
+    description="Retrieve calendar events within a specified time range.",
+)
 async def calendar_get_events(
     time_min: str,
     time_max: str,
     calendar_id: str = "primary",
     max_results: int = 250,
     show_deleted: bool = False,
-) -> dict[str, Any]:
+) -> CalendarEventsOutput:
     """
     Retrieve calendar events within a specified time range.
 
     Args:
-        time_min: Start time in RFC3339 format (e.g., "2024-01-01T00:00:00Z").
-        time_max: End time in RFC3339 format (e.g., "2024-01-01T23:59:59Z").
-        calendar_id: ID of the calendar (defaults to 'primary').
-        max_results: Maximum number of events to return (default: 250).
-        show_deleted: Whether to include deleted events (default: False).
+        time_min: Start of time range (ISO datetime string)
+        time_max: End of time range (ISO datetime string)
+        calendar_id: Calendar identifier (default: 'primary')
+        max_results: Maximum number of events to return
+        show_deleted: Whether to include deleted events
 
     Returns:
-        A dictionary containing the list of events or an error message.
+        CalendarEventsOutput: Structured output containing the events data
     """
-    logger.info(f"Executing calendar_get_events tool on calendar '{calendar_id}' between {time_min} and {time_max}")
-
-    if not calendar_id:
-        raise ValueError("calendar_id parameter is required")
-    if not time_min:
-        raise ValueError("time_min parameter is required")
-    if not time_max:
-        raise ValueError("time_max parameter is required")
+    logger.info(f"Executing calendar_get_events tool for calendar {calendar_id}")
 
     calendar_service = CalendarService()
-    events = calendar_service.get_events(
-        calendar_id=calendar_id,
+    result = calendar_service.get_events(
         time_min=time_min,
         time_max=time_max,
+        calendar_id=calendar_id,
         max_results=max_results,
         show_deleted=show_deleted,
     )
 
-    if isinstance(events, dict) and events.get("error"):
-        raise ValueError(events.get("message", "Error getting calendar events"))
+    # Check for errors in the service result
+    if isinstance(result, dict) and result.get("error"):
+        raise ValueError(result.get("message", "Error retrieving calendar events"))
 
+    # Extract events list - the service returns a dict with 'items' key containing events
+    events = result.get("items", []) if isinstance(result, dict) else result
     if not events:
-        return {"message": "No events found for the specified time range."}
+        events = []
 
-    # Return raw service result
-    return {"count": len(events), "events": events}
+    # Return the Pydantic model instance
+    return CalendarEventsOutput(count=len(events), events=events)
 
 
-# @mcp.tool(
-#     name="calendar_get_event_details",
-# )
-async def calendar_get_event_details(event_id: str, calendar_id: str = "primary") -> dict[str, Any]:
+@mcp.tool(
+    name="calendar_get_event_details",
+    description="Retrieves detailed information for a specific calendar event by its ID.",
+)
+async def calendar_get_event_details(
+    event_id: str, calendar_id: str = "primary"
+) -> CalendarEventDetailsOutput:
     """
-    Retrieves details for a specific event in a Google Calendar.
+    Retrieves detailed information for a specific calendar event by its ID.
 
     Args:
-        event_id: The ID of the event to retrieve.
-        calendar_id: The ID of the calendar containing the event. Defaults to 'primary'.
+        event_id: The unique identifier of the event
+        calendar_id: Calendar identifier (default: 'primary')
 
     Returns:
-        A dictionary containing the event details (summary, start, end, description, attendees, etc.),
-        or an error message.
+        CalendarEventDetailsOutput: Structured output containing the event details
     """
-    logger.info(f"Executing calendar_get_event_details tool for event_id: '{event_id}', calendar_id: '{calendar_id}'")
-    if not event_id or not event_id.strip():
-        raise ValueError("Event ID cannot be empty.")
-    if not calendar_id or not calendar_id.strip():
-        raise ValueError("Calendar ID cannot be empty.")  # Ensure calendar_id is also validated
+    logger.info(f"Executing calendar_get_event_details tool for event {event_id}")
 
     calendar_service = CalendarService()
-    event_details = calendar_service.get_event_details(event_id=event_id, calendar_id=calendar_id)
+    result = calendar_service.get_event_details(
+        event_id=event_id, calendar_id=calendar_id
+    )
 
-    if isinstance(event_details, dict) and event_details.get("error"):
-        raise ValueError(event_details.get("message", "Error retrieving event details"))
+    # Check for errors in the service result
+    if isinstance(result, dict) and result.get("error"):
+        raise ValueError(result.get("message", "Error retrieving event details"))
 
-    if not event_details:  # Should be caught by error dict check
+    if not result:  # Should be caught by error dict check
         raise ValueError(f"Failed to retrieve details for event '{event_id}'")
 
-    return event_details
+    # Return the Pydantic model instance
+    return CalendarEventDetailsOutput(
+        id=result["id"],
+        summary=result.get("summary", ""),
+        start=result.get("start", {}),
+        end=result.get("end", {}),
+        description=result.get("description"),
+        attendees=result.get("attendees"),
+        location=result.get("location"),
+    )
 
 
-# @mcp.tool(
-#     name="create_calendar_event",
-# )
+@mcp.tool(
+    name="create_calendar_event",
+    description="Creates a new event in a specified Google Calendar.",
+)
 async def create_calendar_event(
     summary: str,
     start_time: str,
     end_time: str,
     calendar_id: str = "primary",
-    location: str | None = None,
-    description: str | None = None,
-    attendees: list[str] | None = None,
+    location: str = None,
+    description: str = None,
+    attendees: list[str] = None,
     send_notifications: bool = True,
-    timezone: str | None = None,
-) -> dict[str, Any]:
+    timezone: str = None,
+) -> CalendarEventCreationOutput:
     """
-    Create a new calendar event.
+    Creates a new event in a specified Google Calendar.
 
     Args:
-        summary: Title of the event.
-        start_time: Start time in RFC3339 format (e.g. 2024-12-01T10:00:00Z).
-        end_time: End time in RFC3339 format (e.g. 2024-12-01T11:00:00Z).
-        calendar_id: Calendar ID (defaults to "primary").
-        location: Location of the event (optional).
-        description: Description or notes (optional).
-        attendees: List of attendee email addresses (optional).
-        send_notifications: Whether to send notifications to attendees (default True).
-        timezone: Timezone for the event (e.g., 'America/New_York', defaults to UTC).
+        summary: Event title/summary
+        start_time: Event start time (ISO datetime string)
+        end_time: Event end time (ISO datetime string)
+        calendar_id: Calendar identifier (default: 'primary')
+        location: Event location (optional)
+        description: Event description (optional)
+        attendees: List of attendee email addresses (optional)
+        send_notifications: Whether to send notifications (default: True)
+        timezone: Timezone for the event (optional)
 
     Returns:
-        A dictionary containing the created event details.
+        CalendarEventCreationOutput: Structured output containing the created event data
     """
-    logger.info(f"Executing create_calendar_event on calendar '{calendar_id}'")
-    if not summary or not start_time or not end_time:
-        raise ValueError("Summary, start_time, and end_time are required")
+    logger.info(f"Executing create_calendar_event tool for summary: {summary}")
 
     calendar_service = CalendarService()
     result = calendar_service.create_event(
         summary=summary,
         start_time=start_time,
         end_time=end_time,
+        calendar_id=calendar_id,
         location=location,
         description=description,
         attendees=attendees,
         send_notifications=send_notifications,
         timezone=timezone,
-        calendar_id=calendar_id,
     )
 
-    if not result or (isinstance(result, dict) and result.get("error")):
-        error_msg = "Error creating calendar event"
-        if isinstance(result, dict):
-            error_msg = result.get("message", error_msg)
-        raise ValueError(error_msg)
+    # Check for errors in the service result
+    if isinstance(result, dict) and result.get("error"):
+        raise ValueError(result.get("message", "Error creating calendar event"))
 
-    return result
+    if not result:
+        raise ValueError("Error creating calendar event")
 
+    # Return the Pydantic model instance
+    return CalendarEventCreationOutput(
+        id=result["id"],
+        html_link=result.get("htmlLink", ""),
+        summary=result.get("summary", summary),
+        start=result.get("start", {}),
+        end=result.get("end", {}),
+    )
 
-# @mcp.tool(
-#     name="delete_calendar_event",
-# )
+
+@mcp.tool(
+    name="delete_calendar_event",
+    description="Deletes an event from Google Calendar by its event ID.",
+)
 async def delete_calendar_event(
     event_id: str,
     calendar_id: str = "primary",
     send_notifications: bool = True,
-) -> dict[str, Any]:
+) -> CalendarEventDeletionOutput:
     """
-    Delete a calendar event by its ID.
+    Deletes an event from Google Calendar by its event ID.
 
     Args:
-        event_id: The ID of the event to delete.
-        calendar_id: Calendar ID containing the event (defaults to "primary").
-        send_notifications: Whether to send cancellation notifications (default True).
+        event_id: The unique identifier of the event to delete
+        calendar_id: Calendar identifier (default: 'primary')
+        send_notifications: Whether to send notifications (default: True)
 
     Returns:
-        A dictionary confirming the deletion.
+        CalendarEventDeletionOutput: Structured output containing the deletion result
     """
-    logger.info(f"Executing delete_calendar_event on calendar '{calendar_id}', event '{event_id}'")
-    if not event_id:
-        raise ValueError("Event ID is required")
+    logger.info(f"Executing delete_calendar_event tool for event {event_id}")
 
     calendar_service = CalendarService()
-    success = calendar_service.delete_event(
+    result = calendar_service.delete_event(
         event_id=event_id,
-        send_notifications=send_notifications,
         calendar_id=calendar_id,
+        send_notifications=send_notifications,
     )
 
-    if not success:
-        # Attempt to check if the service returned an error dict
-        error_info = getattr(calendar_service, "last_error", None)  # Hypothetical
-        error_msg = "Failed to delete calendar event"
-        if isinstance(error_info, dict) and error_info.get("error"):
-            error_msg = error_info.get("message", error_msg)
-        raise ValueError(error_msg)
-
-    return {
-        "message": f"Event with ID '{event_id}' deleted successfully from calendar '{calendar_id}'.",
-        "success": True,
-    }
+    # Check for errors in the service result
+    if isinstance(result, dict) and result.get("error"):
+        raise ValueError(result.get("message", "Error deleting calendar event"))
+
+    # Return the Pydantic model instance
+    return CalendarEventDeletionOutput(
+        message=f"Event with ID '{event_id}' deleted successfully from calendar '{calendar_id}'.",
+        success=True,
+    )

google_workspace_mcp/tools/docs_tools.py

@@ -3,18 +3,26 @@ Google Docs tool handlers for Google Workspace MCP.
 """
 
 import logging
-from typing import Any
 
 from google_workspace_mcp.app import mcp
+from google_workspace_mcp.models import (
+    DocumentBatchUpdateOutput,
+    DocumentContentOutput,
+    DocumentCreationOutput,
+    DocumentImageInsertOutput,
+    DocumentMetadataOutput,
+    DocumentUpdateOutput,
+)
 from google_workspace_mcp.services.docs_service import DocsService
 
 logger = logging.getLogger(__name__)
 
 
-# @mcp.tool(
-#     name="docs_create_document",
-# )
-async def docs_create_document(title: str) -> dict[str, Any]:
+@mcp.tool(
+    name="docs_create_document",
+    description="Creates a new Google Document with a specified title.",
+)
+async def docs_create_document(title: str) -> DocumentCreationOutput:
     """
     Creates a new, empty Google Document.
 
@@ -22,8 +30,7 @@ async def docs_create_document(title: str) -> dict[str, Any]:
         title: The title for the new Google Document.
 
     Returns:
-        A dictionary containing the 'document_id', 'title', and 'document_link' of the created document,
-        or an error message.
+        DocumentCreationOutput containing document_id, title, and document_link.
     """
     logger.info(f"Executing docs_create_document tool with title: '{title}'")
     if not title or not title.strip():
@@ -40,13 +47,18 @@ async def docs_create_document(title: str) -> dict[str, Any]:
             f"Failed to create document '{title}' or did not receive a document ID."
         )
 
-    return result
+    return DocumentCreationOutput(
+        document_id=result["document_id"],
+        title=result["title"],
+        document_link=result["document_link"],
+    )
 
 
-# @mcp.tool(
-#     name="docs_get_document_metadata",
-# )
-async def docs_get_document_metadata(document_id: str) -> dict[str, Any]:
+@mcp.tool(
+    name="docs_get_document_metadata",
+    description="Retrieves metadata (like title and ID) for a Google Document.",
+)
+async def docs_get_document_metadata(document_id: str) -> DocumentMetadataOutput:
     """
     Retrieves metadata for a specific Google Document.
 
@@ -54,8 +66,7 @@ async def docs_get_document_metadata(document_id: str) -> dict[str, Any]:
         document_id: The ID of the Google Document.
 
     Returns:
-        A dictionary containing the document's 'document_id', 'title', and 'document_link',
-        or an error message.
+        DocumentMetadataOutput containing document_id, title, and document_link.
     """
     logger.info(
         f"Executing docs_get_document_metadata tool for document_id: '{document_id}'"
@@ -72,13 +83,18 @@ async def docs_get_document_metadata(document_id: str) -> dict[str, Any]:
     if not result or not result.get("document_id"):
         raise ValueError(f"Failed to retrieve metadata for document '{document_id}'.")
 
-    return result
+    return DocumentMetadataOutput(
+        document_id=result["document_id"],
+        title=result["title"],
+        document_link=result["document_link"],
+    )
 
 
-# @mcp.tool(
-#     name="docs_get_content_as_markdown",
-# )
-async def docs_get_content_as_markdown(document_id: str) -> dict[str, Any]:
+@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.",
+)
+async def docs_get_content_as_markdown(document_id: str) -> DocumentContentOutput:
     """
     Retrieves the main textual content of a Google Document, converted to Markdown.
 
@@ -86,8 +102,7 @@ async def docs_get_content_as_markdown(document_id: str) -> dict[str, Any]:
         document_id: The ID of the Google Document.
 
     Returns:
-        A dictionary containing the 'document_id' and 'markdown_content',
-        or an error message.
+        DocumentContentOutput containing document_id and markdown_content.
     """
     logger.info(
         f"Executing docs_get_content_as_markdown tool for document_id: '{document_id}'"
@@ -108,15 +123,18 @@ async def docs_get_content_as_markdown(document_id: str) -> dict[str, Any]:
             f"Failed to retrieve Markdown content for document '{document_id}'."
         )
 
-    return result
+    return DocumentContentOutput(
+        document_id=result["document_id"], markdown_content=result["markdown_content"]
+    )
 
 
-# @mcp.tool(
-#     name="docs_append_text",
-# )
+@mcp.tool(
+    name="docs_append_text",
+    description="Appends text to the end of a specified Google Document.",
+)
 async def docs_append_text(
     document_id: str, text: str, ensure_newline: bool = True
-) -> dict[str, Any]:
+) -> DocumentUpdateOutput:
     """
     Appends the given text to the end of the specified Google Document.
 
@@ -127,7 +145,7 @@ async def docs_append_text(
                         if the document is not empty, to ensure the new text starts on a new line. (Default: True)
 
     Returns:
-        A dictionary indicating success or an error message.
+        DocumentUpdateOutput indicating success or failure.
     """
     logger.info(f"Executing docs_append_text tool for document_id: '{document_id}'")
     if not document_id or not document_id.strip():
@@ -145,15 +163,20 @@ async def docs_append_text(
     if not result or not result.get("success"):
         raise ValueError(f"Failed to append text to document '{document_id}'.")
 
-    return result
+    return DocumentUpdateOutput(
+        success=result["success"],
+        message=result.get("message", "Text appended successfully"),
+        updated_range=result.get("updated_range"),
+    )
 
 
-# @mcp.tool(
-#     name="docs_prepend_text",
-# )
+@mcp.tool(
+    name="docs_prepend_text",
+    description="Prepends text to the beginning of a specified Google Document.",
+)
 async def docs_prepend_text(
     document_id: str, text: str, ensure_newline: bool = True
-) -> dict[str, Any]:
+) -> DocumentUpdateOutput:
     """
     Prepends the given text to the beginning of the specified Google Document.
 
@@ -164,7 +187,7 @@ async def docs_prepend_text(
                         if the document was not empty, to ensure existing content starts on a new line. (Default: True)
 
     Returns:
-        A dictionary indicating success or an error message.
+        DocumentUpdateOutput indicating success or failure.
     """
     logger.info(f"Executing docs_prepend_text tool for document_id: '{document_id}'")
     if not document_id or not document_id.strip():
@@ -182,15 +205,20 @@ async def docs_prepend_text(
     if not result or not result.get("success"):
         raise ValueError(f"Failed to prepend text to document '{document_id}'.")
 
-    return result
+    return DocumentUpdateOutput(
+        success=result["success"],
+        message=result.get("message", "Text prepended successfully"),
+        updated_range=result.get("updated_range"),
+    )
 
 
-# @mcp.tool(
-#     name="docs_insert_text",
-# )
+@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'.",
+)
 async def docs_insert_text(
     document_id: str, text: str, index: int | None = None, segment_id: str | None = None
-) -> dict[str, Any]:
+) -> DocumentUpdateOutput:
     """
     Inserts the given text at a specific location within the specified Google Document.
 
@@ -198,14 +226,14 @@ async def docs_insert_text(
         document_id: The ID of the Google Document.
         text: The text to insert.
         index: Optional. The 0-based index where the text should be inserted within the segment.
-               For the main body, an index of 1 typically refers to the beginning of the content.
-               Consult Google Docs API documentation for details on indexing if precise placement is needed.
-               If omitted, defaults to a sensible starting position (e.g., beginning of the body).
+        For the main body, an index of 1 typically refers to the beginning of the content.
+        Consult Google Docs API documentation for details on indexing if precise placement is needed.
+        If omitted, defaults to a sensible starting position (e.g., beginning of the body).
         segment_id: Optional. The ID of a specific document segment (e.g., header, footer).
                     If omitted, the text is inserted into the main document body.
 
     Returns:
-        A dictionary indicating success or an error message.
+        DocumentUpdateOutput indicating success or failure.
     """
     logger.info(
         f"Executing docs_insert_text tool for document_id: '{document_id}' at index: {index}"
@@ -225,13 +253,20 @@ async def docs_insert_text(
     if not result or not result.get("success"):
         raise ValueError(f"Failed to insert text into document '{document_id}'.")
 
-    return result
+    return DocumentUpdateOutput(
+        success=result["success"],
+        message=result.get("message", "Text inserted successfully"),
+        updated_range=result.get("updated_range"),
+    )
 
 
-# @mcp.tool(
-#     name="docs_batch_update",
-# )
-async def docs_batch_update(document_id: str, requests: list[dict]) -> dict[str, Any]:
+@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.",
+)
+async def docs_batch_update(
+    document_id: str, requests: list[dict]
+) -> DocumentBatchUpdateOutput:
     """
     Applies a list of Google Docs API update requests to the specified document.
     This is an advanced tool; requests must conform to the Google Docs API format.
@@ -240,11 +275,10 @@ async def docs_batch_update(document_id: str, requests: list[dict]) -> dict[str,
     Args:
         document_id: The ID of the Google Document.
         requests: A list of request objects (as dictionaries) to apply.
-                  Example request: {"insertText": {"location": {"index": 1}, "text": "Hello"}}
+        Example request: {"insertText": {"location": {"index": 1}, "text": "Hello"}}
 
     Returns:
-        A dictionary containing the API response from the batchUpdate call (includes replies for each request),
-        or an error message.
+        DocumentBatchUpdateOutput containing the API response from the batchUpdate call.
     """
     logger.info(
         f"Executing docs_batch_update tool for document_id: '{document_id}' with {len(requests)} requests."
@@ -267,19 +301,23 @@ async def docs_batch_update(document_id: str, requests: list[dict]) -> dict[str,
     if not result:  # Should be caught by error dict check
         raise ValueError(f"Failed to execute batch update on document '{document_id}'.")
 
-    return result  # Return the full response which includes documentId and replies
+    return DocumentBatchUpdateOutput(
+        document_id=result.get("documentId", document_id),
+        replies=result.get("replies", []),
+    )
 
 
-# @mcp.tool(
-#     name="docs_insert_image",
-# )
+@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.",
+)
 async def docs_insert_image(
     document_id: str,
     image_url: str,
     index: int,
     width: float | None = None,
     height: float | None = None,
-) -> dict[str, Any]:
+) -> DocumentImageInsertOutput:
     """
     Inserts an image into a Google Document from a URL at a specific index.
 
@@ -291,7 +329,7 @@ async def docs_insert_image(
         height: Optional height of the image in points (PT).
 
     Returns:
-        A dictionary containing the inserted image ID and success status, or an error message.
+        DocumentImageInsertOutput containing the inserted image details.
     """
     logger.info(
         f"Executing docs_insert_image tool for document_id: '{document_id}' at index: {index}"
@@ -327,4 +365,8 @@ async def docs_insert_image(
     if not result or not result.get("success"):
         raise ValueError(f"Failed to insert image into document '{document_id}'.")
 
-    return result
+    return DocumentImageInsertOutput(
+        success=result["success"],
+        image_id=result.get("image_id"),
+        message=result.get("message", "Image inserted successfully"),
+    )