docx_process

Instructions

Implementation Reference

• server.py:2228-2243 (handler)

  The docx_process gateway tool function that routes to the appropriate document operation handler based on the 'route' parameter.

  @mcp.tool()
  def docx_process(ctx: Context, route: str, params: Dict[str, Any]) -> str:
      """
      IMPORTANT: Before calling this tool, you MUST first invoke the "docx-process" skill to load the complete parameter specifications. Do NOT call this tool without first loading the skill documentation.
  
      Word document processing gateway. Use route to select the operation.
  
      Parameters:
      - route: Operation name (e.g. "create_document", "add_paragraph", "search_text")
      - params: Parameters for the selected operation, see skill documentation for details
      """
      handler = ROUTE_HANDLERS.get(route)
      if handler is None:
          available = ", ".join(sorted(ROUTE_HANDLERS.keys()))
          return f"Unknown route: '{route}'. Available routes: {available}"
      return handler(params)

• server.py:2228-2243 (registration)

  Registration of docx_process as an MCP tool using the @mcp.tool() decorator on the FastMCP server instance.

  @mcp.tool()
  def docx_process(ctx: Context, route: str, params: Dict[str, Any]) -> str:
      """
      IMPORTANT: Before calling this tool, you MUST first invoke the "docx-process" skill to load the complete parameter specifications. Do NOT call this tool without first loading the skill documentation.
  
      Word document processing gateway. Use route to select the operation.
  
      Parameters:
      - route: Operation name (e.g. "create_document", "add_paragraph", "search_text")
      - params: Parameters for the selected operation, see skill documentation for details
      """
      handler = ROUTE_HANDLERS.get(route)
      if handler is None:
          available = ", ".join(sorted(ROUTE_HANDLERS.keys()))
          return f"Unknown route: '{route}'. Available routes: {available}"
      return handler(params)

• server.py:2143-2221 (schema)

  Route registry (ROUTE_HANDLERS dict) mapping route names to handler functions, serving as the schema of available operations routed through docx_process.

  ROUTE_HANDLERS = {
      # Document management
      "create_document": _handle_create_document,
      "open_document": _handle_open_document,
      "save_document": _handle_save_document,
      "save_as_document": _handle_save_as_document,
      "create_document_copy": _handle_create_document_copy,
      "close_document": _handle_close_document,
      "reload_document": _handle_reload_document,
      # Content addition
      "add_paragraph": _handle_add_paragraph,
      "add_heading": _handle_add_heading,
      "add_table": _handle_add_table,
      "add_list_item": _handle_add_list_item,
      "add_image": _handle_add_image,
      "add_page_break": _handle_add_page_break,
      "add_section": _handle_add_section,
      "add_table_of_contents": _handle_add_table_of_contents,
      # Content editing
      "search_text": _handle_search_text,
      "search_and_replace": _handle_search_and_replace,
      "find_and_replace": _handle_find_and_replace,
      "replace_section": _handle_replace_section,
      "edit_section_by_keyword": _handle_edit_section_by_keyword,
      "delete_paragraph": _handle_delete_paragraph,
      "delete_text": _handle_delete_text,
      "edit_table_cell": _handle_edit_table_cell,
      # Table operations
      "add_table_row": _handle_add_table_row,
      "add_table_column": _handle_add_table_column,
      "delete_table_row": _handle_delete_table_row,
      "delete_table_column": _handle_delete_table_column,
      "merge_table_cells": _handle_merge_table_cells,
      "split_table": _handle_split_table,
      # Formatting
      "set_page_margins": _handle_set_page_margins,
      "set_page_orientation": _handle_set_page_orientation,
      "set_page_size": _handle_set_page_size,
      "set_header": _handle_set_header,
      "set_footer": _handle_set_footer,
      "set_line_spacing": _handle_set_line_spacing,
      "set_text_highlight": _handle_set_text_highlight,
      "set_text_strikethrough": _handle_set_text_strikethrough,
      "set_superscript": _handle_set_superscript,
      "set_subscript": _handle_set_subscript,
      "set_text_direction": _handle_set_text_direction,
      "add_tab_stop": _handle_add_tab_stop,
      "add_hyperlink": _handle_add_hyperlink,
      # Annotations and references
      "add_bookmark": _handle_add_bookmark,
      "add_comment": _handle_add_comment,
      "add_footnote": _handle_add_footnote,
      "add_endnote": _handle_add_endnote,
      # Query
      "get_document_info": _handle_get_document_info,
      "get_paragraph": _handle_get_paragraph,
      "get_table_cell": _handle_get_table_cell,
      "get_page_info": _handle_get_page_info,
      # Paragraph and cell modification
      "set_paragraph_text": _handle_set_paragraph_text,
      "set_paragraph_format": _handle_set_paragraph_format,
      "set_cell_format": _handle_set_cell_format,
      # P1: Paragraph spacing and indent
      "set_paragraph_spacing": _handle_set_paragraph_spacing,
      # P1: Page number
      "add_page_number": _handle_add_page_number,
      # P1: Table formatting
      "set_table_borders": _handle_set_table_borders,
      "set_cell_shading": _handle_set_cell_shading,
      # P1: Paragraph borders and shading
      "set_paragraph_border": _handle_set_paragraph_border,
      "set_paragraph_shading": _handle_set_paragraph_shading,
      # P1: Column layout
      "set_columns": _handle_set_columns,
      # P1: Style management
      "create_style": _handle_create_style,
      "modify_style": _handle_modify_style,
      "list_styles": _handle_list_styles,
  }

