Office Word MCP Server

Instructions

Implementation Reference

• word_document_server/main.py:302-307 (registration)

  Registration of the 'add_footnote_after_text' MCP tool using @mcp.tool() decorator. This is the entry point for the tool, which delegates execution to the footnote_tools module.
  @mcp.tool() def add_footnote_after_text(filename: str, search_text: str, footnote_text: str, output_filename: str = None): """Add a footnote after specific text with proper superscript formatting. This enhanced function ensures footnotes display correctly as superscript.""" return footnote_tools.add_footnote_after_text(filename, search_text, footnote_text, output_filename)
• word_document_server/tools/footnote_tools.py:243-277 (handler)

  Direct handler function called by the registered tool. Performs file existence and writability checks, then delegates to the core robust implementation with position='after'.
  async def add_footnote_after_text(filename: str, search_text: str, footnote_text: str, output_filename: Optional[str] = None) -> str: """Add a footnote after specific text in a Word document with proper formatting. This enhanced function ensures proper superscript formatting by managing styles at the XML level. Args: filename: Path to the Word document search_text: Text to search for (footnote will be added after this text) footnote_text: Content of the footnote output_filename: Optional output filename (if None, modifies in place) """ filename = ensure_docx_extension(filename) 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, search_text=search_text, footnote_text=footnote_text, output_filename=output_filename, position="after", 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 (handler)

  Core implementation performing the actual footnote addition via direct DOCX XML manipulation. Handles search or index location, inserts proper footnote reference with superscript styling, adds content, manages footnotes.xml, styles, relationships, and saves the modified document.
  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