Enhanced Word Document Server

smithery badge

A powerful, consolidated Model Context Protocol (MCP) server for creating, reading, and manipulating Microsoft Word documents (.docx). This enhanced version registers 25 tools for comprehensive Word document operations through a standardized interface.

Overview

Enhanced-Word-MCP-Server implements the Model Context Protocol with a focus on comprehensive document operations. It registers 25 tools, including:

• Session management for multi-document workflows
• Consolidated operations for better usability
• Enhanced functionality with regex support and advanced formatting
• Academic and professional workflow optimization
• Comprehensive error handling and validation

Example Usage

Creating Academic Documents

# Create document with proper structure
create_document("thesis.docx", title="AI in Healthcare", author="John Doe")

# Add structured content
add_text_content("thesis.docx", "Introduction", content_type="heading", level=1)
add_text_content("thesis.docx", "This paper explores...", content_type="paragraph")

# Footnotes/endnotes are not supported by python-docx and are disabled in this server.

Features Overview

🎯 Consolidated Tools (6 Tools)

Unified operations that replace multiple individual functions:

• get_text - Unified text extraction (replaces 3 tools)
• manage_track_changes - Track changes management (replaces 2 tools)
• add_note - Footnote/endnote tool (currently disabled; python-docx limitation)
• add_text_content - Paragraph/heading creation (replaces 2 tools)
• get_sections - Section extraction (replaces 2 tools)
• manage_protection - Document protection (replaces 2 tools)

📄 Essential Document Tools (7 Tools)

Core document management functionality:

• Document Lifecycle: create_document, copy_document, merge_documents
• Content Operations: enhanced_search_and_replace, add_table, add_picture
• Export: convert_to_pdf

🔧 Advanced Features (6 Tools)

Specialized functionality for professional workflows:

• Collaboration: manage_comments, extract_track_changes, generate_review_summary
• Document Structure: generate_table_of_contents
• Security: add_digital_signature, verify_document

Key Enhancements

🚀 Enhanced Search & Replace

• Regex support for complex pattern matching
• Case-insensitive search options
• Whole word matching
• Advanced formatting application to replaced text
• Group substitutions for regex patterns

# Regex date format conversion
enhanced_search_and_replace("doc.docx", 
    find_text=r"(\d{4})-(\d{2})-(\d{2})", 
    replace_text=r"$2/$3/$1", 
    use_regex=True)

# Case-insensitive formatting
enhanced_search_and_replace("doc.docx", 
    find_text="important", 
    replace_text="CRITICAL",
    match_case=False, 
    apply_formatting=True, 
    bold=True, color="red")

📝 Unified Text Extraction

# Extract full document with formatting
get_text("doc.docx", scope="all", include_formatting=True)

# Search within document
get_text("doc.docx", scope="search", search_term="methodology", match_case=False)

# Extract specific paragraph
get_text("doc.docx", scope="paragraph", paragraph_index=5)

📑 Flexible Section Management

# Extract all sections with formatting
get_sections("doc.docx", mode="overview", include_formatting=True)

# Get specific section content
get_sections("doc.docx", mode="content", section_title="Results")

🔒 Advanced Protection Management

# Password protection
manage_protection("doc.docx", action="protect", protection_type="password", password="secure123")

# Restricted editing with editable sections (metadata + optional encryption depending on environment)
manage_protection("doc.docx", action="protect", protection_type="restricted",
                 password="review123", editable_sections=["Introduction", "Conclusion"])

Installation

NPX Installation (Recommended)

# Install via NPX (latest version)
npx enhanced-word-mcp-server

# Or install globally
npm install -g enhanced-word-mcp-server

Python Dependencies

The server requires Python 3.10+ with the following dependencies:

# Install Python dependencies (including MCP with CLI support)
pip install mcp[cli] python-docx msoffcrypto-tool docx2pdf

# Or install from requirements.txt if cloning the repository
pip install -r requirements.txt

Add to Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "word-mcp": {
      "command": "npx",
      "args": ["enhanced-word-mcp-server"]
    }
  }
}

Manual Installation

# Clone repository
git clone https://github.com/your-username/enhanced-word-mcp-server.git
cd enhanced-word-mcp-server

# Install dependencies
npm install

# Global installation
npm install -g .

Usage Examples

Academic Writing Workflow

# Create research paper structure
create_document("research_paper.docx", title="Machine Learning Analysis", author="Dr. Smith")

# Add structured content
add_text_content("research_paper.docx", "Abstract", content_type="heading", level=1)
add_text_content("research_paper.docx", "This study examines...", content_type="paragraph", 
                style="Normal", position="end")

# Footnotes/endnotes are disabled (python-docx limitation). Insert notes manually in Word if needed.

# Format academic terms
format_research_paper_terms("research_paper.docx")

# Extract structure for review
sections = get_sections("research_paper.docx", mode="overview", max_level=2)

Document Review Workflow

# Extract review elements
comments = manage_comments("draft.docx", action="list")  # list-only (legacy in-text markers)
changes = extract_track_changes("draft.docx")

# Generate comprehensive review summary
summary = generate_review_summary("draft.docx")

