html2pptx-mcp

用受限 HTML 契约生成原生可编辑的 PowerPoint（.pptx），并提供 MCP 服务接口。

现状：0.1.0a1 预览版——转换器、MCP 服务（5 工具）、参考 pptx 逆转与字体子集内嵌均可用。

安装

# 发布后：一行接入任意 MCP 客户端（无需克隆仓库）
uvx html2pptx-mcp

# 或 pip 安装
pip install html2pptx-mcp

为什么不是「HTML 直接转 PPT」

自由 HTML/CSS 到 PPTX 的有损转换，会让你在浏览器里看到的和交付出去的不是同一个东西。 本项目反过来：先用契约把可表达的写法收窄到能一一映射到 DrawingML 的子集，契约之外的 写法一律报错并给出可用写法，而不是静默丢弃。

产物是真正的 PPT 对象（文本框、形状、表格、图片），可以在 PowerPoint 里继续编辑，不是截图。

架构

受限 HTML --lower--> Slide IR(JSON) --emit--> .pptx
                  \-> 诊断报告（error / fix / warning，全部机器可读）

• 契约是数据：属性、标签、取值、修复规则、错误码写在 convert/data/*.json；解析器按 kind 注册， CI 双向对账，杜绝「文档说有、实现没做」。
• IR 是第二个契约：HTML 只是一个前端；发射器只认 IR，后续 native 工具 / 模板系统复用同一层。
• 单次遍历：校验与生成共用一条 lowering 路径，不会出现「校验通过但生成不一致」。

快速开始（开发）

快速开始

需要 Python 3.11+ 与 uv。

uv sync --extra dev
uv run pytest
uv run ruff check .
uv run mypy

命令行

# 校验（不读图片、不生成文件）
uv run html2pptx-cli validate examples/html/04_bad.html

# 生成单页 / 多页
uv run html2pptx-cli build examples/html/01_title.html -o out/01.pptx
uv run html2pptx-cli build examples/html/01_title.html examples/html/03_data.html \
    -o out/deck.pptx --report out/report.json

# 导出契约 / 回读产物几何
uv run html2pptx-cli contract --format json
uv run html2pptx-cli inspect out/deck.pptx

退出码：0 通过；2 存在契约错误（--strict 时警告也算失败）；1 文件或内部错误。

Python API

from pathlib import Path

from html2pptx_mcp.convert import CompileOptions, compile_html

result = compile_html(
    Path("examples/html/01_title.html").read_text(encoding="utf-8"),
    options=CompileOptions(base_dir=Path("examples/html")),
)
if result.ok:
    result.save("out/01.pptx")
else:
    for error in result.report.errors:
        print(error.code, error.message, error.hint)

compile_html 接受单份 HTML 或多份（按顺序拼页），返回结果对象而不是抛异常； validate_html 与它共用同一次遍历，只是不执行发射。

MCP 服务

uv run html2pptx-mcp                                             # stdio（默认）
uv run html2pptx-mcp --transport streamable-http --host 127.0.0.1 --port 8000

客户端（stdio）配置：

{
  "mcpServers": {
    "ppt": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/ppt", "html2pptx-mcp"]
    }
  }
}

试用采集

python scripts/trial.py --dir <候选 HTML 目录> --json-out <报告路径>

统计一次通过率、错误码分布、自动修复条数与 token 估算。候选稿应在没跑过校验的 前提下一次性生成，否则指标失真。首轮自测见 docs/temp/trial/试用报告.md。

视觉对比

python scripts/compare_visual.py --dir tests/fixtures/review --out test/review

对每页 HTML：Edge 无头截图（基准）vs PowerPoint COM 渲染（产物），输出逐像素差异 （diff>16 占比、均值）、差异热点图与上下并排图；report.json 汇总。依赖本机 Edge 与 PowerPoint；几何与样式一致性由 pytest 冒烟保证，本脚本回答「看起来像不像」。

仓库结构

能力边界

• 不做：动画、页面切换、SmartArt、音视频、OLE；这些对象即使出现在第三方 deck 里也只 做原样保留，不编辑（打开/编辑第三方 deck 不在本阶段范围）。
• 流式布局只支持单行 flex 子集：display:flex + row/column + justify-content + align-items + gap + flex 简写（无 wrap、无 *-reverse、无嵌套文档流）；其余元素仍须绝对定位并写全盒。
• 表格是简单表：不支持合并单元格、嵌套表格；单元格只承载纯文本。
• SVG 只有三个图元：rect / circle / line；path、文本、渐变一律拒绝。
• 不读网络图片：只接受 base_dir 内的相对路径与 data:image/*;base64；URL 取图 属服务化阶段的安全项。
• 预览不是交付判据：textfit 是估算器，真实换行由 PowerPoint 决定；排版请以 PowerPoint 打开结果为准。
• 单一画布：1280×720（16:9），其他尺寸属后续扩展；一份 HTML 一页。

文档

• 注释规范
• 总体实施方案
• 阶段一施工方案

许可证

Apache-2.0，见 LICENSE。