insert_header_near_text
Add a styled header before or after a specific paragraph in a Word document. Use text content or paragraph index to locate the target, and customize header title, style, and position.
Instructions
Insert a header (with specified style) before or after the target paragraph. Specify by text or paragraph index. Args: filename (str), target_text (str, optional), header_title (str), position ('before' or 'after'), header_style (str, default 'Heading 1'), target_paragraph_index (int, optional).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| filename | Yes | ||
| header_style | No | Heading 1 | |
| header_title | No | ||
| position | No | after | |
| target_paragraph_index | No | ||
| target_text | No |
Input Schema (JSON Schema)
{
"properties": {
"filename": {
"title": "Filename",
"type": "string"
},
"header_style": {
"default": "Heading 1",
"title": "Header Style",
"type": "string"
},
"header_title": {
"default": null,
"title": "Header Title",
"type": "string"
},
"position": {
"default": "after",
"title": "Position",
"type": "string"
},
"target_paragraph_index": {
"default": null,
"title": "Target Paragraph Index",
"type": "integer"
},
"target_text": {
"default": null,
"title": "Target Text",
"type": "string"
}
},
"required": [
"filename"
],
"type": "object"
}
Implementation Reference
- word_document_server/main.py:558-561 (registration)Registration of the MCP tool 'insert_header_near_text' using FastMCP @mcp.tool() decorator. Includes input schema in docstring and delegates to content_tools handler.async def insert_header_near_text(filename: str, target_text: Optional[str] = None, header_title: Optional[str] = None, position: str = 'after', header_style: str = 'Heading 1', target_paragraph_index: Optional[int] = None): """Insert a header (with specified style) before or after the target paragraph. Specify by text or paragraph index. Args: filename (str), target_text (str, optional), header_title (str), position ('before' or 'after'), header_style (str, default 'Heading 1'), target_paragraph_index (int, optional).""" return await content_tools.insert_header_near_text_tool(filename, target_text, header_title, position, header_style, target_paragraph_index)
- Tool handler function in content_tools that wraps and calls the core implementation.async def insert_header_near_text_tool(filename: str, target_text: str = None, header_title: str = "", position: str = 'after', header_style: str = 'Heading 1', target_paragraph_index: int = None) -> str: """Insert a header (with specified style) before or after the target paragraph. Specify by text or paragraph index.""" return insert_header_near_text(filename, target_text, header_title, position, header_style, target_paragraph_index)
- Core implementation of the tool logic: finds target paragraph by text or index, inserts new header paragraph with specified style before/after it, handles TOC skipping, file resolution from path/URL/temp, saves document.def insert_header_near_text(doc_path: str, target_text: str = None, header_title: str = "", position: str = 'after', header_style: str = 'Heading 1', target_paragraph_index: int = None) -> str: """Insert a header (with specified style) before or after the target paragraph. Specify by text or paragraph index. Skips TOC paragraphs in text search. Supports URLs.""" success, message, resolved_path, is_temp = resolve_file_path(doc_path) if not success: return message try: doc = Document(resolved_path) found = False para = None if target_paragraph_index is not None: if target_paragraph_index < 0 or target_paragraph_index >= len(doc.paragraphs): return f"Invalid target_paragraph_index: {target_paragraph_index}. Document has {len(doc.paragraphs)} paragraphs." para = doc.paragraphs[target_paragraph_index] found = True else: for i, p in enumerate(doc.paragraphs): # Skip TOC paragraphs if p.style and p.style.name.lower().startswith("toc"): continue if target_text and target_text in p.text: para = p found = True break if not found or para is None: return f"Target paragraph not found (by index or text). (TOC paragraphs are skipped in text search)" # Save anchor index before insertion if target_paragraph_index is not None: anchor_index = target_paragraph_index else: anchor_index = None for i, p in enumerate(doc.paragraphs): if p is para: anchor_index = i break new_para = doc.add_paragraph(header_title, style=header_style) if position == 'before': para._element.addprevious(new_para._element) else: para._element.addnext(new_para._element) doc.save(resolved_path) # Build response message if anchor_index is not None: result = f"Header '{header_title}' (style: {header_style}) inserted {position} paragraph (index {anchor_index})." else: result = f"Header '{header_title}' (style: {header_style}) inserted {position} the target paragraph." # Add temp file info if applicable if is_temp: result += f" Modified file saved to temporary location: {resolved_path}" return result except Exception as e: return f"Failed to insert header: {str(e)}"