Office Word MCP Server

Instructions

Implementation Reference

• word_document_server/main.py:347-356 (registration)

  MCP tool registration for 'add_footnote_robust' that proxies to the implementation in footnote_tools
  @mcp.tool() def add_footnote_robust(filename: str, search_text: str = None, paragraph_index: int = None, footnote_text: str = "", validate_location: bool = True, auto_repair: bool = False): """Add footnote with robust validation and Word compliance. This is the production-ready version with comprehensive error handling.""" return footnote_tools.add_footnote_robust_tool( filename, search_text, paragraph_index, footnote_text, validate_location, auto_repair )
• word_document_server/tools/footnote_tools.py:462-522 (handler)

  Primary tool handler that validates inputs and delegates to core footnote addition logic
  async def add_footnote_robust_tool( filename: str, search_text: Optional[str] = None, paragraph_index: Optional[int] = None, footnote_text: str = "", validate_location: bool = True, auto_repair: bool = False ) -> Dict[str, Any]: """ Add a footnote with robust validation and error handling. This is the production-ready version with comprehensive Word compliance. Args: filename: Path to the Word document search_text: Text to search for (mutually exclusive with paragraph_index) paragraph_index: Index of paragraph (mutually exclusive with search_text) footnote_text: Content of the footnote validate_location: Whether to validate placement restrictions auto_repair: Whether to attempt automatic document repair Returns: Dict with success status, message, and optional details """ filename = ensure_docx_extension(filename) # Check if file is writeable is_writeable, error_message = check_file_writeable(filename) if not is_writeable: return { "success": False, "message": f"Cannot modify document: {error_message}", "details": None } # Convert paragraph_index if provided as string if paragraph_index is not None: try: paragraph_index = int(paragraph_index) except (ValueError, TypeError): return { "success": False, "message": "Invalid parameter: paragraph_index must be an integer", "details": None } # Call robust implementation success, message, details = add_footnote_robust( filename=filename, search_text=search_text, paragraph_index=paragraph_index, footnote_text=footnote_text, validate_location=validate_location, auto_repair=auto_repair ) return { "success": success, "message": message, "details": details }
