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

google_workspace_mcp/tools/sheets_tools.py

@@ -6,15 +6,25 @@ import logging
 from typing import Any
 
 from google_workspace_mcp.app import mcp
+from google_workspace_mcp.models import (
+    SheetsAddSheetOutput,
+    SheetsAppendOutput,
+    SheetsClearOutput,
+    SheetsCreationOutput,
+    SheetsDeleteSheetOutput,
+    SheetsReadOutput,
+    SheetsWriteOutput,
+)
 from google_workspace_mcp.services.sheets_service import SheetsService
 
 logger = logging.getLogger(__name__)
 
 
-# @mcp.tool(
-#     name="sheets_create_spreadsheet",
-# )
-async def sheets_create_spreadsheet(title: str) -> dict[str, Any]:
+@mcp.tool(
+    name="sheets_create_spreadsheet",
+    description="Creates a new Google Spreadsheet with a specified title.",
+)
+async def sheets_create_spreadsheet(title: str) -> SheetsCreationOutput:
     """
     Creates a new, empty Google Spreadsheet.
 
@@ -22,8 +32,7 @@ async def sheets_create_spreadsheet(title: str) -> dict[str, Any]:
         title: The title for the new Google Spreadsheet.
 
     Returns:
-        A dictionary containing the 'spreadsheet_id', 'title', and 'spreadsheet_url'
-        of the created spreadsheet, or an error message.
+        SheetsCreationOutput containing the spreadsheet_id, title, and spreadsheet_url.
     """
     logger.info(f"Executing sheets_create_spreadsheet tool with title: '{title}'")
     if not title or not title.strip():
@@ -36,15 +45,22 @@ async def sheets_create_spreadsheet(title: str) -> dict[str, Any]:
         raise ValueError(result.get("message", "Error creating spreadsheet"))
 
     if not result or not result.get("spreadsheet_id"):
-        raise ValueError(f"Failed to create spreadsheet '{title}' or did not receive a spreadsheet ID.")
-
-    return result
+        raise ValueError(
+            f"Failed to create spreadsheet '{title}' or did not receive a spreadsheet ID."
+        )
+
+    return SheetsCreationOutput(
+        spreadsheet_id=result["spreadsheet_id"],
+        title=result["title"],
+        spreadsheet_url=result["spreadsheet_url"],
+    )
 
 
 @mcp.tool(
     name="sheets_read_range",
+    description="Reads data from a specified range in a Google Spreadsheet (e.g., 'Sheet1!A1:B5').",
 )
-async def sheets_read_range(spreadsheet_id: str, range_a1: str) -> dict[str, Any]:
+async def sheets_read_range(spreadsheet_id: str, range_a1: str) -> SheetsReadOutput:
     """
     Reads data from a given A1 notation range in a Google Spreadsheet.
 
@@ -54,10 +70,11 @@ async def sheets_read_range(spreadsheet_id: str, range_a1: str) -> dict[str, Any
                   to the first visible sheet or if sheet name is part of it).
 
     Returns:
-        A dictionary containing the range and a list of lists representing the cell values,
-        or an error message.
+        SheetsReadOutput containing the range and cell values.
     """
-    logger.info(f"Executing sheets_read_range tool for spreadsheet_id: '{spreadsheet_id}', range: '{range_a1}'")
+    logger.info(
+        f"Executing sheets_read_range tool for spreadsheet_id: '{spreadsheet_id}', range: '{range_a1}'"
+    )
     if not spreadsheet_id or not spreadsheet_id.strip():
         raise ValueError("Spreadsheet ID cannot be empty.")
     if not range_a1 or not range_a1.strip():
