Office Word MCP Server

Instructions

Implementation Reference

• word_document_server/main.py:129-133 (registration)

  Tool registration using FastMCP @mcp.tool() decorator. Defines the tool name, parameters, docstring (schema description), and delegates execution to the handler in content_tools.

  @mcp.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 handler function registered indirectly via main.py. Thin wrapper that invokes the core helper function performing the actual document manipulation.

  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-241 (helper)

  Core utility function implementing the logic: loads document, finds target paragraph by text (skipping TOC) or index, creates new styled paragraph, inserts via XML element manipulation before/after target, 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)}"