Office Word MCP Server

Instructions

Implementation Reference

• word_document_server/main.py:141-144 (registration)

  MCP tool registration using @mcp.tool() decorator. Delegates to the content_tools handler.

  @mcp.tool()
  def insert_numbered_list_near_text(filename: str, target_text: str = None, list_items: list = None, position: str = 'after', target_paragraph_index: int = None, bullet_type: str = 'bullet'):
      """Insert a bulleted or numbered list before or after the target paragraph. Specify by text or paragraph index. Args: filename (str), target_text (str, optional), list_items (list of str), position ('before' or 'after'), target_paragraph_index (int, optional), bullet_type ('bullet' for bullets or 'number' for numbered lists, default: 'bullet')."""
      return content_tools.insert_numbered_list_near_text_tool(filename, target_text, list_items, position, target_paragraph_index, bullet_type)

• word_document_server/tools/content_tools.py:467-469 (handler)

  Async handler function in content_tools that invokes the core implementation from document_utils.

  async def insert_numbered_list_near_text_tool(filename: str, target_text: str = None, list_items: list = None, position: str = 'after', target_paragraph_index: int = None, bullet_type: str = 'bullet') -> str:
      """Insert a bulleted or numbered list before or after the target paragraph. Specify by text or paragraph index."""
      return insert_numbered_list_near_text(filename, target_text, list_items, position, target_paragraph_index, bullet_type)

• word_document_server/utils/document_utils.py:337-417 (handler)

  Core implementation of the tool logic: finds target paragraph, creates list paragraphs, applies bullet/numbering via XML manipulation, inserts near target.

  def insert_numbered_list_near_text(doc_path: str, target_text: str = None, list_items: list = None, position: str = 'after', target_paragraph_index: int = None, bullet_type: str = 'bullet') -> str:
      """
      Insert a bulleted or numbered list before or after the target paragraph. Specify by text or paragraph index. Skips TOC paragraphs in text search.
      Args:
          doc_path: Path to the Word document
          target_text: Text to search for in paragraphs (optional if using index)
          list_items: List of strings, each as a list item
          position: 'before' or 'after' (default: 'after')
          target_paragraph_index: Optional paragraph index to use as anchor
          bullet_type: 'bullet' for bullets (•), 'number' for numbers (1,2,3) (default: 'bullet')
      Returns:
          Status message
      """
      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
          # Determine numbering ID based on bullet_type
          num_id = 1 if bullet_type == 'bullet' else 2
  
          # Use ListParagraph style for proper list formatting
          style_name = None
          for candidate in ['List Paragraph', 'ListParagraph', 'Normal']:
              try:
                  _ = doc.styles[candidate]
                  style_name = candidate
                  break
              except KeyError:
                  continue
          if not style_name:
              style_name = None  # fallback to default
  
          new_paras = []
          for item in (list_items or []):
              p = doc.add_paragraph(item, style=style_name)
              # Add bullet numbering XML - this is the fix!
              add_bullet_numbering(p, num_id=num_id, level=0)
              new_paras.append(p)
          # Move the new paragraphs to the correct position
          for p in reversed(new_paras):
              if position == 'before':
                  para._element.addprevious(p._element)
              else:
                  para._element.addnext(p._element)
          doc.save(doc_path)
          list_type = "bulleted" if bullet_type == 'bullet' else "numbered"
          if anchor_index is not None:
              return f"{list_type.capitalize()} list with {len(new_paras)} items inserted {position} paragraph (index {anchor_index})."
          else:
              return f"{list_type.capitalize()} list with {len(new_paras)} items inserted {position} the target paragraph."
      except Exception as e:
          return f"Failed to insert numbered list: {str(e)}"

• word_document_server/utils/document_utils.py:298-335 (helper)

  Helper function to add bullet or numbering formatting to paragraphs using direct XML manipulation.

  def add_bullet_numbering(paragraph, num_id=1, level=0):
      """
      Add bullet/numbering XML to a paragraph.
  
      Args:
          paragraph: python-docx Paragraph object
          num_id: Numbering definition ID (1=bullets, 2=numbers, etc.)
          level: Indentation level (0=first level, 1=second level, etc.)
  
      Returns:
          The modified paragraph
      """
      # Get or create paragraph properties
      pPr = paragraph._element.get_or_add_pPr()
  
      # Remove existing numPr if any (to avoid duplicates)
      existing_numPr = pPr.find(qn('w:numPr'))
      if existing_numPr is not None:
          pPr.remove(existing_numPr)
  
      # Create numbering properties element
      numPr = OxmlElement('w:numPr')
  
      # Set indentation level
      ilvl = OxmlElement('w:ilvl')
      ilvl.set(qn('w:val'), str(level))
      numPr.append(ilvl)
  
      # Set numbering definition ID
      numId = OxmlElement('w:numId')
      numId.set(qn('w:val'), str(num_id))
      numPr.append(numId)
  
      # Add to paragraph properties
      pPr.append(numPr)
  
      return paragraph