Office Word MCP Server

Instructions

Implementation Reference

• word_document_server/main.py:316-321 (registration)

  Registration of the MCP tool 'add_footnote_enhanced' which wraps and delegates to the implementation in footnote_tools
  @mcp.tool() def add_footnote_enhanced(filename: str, paragraph_index: int, footnote_text: str, output_filename: str = None): """Enhanced footnote addition with guaranteed superscript formatting. Adds footnote at the end of a specific paragraph with proper style handling.""" return footnote_tools.add_footnote_enhanced(filename, paragraph_index, footnote_text, output_filename)
• word_document_server/tools/footnote_tools.py:317-357 (handler)

  Primary handler implementation for add_footnote_enhanced: validates inputs, checks file access, and delegates to core add_footnote_robust for XML-level footnote insertion
  async def add_footnote_enhanced(filename: str, paragraph_index: int, footnote_text: str, output_filename: Optional[str] = None) -> str: """Enhanced version of add_footnote_to_document with proper superscript formatting. Now uses the robust implementation for better reliability. Args: filename: Path to the Word document paragraph_index: Index of the paragraph to add footnote to (0-based) footnote_text: Text content of the footnote output_filename: Optional output filename (if None, modifies in place) """ filename = ensure_docx_extension(filename) # Ensure paragraph_index is an integer try: paragraph_index = int(paragraph_index) except (ValueError, TypeError): return "Invalid parameter: paragraph_index must be an integer" if not os.path.exists(filename): return f"Document {filename} does not exist" # Check if file is writeable is_writeable, error_message = check_file_writeable(filename) if not is_writeable: return f"Cannot modify document: {error_message}. Consider creating a copy first." try: # Use robust implementation success, message, details = add_footnote_robust( filename=filename, paragraph_index=paragraph_index, footnote_text=footnote_text, output_filename=output_filename, validate_location=True ) return message except Exception as e: return f"Failed to add footnote: {str(e)}"
• word_document_server/core/footnotes.py:283-490 (helper)

  Core helper function performing low-level DOCX XML manipulation to create proper footnotes: handles namespaces, creates styles (FootnoteReference, FootnoteText), ensures relationships and content types, inserts references and content safely avoiding conflicts.
  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