google-workspace-mcp 1.0.0__py3-none-any.whl

google_workspace_mcp/tools/__init__.py

@@ -0,0 +1,7 @@
+"""
+Tool implementations for Google Workspace MCP.
+
+Exports the individual tool modules.
+"""
+
+__all__ = []

google_workspace_mcp/tools/calendar.py

@@ -0,0 +1,229 @@
+"""
+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.services.calendar import CalendarService
+
+logger = logging.getLogger(__name__)
+
+
+# --- Calendar Tool Functions --- #
+
+
+# @mcp.tool(
+#     name="list_calendars",
+#     description="Lists all calendars accessible by the user.",
+# )
+# async def list_calendars() -> dict[str, Any]:
+#     """
+#     Lists all calendars accessible by the user.
+
+#     Returns:
+#         A dictionary containing the list of calendars or an error message.
+#     """
+#     logger.info("Executing list_calendars tool")
+
+#     calendar_service = CalendarService()
+#     calendars = calendar_service.list_calendars()
+
+#     if isinstance(calendars, dict) and calendars.get("error"):
+#         raise ValueError(calendars.get("message", "Error listing calendars"))
+
+#     if not calendars:
+#         return {"message": "No calendars found."}
+
+#     # Return raw service result
+#     return {"count": len(calendars), "calendars": calendars}
+
+
+@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]:
+    """
+    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).
+
+    Returns:
+        A dictionary containing the list of events or an error message.
+    """
+    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")
+
+    calendar_service = CalendarService()
+    events = calendar_service.get_events(
+        calendar_id=calendar_id,
+        time_min=time_min,
+        time_max=time_max,
+        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"))
+
+    if not events:
+        return {"message": "No events found for the specified time range."}
+
+    # Return raw service result
+    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.",
+)
+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.
+
+    Args:
+        event_id: The ID of the event to retrieve.
+        calendar_id: The ID of the calendar containing the event. Defaults to 'primary'.
+
+    Returns:
+        A dictionary containing the event details (summary, start, end, description, attendees, etc.),
+        or an error message.
+    """
+    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
+
+    calendar_service = CalendarService()
+    event_details = 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"))
+
+    if not event_details:  # Should be caught by error dict check
+        raise ValueError(f"Failed to retrieve details for event '{event_id}'")
+
+    return event_details
+
+
+@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,
+    send_notifications: bool = True,
+    timezone: str | None = None,
+) -> dict[str, Any]:
+    """
+    Create a new calendar event.
+
+    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).
+
+    Returns:
+        A dictionary containing the created event details.
+    """
+    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")
+
+    calendar_service = CalendarService()
+    result = calendar_service.create_event(
+        summary=summary,
+        start_time=start_time,
+        end_time=end_time,
+        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)
+
+    return result
+
+
+@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]:
+    """
+    Delete a calendar event by its 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).
+
+    Returns:
+        A dictionary confirming the deletion.
+    """
+    logger.info(f"Executing delete_calendar_event on calendar '{calendar_id}', event '{event_id}'")
+    if not event_id:
+        raise ValueError("Event ID is required")
+
+    calendar_service = CalendarService()
+    success = calendar_service.delete_event(
+        event_id=event_id,
+        send_notifications=send_notifications,
+        calendar_id=calendar_id,
+    )
+
+    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,
+    }

google_workspace_mcp/tools/docs_tools.py

@@ -0,0 +1,277 @@
+"""
+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.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.",
+)
+async def docs_create_document(title: str) -> dict[str, Any]:
+    """
+    Creates a new, empty Google Document.
+
+    Args:
+        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.
+    """
+    logger.info(f"Executing docs_create_document tool with title: '{title}'")
+    if not title or not title.strip():
+        raise ValueError("Document title cannot be empty.")
+
+    docs_service = DocsService()
+    result = docs_service.create_document(title=title)
+
+    if isinstance(result, dict) and result.get("error"):
+        raise ValueError(result.get("message", "Error creating document"))
+
+    if not result or not result.get("document_id"):
+        raise ValueError(
+            f"Failed to create document '{title}' or did not receive a document ID."
+        )
+
+    return result
+
+
+@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) -> dict[str, Any]:
+    """
+    Retrieves metadata for a specific Google Document.
+
+    Args:
+        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.
+    """
+    logger.info(
+        f"Executing docs_get_document_metadata tool for document_id: '{document_id}'"
+    )
+    if not document_id or not document_id.strip():
+        raise ValueError("Document ID cannot be empty.")
+
+    docs_service = DocsService()
+    result = docs_service.get_document_metadata(document_id=document_id)
+
+    if isinstance(result, dict) and result.get("error"):
+        raise ValueError(result.get("message", "Error retrieving document metadata"))
+
+    if not result or not result.get("document_id"):
+        raise ValueError(f"Failed to retrieve metadata for document '{document_id}'.")
+
+    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.",
+)
+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.
+
+    Args:
+        document_id: The ID of the Google Document.
+
+    Returns:
+        A dictionary containing the 'document_id' and 'markdown_content',
+        or an error message.
+    """
+    logger.info(
+        f"Executing docs_get_content_as_markdown tool for document_id: '{document_id}'"
+    )
+    if not document_id or not document_id.strip():
+        raise ValueError("Document ID cannot be empty.")
+
+    docs_service = DocsService()
+    result = docs_service.get_document_content_as_markdown(document_id=document_id)
+
+    if isinstance(result, dict) and result.get("error"):
+        raise ValueError(
+            result.get("message", "Error retrieving document content as Markdown")
+        )
+
+    if not result or "markdown_content" not in result:
+        raise ValueError(
+            f"Failed to retrieve Markdown content for document '{document_id}'."
+        )
+
+    return result
+
+
+@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]:
+    """
+    Appends the given text to the end of the specified Google Document.
+
+    Args:
+        document_id: The ID of the Google Document.
+        text: The text to append.
+        ensure_newline: If True, prepends a newline to the text before appending,
+                        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.
+    """
+    logger.info(f"Executing docs_append_text tool for document_id: '{document_id}'")
+    if not document_id or not document_id.strip():
+        raise ValueError("Document ID cannot be empty.")
+    # Text can be empty, that's fine.
+
+    docs_service = DocsService()
+    result = docs_service.append_text(
+        document_id=document_id, text=text, ensure_newline=ensure_newline
+    )
+
+    if isinstance(result, dict) and result.get("error"):
+        raise ValueError(result.get("message", "Error appending text to document"))
+
+    if not result or not result.get("success"):
+        raise ValueError(f"Failed to append text to document '{document_id}'.")
+
+    return result
+
+
+@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]:
+    """
+    Prepends the given text to the beginning of the specified Google Document.
+
+    Args:
+        document_id: The ID of the Google Document.
+        text: The text to prepend.
+        ensure_newline: If True, appends a newline to the text after prepending,
+                        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.
+    """
+    logger.info(f"Executing docs_prepend_text tool for document_id: '{document_id}'")
+    if not document_id or not document_id.strip():
+        raise ValueError("Document ID cannot be empty.")
+    # Text can be empty, that's fine.
+
+    docs_service = DocsService()
+    result = docs_service.prepend_text(
+        document_id=document_id, text=text, ensure_newline=ensure_newline
+    )
+
+    if isinstance(result, dict) and result.get("error"):
+        raise ValueError(result.get("message", "Error prepending text to document"))
+
+    if not result or not result.get("success"):
+        raise ValueError(f"Failed to prepend text to document '{document_id}'.")
+
+    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'.",
+)
+async def docs_insert_text(
+    document_id: str, text: str, index: int | None = None, segment_id: str | None = None
+) -> dict[str, Any]:
+    """
+    Inserts the given text at a specific location within the specified Google Document.
+
+    Args:
+        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).
+        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.
+    """
+    logger.info(
+        f"Executing docs_insert_text tool for document_id: '{document_id}' at index: {index}"
+    )
+    if not document_id or not document_id.strip():
+        raise ValueError("Document ID cannot be empty.")
+    # Text can be empty, that's a valid insertion (though perhaps not useful).
+
+    docs_service = DocsService()
+    result = docs_service.insert_text(
+        document_id=document_id, text=text, index=index, segment_id=segment_id
+    )
+
+    if isinstance(result, dict) and result.get("error"):
+        raise ValueError(result.get("message", "Error inserting text into document"))
+
+    if not result or not result.get("success"):
+        raise ValueError(f"Failed to insert text into document '{document_id}'.")
+
+    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.",
+)
+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.
+    This is an advanced tool; requests must conform to the Google Docs API format.
+    See: https://developers.google.com/docs/api/reference/rest/v1/documents/request
+
+    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"}}
+
+    Returns:
+        A dictionary containing the API response from the batchUpdate call (includes replies for each request),
+        or an error message.
+    """
+    logger.info(
+        f"Executing docs_batch_update tool for document_id: '{document_id}' with {len(requests)} requests."
+    )
+    if not document_id or not document_id.strip():
+        raise ValueError("Document ID cannot be empty.")
+    if not isinstance(requests, list):
+        raise ValueError("Requests must be a list.")
+    # Further validation of individual request structures is complex here and usually
+    # left to the API, but basic check for list is good.
+
+    docs_service = DocsService()
+    result = docs_service.batch_update(document_id=document_id, requests=requests)
+
+    if isinstance(result, dict) and result.get("error"):
+        raise ValueError(
+            result.get("message", "Error executing batch update on document")
+        )
+
+    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