Office Word MCP Server

Instructions

Implementation Reference

• word_document_server/tools/extended_document_tools.py:41-63 (handler)

  The main asynchronous handler function for the 'find_text_in_document' tool. It validates inputs, ensures .docx extension, calls the core find_text helper, formats the result as JSON, and handles errors.
  async def find_text_in_document(filename: str, text_to_find: str, match_case: bool = True, whole_word: bool = False) -> str: """Find occurrences of specific text in a Word document. Args: filename: Path to the Word document text_to_find: Text to search for in the document match_case: Whether to match case (True) or ignore case (False) whole_word: Whether to match whole words only (True) or substrings (False) """ filename = ensure_docx_extension(filename) if not os.path.exists(filename): return f"Document {filename} does not exist" if not text_to_find: return "Search text cannot be empty" try: result = find_text(filename, text_to_find, match_case, whole_word) return json.dumps(result, indent=2) except Exception as e: return f"Failed to search for text: {str(e)}"
• word_document_server/main.py:810-816 (registration)

  The MCP tool registration using FastMCP's @mcp.tool() decorator. This defines the tool schema via function signature and delegates execution to the handler in extended_document_tools.py.
  async def find_text_in_document(filename: str, text_to_find: str, match_case: bool = True, whole_word: bool = False): """Find occurrences of specific text in a Word document.""" return await extended_document_tools.find_text_in_document( filename, text_to_find, match_case, whole_word )
• word_document_server/utils/extended_document_utils.py:42-165 (helper)

  Core synchronous helper function implementing the text search logic across paragraphs and tables in the Word document using python-docx. Returns structured results with occurrences, counts, and context.
  def find_text(doc_path: str, text_to_find: str, match_case: bool = True, whole_word: bool = False) -> Dict[str, Any]: """ Find all occurrences of specific text in a Word document. Args: doc_path: Path to the Word document text_to_find: Text to search for match_case: Whether to perform case-sensitive search whole_word: Whether to match whole words only Returns: Dictionary with search results """ import os if not os.path.exists(doc_path): return {"error": f"Document {doc_path} does not exist"} if not text_to_find: return {"error": "Search text cannot be empty"} try: doc = Document(doc_path) results = { "query": text_to_find, "match_case": match_case, "whole_word": whole_word, "occurrences": [], "total_count": 0 } # Search in paragraphs for i, para in enumerate(doc.paragraphs): # Prepare text for comparison para_text = para.text search_text = text_to_find if not match_case: para_text = para_text.lower() search_text = search_text.lower() # Find all occurrences (simple implementation) start_pos = 0 while True: if whole_word: # For whole word search, we need to check word boundaries words = para_text.split() found = False for word_idx, word in enumerate(words): if (word == search_text or (not match_case and word.lower() == search_text.lower())): results["occurrences"].append({ "paragraph_index": i, "position": word_idx, "context": para.text[:100] + ("..." if len(para.text) > 100 else "") }) results["total_count"] += 1 found = True # Break after checking all words break else: # For substring search pos = para_text.find(search_text, start_pos) if pos == -1: break results["occurrences"].append({ "paragraph_index": i, "position": pos, "context": para.text[:100] + ("..." if len(para.text) > 100 else "") }) results["total_count"] += 1 start_pos = pos + len(search_text) # Search in tables for table_idx, table in enumerate(doc.tables): for row_idx, row in enumerate(table.rows): for col_idx, cell in enumerate(row.cells): for para_idx, para in enumerate(cell.paragraphs): # Prepare text for comparison para_text = para.text search_text = text_to_find if not match_case: para_text = para_text.lower() search_text = search_text.lower() # Find all occurrences (simple implementation) start_pos = 0 while True: if whole_word: # For whole word search, check word boundaries words = para_text.split() found = False for word_idx, word in enumerate(words): if (word == search_text or (not match_case and word.lower() == search_text.lower())): results["occurrences"].append({ "location": f"Table {table_idx}, Row {row_idx}, Column {col_idx}", "position": word_idx, "context": para.text[:100] + ("..." if len(para.text) > 100 else "") }) results["total_count"] += 1 found = True # Break after checking all words break else: # For substring search pos = para_text.find(search_text, start_pos) if pos == -1: break results["occurrences"].append({ "location": f"Table {table_idx}, Row {row_idx}, Column {col_idx}", "position": pos, "context": para.text[:100] + ("..." if len(para.text) > 100 else "") }) results["total_count"] += 1 start_pos = pos + len(search_text) return results except Exception as e: return {"error": f"Failed to search for text: {str(e)}"}
• word_document_server/utils/file_utils.py:73-85 (helper)

  Utility helper function used by the handler to ensure the filename has the .docx extension.
  def ensure_docx_extension(filename: str) -> str: """ Ensure filename has .docx extension. Args: filename: The filename to check Returns: Filename with .docx extension """ if not filename.endswith('.docx'): return filename + '.docx' return filename