Office Word MCP Server

Instructions

Implementation Reference

• word_document_server/main.py:364-371 (registration)

  MCP tool registration for 'delete_footnote_robust'. This decorated function registers the tool and serves as the entry point, delegating to the async handler in footnote_tools.
  @mcp.tool() def delete_footnote_robust(filename: str, footnote_id: int = None, search_text: str = None, clean_orphans: bool = True): """Delete footnote with comprehensive cleanup and orphan removal. Ensures complete removal from document.xml, footnotes.xml, and relationships.""" return footnote_tools.delete_footnote_robust_tool( filename, footnote_id, search_text, clean_orphans )
• word_document_server/tools/footnote_tools.py:525-577 (handler)

  Primary async handler function for the delete_footnote_robust tool. Handles input validation, file checks, and delegates to core implementation.
  async def delete_footnote_robust_tool( filename: str, footnote_id: Optional[int] = None, search_text: Optional[str] = None, clean_orphans: bool = True ) -> Dict[str, Any]: """ Delete a footnote with comprehensive cleanup. Args: filename: Path to the Word document footnote_id: ID of footnote to delete search_text: Text near footnote reference clean_orphans: Whether to remove orphaned content 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 footnote_id if provided as string if footnote_id is not None: try: footnote_id = int(footnote_id) except (ValueError, TypeError): return { "success": False, "message": "Invalid parameter: footnote_id must be an integer", "details": None } # Call robust implementation success, message, details = delete_footnote_robust( filename=filename, footnote_id=footnote_id, search_text=search_text, clean_orphans=clean_orphans ) return { "success": success, "message": message, "details": details }
• word_document_server/core/footnotes.py:492-611 (helper)

  Core helper function implementing the actual DOCX XML manipulation: removes footnote references, content, cleans orphans, and rewrites the ZIP archive.
  def delete_footnote_robust( filename: str, footnote_id: Optional[int] = None, search_text: Optional[str] = None, output_filename: Optional[str] = None, clean_orphans: bool = True ) -> Tuple[bool, str, Optional[Dict[str, Any]]]: """Delete a footnote with comprehensive cleanup.""" if not footnote_id and not search_text: return False, "Must provide either footnote_id or search_text", 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 with zipfile.ZipFile(filename, 'r') as zin: doc_xml = zin.read('word/document.xml') if 'word/footnotes.xml' not in zin.namelist(): return False, "No footnotes in document", None footnotes_xml = zin.read('word/footnotes.xml') # Parse documents doc_root = etree.fromstring(doc_xml) footnotes_root = etree.fromstring(footnotes_xml) nsmap = {'w': W_NS} # Find footnote to delete if search_text: # Find footnote reference near text 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: # Look for footnote reference in this paragraph fn_refs = para.xpath('.//w:footnoteReference', namespaces=nsmap) if fn_refs: footnote_id = int(fn_refs[0].get(f'{{{W_NS}}}id')) break if not footnote_id: return False, f"No footnote found near text '{search_text}'", None # Remove footnote reference from document refs_removed = 0 for fn_ref in doc_root.xpath(f'//w:footnoteReference[@w:id="{footnote_id}"]', namespaces=nsmap): # Remove the entire run containing the reference run = fn_ref.getparent() if run is not None and run.tag == f'{{{W_NS}}}r': para = run.getparent() if para is not None: para.remove(run) refs_removed += 1 if refs_removed == 0: return False, f"Footnote {footnote_id} not found", None # Remove footnote content content_removed = 0 for fn in footnotes_root.xpath(f'//w:footnote[@w:id="{footnote_id}"]', namespaces=nsmap): footnotes_root.remove(fn) content_removed += 1 # Clean orphans if requested orphans_removed = [] if clean_orphans: # Find all referenced IDs referenced_ids = set() for ref in doc_root.xpath('//w:footnoteReference', namespaces=nsmap): ref_id = ref.get(f'{{{W_NS}}}id') if ref_id: referenced_ids.add(ref_id) # Remove unreferenced footnotes (except separators) for fn in footnotes_root.xpath('//w:footnote', namespaces=nsmap): fn_id = fn.get(f'{{{W_NS}}}id') if fn_id and fn_id not in referenced_ids and fn_id not in ['-1', '0']: footnotes_root.remove(fn) orphans_removed.append(fn_id) # 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: for item in zin.infolist(): if item.filename == 'word/document.xml': zout.writestr(item, etree.tostring(doc_root, encoding='UTF-8', xml_declaration=True, standalone="yes")) elif item.filename == 'word/footnotes.xml': zout.writestr(item, etree.tostring(footnotes_root, encoding='UTF-8', xml_declaration=True, standalone="yes")) else: zout.writestr(item, zin.read(item.filename)) os.replace(temp_file, working_file) details = { 'footnote_id': footnote_id, 'references_removed': refs_removed, 'content_removed': content_removed, 'orphans_removed': orphans_removed } message = f"Successfully deleted footnote {footnote_id}" if orphans_removed: message += f" and {len(orphans_removed)} orphaned footnotes" return True, message, details except Exception as e: return False, f"Error deleting footnote: {str(e)}", None