• server.py:1-61 (helper)

  Server setup, DocxProcessor class, global state, lifespan management, and FastMCP server creation that hosts the docx_process tool.

  """
  MCP Docx Processing Service
  Provides a single gateway tool "docx_process" that routes to document operations.
  Implemented using the official MCP library
  """
  
  import os
  import json
  import tempfile
  import time
  import logging
  from contextlib import asynccontextmanager
  from typing import AsyncIterator, Dict, Any
  
  from mcp.server.fastmcp import FastMCP, Context
  from docx import Document
  from docx.shared import Pt, RGBColor, Cm
  from docx.enum.text import WD_PARAGRAPH_ALIGNMENT, WD_LINE_SPACING, WD_COLOR_INDEX
  from docx.enum.style import WD_STYLE_TYPE
  from docx.enum.section import WD_ORIENT, WD_SECTION_START
  from docx.opc.constants import RELATIONSHIP_TYPE as RT
  from docx.oxml.ns import qn
  from docx.oxml import OxmlElement
  
  # Configure logging
  logging.basicConfig(
      level=logging.INFO,
      format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
      handlers=[
          logging.FileHandler(os.path.join(tempfile.gettempdir(), "docx_mcp_server.log")),
          logging.StreamHandler()
      ]
  )
  logger = logging.getLogger("DocxMCPServer")
  
  class DocxProcessor:
      """Class for processing Docx documents, implementing various document operations"""
  
      def __init__(self):
          self.documents = {}  # Store opened documents
          self.current_document = None
          self.current_file_path = None
  
  # Create global processor instance
  processor = DocxProcessor()
  
  @asynccontextmanager
  async def server_lifespan(server: FastMCP) -> AsyncIterator[Dict[str, Any]]:
      """Manage server lifecycle"""
      try:
          logger.info("DocxProcessor MCP server starting with clean state...")
          yield {"processor": processor}
      finally:
          logger.info("DocxProcessor MCP server shutting down...")
  
  # Create MCP server
  mcp = FastMCP(
      name="DocxProcessor",
      instructions="Word document processing service. Use the docx_process gateway tool with route and params to perform document operations. Refer to the docx-process skill for available routes and parameter details.",
      lifespan=server_lifespan
  )

• server.py:63-97 (helper)

  Helper functions (_save_paragraph_styles, _replace_paragraphs_in_range, _set_run_font, _parse_hex_color, etc.) used by the route handlers invoked via docx_process.

  # ============================================================================
  # Helper functions
  # ============================================================================
  
  def _save_paragraph_styles(doc, start_index, count):
      """Save style and format info for paragraphs in range [start_index, start_index+count)"""
      original_styles = []
      for i in range(start_index, start_index + count):
          if i < len(doc.paragraphs):
              para = doc.paragraphs[i]
              style_info = {
                  'style': para.style,
                  'alignment': para.alignment,
                  'runs': []
              }
              for run in para.runs:
                  run_info = {
                      'bold': run.bold,
                      'italic': run.italic,
                      'underline': run.underline,
                      'font_size': run.font.size,
                      'font_name': run.font.name,
                      'color': run.font.color.rgb if run.font.color.rgb else None
                  }
                  style_info['runs'].append(run_info)
              original_styles.append(style_info)
          else:
              original_styles.append(original_styles[-1] if original_styles else {
                  'style': None, 'alignment': None, 'runs': []
              })
      while len(original_styles) < count:
          original_styles.append(original_styles[-1] if original_styles else {
              'style': None, 'alignment': None, 'runs': []
          })
      return original_styles