Office Word MCP Server

Instructions

Implementation Reference

• word_document_server/main.py:130-132 (registration)

  Registration of the MCP tool 'insert_header_near_text' with @mcp.tool() decorator. This is the entry point for the tool.
  def insert_header_near_text(filename: str, target_text: str = None, header_title: str = None, position: str = 'after', header_style: str = 'Heading 1', target_paragraph_index: 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 content_tools.insert_header_near_text_tool(filename, target_text, header_title, position, header_style, target_paragraph_index)
• word_document_server/tools/content_tools.py:463-465 (handler)

  Async tool handler in content_tools that delegates to the core insert_header_near_text function.
  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)
• word_document_server/utils/document_utils.py:194-240 (handler)

  Core implementation of insert_header_near_text: loads document, finds target paragraph (skipping TOC), inserts new styled paragraph before/after it, 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.""" import os from docx import Document if not os.path.exists(doc_path): return f"Document {doc_path} does not exist" try: doc = Document(doc_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(doc_path) if anchor_index is not None: return f"Header '{header_title}' (style: {header_style}) inserted {position} paragraph (index {anchor_index})." else: return f"Header '{header_title}' (style: {header_style}) inserted {position} the target paragraph." except Exception as e: return f"Failed to insert header: {str(e)}"
• word_document_server/tools/content_tools.py:13-13 (helper)

  Import of the core insert_header_near_text function from document_utils.
  from word_document_server.utils.document_utils import find_and_replace_text, insert_header_near_text, insert_numbered_list_near_text, insert_line_or_paragraph_near_text, replace_paragraph_block_below_header, replace_block_between_manual_anchors