# Manage track changes selectively
manage_track_changes("draft.docx", action="accept", change_type="insertions")
manage_track_changes("draft.docx", action="reject", change_type="deletions", author="Reviewer1")

Document Security Workflow

# Apply comprehensive protection
manage_protection("confidential.docx", action="protect", 
                 protection_type="password", password="secure123")

# Add digital signature
add_digital_signature("contract.docx", signer_name="John Doe", 
                     reason="Document approval")

# Verify document integrity
verification = verify_document("contract.docx")

Tool Reference

Consolidated Tools

get_text(filename, scope, **options)

Unified text extraction with multiple modes:

• scope: "all" | "paragraph" | "search" | "range"
• include_formatting: Extract formatting information
• search_term: Text to search for (when scope="search")
• paragraph_index: Specific paragraph (when scope="paragraph")

manage_track_changes(filename, action, **filters)

Comprehensive track changes management:

• action: "accept" | "reject" | "extract"
• change_type: "all" | "insertions" | "deletions" | "formatting"
• author: Filter by specific author
• date_range: Filter by date range

add_note(...)

Footnotes/endnotes are disabled in this server (python-docx limitation). Insert notes manually in Word.

add_text_content(filename, text, content_type, **options)

Unified content creation:

• content_type: "paragraph" | "heading"
• level: Heading level (1-6)
• style: Apply document style
• position: "beginning" | "end" | "before" | "after"

get_sections(filename, mode, **options)

Advanced section extraction:

• mode: "overview" | "content"
• section_title: Optional section to target
• max_level: Maximum heading level
• output_format: "text" | "json"

manage_protection(filename, action, protection_type, **options)

Document protection management:

• action: "protect" | "unprotect" | "verify" | "status"
• protection_type: "password" | "restricted" | "signature"
• password: Protection password
• editable_sections: Section names editable under restricted mode

Safety Guardrails

enhanced_search_and_replace and get_text(scope="search") apply configurable limits to avoid runaway searches, oversized responses, and memory pressure:

• EW_MAX_MATCHES_PER_CALL (default 1000)
• EW_MAX_SEARCH_OUTPUT_CHARS (default 200000)
• EW_MAX_REGEX_PATTERN_CHARS (default 5000)
• EW_MAX_REGEX_SCAN_CHARS (default 2000000)
• EW_MAX_DOC_BYTES_PER_OPERATION (default 50000000)
• EW_MAX_UNDO_BYTES_TOTAL (default 200000000)
• EW_LONG_SESSION_OP_LIMIT (default 2000)
• EW_REGEX_TIMEOUT_MS (default 0; if set and timeout runtime is unavailable, operation is refused explicitly)

When limits are hit, tools return explicit guardrail codes/messages, including:

• LIMIT_EXCEEDED
• REGEX_COMPLEXITY_BLOCKED
• DOC_TOO_LARGE
• UNDO_BUDGET_EXCEEDED
• SESSION_CONSISTENCY_WARNING

Mutation-heavy operations use fail-before-mutate semantics for preflight guardrail failures.

Session Consistency Contract

• Disk path is authoritative for document state.
• document_id is a routing alias to file paths.
• In-memory session metadata is advisory and may lag; tools read from file paths each call.

Error Handling

All tools provide comprehensive error handling:

# Typical error responses
{
  "status": "error",
  "message": "Document not found: nonexistent.docx",
  "error_type": "FileNotFoundError",
  "suggestions": ["Check file path", "Ensure file exists"]
}

Development

Project Structure

enhanced-word-mcp-server/
├── word_document_server/
│   ├── main.py              # MCP server entry point
│   ├── tools/               # Tool implementations
│   │   ├── document_tools.py      # Document management
│   │   ├── content_tools.py       # Content creation
│   │   ├── review_tools.py        # Review and collaboration
│   │   ├── section_tools.py       # Document structure
│   │   ├── protection_tools.py    # Security features
│   │   └── footnote_tools.py      # Notes and references
│   └── utils/               # Utility modules
├── bin/
│   └── enhanced-word-mcp-server.js  # NPX entry point
├── package.json
└── README.md

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

Testing

# Run test suite
python test_enhanced_features.py
pytest -q -m "not stress"

# Run only end-to-end MCP stdio tests
pytest -q -m e2e

# Run stress/performance/soak tier (nightly/manual)
pytest -q -m stress --durations=30

# Test specific functionality
python -c "from word_document_server.tools.content_tools import enhanced_search_and_replace; print(enhanced_search_and_replace('test.docx', 'old', 'new'))"

License

MIT License - see LICENSE file for details.

Version History

v2.0.0 (Enhanced)

• 🎯 25 registered tools for comprehensive document operations
• 🚀 Enhanced search & replace with regex support
• 📝 Consolidated operations for better usability
• 🔧 Improved error handling and validation
• 📚 Comprehensive documentation with examples

v1.0.0 (Original)

• Initial release with 47 individual tools
• Basic Word document operations
• Simple MCP server implementation

Support

For issues, feature requests, or questions:

• 📧 Create an issue on GitHub
• 📖 Check the documentation and examples
• 🔍 Review error messages for troubleshooting guidance