Docx_MCP_cj

# Tool List A powerful Word document table filling system that supports intelligent analysis and precise filling of tables in any format. Based on the MCP (Model Context Protocol) protocol, it provides complete Word document table processing capabilities for AI. ## ✨ Main Features - **🎯 Coordinate Filling** - Precise table filling based on coordinates (main feature) - **🔍 Intelligent Analysis** - Automatic analysis of table structure and field positions - **🤖 AI Friendly** - MCP tool interface directly usable for AI - **📄 Universal Support** - Supports any Word table format, no hardcoding required - **🔄 Complete Workflow** - AI can complete the entire filling process autonomously - **📋 File Management** - Supports document copying, working copy creation - **💾 State Management** - Intelligent document state management and saving mechanism ## 🚀 Quick Start ### System Requirements - Python 3.8+ - Windows 10/11 (recommended) - Microsoft Word or compatible docx processing library ### Install Dependencies ```bash # Clone the project git clone <repository-url> cd docx_mcp # Install dependencies pip install -r requirements.txt ``` ### Start MCP Server ```bash python final_complete_server.py ``` The server will display: ``` Starting the final complete MCP server... Functional modules: - Basic document management (8 tools) - Intelligent document creation (1 tool) - Basic text content (4 tools) - Intelligent content processing (1 tool) - Basic table processing (5 tools) - Table structure extraction (4 tools) - Intelligent table processing (2 tools) - Intelligent planning guidance (3 tools) - Basic image processing (3 tools) - Basic page settings (3 tools) - Intelligent suggestions (1 tool) - System status (3 tools) Total: 42 tools (32 basic tools + 10 intelligent tools) ``` ## 🎯 Core Functionality ### 1. Coordinate Filling Workflow This is the core functionality of the system, providing precise table filling capabilities: ```python # 1. Analyze document structure, extract coordinate information analysis = extract_fillable_fields("Internship Identification Form.docx") # 2. Create filling plan based on analysis results fill_plan = { "Zhang San": [1, 0, 2], # Table 1, row 0, column 2 (name field right side) "2024001234": [1, 1, 2], # Table 1, row 1, column 2 (student ID field right side) "School of Computer Science": [1, 0, 4], # Table 1, row 0, column 4 (school field right side) "Software Engineering Major": [1, 0, 6], # Table 1, row 0, column 6 (major field right side) "Tencent Technology Co., Ltd.": [1, 1, 4], # Table 1, row 1, column 4 (internship unit field right side) "July 2024 - September 2024": [1, 1, 6] # Table 1, row 1, column 6 (internship period field right side) } # 3. Execute precise filling result = fill_with_coordinates("Internship Identification Form.docx", fill_plan) ``` ### 2. Intelligent Analysis Function The system will automatically analyze the document structure, identifying: - Field names and positions - Fillable empty position coordinates - Filling rules and suggestions - AI judgment guidance information ### 3. File Management Function ```python # Create document copy copy_document("Original Document.docx", "Working Copy.docx") # Create working copy create_work_copy("Internship Identification Form.docx", "_Filled Version") ``` ## 📋 Complete MCP Tool List ### Basic Document Management (8 tools) - `create_document()` - Create new document - `open_document()` - Open existing document - `save_document()` - Save current document - `save_as_document()` - Save as document - `copy_document()` - Copy document file - `create_work_copy()` - Create working copy - `close_document()` - Close document - `get_document_info()` - Get document information ### Table Processing Tools (13 tools) - `extract_fillable_fields()` - Extract fillable field coordinates - `fill_with_coordinates()` - Execute precise coordinate filling - `basic_table_fill()` - Basic table filling - `intelligent_table_fill()` - Intelligent filling guidance - `add_table()` - Add table - `add_table_row()` - Add table row - `add_table_column()` - Add table column - `format_table()` - Format table - `merge_table_cells()` - Merge table cells - `extract_table_structure()` - Extract table structure - `extract_all_tables_structure()` - Extract all table structures ### Content Processing Tools (9 tools) - `add_paragraph()` - Add paragraph - `add_heading()` - Add heading - `add_text_with_formatting()` - Add formatted text - `search_and_replace()` - Search and replace - `smart_add_content()` - Intelligent add content - `intelligent_create_document()` - Intelligent create document - `intelligent_create_table()` - Intelligent create table ### Other Tools (12 tools) - `add_image()` - Add image - `extract_images()` - Extract images - `resize_image()` - Resize image - `set_page_margins()` - Set page margins - `set_page_orientation()` - Set page orientation - `set_page_size()` - Set page size - `get_smart_suggestions()` - Get intelligent suggestions - `get_system_status()` - Get system status - `test_connection()` - Test connection - `get_server_info()` - Get server information ## 📊 System Advantages ### ✅ Precise Control - Based on 3D coordinate system `(table index, row index, column index)` - 100% precise filling position control - Supports intelligent processing of merged cells ### ✅ Strong Universality - Supports any Word table format - No need for hardcoded field mapping - Automatic recognition of table structure and field type ### ✅ AI Friendly - Provides MCP tool interface directly usable for AI - Intelligent filling suggestions and AI judgment guidance - Clear workflow and error handling ### ✅ Easy to Use - Simple three-step workflow: analysis → planning → filling - Detailed usage instructions and examples - Complete error handling and logging ### ✅ High Reliability - Intelligent document state management - Automatic file locking processing - Complete saving and restoring mechanism ## 🔧 Technical Architecture ### Core Components ``` docx_mcp/ ├── core/ # Core components │ ├── intelligent_table_analyzer.py # Intelligent table analyzer │ ├── universal_table_filler.py # Universal table filler │ ├── table_structure_extractor.py # Table structure extractor │ ├── intelligent_tool_planner.py # Intelligent tool planner │ ├── smart_suggestion_engine.py # Smart suggestion engine │ ├── enhanced_state_manager.py # Enhanced state manager │ ├── ai_guidance_enhancer.py # AI guidance enhancer │ ├── workflow_engine.py # Workflow engine │ ├── template_engine.py # Template engine │ ├── json_validation_engine.py # JSON validation engine │ ├── font_processor.py # Font processor │ ├── image_processor.py # Image processor │ ├── oss_processor.py # OSS processor │ ├── file_path_utils.py # File path utilities │ ├── fixed_docx_processor.py # Fixed docx processor │ ├── enhanced_docx_processor.py # Enhanced docx processor │ ├── ai_interface.py # AI interface │ ├── docx_processor.py # docx processor │ ├── state_machine.py # State machine │ ├── state_manager.py # State manager │ └── models.py # Data models ├── templates/ # Template files │ └── academic/ # Academic templates │ └── academic_paper_simple.json # Academic paper simple template ├── tests/ # Test files │ ├── test_universal_table_filler.py # Universal table filler test │ ├── test_intelligent_analyzer.py # Intelligent analyzer test │ ├── test_table_structure_extractor.py # Table structure extractor test │ ├── test_intelligent_tool_planner.py # Intelligent tool planner test │ ├── test_smart_suggestion_engine.py # Smart suggestion engine test │ ├── test_enhanced_state_manager.py # Enhanced state manager test │ ├── test_ai_guidance_enhancer.py # AI guidance enhancer test │ ├── test_workflow_engine.py # Workflow engine test │ ├── test_template_engine.py # Template engine test │ ├── test_json_validation_engine.py # JSON validation engine test │ ├── test_font_processor.py # Font processor test │ ├── test_image_processor.py # Image processor test │ ├── test_oss_processor.py # OSS processor test │ └── test_integration.py # Integration test ├── docs/ # Test documents │ ├── Attachment 7:岭南师范学院毕业（生产）实习鉴定表A3打印.docx │ ├── Attachment 11:岭南师范学院专业实习优秀实习生登记表.docx │ └── ... (other test documents) ├── final_complete_server.py # Main MCP server ├── requirements.txt # Dependency file ├── pyproject.toml # Project configuration ├── README.md # Project description ├── LICENSE # License └── COMPREHENSIVE_PROJECT_DOCUMENTATION.md # Comprehensive project documentation ``` ### Data Flow ``` Document input → Structure analysis → Field recognition → Coordinate extraction → Filling plan → Precise filling → Document saving ↓ ↓ ↓ ↓ ↓ ↓ ↓ .docx → Table structure → Field position → 3D coordinates → Filling plan → Content writing → Saving completed ``` ## 🎯 Usage Example ### Example 1: Filling Internship Identification Form ```python # 1. Open document open_document("Internship Identification Form.docx") # 2. Analyze document structure analysis = extract_fillable_fields("Internship Identification Form.docx") print("Field coordinates:", analysis['field_coordinates']) print("Filling suggestions:", analysis['fill_suggestions']) # 3. Create filling plan fill_plan = { "Zhang San": [1, 0, 2], # Name "2024001234": [1, 1, 2], # Student ID "School of Computer Science": [1, 0, 4], # School "Software Engineering Major 2021 Class 1": [1, 0, 6], # Major and class "Tencent Technology Co., Ltd.": [1, 1, 4], # Internship unit "July 2024 - September 2024": [1, 1, 6] # Internship period } # 4. Execute filling result = fill_with_coordinates("Internship Identification Form.docx", fill_plan) print("Filling result:", result) # 5. Save document save_document() ``` ### Example 2: Intelligent Filling ```python # Use intelligent filling function (automatically match fields) fill_data = { "Name": "Zhang San", "Student ID": "2024001234", "School": "School of Computer Science", "Major": "Software Engineering", "Internship Unit": "Tencent Technology Co., Ltd.", "Internship Period": "July 2024 - September 2024" } result = basic_table_fill("Internship Identification Form.docx", fill_data) print("Intelligent filling result:", result) ``` ### Example 3: Document Management ```python # Create document copy copy_result = copy_document( "Original Document.docx", "Working Copy.docx" ) # Create working copy work_copy = create_work_copy( "Internship Identification Form.docx", "_Filled Version" ) # Open working copy open_document("Internship Identification Form_Filled Version.docx") # Perform filling operation... # Save and close save_document() close_document() ``` ## 🔍 Coordinate System Description ### 3D Coordinate Format - **Format**: `[table index, row index, column index]` - **Table index**: Starts from 0, representing the index of the table in the document - **Row index**: Starts from 0, representing the row index in the table - **Column index**: Starts from 0, representing the column index in the table ### Filling Rules 1. **Field right side filling**: Field values are usually filled on the right side of the field name, i.e., `(z, x, y+1)` 2. **Field below filling**: In some cases, fill below the field name, i.e., `(z, x+1, y)` 3. **AI judgment guidance**: The system provides AI judgment guidance to help decide whether to overwrite existing content ### Example Coordinates ```python # Basic information filling for Table 1 "Zhang San": [1, 0, 2], # Name field right side "School of Computer Science": [1, 0, 4], # School field right side "2024001234": [1, 1, 2], # Student ID field right side "Tencent Technology Co., Ltd.": [1, 1, 4] # Internship unit field right side ``` ## 🛠️ Development Guide ### Add New Filling Rules 1. Modify `_generate_fill_rules` method in `core/intelligent_table_analyzer.py` 2. Add new filling logic in `core/universal_table_filler.py` 3. Update test files to verify new functionality ### Extend MCP Tools 1. Add new tool functions in `final_complete_server.py` 2. Use `@mcp.tool()` decorator to register tools 3. Update `available_tools` list ### Run Tests ```bash # Run all tests python -m pytest tests/ # Run specific tests python tests/test_universal_table_filler.py python tests/test_intelligent_analyzer.py # Run integration test python tests/test_integration.py ``` ## 📚 Detailed Documentation View the following documents for more information: - [COMPREHENSIVE_PROJECT_DOCUMENTATION.md](COMPREHENSIVE_PROJECT_DOCUMENTATION.md) - Comprehensive project documentation - [PROJECT_SUMMARY.md](PROJECT_SUMMARY.md) - Project summary - [INTELLIGENT_PLANNING_GUIDE.md](INTELLIGENT_PLANNING_GUIDE.md) - Intelligent planning guide - [TOOL_USAGE_GUIDE.md](TOOL_USAGE_GUIDE.md) - Tool usage guide ## 🐛 Troubleshooting ### Common Issues 1. **Document locked** ```bash # Solution: Close document and reopen close_document() open_document("Document.docx") ``` 2. **Filling position error** ```bash # Solution: Check coordinate format, ensure using [table index, row index, column index] ``` 3. **MCP tool not registered** ```bash # Solution: Restart MCP server python final_complete_server.py ``` ### Debug Mode ```bash # Enable detailed logging export LOG_LEVEL=DEBUG python final_complete_server.py ``` ## 🤝 Contribution Guide ### How to Contribute 1. Fork project 2. Create feature branch (`git checkout -b feature/AmazingFeature`) 3. Commit changes (`git commit -m 'Add some AmazingFeature'`) 4. Push to branch (`git push origin feature/AmazingFeature`) 5. Open Pull Request ### Code Style - Use Python 3.8+ syntax - Follow PEP 8 code style - Add appropriate type annotations - Write unit tests - Update documentation ## 📄 License This project uses MIT License - See [LICENSE](LICENSE) file for details. ## 🙏 Acknowledgments - [python-docx](https://github.com/python-openxml/python-docx) - Word document processing library - [FastMCP](https://github.com/pydantic/fastmcp) - MCP protocol implementation - [pydantic](https://github.com/pydantic/pydantic) - Data validation library ## 📞 Support If you encounter issues or have suggestions: 1. Check [Troubleshooting](#-troubleshooting) section 2. Search existing [Issues](../../issues) 3. Create new Issue describing your problem 4. Contact maintainers --- **Note**: This is a powerful table filling system designed for AI and automation scenarios. Please ensure you understand the system's functionality and limitations before using.