Office Word MCP Server

Instructions

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)

• word_document_server/tools/content_tools.py:437-439 (handler)

  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)

• word_document_server/utils/document_utils.py:247-302 (handler)

  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)}"