Office Word MCP Server

Instructions

Implementation Reference

• word_document_server/main.py:392-396 (registration)

  MCP tool registration with @mcp.tool() decorator. Thin wrapper that calls the content_tools handler.

  @mcp.tool()
  def replace_paragraph_block_below_header(filename: str, header_text: str, new_paragraphs: list, detect_block_end_fn=None):
      """Reemplaza el bloque de párrafos debajo de un encabezado, evitando modificar TOC."""
      return replace_paragraph_block_below_header_tool(filename, header_text, new_paragraphs, detect_block_end_fn)

• word_document_server/tools/content_tools.py:475-477 (handler)

  Async tool handler function that delegates to the core implementation in document_utils.

  async def replace_paragraph_block_below_header_tool(filename: str, header_text: str, new_paragraphs: list, detect_block_end_fn=None) -> str:
      """Reemplaza el bloque de párrafos debajo de un encabezado, evitando modificar TOC."""
      return replace_paragraph_block_below_header(filename, header_text, new_paragraphs, detect_block_end_fn)

• word_document_server/utils/document_utils.py:483-528 (helper)

  Core helper function implementing the logic to find header, delete block below it until next heading/TOC, and insert new paragraphs.

  def replace_paragraph_block_below_header(
      doc_path: str,
      header_text: str,
      new_paragraphs: list,
      detect_block_end_fn=None,
      new_paragraph_style: str = None
  ) -> str:
      """
      Reemplaza todo el contenido debajo de una cabecera (por texto), hasta el siguiente encabezado/TOC (por estilo).
      """
      from docx import Document
      import os
      if not os.path.exists(doc_path):
          return f"Document {doc_path} not found."
      
      doc = Document(doc_path)
      
      # Find the header paragraph first
      header_para = None
      header_idx = None
      for i, para in enumerate(doc.paragraphs):
          para_text = para.text.strip().lower()
          is_toc = is_toc_paragraph(para)
          if para_text == header_text.strip().lower() and not is_toc:
              header_para = para
              header_idx = i
              break
      
      if header_para is None:
          return f"Header '{header_text}' not found in document."
      
      # Delete everything under the header using the same document instance
      header_el, removed_count = delete_block_under_header(doc, header_text)
      
      # Now insert new paragraphs after the header (which should still be in the document)
      style_to_use = new_paragraph_style or "Normal"
      
      # Find the header again after deletion (it should still be there)
      current_para = header_para
      for text in new_paragraphs:
          new_para = doc.add_paragraph(text, style=style_to_use)
          current_para._element.addnext(new_para._element)
          current_para = new_para
      
      doc.save(doc_path)
      return f"Replaced content under '{header_text}' with {len(new_paragraphs)} paragraph(s), style: {style_to_use}, removed {removed_count} elements."

• word_document_server/utils/document_utils.py:441-481 (helper)

  Supporting helper function to delete the block of content under a header until the next heading or TOC.

  def delete_block_under_header(doc, header_text):
      """
      Remove all elements (paragraphs, tables, etc.) after the header (by text) and before the next heading/TOC (by style).
      Returns: (header_element, elements_removed)
      """
      # Find the header paragraph by text (like delete_paragraph finds by index)
      header_para = None
      header_idx = None
      
      for i, para in enumerate(doc.paragraphs):
          if para.text.strip().lower() == header_text.strip().lower():
              header_para = para
              header_idx = i
              break
      
      if header_para is None:
          return None, 0
      
      # Find the next heading/TOC paragraph to determine the end of the block
      end_idx = None
      for i in range(header_idx + 1, len(doc.paragraphs)):
          para = doc.paragraphs[i]
          if para.style and para.style.name.lower().startswith(('heading', 'título', 'toc')):
              end_idx = i
              break
      
      # If no next heading found, delete until end of document
      if end_idx is None:
          end_idx = len(doc.paragraphs)
      
      # Remove paragraphs by index (like delete_paragraph does)
      removed_count = 0
      for i in range(header_idx + 1, end_idx):
          if i < len(doc.paragraphs):  # Safety check
              para = doc.paragraphs[header_idx + 1]  # Always remove the first paragraph after header
              p = para._p
              p.getparent().remove(p)
              removed_count += 1
      
      return header_para._p, removed_count