Office Word MCP Server

Instructions

Implementation Reference

• word_document_server/tools/format_tools.py:19-127 (handler)

  Core handler function that executes the format_text tool logic: loads the DOCX, finds the paragraph, recreates runs for the specified range, applies bold/italic/underline/color/font formatting, and saves the document.

  async def format_text(filename: str, paragraph_index: int, start_pos: int, end_pos: int, 
                       bold: Optional[bool] = None, italic: Optional[bool] = None, 
                       underline: Optional[bool] = None, color: Optional[str] = None,
                       font_size: Optional[int] = None, font_name: Optional[str] = None) -> str:
      """Format a specific range of text within a paragraph.
      
      Args:
          filename: Path to the Word document
          paragraph_index: Index of the paragraph (0-based)
          start_pos: Start position within the paragraph text
          end_pos: End position within the paragraph text
          bold: Set text bold (True/False)
          italic: Set text italic (True/False)
          underline: Set text underlined (True/False)
          color: Text color (e.g., 'red', 'blue', etc.)
          font_size: Font size in points
          font_name: Font name/family
      """
      filename = ensure_docx_extension(filename)
      
      # Ensure numeric parameters are the correct type
      try:
          paragraph_index = int(paragraph_index)
          start_pos = int(start_pos)
          end_pos = int(end_pos)
          if font_size is not None:
              font_size = int(font_size)
      except (ValueError, TypeError):
          return "Invalid parameter: paragraph_index, start_pos, end_pos, and font_size 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 paragraph index
          if paragraph_index < 0 or paragraph_index >= len(doc.paragraphs):
              return f"Invalid paragraph index. Document has {len(doc.paragraphs)} paragraphs (0-{len(doc.paragraphs)-1})."
          
          paragraph = doc.paragraphs[paragraph_index]
          text = paragraph.text
          
          # Validate text positions
          if start_pos < 0 or end_pos > len(text) or start_pos >= end_pos:
              return f"Invalid text positions. Paragraph has {len(text)} characters."
          
          # Get the text to format
          target_text = text[start_pos:end_pos]
          
          # Clear existing runs and create three runs: before, target, after
          for run in paragraph.runs:
              run.clear()
          
          # Add text before target
          if start_pos > 0:
              run_before = paragraph.add_run(text[:start_pos])
          
          # Add target text with formatting
          run_target = paragraph.add_run(target_text)
          if bold is not None:
              run_target.bold = bold
          if italic is not None:
              run_target.italic = italic
          if underline is not None:
              run_target.underline = underline
          if color:
              # Define common RGB colors
              color_map = {
                  'red': RGBColor(255, 0, 0),
                  'blue': RGBColor(0, 0, 255),
                  'green': RGBColor(0, 128, 0),
                  'yellow': RGBColor(255, 255, 0),
                  'black': RGBColor(0, 0, 0),
                  'gray': RGBColor(128, 128, 128),
                  'white': RGBColor(255, 255, 255),
                  'purple': RGBColor(128, 0, 128),
                  'orange': RGBColor(255, 165, 0)
              }
              
              try:
                  if color.lower() in color_map:
                      # Use predefined RGB color
                      run_target.font.color.rgb = color_map[color.lower()]
                  else:
                      # Try to set color by name
                      run_target.font.color.rgb = RGBColor.from_string(color)
              except Exception as e:
                  # If all else fails, default to black
                  run_target.font.color.rgb = RGBColor(0, 0, 0)
          if font_size:
              run_target.font.size = Pt(font_size)
          if font_name:
              run_target.font.name = font_name
          
          # Add text after target
          if end_pos < len(text):
              run_after = paragraph.add_run(text[end_pos:])
          
          doc.save(filename)
          return f"Text '{target_text}' formatted successfully in paragraph {paragraph_index}."
      except Exception as e:
          return f"Failed to format text: {str(e)}"

• word_document_server/main.py:753-764 (registration)

  MCP tool registration decorator @mcp.tool() defining the tool interface and delegating to the core handler in format_tools.

  @mcp.tool()
  async def format_text(filename: str, paragraph_index: int, start_pos: int, end_pos: int,
                 bold: Optional[bool] = None, italic: Optional[bool] = None, underline: Optional[bool] = None,
                 color: Optional[str] = None, font_size: Optional[int] = None, font_name: Optional[str] = None):
      """Format a specific range of text within a paragraph.
      
      IMPORTANT: When specifying the color parameter, use a hex code WITHOUT the leading # (e.g., '0070C0', not '#0070C0').
      """
      return await format_tools.format_text(
          filename, paragraph_index, start_pos, end_pos, bold, italic, 
          underline, color, font_size, font_name
      )

• word_document_server/main.py:757-760 (schema)

  Tool description and parameter notes in the docstring, which serves as the schema documentation for MCP.

  """Format a specific range of text within a paragraph.
  
  IMPORTANT: When specifying the color parameter, use a hex code WITHOUT the leading # (e.g., '0070C0', not '#0070C0').
  """

• word_document_server/tools/__init__.py:23-25 (registration)

  Export of format_text function for use in main.py registration.

  from word_document_server.tools.format_tools import (
      format_text, create_custom_style, format_table
  )