Office Word MCP Server

Instructions

Implementation Reference

• word_document_server/tools/content_tools.py:17-110 (handler)

  Core implementation of the add_heading tool: opens the document, adds a heading with specified level and formatting (font, size, bold, italic, border), handles errors and saves the document.

  async def add_heading(filename: str, text: str, level: int = 1,
                        font_name: Optional[str] = None, font_size: Optional[int] = None,
                        bold: Optional[bool] = None, italic: Optional[bool] = None,
                        border_bottom: bool = False) -> str:
      """Add a heading to a Word document with optional formatting.
  
      Args:
          filename: Path to the Word document
          text: Heading text
          level: Heading level (1-9, where 1 is the highest level)
          font_name: Font family (e.g., 'Helvetica')
          font_size: Font size in points (e.g., 14)
          bold: True/False for bold text
          italic: True/False for italic text
          border_bottom: True to add bottom border (for section headers)
      """
      filename = ensure_docx_extension(filename)
  
      # Ensure level is converted to integer
      try:
          level = int(level)
      except (ValueError, TypeError):
          return "Invalid parameter: level must be an integer between 1 and 9"
  
      # Validate level range
      if level < 1 or level > 9:
          return f"Invalid heading level: {level}. Level must be between 1 and 9."
  
      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:
          # Suggest creating a copy
          return f"Cannot modify document: {error_message}. Consider creating a copy first or creating a new document."
  
      try:
          doc = Document(filename)
  
          # Ensure heading styles exist
          ensure_heading_style(doc)
  
          # Try to add heading with style
          try:
              heading = doc.add_heading(text, level=level)
          except Exception as style_error:
              # If style-based approach fails, use direct formatting
              heading = doc.add_paragraph(text)
              heading.style = doc.styles['Normal']
              if heading.runs:
                  run = heading.runs[0]
                  run.bold = True
                  # Adjust size based on heading level
                  if level == 1:
                      run.font.size = Pt(16)
                  elif level == 2:
                      run.font.size = Pt(14)
                  else:
                      run.font.size = Pt(12)
  
          # Apply formatting to all runs in the heading
          if any([font_name, font_size, bold is not None, italic is not None]):
              for run in heading.runs:
                  if font_name:
                      run.font.name = font_name
                  if font_size:
                      run.font.size = Pt(font_size)
                  if bold is not None:
                      run.font.bold = bold
                  if italic is not None:
                      run.font.italic = italic
  
          # Add bottom border if requested
          if border_bottom:
              from docx.oxml import OxmlElement
              from docx.oxml.ns import qn
  
              pPr = heading._element.get_or_add_pPr()
              pBdr = OxmlElement('w:pBdr')
  
              bottom = OxmlElement('w:bottom')
              bottom.set(qn('w:val'), 'single')
              bottom.set(qn('w:sz'), '4')  # 0.5pt border
              bottom.set(qn('w:space'), '0')
              bottom.set(qn('w:color'), '000000')
  
              pBdr.append(bottom)
              pPr.append(pBdr)
  
          doc.save(filename)
          return f"Heading '{text}' (level {level}) added to {filename}"
      except Exception as e:
          return f"Failed to add heading: {str(e)}"

• word_document_server/main.py:164-180 (registration)

  MCP tool registration using @mcp.tool() decorator, defines input parameters and docstring schema, delegates execution to content_tools.add_heading.

  @mcp.tool()
  def add_heading(filename: str, text: str, level: int = 1,
                  font_name: str = None, font_size: int = None,
                  bold: bool = None, italic: bool = None, border_bottom: bool = False):
      """Add a heading to a Word document with optional formatting.
  
      Args:
          filename: Path to Word document
          text: Heading text
          level: Heading level (1-9)
          font_name: Font family (e.g., 'Helvetica')
          font_size: Font size in points (e.g., 14)
          bold: Make heading bold
          italic: Make heading italic
          border_bottom: Add bottom border (for section headers)
      """
      return content_tools.add_heading(filename, text, level, font_name, font_size, bold, italic, border_bottom)

• word_document_server/main.py:164-180 (schema)

  Input schema defined by function signature type hints and Args docstring in the registered tool function.

  @mcp.tool()
  def add_heading(filename: str, text: str, level: int = 1,
                  font_name: str = None, font_size: int = None,
                  bold: bool = None, italic: bool = None, border_bottom: bool = False):
      """Add a heading to a Word document with optional formatting.
  
      Args:
          filename: Path to Word document
          text: Heading text
          level: Heading level (1-9)
          font_name: Font family (e.g., 'Helvetica')
          font_size: Font size in points (e.g., 14)
          bold: Make heading bold
          italic: Make heading italic
          border_bottom: Add bottom border (for section headers)
      """
      return content_tools.add_heading(filename, text, level, font_name, font_size, bold, italic, border_bottom)