@@ -69,21 +86,30 @@ async def sheets_read_range(spreadsheet_id: str, range_a1: str) -> dict[str, Any
     if isinstance(result, dict) and result.get("error"):
         raise ValueError(result.get("message", "Error reading range from spreadsheet"))
 
-    if not result or "values" not in result:  # Check for 'values' as it's key for successful read
-        raise ValueError(f"Failed to read range '{range_a1}' from spreadsheet '{spreadsheet_id}'.")
-
-    return result
+    if (
+        not result or "values" not in result
+    ):  # Check for 'values' as it's key for successful read
+        raise ValueError(
+            f"Failed to read range '{range_a1}' from spreadsheet '{spreadsheet_id}'."
+        )
+
+    return SheetsReadOutput(
+        range=result.get("range", range_a1),
+        values=result.get("values", []),
+        major_dimension=result.get("major_dimension", "ROWS"),
+    )
 
 
-# @mcp.tool(
-#     name="sheets_write_range",
-# )
+@mcp.tool(
+    name="sheets_write_range",
+    description="Writes data to a specified range in a Google Spreadsheet (e.g., 'Sheet1!A1:B5').",
+)
 async def sheets_write_range(
     spreadsheet_id: str,
     range_a1: str,
     values: list[list[Any]],
     value_input_option: str = "USER_ENTERED",
-) -> dict[str, Any]:
+) -> SheetsWriteOutput:
     """
     Writes data (list of lists) to a given A1 notation range in a Google Spreadsheet.
 
@@ -96,10 +122,11 @@ async def sheets_write_range(
                             "USER_ENTERED": Values parsed as if typed by user (e.g., formulas).
                             "RAW": Values taken literally. (Default: "USER_ENTERED")
     Returns:
-        A dictionary detailing the update (updated range, number of cells, etc.),
-        or an error message.
+        SheetsWriteOutput detailing the update.
     """
-    logger.info(f"Executing sheets_write_range tool for spreadsheet_id: '{spreadsheet_id}', range: '{range_a1}'")
+    logger.info(
+        f"Executing sheets_write_range tool for spreadsheet_id: '{spreadsheet_id}', range: '{range_a1}'"
+    )
     if not spreadsheet_id or not spreadsheet_id.strip():
         raise ValueError("Spreadsheet ID cannot be empty.")
     if not range_a1 or not range_a1.strip():
@@ -121,21 +148,29 @@ async def sheets_write_range(
         raise ValueError(result.get("message", "Error writing to range in spreadsheet"))
 
     if not result or not result.get("updated_range"):
-        raise ValueError(f"Failed to write to range '{range_a1}' in spreadsheet '{spreadsheet_id}'.")
-
-    return result
+        raise ValueError(
+            f"Failed to write to range '{range_a1}' in spreadsheet '{spreadsheet_id}'."
+        )
+
+    return SheetsWriteOutput(
+        updated_range=result["updated_range"],
+        updated_rows=result.get("updated_rows", 0),
+        updated_columns=result.get("updated_columns", 0),
+        updated_cells=result.get("updated_cells", 0),
+    )
 
 
-# @mcp.tool(
-#     name="sheets_append_rows",
-# )
+@mcp.tool(
+    name="sheets_append_rows",
+    description="Appends rows of data to a sheet or table in a Google Spreadsheet (e.g., to 'Sheet1').",
+)
 async def sheets_append_rows(
     spreadsheet_id: str,
     range_a1: str,
     values: list[list[Any]],
     value_input_option: str = "USER_ENTERED",
     insert_data_option: str = "INSERT_ROWS",
-) -> dict[str, Any]:
+) -> SheetsAppendOutput:
     """
     Appends rows of data to a sheet or table in a Google Spreadsheet.
 
@@ -148,10 +183,11 @@ async def sheets_append_rows(
         insert_data_option: How new data should be inserted ("INSERT_ROWS" or "OVERWRITE"). Default: "INSERT_ROWS".
 
     Returns:
-        A dictionary detailing the append operation (e.g., range of appended data),
-        or an error message.
+        SheetsAppendOutput detailing the append operation.
     """
-    logger.info(f"Executing sheets_append_rows tool for spreadsheet_id: '{spreadsheet_id}', range: '{range_a1}'")
+    logger.info(
+        f"Executing sheets_append_rows tool for spreadsheet_id: '{spreadsheet_id}', range: '{range_a1}'"
+    )
     if not spreadsheet_id or not spreadsheet_id.strip():
         raise ValueError("Spreadsheet ID cannot be empty.")
     if not range_a1 or not range_a1.strip():
