add_heading
Add structured headings to Microsoft Word documents, specifying text and level for improved organization and readability. Helps manage content hierarchy efficiently.
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: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)}"
- 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 )