Docx 转 HTML 转换工具 - MCP 服务

服务介绍

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

核心优势：

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

功能特性

依赖环境

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

依赖安装命令：

pip install fastmcp python-docx

服务配置（Server Config）

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

# 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 键值对，建议在部署前配置完成：

使用示例

1. 基础使用（默认输出路径）

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

2. 自定义输出路径

# 先修改底层函数调用，指定 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 清理（保留原始标签）

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 服务创建流程，系统将自动解析最新配置