@@ -163,7 +199,9 @@ async def sheets_append_rows(
     if value_input_option not in ["USER_ENTERED", "RAW"]:
         raise ValueError("value_input_option must be either 'USER_ENTERED' or 'RAW'.")
     if insert_data_option not in ["INSERT_ROWS", "OVERWRITE"]:
-        raise ValueError("insert_data_option must be either 'INSERT_ROWS' or 'OVERWRITE'.")
+        raise ValueError(
+            "insert_data_option must be either 'INSERT_ROWS' or 'OVERWRITE'."
+        )
 
     sheets_service = SheetsService()
     result = sheets_service.append_rows(
@@ -178,15 +216,22 @@ async def sheets_append_rows(
         raise ValueError(result.get("message", "Error appending rows to spreadsheet"))
 
     if not result:  # Check for empty or None result as well
-        raise ValueError(f"Failed to append rows to range '{range_a1}' in spreadsheet '{spreadsheet_id}'.")
+        raise ValueError(
+            f"Failed to append rows to range '{range_a1}' in spreadsheet '{spreadsheet_id}'."
+        )
 
-    return result
+    return SheetsAppendOutput(
+        spreadsheet_id=spreadsheet_id,
+        table_range=result.get("table_range", range_a1),
+        updates=result.get("updates", {}),
+    )
 
 
-# @mcp.tool(
-#     name="sheets_clear_range",
-# )
-async def sheets_clear_range(spreadsheet_id: str, range_a1: str) -> dict[str, Any]:
+@mcp.tool(
+    name="sheets_clear_range",
+    description="Clears values from a specified range in a Google Spreadsheet (e.g., 'Sheet1!A1:B5').",
+)
+async def sheets_clear_range(spreadsheet_id: str, range_a1: str) -> SheetsClearOutput:
     """
     Clears all values from a given A1 notation range in a Google Spreadsheet.
     Note: This usually clears only the values, not formatting.
@@ -196,30 +241,39 @@ async def sheets_clear_range(spreadsheet_id: str, range_a1: str) -> dict[str, An
         range_a1: The A1 notation of the range to clear (e.g., "Sheet1!A1:B5").
 
     Returns:
-        A dictionary confirming the cleared range, or an error message.
+        SheetsClearOutput confirming the cleared range.
     """
-    logger.info(f"Executing sheets_clear_range tool for spreadsheet_id: '{spreadsheet_id}', range: '{range_a1}'")
+    logger.info(
+        f"Executing sheets_clear_range tool for spreadsheet_id: '{spreadsheet_id}', range: '{range_a1}'"
+    )
     if not spreadsheet_id or not spreadsheet_id.strip():
         raise ValueError("Spreadsheet ID cannot be empty.")
     if not range_a1 or not range_a1.strip():
         raise ValueError("Range (A1 notation) cannot be empty.")
 
     sheets_service = SheetsService()
-    result = sheets_service.clear_range(spreadsheet_id=spreadsheet_id, range_a1=range_a1)
+    result = sheets_service.clear_range(
+        spreadsheet_id=spreadsheet_id, range_a1=range_a1
+    )
 
     if isinstance(result, dict) and result.get("error"):
         raise ValueError(result.get("message", "Error clearing range in spreadsheet"))
 
     if not result or not result.get("cleared_range"):
-        raise ValueError(f"Failed to clear range '{range_a1}' in spreadsheet '{spreadsheet_id}'.")
+        raise ValueError(
+            f"Failed to clear range '{range_a1}' in spreadsheet '{spreadsheet_id}'."
+        )
 
-    return result
+    return SheetsClearOutput(
+        cleared_range=result["cleared_range"], spreadsheet_id=spreadsheet_id
+    )
 
 
-# @mcp.tool(
-#     name="sheets_add_sheet",
-# )
-async def sheets_add_sheet(spreadsheet_id: str, title: str) -> dict[str, Any]:
+@mcp.tool(
+    name="sheets_add_sheet",
+    description="Adds a new sheet (tab) to an existing Google Spreadsheet.",
+)
+async def sheets_add_sheet(spreadsheet_id: str, title: str) -> SheetsAddSheetOutput:
     """
     Adds a new sheet with the given title to the specified spreadsheet.
 
@@ -228,10 +282,11 @@ async def sheets_add_sheet(spreadsheet_id: str, title: str) -> dict[str, Any]:
         title: The title for the new sheet.
 
     Returns:
-        A dictionary containing properties of the newly created sheet (like sheetId, title, index),
-        or an error message.
+        SheetsAddSheetOutput containing properties of the newly created sheet.
     """
-    logger.info(f"Executing sheets_add_sheet tool for spreadsheet_id: '{spreadsheet_id}', title: '{title}'")
+    logger.info(
+        f"Executing sheets_add_sheet tool for spreadsheet_id: '{spreadsheet_id}', title: '{title}'"
+    )
     if not spreadsheet_id or not spreadsheet_id.strip():
         raise ValueError("Spreadsheet ID cannot be empty.")
     if not title or not title.strip():
@@ -244,15 +299,22 @@ async def sheets_add_sheet(spreadsheet_id: str, title: str) -> dict[str, Any]:
         raise ValueError(result.get("message", "Error adding sheet to spreadsheet"))
 
     if not result or not result.get("sheet_properties"):
-        raise ValueError(f"Failed to add sheet '{title}' to spreadsheet '{spreadsheet_id}'.")
+        raise ValueError(
+            f"Failed to add sheet '{title}' to spreadsheet '{spreadsheet_id}'."
+        )
 
-    return result
+    return SheetsAddSheetOutput(
+        sheet_properties=result["sheet_properties"], spreadsheet_id=spreadsheet_id
+    )
 
 
-# @mcp.tool(
-#     name="sheets_delete_sheet",
-# )
-async def sheets_delete_sheet(spreadsheet_id: str, sheet_id: int) -> dict[str, Any]:
+@mcp.tool(
+    name="sheets_delete_sheet",
+    description="Deletes a specific sheet (tab) from a Google Spreadsheet using its numeric sheet ID.",
+)
+async def sheets_delete_sheet(
+    spreadsheet_id: str, sheet_id: int
+) -> SheetsDeleteSheetOutput:
     """
     Deletes a sheet from the specified spreadsheet using its numeric ID.
 
@@ -261,21 +323,32 @@ async def sheets_delete_sheet(spreadsheet_id: str, sheet_id: int) -> dict[str, A
         sheet_id: The numeric ID of the sheet to delete.
 
     Returns:
-        A dictionary confirming the deletion or an error message.
+        SheetsDeleteSheetOutput confirming the deletion.
     """
-    logger.info(f"Executing sheets_delete_sheet tool for spreadsheet_id: '{spreadsheet_id}', sheet_id: {sheet_id}")
+    logger.info(
+        f"Executing sheets_delete_sheet tool for spreadsheet_id: '{spreadsheet_id}', sheet_id: {sheet_id}"
+    )
     if not spreadsheet_id or not spreadsheet_id.strip():
         raise ValueError("Spreadsheet ID cannot be empty.")
     if not isinstance(sheet_id, int):
         raise ValueError("Sheet ID must be an integer.")
 
     sheets_service = SheetsService()
-    result = sheets_service.delete_sheet(spreadsheet_id=spreadsheet_id, sheet_id=sheet_id)
+    result = sheets_service.delete_sheet(
+        spreadsheet_id=spreadsheet_id, sheet_id=sheet_id
+    )
 
     if isinstance(result, dict) and result.get("error"):
         raise ValueError(result.get("message", "Error deleting sheet from spreadsheet"))
 
     if not result or not result.get("success"):
-        raise ValueError(f"Failed to delete sheet ID '{sheet_id}' from spreadsheet '{spreadsheet_id}'.")
+        raise ValueError(
+            f"Failed to delete sheet ID '{sheet_id}' from spreadsheet '{spreadsheet_id}'."
+        )
 
-    return result
+    return SheetsDeleteSheetOutput(
+        success=result["success"],
+        message=result.get("message", f"Sheet ID '{sheet_id}' deleted successfully"),
+        spreadsheet_id=spreadsheet_id,
+        deleted_sheet_id=sheet_id,
+    )