Google Workspace MCP Server

Instructions

Implementation Reference

• gdocs/docs_tools.py:967-1051 (handler)

  The core handler function for the 'debug_table_structure' tool. Decorated with @server.tool() for MCP registration. Fetches document via Google Docs API, uses find_tables helper to locate tables, then extracts detailed cell information including positions, content, and ranges, returning a JSON-formatted debug output.

  @server.tool()
  @handle_http_errors("debug_table_structure", is_read_only=True, service_type="docs")
  @require_google_service("docs", "docs_read")
  async def debug_table_structure(
      service,
      user_google_email: str,
      document_id: str,
      table_index: int = 0,
  ) -> str:
      """
      ESSENTIAL DEBUGGING TOOL - Use this whenever tables don't work as expected.
  
      USE THIS IMMEDIATELY WHEN:
      - Table population put data in wrong cells
      - You get "table not found" errors
      - Data appears concatenated in first cell
      - Need to understand existing table structure
      - Planning to use populate_existing_table
  
      WHAT THIS SHOWS YOU:
      - Exact table dimensions (rows × columns)
      - Each cell's position coordinates (row,col)
      - Current content in each cell
      - Insertion indices for each cell
      - Table boundaries and ranges
  
      HOW TO READ THE OUTPUT:
      - "dimensions": "2x3" = 2 rows, 3 columns
      - "position": "(0,0)" = first row, first column
      - "current_content": What's actually in each cell right now
      - "insertion_index": Where new text would be inserted in that cell
  
      WORKFLOW INTEGRATION:
      1. After creating table → Use this to verify structure
      2. Before populating → Use this to plan your data format
      3. After population fails → Use this to see what went wrong
      4. When debugging → Compare your data array to actual table structure
  
      Args:
          user_google_email: User's Google email address
          document_id: ID of the document to inspect
          table_index: Which table to debug (0 = first table, 1 = second table, etc.)
  
      Returns:
          str: Detailed JSON structure showing table layout, cell positions, and current content
      """
      logger.debug(f"[debug_table_structure] Doc={document_id}, table_index={table_index}")
  
      # Get the document
      doc = await asyncio.to_thread(
          service.documents().get(documentId=document_id).execute
      )
  
      # Find tables
      tables = find_tables(doc)
      if table_index >= len(tables):
          return f"Error: Table index {table_index} not found. Document has {len(tables)} table(s)."
  
      table_info = tables[table_index]
  
      import json
  
      # Extract detailed cell information
      debug_info = {
          'table_index': table_index,
          'dimensions': f"{table_info['rows']}x{table_info['columns']}",
          'table_range': f"[{table_info['start_index']}-{table_info['end_index']}]",
          'cells': []
      }
  
      for row_idx, row in enumerate(table_info['cells']):
          row_info = []
          for col_idx, cell in enumerate(row):
              cell_debug = {
                  'position': f"({row_idx},{col_idx})",
                  'range': f"[{cell['start_index']}-{cell['end_index']}]",
                  'insertion_index': cell.get('insertion_index', 'N/A'),
                  'current_content': repr(cell.get('content', '')),
                  'content_elements_count': len(cell.get('content_elements', []))
              }
              row_info.append(cell_debug)
          debug_info['cells'].append(row_info)
  
      link = f"https://docs.google.com/document/d/{document_id}/edit"
      return f"Table structure debug for table {table_index}:\n\n{json.dumps(debug_info, indent=2)}\n\nLink: {link}"

• gdocs/docs_structure.py:170-193 (helper)

  Helper function used by the tool to parse document structure and extract all tables with their dimensions, positions, and cell details from the raw Google Docs API response.

  def find_tables(doc_data: dict[str, Any]) -> list[dict[str, Any]]:
      """
      Find all tables in the document with their positions and dimensions.
      
      Args:
          doc_data: Raw document data from Google Docs API
      
      Returns:
          List of table information dictionaries
      """
      tables = []
      structure = parse_document_structure(doc_data)
      
      for idx, table_info in enumerate(structure['tables']):
          tables.append({
              'index': idx,
              'start_index': table_info['start_index'],
              'end_index': table_info['end_index'],
              'rows': table_info['rows'],
              'columns': table_info['columns'],
              'cells': table_info['cells']
          })
      
      return tables