Office Word MCP Server

Instructions

Implementation Reference

• word_document_server/main.py:247-251 (registration)

  Registration of the 'highlight_table_header' tool using the @mcp.tool() decorator. This is a thin synchronous wrapper that delegates execution to the async implementation in format_tools.

  @mcp.tool()
  def highlight_table_header(filename: str, table_index: int, 
                           header_color: str = "4472C4", text_color: str = "FFFFFF"):
      """Apply special highlighting to table header row."""
      return format_tools.highlight_table_header(filename, table_index, header_color, text_color)

• word_document_server/tools/format_tools.py:341-385 (handler)

  Main handler implementation: loads the Word document using python-docx, validates inputs, applies highlighting via helper function, and saves the modified document.

  async def highlight_table_header(filename: str, table_index: int, 
                                 header_color: str = "4472C4", text_color: str = "FFFFFF") -> str:
      """Apply special highlighting to table header row.
      
      Args:
          filename: Path to the Word document
          table_index: Index of the table (0-based)
          header_color: Background color for header (hex string, default blue)
          text_color: Text color for header (hex string, default white)
      """
      filename = ensure_docx_extension(filename)
      
      # Ensure numeric parameters are the correct type
      try:
          table_index = int(table_index)
      except (ValueError, TypeError):
          return "Invalid parameter: table_index must be an integer"
      
      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]
          
          # Apply header highlighting
          success = highlight_header_row(table, header_color, text_color)
          
          if success:
              doc.save(filename)
              return f"Header highlighting applied successfully to table {table_index}."
          else:
              return f"Failed to apply header highlighting."
      except Exception as e:
          return f"Failed to apply header highlighting: {str(e)}"

• word_document_server/core/tables.py:223-258 (helper)

  Core helper function that applies background shading and bold white text formatting to the first row (header) cells of the table using direct XML manipulation and python-docx APIs.

  def highlight_header_row(table, header_color="4472C4", text_color="FFFFFF"):
      """
      Apply special shading to header row.
      
      Args:
          table: The table to format
          header_color: Background color for header (hex string)
          text_color: Text color for header (hex string)
          
      Returns:
          True if successful, False otherwise
      """
      try:
          if table.rows:
              for cell in table.rows[0].cells:
                  # Apply background shading
                  set_cell_shading(cell, fill_color=header_color)
                  
                  # Apply text formatting
                  for paragraph in cell.paragraphs:
                      for run in paragraph.runs:
                          run.bold = True
                          if text_color and text_color != "auto":
                              # Convert hex to RGB
                              try:
                                  text_color = text_color.lstrip('#')
                                  r = int(text_color[0:2], 16)
                                  g = int(text_color[2:4], 16)
                                  b = int(text_color[4:6], 16)
                                  run.font.color.rgb = RGBColor(r, g, b)
                              except:
                                  pass  # Skip if color format is invalid
          return True
      except Exception as e:
          print(f"Error highlighting header row: {e}")
          return False