Google Workspace MCP Server

Instructions

Implementation Reference

• gdocs/docs_tools.py:873-965 (handler)

  Main MCP tool handler for 'create_table_with_data'. Includes @server.tool() registration, input validation, error handling, and delegates core logic to TableOperationManager. Input schema defined by function parameters and type hints.
  @server.tool() @handle_http_errors("create_table_with_data", service_type="docs") @require_google_service("docs", "docs_write") async def create_table_with_data( service, user_google_email: str, document_id: str, table_data: list, index: int, bold_headers: bool = True, ) -> str: """ Creates a table and populates it with data in one reliable operation. CRITICAL: YOU MUST CALL inspect_doc_structure FIRST TO GET THE INDEX! MANDATORY WORKFLOW - DO THESE STEPS IN ORDER: Step 1: ALWAYS call inspect_doc_structure first Step 2: Use the 'total_length' value from inspect_doc_structure as your index Step 3: Format data as 2D list: [["col1", "col2"], ["row1col1", "row1col2"]] Step 4: Call this function with the correct index and data EXAMPLE DATA FORMAT: table_data = [ ["Header1", "Header2", "Header3"], # Row 0 - headers ["Data1", "Data2", "Data3"], # Row 1 - first data row ["Data4", "Data5", "Data6"] # Row 2 - second data row ] CRITICAL INDEX REQUIREMENTS: - NEVER use index values like 1, 2, 10 without calling inspect_doc_structure first - ALWAYS get index from inspect_doc_structure 'total_length' field - Index must be a valid insertion point in the document DATA FORMAT REQUIREMENTS: - Must be 2D list of strings only - Each inner list = one table row - All rows MUST have same number of columns - Use empty strings "" for empty cells, never None - Use debug_table_structure after creation to verify results Args: user_google_email: User's Google email address document_id: ID of the document to update table_data: 2D list of strings - EXACT format: [["col1", "col2"], ["row1col1", "row1col2"]] index: Document position (MANDATORY: get from inspect_doc_structure 'total_length') bold_headers: Whether to make first row bold (default: true) Returns: str: Confirmation with table details and link """ logger.debug(f"[create_table_with_data] Doc={document_id}, index={index}") # Input validation validator = ValidationManager() is_valid, error_msg = validator.validate_document_id(document_id) if not is_valid: return f"ERROR: {error_msg}" is_valid, error_msg = validator.validate_table_data(table_data) if not is_valid: return f"ERROR: {error_msg}" is_valid, error_msg = validator.validate_index(index, "Index") if not is_valid: return f"ERROR: {error_msg}" # Use TableOperationManager to handle the complex logic table_manager = TableOperationManager(service) # Try to create the table, and if it fails due to index being at document end, retry with index-1 success, message, metadata = await table_manager.create_and_populate_table( document_id, table_data, index, bold_headers ) # If it failed due to index being at or beyond document end, retry with adjusted index if not success and "must be less than the end index" in message: logger.debug(f"Index {index} is at document boundary, retrying with index {index - 1}") success, message, metadata = await table_manager.create_and_populate_table( document_id, table_data, index - 1, bold_headers ) if success: link = f"https://docs.google.com/document/d/{document_id}/edit" rows = metadata.get('rows', 0) columns = metadata.get('columns', 0) return f"SUCCESS: {message}. Table: {rows}x{columns}, Index: {index}. Link: {link}" else: return f"ERROR: {message}"
• gdocs/managers/table_operation_manager.py:37-94 (helper)

  Core helper method in TableOperationManager that implements the table creation and population logic. Handles multi-step process: create empty table, refresh structure, populate cells one-by-one with index correction to avoid shifting issues.
  async def create_and_populate_table( self, document_id: str, table_data: List[List[str]], index: int, bold_headers: bool = True ) -> Tuple[bool, str, Dict[str, Any]]: """ Creates a table and populates it with data in a reliable multi-step process. This method extracts the complex logic from create_table_with_data tool function. Args: document_id: ID of the document to update table_data: 2D list of strings for table content index: Position to insert the table bold_headers: Whether to make the first row bold Returns: Tuple of (success, message, metadata) """ logger.debug(f"Creating table at index {index}, dimensions: {len(table_data)}x{len(table_data[0]) if table_data and len(table_data) > 0 else 0}") # Validate input data is_valid, error_msg = validate_table_data(table_data) if not is_valid: return False, f"Invalid table data: {error_msg}", {} rows = len(table_data) cols = len(table_data[0]) try: # Step 1: Create empty table await self._create_empty_table(document_id, index, rows, cols) # Step 2: Get fresh document structure to find actual cell positions fresh_tables = await self._get_document_tables(document_id) if not fresh_tables: return False, "Could not find table after creation", {} # Step 3: Populate each cell with proper index refreshing population_count = await self._populate_table_cells( document_id, table_data, bold_headers ) metadata = { 'rows': rows, 'columns': cols, 'populated_cells': population_count, 'table_index': len(fresh_tables) - 1 } return True, f"Successfully created {rows}x{cols} table and populated {population_count} cells", metadata except Exception as e: logger.error(f"Failed to create and populate table: {str(e)}") return False, f"Table creation failed: {str(e)}", {}
• gdocs/docs_tables.py:385-438 (schema)

  Input validation function for table_data parameter. Checks for 2D list format, consistent dimensions, size limits, no None values. Provides LLM-friendly error messages with examples.
  def validate_table_data(data: List[List[str]]) -> Tuple[bool, str]: """ Validates table data format and provides specific error messages for LLMs. WHAT THIS CHECKS: - Data is a 2D list (list of lists) - All rows have consistent column counts - Dimensions are within Google Docs limits - No None or undefined values VALID FORMAT EXAMPLE: [ ["Header1", "Header2"], # Row 0 - 2 columns ["Data1", "Data2"], # Row 1 - 2 columns ["Data3", "Data4"] # Row 2 - 2 columns ] INVALID FORMATS: - [["col1"], ["col1", "col2"]] # Inconsistent column counts - ["col1", "col2"] # Not 2D (missing inner lists) - [["col1", None]] # Contains None values - [] or [[]] # Empty data Args: data: 2D array of data to validate Returns: Tuple of (is_valid, error_message_with_examples) """ if not data: return False, "Data is empty. Use format: [['col1', 'col2'], ['row1col1', 'row1col2']]" if not isinstance(data, list): return False, f"Data must be a list, got {type(data).__name__}. Use format: [['col1', 'col2'], ['row1col1', 'row1col2']]" if not all(isinstance(row, list) for row in data): return False, f"Data must be a 2D list (list of lists). Each row must be a list. Check your format: {data}" # Check for consistent column count col_counts = [len(row) for row in data] if len(set(col_counts)) > 1: return False, f"All rows must have same number of columns. Found: {col_counts}. Fix your data format." # Check for reasonable size rows = len(data) cols = col_counts[0] if col_counts else 0 if rows > 1000: return False, f"Too many rows ({rows}). Google Docs limit is 1000 rows." if cols > 20: return False, f"Too many columns ({cols}). Google Docs limit is 20 columns." return True, f"Valid table data: {rows}x{cols} table format"
• gdocs/docs_tools.py:873-873 (registration)

  MCP tool registration via @server.tool() decorator on the handler function, with error handling and auth requirements.
  @server.tool()