• word_document_server/core/footnotes.py:283-490 (handler)

  Core implementation performing low-level XML manipulation of DOCX ZIP parts to add compliant Word footnotes, including relationships, styles, and validation
  def add_footnote_robust( filename: str, search_text: Optional[str] = None, paragraph_index: Optional[int] = None, footnote_text: str = "", output_filename: Optional[str] = None, position: str = "after", validate_location: bool = True, auto_repair: bool = False ) -> Tuple[bool, str, Optional[Dict[str, Any]]]: """ Add a footnote with robust validation and error handling. This is the main production-ready function with all fixes applied. """ # Validate inputs if not search_text and paragraph_index is None: return False, "Must provide either search_text or paragraph_index", None if search_text and paragraph_index is not None: return False, "Cannot provide both search_text and paragraph_index", None if not os.path.exists(filename): return False, f"File not found: {filename}", None # Set working file working_file = output_filename if output_filename else filename if output_filename and filename != output_filename: import shutil shutil.copy2(filename, output_filename) try: # Read document parts doc_parts = {} with zipfile.ZipFile(filename, 'r') as zin: doc_parts['document'] = zin.read('word/document.xml') doc_parts['content_types'] = zin.read('[Content_Types].xml') doc_parts['document_rels'] = zin.read('word/_rels/document.xml.rels') # Read or create footnotes.xml if 'word/footnotes.xml' in zin.namelist(): doc_parts['footnotes'] = zin.read('word/footnotes.xml') else: doc_parts['footnotes'] = _create_minimal_footnotes_xml() # Read styles if 'word/styles.xml' in zin.namelist(): doc_parts['styles'] = zin.read('word/styles.xml') else: # Create minimal styles doc_parts['styles'] = b'<?xml version="1.0" encoding="UTF-8" standalone="yes"?><w:styles xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"/>' # Parse XML documents doc_root = etree.fromstring(doc_parts['document']) footnotes_root = etree.fromstring(doc_parts['footnotes']) styles_root = etree.fromstring(doc_parts['styles']) # Find target location nsmap = {'w': W_NS} if search_text: # Search for text in paragraphs found = False for para in doc_root.xpath('//w:p', namespaces=nsmap): para_text = ''.join(para.xpath('.//w:t/text()', namespaces=nsmap)) if search_text in para_text: target_para = para found = True break if not found: return False, f"Text '{search_text}' not found in document", None else: # Use paragraph index paragraphs = doc_root.xpath('//w:p', namespaces=nsmap) if paragraph_index >= len(paragraphs): return False, f"Paragraph index {paragraph_index} out of range", None target_para = paragraphs[paragraph_index] # Validate location if requested if validate_location: # Check if paragraph is in header/footer parent = target_para.getparent() while parent is not None: if parent.tag in [f'{{{W_NS}}}hdr', f'{{{W_NS}}}ftr']: return False, "Cannot add footnote in header/footer", None parent = parent.getparent() # Get safe footnote ID footnote_id = _get_safe_footnote_id(footnotes_root) # Add footnote reference to document if position == "after": # Find last run in paragraph or create one runs = target_para.xpath('.//w:r', namespaces=nsmap) if runs: last_run = runs[-1] # Insert after last run insert_pos = target_para.index(last_run) + 1 else: insert_pos = len(target_para) else: # before # Find first run with text runs = target_para.xpath('.//w:r[w:t]', namespaces=nsmap) if runs: first_run = runs[0] insert_pos = target_para.index(first_run) else: insert_pos = 0 # Create footnote reference run ref_run = etree.Element(f'{{{W_NS}}}r') # Add run properties with superscript rPr = etree.SubElement(ref_run, f'{{{W_NS}}}rPr') rStyle = etree.SubElement(rPr, f'{{{W_NS}}}rStyle') rStyle.set(f'{{{W_NS}}}val', 'FootnoteReference') # Add footnote reference fn_ref = etree.SubElement(ref_run, f'{{{W_NS}}}footnoteReference') fn_ref.set(f'{{{W_NS}}}id', str(footnote_id)) # Insert the reference run target_para.insert(insert_pos, ref_run) # Add footnote content new_footnote = etree.Element(f'{{{W_NS}}}footnote', attrib={f'{{{W_NS}}}id': str(footnote_id)} ) # Add paragraph to footnote fn_para = etree.SubElement(new_footnote, f'{{{W_NS}}}p') # Add paragraph properties pPr = etree.SubElement(fn_para, f'{{{W_NS}}}pPr') pStyle = etree.SubElement(pPr, f'{{{W_NS}}}pStyle') pStyle.set(f'{{{W_NS}}}val', 'FootnoteText') # Add the footnote reference marker marker_run = etree.SubElement(fn_para, f'{{{W_NS}}}r') marker_rPr = etree.SubElement(marker_run, f'{{{W_NS}}}rPr') marker_rStyle = etree.SubElement(marker_rPr, f'{{{W_NS}}}rStyle') marker_rStyle.set(f'{{{W_NS}}}val', 'FootnoteReference') marker_ref = etree.SubElement(marker_run, f'{{{W_NS}}}footnoteRef') # Add space after marker space_run = etree.SubElement(fn_para, f'{{{W_NS}}}r') space_text = etree.SubElement(space_run, f'{{{W_NS}}}t') space_text.set(f'{{{XML_NS}}}space', 'preserve') space_text.text = ' ' # Add footnote text text_run = etree.SubElement(fn_para, f'{{{W_NS}}}r') text_elem = etree.SubElement(text_run, f'{{{W_NS}}}t') text_elem.text = footnote_text # Append footnote to footnotes.xml footnotes_root.append(new_footnote) # Ensure styles exist _ensure_footnote_styles(styles_root) # Ensure coherence content_types_xml = _ensure_content_types(doc_parts['content_types']) document_rels_xml = _ensure_document_rels(doc_parts['document_rels']) # Write modified document temp_file = working_file + '.tmp' with zipfile.ZipFile(temp_file, 'w', zipfile.ZIP_DEFLATED) as zout: with zipfile.ZipFile(filename, 'r') as zin: # Copy unchanged files for item in zin.infolist(): if item.filename not in [ 'word/document.xml', 'word/footnotes.xml', 'word/styles.xml', '[Content_Types].xml', 'word/_rels/document.xml.rels' ]: zout.writestr(item, zin.read(item.filename)) # Write modified files zout.writestr('word/document.xml', etree.tostring(doc_root, encoding='UTF-8', xml_declaration=True, standalone="yes")) zout.writestr('word/footnotes.xml', etree.tostring(footnotes_root, encoding='UTF-8', xml_declaration=True, standalone="yes")) zout.writestr('word/styles.xml', etree.tostring(styles_root, encoding='UTF-8', xml_declaration=True, standalone="yes")) zout.writestr('[Content_Types].xml', content_types_xml) zout.writestr('word/_rels/document.xml.rels', document_rels_xml) # Replace original with temp file os.replace(temp_file, working_file) details = { 'footnote_id': footnote_id, 'location': 'search_text' if search_text else 'paragraph_index', 'styles_created': ['FootnoteReference', 'FootnoteText'], 'coherence_verified': True } return True, f"Successfully added footnote (ID: {footnote_id}) to {working_file}", details except Exception as e: # Clean up temp file if exists temp_file = working_file + '.tmp' if os.path.exists(temp_file): os.remove(temp_file) return False, f"Error adding footnote: {str(e)}", None