add_heading
Insert headings into a Word document by specifying the filename, text, and level. Simplify document structuring for improved organization and readability.
Instructions
Add a heading to a Word document.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| filename | Yes | ||
| level | No | ||
| text | Yes |
Implementation Reference
- word_document_server/main.py:164-180 (registration)FastMCP tool registration for 'add_heading'. This is the entry point for the MCP tool, delegating to the core implementation in content_tools.@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)
- Core handler function that implements the add_heading logic using python-docx: adds heading, applies custom formatting to runs, adds bottom border if requested, 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)}"