Office Word MCP Server

Instructions

Implementation Reference

• word_document_server/tools/format_tools.py:236-291 (handler)

  The primary asynchronous handler for the set_table_cell_shading tool. Handles input validation, document loading/saving, index validation, and delegates the actual shading to the core tables helper.

  async def set_table_cell_shading(filename: str, table_index: int, row_index: int, 
                                  col_index: int, fill_color: str, pattern: str = "clear") -> str:
      """Apply shading/filling to a specific table cell.
      
      Args:
          filename: Path to the Word document
          table_index: Index of the table (0-based)
          row_index: Row index of the cell (0-based)
          col_index: Column index of the cell (0-based)
          fill_color: Background color (hex string like "FF0000" or "red")
          pattern: Shading pattern ("clear", "solid", "pct10", "pct20", etc.)
      """
      filename = ensure_docx_extension(filename)
      
      # Ensure numeric parameters are the correct type
      try:
          table_index = int(table_index)
          row_index = int(row_index)
          col_index = int(col_index)
      except (ValueError, TypeError):
          return "Invalid parameter: table_index, row_index, and col_index must be integers"
      
      if not os.path.exists(filename):
          return f"Document {filename} does not exist"
      
      # Check if file is writeable
      is_writeable, error_message = check_file_writeable(filename)
      if not is_writeable:
          return f"Cannot modify document: {error_message}. Consider creating a copy first."
      
      try:
          doc = Document(filename)
          
          # Validate table index
          if table_index < 0 or table_index >= len(doc.tables):
              return f"Invalid table index. Document has {len(doc.tables)} tables (0-{len(doc.tables)-1})."
          
          table = doc.tables[table_index]
          
          # Validate row and column indices
          if row_index < 0 or row_index >= len(table.rows):
              return f"Invalid row index. Table has {len(table.rows)} rows (0-{len(table.rows)-1})."
          
          if col_index < 0 or col_index >= len(table.rows[row_index].cells):
              return f"Invalid column index. Row has {len(table.rows[row_index].cells)} cells (0-{len(table.rows[row_index].cells)-1})."
          
          # Apply cell shading
          success = set_cell_shading_by_position(table, row_index, col_index, fill_color, pattern)
          
          if success:
              doc.save(filename)
              return f"Cell shading applied successfully to table {table_index}, row {row_index}, column {col_index}."
          else:
              return f"Failed to apply cell shading."
      except Exception as e:
          return f"Failed to apply cell shading: {str(e)}"

• word_document_server/main.py:235-240 (registration)

  Registers the tool with the FastMCP server using the @mcp.tool() decorator. Provides a synchronous wrapper function that calls the async handler from format_tools.

  @mcp.tool()
  def set_table_cell_shading(filename: str, table_index: int, row_index: int, 
                            col_index: int, fill_color: str, pattern: str = "clear"):
      """Apply shading/filling to a specific table cell."""
      return format_tools.set_table_cell_shading(filename, table_index, row_index, col_index, fill_color, pattern)

• word_document_server/core/tables.py:261-284 (helper)

  Core utility function that locates the specific table cell by row and column indices and applies shading by calling the lower-level set_cell_shading function on the cell.

  def set_cell_shading_by_position(table, row_index, col_index, fill_color, pattern="clear"):
      """
      Apply shading to a specific cell by row/column position.
      
      Args:
          table: The table containing the cell
          row_index: Row index (0-based)
          col_index: Column index (0-based)
          fill_color: Background color (hex string)
          pattern: Shading pattern
          
      Returns:
          True if successful, False otherwise
      """
      try:
          if (0 <= row_index < len(table.rows) and 
              0 <= col_index < len(table.rows[row_index].cells)):
              cell = table.rows[row_index].cells[col_index]
              return set_cell_shading(cell, fill_color=fill_color, pattern=pattern)
          else:
              return False
      except Exception as e:
          print(f"Error setting cell shading by position: {e}")
          return False