lzwcai-mcp-server-package/lzwcai_mcpskills_generate_reports/README.md

lzwcai-mcpskills-generate-reports

用户提供 docx 模板 + JSON 数据，本包负责渲染成 docx，并可选做样式迁移。

本包不内置模板，模板完全由调用方维护。

安装

cd lzwcai_mcpskills_generate_reports
pip install -e .

Python API

核心入口 generate / scan_template

from lzwcai_mcpskills_generate_reports import generate, scan_template

# 扫描模板需要哪些占位符 / for / if 块
result = scan_template("./模板.docx")          # 本地路径或 http/https URL

# 渲染
out_path = generate(
    data="data.json",              # dict 或 JSON 文件路径
    template="./模板.docx",        # 本地路径或 http/https URL（自动下载）
    out_path="_out/报价方案.docx",
    style_ref="./用户样式.docx",   # 可选：把用户模板的 theme/字体套过来
)

便捷封装 main 模块

main 模块在核心入口之上做了两点增强，适合程序化调用：

1. data 除 dict / 本地 JSON 路径外，还支持 JSON 文件 URL（自动下载、用完即删）。
2. out 可省略；省略时落到当前目录 _out/，文件名按 模板名_时间戳.docx 自动生成。

from lzwcai_mcpskills_generate_reports.main import generate_report, scan_report

# data 传 dict，out 省略 -> 默认 _out/ 下自动命名
generate_report(template="./模板.docx", data={...})

# data 传本地 JSON 路径
generate_report(template="./模板.docx", data="data.json", out="_out/a.docx")

# template / data 都传 URL
generate_report(
    template="https://host/模板.docx",
    data="https://host/data.json",
)

# 扫描占位符，支持本地路径或 URL
scan_report(template="https://host/模板.docx")

generate_report 返回 {"output": 输出文件绝对路径}。

扫描结果结构

# scan_template / scan_report 返回：
# {
#   "placeholders": ["project_title", "contact_person", "equipments", ...],
#   "blocks": [
#       {"type": "for", "iterator": "eq", "variable": "equipments"},
#       {"type": "if", "condition": "show_layout"},
#       ...
#   ]
# }

MCP Server

本包同时提供 MCP Server（stdio 模式），把渲染引擎暴露成 2 个 MCP 工具：

工具	说明	参数
generate_report	模板 + 数据 → 渲染输出 docx，返回输出文件绝对路径	必填 template、data；可选 out（省略落到 _out/ 自动命名）、style_ref
scan_template	扫描模板占位符与 for/if 块结构	必填 template

其中 data 既可以传 JSON 对象，也可以传指向 JSON 文件的路径或 URL 字符串；template 支持本地路径或 http/https URL。数据契约校验由 generate_report 内部自动完成（不合法会报错）。

启动

# 安装后用 console script 启动
lzwcai-mcpskills-generate-reports

# 或以模块方式运行
python -m lzwcai_mcpskills_generate_reports.server

MCP 客户端配置示例

{
  "mcpServers": {
    "generate-reports": {
      "command": "lzwcai-mcpskills-generate-reports"
    }
  }
}

stdio 模式下 stdout 被 MCP 协议占用，所有日志写入 logs/ 目录与 stderr。

环境变量

变量	默认	说明
LOG_LEVEL	INFO	日志级别（DEBUG/INFO/WARNING/ERROR/CRITICAL）。
LZWCAI_INSECURE_SSL	关闭	设为 1/true/yes 时，下载模板/数据/图片关闭 SSL 证书校验。仅用于内网自签名证书等可信场景，生产慎用。

数据契约（QuoteData）

{
  "project_title": "大米罐装线",
  "contact_person": "张经理",
  "contact_phone": "138-0000-0000",
  "requirements": ["要求1", "要求2"],
  "layout_image": "",
  "layout_title": "整线布局尺寸图",
  "equipments": [
    {
      "index": "四",
      "name": "自动理瓶机",
      "images": [""],
      "features": [{"title": "特点", "lines": ["说明"]}],
      "params": [{"k": "材料", "v": "不锈钢"}]
    }
  ],
  "quote_items": [
    {"name": "设备名", "qty": "一套", "image": "", "desc": "说明", "price": "面议"}
  ]
}

• 必填顶层字段：project_title、contact_person、contact_phone、requirements。
• requirements 传列表会自动拼成多行字符串。
• equipments[].index 省略时自动从"四"起按中文数字补全（前三章固定为公司简介 / 客户要求 / 布局图）。
• params[].v 允许为 0、空串等合法假值；仅当键缺失或值为 null 才算缺失。
• 图片字段约定：路径/URL → 真实图；"" → 默认占位图；None → 不显示。

目录结构

lzwcai_mcpskills_generate_reports/
├── pyproject.toml
├── README.md
├── main.py                                # 使用本包的示例脚本（仓库根，非包内）
├── templates/                             # 用户模板（示例，不在包内）
│   └── standard/
│       ├── template.docx
│       └── meta.json
├── samples/                               # 示例数据（不在包内）
│   └── sample_data.json
└── lzwcai_mcpskills_generate_reports/     # Python 包
    ├── __init__.py                        # 公共 API 入口
    ├── main.py                            # 程序化便捷封装（URL data / out 可省略）
    ├── server.py                          # MCP Server (stdio)
    ├── pipeline.py                        # 总入口
    ├── schema.py                          # 数据契约 + 校验器
    ├── render_quote.py                    # 渲染引擎
    ├── style_transfer.py                  # 样式迁移
    ├── template_scanner.py                # 模板占位符扫描
    └── utils/                             # 下载 / 日志等工具

模板约定

• 使用 Jinja2 语法写占位符，如 {{ project_title }}、{% for eq in equipments %}。
• 模板文件旁的 meta.json（可选）声明图片字段宽度，例如：

{
  "image_fields": {
    "layout_image":          {"width_mm": 160},
    "equipments[].images[]": {"width_mm": 120},
    "quote_items[].image":   {"width_mm": 30}
  }
}

• BUSINESS 逻辑（内置模板维护、模板市场等）交给包外的上层系统处理。