# docx2html-mcp

**Repository Path**: isycr/docx2html-mcp

## Basic Information

- **Project Name**: docx2html-mcp
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-18
- **Last Updated**: 2025-11-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Docx 转 HTML 转换工具 - MCP 服务

## 服务介绍
本 MCP 服务基于 FastMCP 框架开发，提供 **Docx 文件到 HTML 的自动化转换功能**，支持完整保留 Docx 文档中的格式信息（包括字体样式、段落布局、表格结构及合并单元格等），并输出可直接使用的标准 HTML 内容。

核心优势：
- **格式高保真**：精准提取 Docx 中的字体大小/颜色/粗细、段落对齐/行距/缩进、表格边框/背景色/合并单元格等样式，无信息丢失
- **自动化处理**：无需手动配置格式映射，传入 Docx 文件路径即可自动生成 HTML，支持自定义输出路径
- **轻量易用**：提供简洁的工具函数接口，集成到业务流程中仅需一行代码调用
- **HTML 优化**：自动清理空标签、冗余样式，输出结构简洁、可维护的 HTML 内容


## 功能特性
| 功能模块         | 具体能力                                                                 |
|------------------|--------------------------------------------------------------------------|
| 文本样式转换     | 支持字体大小（pt）、字体名称、粗体/斜体/下划线/删除线、字体颜色（RGB）提取 |
| 段落样式转换     | 支持行距、段前/段后间距、首行缩进提取，保留段落结构                       |
| 表格样式转换     | 支持表格边框（宽度/颜色）、单元格背景色、单元格边距提取                   |
| 合并单元格处理   | 自动识别并保留 Docx 中的行合并（rowspan）、列合并（colspan）逻辑           |
| HTML 清理优化    | 自动删除空段落/空 span 标签、冗余样式属性，压缩标签间多余空白             |
| 输出路径灵活配置 | 支持自定义 HTML 输出路径，未指定时默认在 Docx 同目录生成同名 HTML 文件    |


## 依赖环境
运行本服务需满足以下环境依赖，系统会自动校验基础环境，缺失依赖将导致服务启动失败：

| 依赖类型         | 具体要求                                                                 |
|------------------|--------------------------------------------------------------------------|
| 运行环境         | Python 3.8+                                                              |
| 核心依赖库       | fastmcp>=2.11.0（MCP 框架）、python-docx>=1.2.0（Docx 解析）              |
| 辅助依赖库       | html（HTML 特殊字符转义）、re（正则表达式优化）、os（文件路径处理）       |

**依赖安装命令**：
```bash
pip install fastmcp python-docx
```


## 服务配置（Server Config）
本服务通过工具函数 `docxToHtml` 对外提供能力，核心配置如下（需确保配置字段完整，否则将中断 MCP 服务创建）：

```python
# 1. 服务初始化配置
from fastmcp import FastMCP
# 初始化 MCP 服务，服务名称为“演示 🚀”（可根据需求修改）
mcp = FastMCP("演示 🚀")

# 2. 核心工具函数配置（Docx 转 HTML 主逻辑）
@mcp.tool
def docxToHtml(docx_path: str) -> str:
    """
    将 Docx 文件转换为 HTML 并返回输出文件路径
    
    Args:
        docx_path: str - Docx 文件的绝对路径（必填，路径错误将返回异常）
    
    Returns:
        str - 生成的 HTML 文件绝对路径（转换成功）/ 错误信息（转换失败）
    
    示例调用：
        docxToHtml("/home/user/docs/example.docx")
        # 返回："/home/user/docs/example.html"（转换成功）
    """
    return docx_to_html(docx_path)  # 调用底层转换逻辑（详见代码实现）

# 3. 底层转换函数配置（docx_to_html）
def docx_to_html(docx_path, output_file=None, clean=True):
    """
    底层 Docx 转 HTML 处理函数，支持自定义输出路径和 HTML 清理
    
    Args:
        docx_path: str - Docx 文件路径（必填）
        output_file: str | None - 自定义 HTML 输出路径（可选，默认同目录同名）
        clean: bool - 是否清理冗余 HTML 标签（可选，默认 True）
    
    Returns:
        str - HTML 输出路径
    """
    # 具体实现逻辑：解析 Docx 元素→转换为 HTML 标签→优化输出（详见代码）
```


## 环境变量配置（env）
本服务依赖以下环境变量，系统将从服务配置中自动提取 `env` 键值对，建议在部署前配置完成：

| 环境变量名          | 类型   | 说明                                                                 | 默认值                |
|---------------------|--------|----------------------------------------------------------------------|-----------------------|
| `PYTHONPATH`        | str    | Python 依赖包搜索路径，确保 fastmcp、python-docx 能被正确导入          | 系统默认 Python 路径  |
| `DOCX_CONVERT_LOG`  | str    | 转换日志输出路径，用于记录转换成功/失败信息（可选）                    | "/var/log/docx2html.log" |
| `MAX_DOCX_SIZE`     | int    | 支持转换的最大 Docx 文件大小（单位：MB），超过将拒绝转换                | 50（即 50MB）         |


## 使用示例
### 1. 基础使用（默认输出路径）
```python
# 调用 MCP 工具函数，转换 Docx 文件（默认输出到同目录）
result = docxToHtml("/data/docs/report.docx")
print(result)
# 输出："/data/docs/report.html"（转换成功）
```

### 2. 自定义输出路径
```python
# 先修改底层函数调用，指定 output_file 参数
result = docx_to_html(
    docx_path="/data/docs/report.docx",
    output_file="/data/html/report_2024.html"
)
print(result)
# 输出："/data/html/report_2024.html"（转换成功）
```

### 3. 关闭 HTML 清理（保留原始标签）
```python
result = docx_to_html(
    docx_path="/data/docs/report.docx",
    clean=False  # 不清理空标签和冗余样式
)
```


## 常见问题（FAQ）
1. **Q：转换失败，提示“文件路径不存在”？**  
   A：请检查 `docx_path` 是否为绝对路径，且文件是否存在；相对路径可能因服务运行目录不同导致找不到文件。

2. **Q：转换后的 HTML 丢失表格合并单元格？**  
   A：确保 `calculate_rowspan` 函数正常运行（代码中已处理行合并逻辑），若仍有问题，检查 Docx 表格是否为标准合并格式（非嵌套表格）。

3. **Q：字体颜色/背景色未正确显示？**  
   A：目前支持 Docx 中的标准 RGB 颜色和高亮色，若使用自定义色板，需补充 `get_inline_style` 函数中的颜色映射逻辑。

4. **Q：转换大文件（>50MB）时失败？**  
   A：可通过修改环境变量 `MAX_DOCX_SIZE` 增大支持的文件大小，例如 `export MAX_DOCX_SIZE=100`（支持 100MB）。


## 维护与更新
- **版本说明**：当前版本 V1.0，支持基础 Docx 转 HTML 功能，后续将新增“图片转换”“公式渲染”等特性
- **问题反馈**：若遇到格式丢失、转换崩溃等问题，可提交日志文件（`DOCX_CONVERT_LOG` 路径）至维护邮箱
- **更新方式**：通过 GitHub 仓库更新代码后，需重新执行 MCP 服务创建流程，系统将自动解析最新配置