Skip to main content
Glama

ppt-word-gen

AI 驱动的可编辑 PPTX 与标准化 Word 仿真测试报告生成服务
单一轻量服务在同一端口提供 MCP (Model Context Protocol) Server、REST API 与 Web Demo。


🚀 MCP (Model Context Protocol) 服务

ppt-word-gen 原生实现标准 MCP 协议(支持 Streamable HTTP 与 STDIO 双传输通道),赋能各类 Agent 客户端(如 Claude Code, Claude Desktop, Cursor, Cline, OpenWebUI 等)自主完成文档格式提取、用户确认、异步排队生成、语义多轮修订与安全文件下载。

1. 客户端接入配置 (.mcp.json)

项目根目录已内置 .mcp.json,Agent 工具打开本目录即可自动发现并加载服务。

方式 A:HTTP 传输模式(推荐,适用于容器部署 / 局域网服务 / 本机服务)

在项目根目录创建或编辑 .mcp.json:

{
  "mcpServers": {
    "ppt-word-gen": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

若服务开启了 Bearer Token 鉴权(配置了 PPT_WORD_GEN_TOKEN),可添加请求头:

{
  "mcpServers": {
    "ppt-word-gen": {
      "type": "http",
      "url": "http://YOUR_SERVER_IP:8000/mcp",
      "headers": {
        "Authorization": "Bearer ${PPT_WORD_GEN_TOKEN}"
      }
    }
  }
}

使用 Claude Code CLI 一键注册:

# 项目级注册(写入当前目录 .mcp.json)
claude mcp add --transport http --scope project ppt-word-gen http://127.0.0.1:8000/mcp

# 用户全局注册
claude mcp add --transport http --scope user ppt-word-gen http://127.0.0.1:8000/mcp

方式 B:STDIO 传输模式(本机免起 HTTP 端口直接调用)

在客户端配置中直接通过 Python 进程启动:

{
  "mcpServers": {
    "ppt-word-gen": {
      "command": "python",
      "args": ["-m", "ppt_word_gen.mcp_stdio"]
    }
  }
}

2. MCP 核心协作工作流

[用户输入 / 来源资料 / 模板]
             │
             ▼
[可选:upload_file / create_upload_ticket 暂存来源文件与 Word 模板]
             │
             ▼
[preview_word_report_format 提取模板默认格式(字体、字号、行距、多级标题、编号规范)]
             │
             ▼
[向用户展示预览并获取确认 ➔ 获得绑定格式哈希的 confirmation_token]
             │
             ▼
[generate_presentation / generate_word_report 发起异步生成任务]
             │
             ▼
[wait_generation_task / get_generation_task 轮询进度状态]
             │
             ▼
[get_artifact 获取 24 小时有效的安全签名 ResourceLink 下载链接]
             │
             ▼
[可选:revise_presentation / revise_word_report 进行多轮语义增量修订]

3. MCP 工具全集(15 个 Tools)

工具名称

功能描述

关键参数

list_generation_profiles

列出可生成的文档类型、支持格式与二进制上传约定

无

preview_word_report_format

提取模板默认格式(或内置模板)并应用修改;返回格式信息与 confirmation_token

template_upload_id, custom_format

generate_presentation

创建可编辑 PPTX 异步生成任务

prompt, format, source_upload_ids, model 等

generate_word_report

提交 Word 报告任务(必须携带 confirmation_token)

title, report_type, confirmation_token, source_upload_ids

get_generation_task

查询 PPT 或 Word 异步任务的阶段、百分比进度、错误与产物状态

task_id, task_type

wait_generation_task

最长等待 55 秒,任务完成立即返回,超时则返回最新状态

task_id, task_type, timeout_seconds

cancel_generation_task

请求取消尚未结束的异步生成任务

task_id, task_type

get_artifact

任务完成后获取带标准 ResourceLink 的 24 小时安全签名下载直链

task_id, task_type

upload_file

Base64 内联上传小文件(不超过 5MB)

filename, content_base64, purpose

create_upload_ticket

为大文件创建一次性 PUT 上传地址(避免大内容占用 Agent 上下文)

filename, purpose, max_bytes

list_business_templates

列出内置与企业自定义的 PPT/Word 业务规范模板

无

register_business_template

注册企业业务内容与风格规范模板

template_id, name, spec

delete_business_template

删除自定义业务模板(内置模板受保护不可删除)

template_id

revise_presentation

将已有 PPTX 作为上下文,按自然语言指令生成新版本

parent_task_id, revision_prompt

revise_word_report

用户确认格式后,将已有 DOCX 作为基础增量生成新版本

parent_task_id, confirmation_token, revision_instructions

4. MCP 规则与资产资源(4 个 Resources)

Agent 可直接读取规范指南与设计约束:

  • ppt-word://rules/workflow:MCP 完整交互与格式确认规范

  • ppt-word://rules/presentation:PPT Master 设计与排版规范

  • ppt-word://rules/word-report:仿真与工程 Word 报告排版标准

  • ppt-word://templates/catalog:业务模板目录与规范速查


Related MCP server: Formatix AI MCP Server

📁 项目结构

ppt-word-gen/
├── ppt_word_gen/              # Python 核心业务包
│   ├── app.py                 # FastAPI 入口(Demo、REST API、MCP Streamable HTTP)
│   ├── mcp_server.py          # MCP Server 实现(15 工具、4 资源、双向协议)
│   ├── mcp_stdio.py           # MCP STDIO 运行入口
│   ├── tasks.py               # PPT 异步任务队列与状态机
│   ├── report_tasks.py        # Word 异步任务队列与状态机
│   ├── report_agent.py        # Word 报告生成 Agent
│   ├── report_documents.py    # Word 文档排版、格式继承与 GBK 修复引擎
│   ├── word_format.py         # Word 格式解析、修改与防篡改 Token 校验
│   ├── signed_tokens.py       # HMAC-SHA256 签名下载与上传票据
│   ├── pptmaster.py           # PPT Master 脚本适配与执行
│   ├── upload_store.py        # 临时文件上传与生命周期管理
│   ├── task_store.py          # SQLite 持久化任务存储
│   └── config.py              # 全局配置读取
├── assets/word_templates/     # 内置 Word 模板(CID629 电驱系统联合仿真 v1.5)
├── skills/ai-simulation-report/# 仿真报告标准契约与校验规则
├── static/                    # 前端 Web Demo 页面
├── tests/                     # 41 项单元测试与集成测试
├── Dockerfile                 # 容器构建文件(支持联网/离线两种模式)
├── docker-compose.yml         # 生产/测试容器编排配置
├── build-overlay.ps1          # 企业级解密与离线 wheel 构建脚本
├── requirements.txt           # 依赖清单
├── .env.example               # 环境变量参考模板
└── .mcp.json                  # MCP 配置文件

💻 本地快速启动

1. 安装依赖与执行测试

# 安装依赖
python -m pip install -r requirements.txt

# 运行全套 41 项自动化测试
python -m unittest discover -s tests -v

2. 启动服务

# 启动 HTTP + MCP 服务(默认监听 0.0.0.0:8000)
python -m ppt_word_gen
  • Web Demo 页面:http://127.0.0.1:8000/demo

  • OpenAPI 交互文档:http://127.0.0.1:8000/docs

  • MCP HTTP 端点:http://127.0.0.1:8000/mcp

  • 健康检查:http://127.0.0.1:8000/health


🐳 Docker / WSL 容器化部署

1. 标准部署

在 Ubuntu / WSL 终端中:

cd /path/to/ppt-word-gen
cp .env.example .env.compose

# 按需修改 .env.compose(接入真实模型时设置 MOCK_LLM=0 并填写 API Key)
sudo service docker start
docker compose --env-file .env.compose up -d --build --wait

2. 企业离线 Wheel 构建

在具备企业数据防泄露(DLP)或内网隔离的环境下,在 Windows PowerShell 中执行:

pwsh ./build-overlay.ps1

该脚本将自动通过文件流安全复制并调用 OFFLINE_INSTALL=1 进行本地 Wheel 离线构建。

3. 服务状态检查与停止

# 查看容器状态与健康指标
docker compose ps
curl http://127.0.0.1:8000/health

# 停止容器(数据保留在 ppt-word-gen-data 卷中)
docker compose stop

⚙️ 环境变量说明

复制 .env.example 为 .env 或 .env.compose:

变量名

默认值

说明

LLM_BASE_URL

https://dashscope.aliyuncs.com/compatible-mode/v1

OpenAI 兼容接口 Base URL

LLM_API_KEY

无

大语言模型 API Key

LLM_MODEL

qwen3.7-plus

默认创作模型名称

MOCK_LLM

1

1 无需 API Key 即可全流程自测演示;接入真实模型改为 0

PPT_WORD_GEN_TOKEN

留空

Bearer Token 鉴权,留空则无需认证

PUBLIC_BASE_URL

http://127.0.0.1:8000

产物下载与大文件上传的基础 URL(局域网调用请设为服务器内网 IP)

DOWNLOAD_SIGNING_SECRET

留空(自动生成)

HMAC 签名密钥,用于生成 24 小时临时下载凭证

MAX_CONCURRENT_TASKS

2

PPT 最大并发处理任务数

MAX_CONCURRENT_REPORT_TASKS

1

Word 最大并发处理任务数

MCP_INLINE_UPLOAD_MB

5

MCP Base64 内联上传上限(MB)

MAX_UPLOAD_MB

20

REST / 大文件 Ticket 上传上限(MB)


🔌 核心 REST API

请求方法

路径

描述

GET

/health

服务健康检查(含 SQLite 存储与任务队列状态)

GET

/demo

内置 Web 演示页面

GET

/api/v1/word-format

获取内置 Word 模板默认格式及确认 Token

POST

/api/v1/word-format

提取自定义模板格式、应用修改并生成确认 Token

POST

/api/v1/report-tasks

提交 Word 仿真/技术报告生成任务

GET

/api/v1/report-tasks/{id}

查询 Word 报告任务进度与详情

GET

/api/v1/report-tasks/{id}/result

下载生成的 DOCX 报告

POST

/api/v1/tasks

提交 PPT 演示文稿生成任务

GET

/api/v1/tasks/{id}

查询 PPT 任务进度与详情

GET

/api/v1/tasks/{id}/result

下载生成的 PPTX 文件

POST

/api/v1/uploads

暂存二进制来源文件或模板

PUT

/api/v1/upload-tickets/{token}

一次性大文件直传接口

GET

/api/v1/artifacts/{token}

24 小时 HMAC 签名安全下载接口

POST

/mcp

MCP Streamable HTTP 协议端点


📄 开源许可

本项目遵循 MIT License。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers