docx-mcp 0.1.4
DOCX MCP处理器 - 完整的Word文档处理工具，支持图片编辑和表格操作
License: MIT
Requires Python: >=3.8
Keywords: docx, word, document, mcp, ai-tools, document-processing, image-processing, font-management

# 增强版DOCX MCP处理器

一个功能完整、模块化设计的Word文档处理系统，基于MCP（Model Context Protocol）协议，为AI工具提供强大的文档操作能力。

## 🌟 主要特性

### 1. 架构优势
- **模块化设计**: 功能清晰分离，易于维护和扩展
- **MCP协议**: 标准化的AI工具接口，兼容性好
- **状态管理**: 支持会话持久化，用户体验好
- **异步支持**: 使用FastMCP框架，性能优秀

### 2. 功能完整性
- **全面的文档操作**: 涵盖创建、编辑、格式化等全流程
- **丰富的表格功能**: 支持复杂的表格操作
- **图片处理**: 插入、删除、缩放、定位
- **字体管理**: 完整的字体样式控制
- **智能搜索替换**: 支持预览模式，减少误操作
- **格式保持**: 替换内容时保持原有格式

### 3. 可靠性
- **异常处理**: 每个函数都有完善的错误处理
- **日志记录**: 详细的操作日志，便于调试
- **状态恢复**: 服务重启后自动恢复工作状态
- **参数验证**: 严格的输入参数检查

### 4. 易用性
- **清晰的API**: 函数命名直观，参数明确
- **详细的文档**: 每个函数都有完整的docstring
- **错误提示**: 友好的错误信息，便于用户理解
- **交互模式**: 支持命令行交互，便于测试和调试

## 📋 功能清单

### A. 文档生命周期管理
- `create_document()` - 创建新的Word文档
- `open_document()` - 打开现有文档
- `save_document()` - 保存到原文件
- `save_as_document()` - 保存为新文件
- `close_document()` - 关闭文档
- `create_document_copy()` - 创建文档副本

### B. 内容编辑功能
- `add_paragraph()` - 添加段落，支持丰富格式
- `add_heading()` - 添加各级标题
- `add_page_break()` - 添加分页符
- `delete_paragraph()` - 删除段落

### C. 表格操作功能
- `add_table()` - 创建表格
- `add_table_row()` - 添加行
- `delete_table_row()` - 删除行
- `edit_table_cell()` - 编辑单元格
- `merge_table_cells()` - 合并单元格

### D. 图片处理功能
- `add_image()` - 插入图片，支持尺寸和位置控制
- `resize_image()` - 调整图片大小
- `delete_image()` - 删除图片
- `list_images()` - 列出所有图片信息

### E. 字体和格式化功能
- `set_paragraph_font()` - 设置段落字体样式
- `set_text_range_font()` - 设置文本范围字体
- `get_font_info()` - 获取字体信息
- `batch_format_paragraphs()` - 批量格式化段落

### F. 文本处理功能
- `search_text()` - 全文搜索
- `find_and_replace()` - 查找替换

### G. 页面设置功能
- `set_page_margins()` - 设置页边距

## 🚀 快速开始

### 安装依赖

```bash
pip install -r requirements_enhanced.txt
```

### 运行方式

#### 1. MCP服务器模式（推荐）
```bash
python enhanced_main.py
```

#### 2. 交互式模式
```bash
python enhanced_main.py --interactive
```

#### 3. 详细日志模式
```bash
python enhanced_main.py --verbose
```

### 基本使用示例

#### MCP工具调用示例
```python
# 通过MCP协议调用
{
    "tool": "create_document",
    "arguments": {
        "file_path": "/path/to/new_document.docx"
    }
}

{
    "tool": "add_paragraph",
    "arguments": {
        "text": "这是一个测试段落",
        "font_size": 12,
        "font_name": "微软雅黑",
        "bold": true
    }
}

{
    "tool": "add_image",
    "arguments": {
        "image_path": "/path/to/image.jpg",
        "width": "10cm",
        "alignment": "center"
    }
}
```

