add_heading

Instructions

Implementation Reference

• word_document_server/main.py:672-711 (handler)

  Primary MCP tool handler for 'add_heading' registered with @mcp.tool() decorator. Implements the core logic using document resolver, heading styles, and fallback formatting.

  @mcp.tool()
  async def add_heading(filename: str, text: str, level: int = 1):
      """Add a heading to a Word document."""
      try:
          # Validate level
          if level < 1 or level > 9:
              return f"Invalid heading level: {level}. Level must be between 1 and 9."
          
          # Use resolver to find the document
          doc, resolved_path = load_document_with_resolver(filename)
          
          # Add the heading
          from word_document_server.core.styles import ensure_heading_style
          ensure_heading_style(doc)
          
          try:
              heading = doc.add_heading(text, level=level)
          except Exception:
              # Fallback to direct formatting if style fails
              from docx.shared import Pt
              paragraph = doc.add_paragraph(text)
              paragraph.style = doc.styles['Normal']
              run = paragraph.runs[0]
              run.bold = True
              if level == 1:
                  run.font.size = Pt(16)
              elif level == 2:
                  run.font.size = Pt(14)
              else:
                  run.font.size = Pt(12)
          
          # Save the document
          save_document_with_resolver(doc, filename, resolved_path)
          return f"Heading '{text}' (level {level}) added to {filename}"
          
      except FileNotFoundError as e:
          return str(e)
      except Exception as e:
          return f"Failed to add heading: {str(e)}"

• word_document_server/tools/content_tools.py:17-75 (helper)

  Supporting helper function for adding headings, with file validation and write checks. Similar logic to MCP handler but without resolver integration.

  async def add_heading(filename: str, text: str, level: int = 1) -> str:
      """Add a heading to a Word document.
      
      Args:
          filename: Path to the Word document
          text: Heading text
          level: Heading level (1-9, where 1 is the highest level)
      """
      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)
              doc.save(filename)
              return f"Heading '{text}' (level {level}) added to {filename}"
          except Exception as style_error:
              # If style-based approach fails, use direct formatting
              paragraph = doc.add_paragraph(text)
              paragraph.style = doc.styles['Normal']
              run = paragraph.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)
              
              doc.save(filename)
              return f"Heading '{text}' added to {filename} with direct formatting (style not available)"
      except Exception as e:
          return f"Failed to add heading: {str(e)}"

• word_document_server/tools/__init__.py:16-20 (registration)

  Exports the add_heading function from content_tools for use across the tools package.

  from word_document_server.tools.content_tools import (
      add_heading, add_paragraph, add_table, add_picture,
      add_page_break, add_table_of_contents, delete_paragraph,
      search_and_replace
  )