#### 交互式命令示例
```bash
docx> create test.docx
文档创建成功: test.docx

docx> addp "这是第一个段落"
段落添加成功

docx> addh "章节标题" 1
添加了 1 级标题

docx> addtable 3 3
添加了 3x3 表格

docx> addimg photo.jpg
图片已添加: photo.jpg

docx> save
文档保存成功: test.docx
```

## 🏗️ 架构设计

### 核心模块

#### 1. `EnhancedDocxProcessor` - 主处理器
- 整合所有功能模块
- 提供统一的API接口
- 管理文档状态

#### 2. `StateManager` - 状态管理器
- 处理文档会话持久化
- 管理当前文档状态
- 支持多文档管理

#### 3. `ImageProcessor` - 图片处理器
- 图片插入、删除、缩放
- 位置控制和格式化
- 支持多种图片格式

#### 4. `FontProcessor` - 字体处理器
- 字体样式管理
- 文本格式化
- 批量样式应用

#### 5. `enhanced_server.py` - MCP服务器
- 基于FastMCP框架
- 提供完整的MCP工具集
- 异步处理和错误管理

### 模块关系图

```
enhanced_server.py (MCP接口层)
    ↓
EnhancedDocxProcessor (主处理器)
    ├── StateManager (状态管理)
    ├── ImageProcessor (图片处理)
    ├── FontProcessor (字体处理)
    └── DocxProcessor (原有核心功能)
```

## 🔧 配置选项

### 日志配置
- 日志文件位置: `%TEMP%/enhanced_docx_processor.log`
- 支持控制台和文件双重输出
- 可配置日志级别

### 状态持久化
- 状态文件位置: `%TEMP%/docx_mcp_current_doc.txt`
- 自动保存当前文档状态
- 服务重启后自动恢复

## 🔍 高级功能

### 1. 上下文管理器
```python
with processor.document_context("document.docx") as proc:
    proc.add_paragraph("临时操作")
    # 自动管理文档状态
```

### 2. 批量操作
```python
# 批量格式化段落
processor.batch_format_paragraphs(0, 10, font_name="宋体", font_size=12)
```

### 3. 图片精确控制
```python
# 添加图片并精确控制尺寸和位置
processor.add_image("image.jpg", width="5cm", height="3cm", alignment="center")
```

### 4. 智能搜索替换
```python
# 搜索并预览替换结果
result = processor.search_text("关键词")
result = processor.find_and_replace("旧文本", "新文本")
```

## 🐛 调试和日志

### 启用详细日志
```bash
python enhanced_main.py --verbose
```

### 查看日志文件
- Windows: `%TEMP%/enhanced_docx_processor.log`
- Linux/Mac: `/tmp/enhanced_docx_processor.log`

### 常见问题排查
1. **文档打开失败**: 检查文件路径和权限
2. **图片添加失败**: 确认图片文件存在且格式支持
3. **字体设置无效**: 确认字体名称正确且系统已安装
4. **状态恢复失败**: 检查临时目录权限

## 📈 性能优化

### 1. 内存管理
- 自动清理不使用的文档对象
- 支持大文档的分块处理

### 2. 异步处理
- 基于FastMCP的异步架构
- 非阻塞的文档操作

### 3. 缓存机制
- 文档状态缓存
- 样式信息缓存

## 🔄 升级和兼容性

### 从原版升级
1. 安装新依赖: `pip install -r requirements_enhanced.txt`
2. 使用新的启动脚本: `python enhanced_main.py`
3. 原有API完全兼容，无需修改调用代码

### 向后兼容
- 保持所有原有API接口
- 支持原有的配置文件格式
- 兼容原有的文档格式

## 📝 开发指南

### 添加新功能
1. 在相应的处理器模块中添加功能
2. 在`EnhancedDocxProcessor`中添加代理方法
3. 在`enhanced_server.py`中添加MCP工具
4. 更新文档和测试

### 代码规范
- 遵循PEP 8编码规范
- 使用类型提示
- 添加完整的docstring
- 包含错误处理和日志记录

## 📄 许可证

本项目采用MIT许可证，详见LICENSE文件。

## 🤝 贡献

欢迎提交Issue和Pull Request来改进项目！

---

**增强版DOCX MCP处理器** - 让AI更好地处理Word文档！