ChatPPT

ChatPPT

ChatPPT 是一个用于以编程方式创建和编辑 PowerPoint，并借助 AI 的模型上下文协议（MCP）服务。ChatPPT 基于 Node.js 20+ 和 @office-kit/pptx 构建，通过标准输入输出，为 Visual Studio Code 及其他兼容 MCP 的客户端中的大模型提供安全、结构化、面向资源的 CRUD API。

---

主要功能

• 稳定的不透明 ID：每个演示文稿、幻灯片、幻灯片集合和幻灯片元素都通过稳定的 UUID 进行跟踪。
• 双重存储模型：
  • 演示文稿文件存储在 presentations/<deckId>.pptx 下。
  • 服务元数据、幻灯片集合和元素映射记录在 .chatppt/registry.json 中。
• 原子操作与一致性：所有文件写入都使用临时文件和原子重命名，防止文件部分损坏。
• 幻灯片视觉预览：使用 @office-kit/pptx-preview 将任意幻灯片渲染为 PNG 图像，供 Agent 进行视觉反馈。
• 向量化 / 批量操作：在一次工具调用中创建、更新或删除多个幻灯片或元素，以优化大模型交互。
• 丰富的元素：创建和更新文本框、预设形状（180+ 种 DrawingML 几何形状）、直线、表格、图表（柱形图、条形图、折线图、饼图、圆环图、面积图）和图像。
• 全面的字体排版与样式：自定义字体、字号、粗体、斜体、文本颜色、填充、边框 / 描边、对齐方式和 z-index 排序。

---

在 VS Code 中安装和配置

选项 1：工作区 MCP 配置（.vscode/mcp.json）

若要在 VS Code 工作区中使用 ChatPPT，请在工作区根目录下添加或更新 .vscode/mcp.json：

{
  "servers": {
    "chatppt": {
      "type": "stdio",
      "command": "node",
      "args": ["${workspaceFolder}/dist/index.js"]
    }
  }
}

选项 2：已发布的软件包或通过 npx 执行

通过 npx 或已发布的二进制文件运行时，可使用 --workspace 标志或环境变量，将 ChatPPT 配置为指向特定工作区：

{
  "servers": {
    "chatppt": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@jparkerdiamond/chatppt", "--workspace", "${workspaceFolder}"]
    }
  }
}

随包提供的 Agent 技能

npm 软件包包含便于移植的 create-deck-skeleton Agent 技能，位于 skills/create-deck-skeleton/SKILL.md。MCP 客户端连接到服务时不会自动加载 Agent 技能。若要使用该技能，请将此目录安装或复制到 Agent 宿主支持的技能发现位置，例如 .github/skills/、.agents/skills/ 或 .claude/skills/。该技能使用 ChatPPT 的 MCP 工具，不依赖特定操作系统或编辑器。

---

工作区行为与安全边界

ChatPPT 会按以下优先级顺序解析确定的工作区根目录：

1. 命令行参数：--workspace <path> 或 -w <path>
2. 环境变量：CHATPPT_WORKSPACE_ROOT 或 WORKSPACE_ROOT
3. 回退选项：process.cwd()（当前工作目录）

管理的文件和目录

• 演示文稿：<workspace>/presentations/<deckId>.pptx
• 注册表和元数据：<workspace>/.chatppt/registry.json

安全与信任边界

• 路径隔离：严格检查所有演示文稿路径、临时写入缓冲区和图像元素路径，确保它们位于配置的工作区内。
• 路径遍历防护：演示文稿 ID 必须匹配 ^[a-zA-Z0-9_-]+$。若绝对路径或试图通过相对路径（..）遍历到工作区根目录之外，将被检测到并以 ValidationError 拒绝。

---

已知限制

• 加密演示文稿：检测到加密或受密码保护的 .pptx 演示文稿时会拒绝处理。
• 母版 / 主题布局创作：创建幻灯片时使用演示文稿模板内置的布局；从头创建自定义幻灯片母版主题的功能将推迟到 1.0 之后。

---

可用的 MCP 工具

演示文稿管理（deck_*）

• deck_create：创建新的空白演示文稿。
• deck_import：将现有 PowerPoint 文件导入托管工作区，并登记其幻灯片。
• deck_list：列出工作区中的所有托管演示文稿。
• deck_read：读取演示文稿的元数据及幻灯片／集合列表。
• deck_update：更新演示文稿元数据（标题），并可选择进行乐观修订检查（expectedRevision）。
• deck_delete：永久删除演示文稿及其 .pptx 文件。
• deck_validate：对 PPTX 内容和注册表元数据运行诊断不变量检查。

幻灯片管理（slide_*）

• slide_create：批量添加一张或多张幻灯片（支持 title 和 notes）。
• slide_list：按演示顺序列出幻灯片，position 索引从 0 开始。
• slide_read：读取幻灯片元数据及其元素列表。
• slide_render：将幻灯片渲染为 PNG 图像预览，以便进行视觉反馈。可选参数 width 表示像素宽度，默认值为 1280，并返回 MCP image 内容项。
• slide_update：批量更新幻灯片标题和演讲者备注。
• slide_delete：永久删除幻灯片并清理集合引用。
• slide_move：移动幻灯片，或通过提供 slideOrder 数组重新排序。
• slide_duplicate：复制幻灯片，并为幻灯片及其所有元素分配新的稳定 ID。

幻灯片集合管理（slide_collection_*）

• slide_collection_create：创建由现有幻灯片组成的命名有序分组。
• slide_collection_list：列出演示文稿中的集合。
• slide_collection_read：读取集合详情和幻灯片成员。
• slide_collection_update：重命名集合或替换幻灯片成员。
• slide_collection_delete：删除集合，但不删除幻灯片。

幻灯片元素管理（element_*）

• element_create：批量创建文本框、预设形状、线条、表格、图表或图像（可选支持 clientId 关联）。
• element_list：按 z-index 顺序列出幻灯片上的所有元素。
• element_read：读取元素元数据和样式属性。
• element_update：批量更新位置、大小、文本、填充、字体、字号、粗体、斜体、文本颜色、描边和对齐方式。
• element_delete：批量删除幻灯片元素。
• element_reorder：调整元素的 z-index（bringToFront、sendToBack、bringForward、sendBackward）。

渲染幻灯片预览

使用演示文稿和幻灯片的 UUID 调用 slide_render。响应中包含 base64 编码的 image/png 内容项，MCP 客户端可直接显示：

{
  "deckId": "<deck UUID>",
  "slideId": "<slide UUID>",
  "width": 1280
}

渲染器可确定性地近似 PowerPoint 输出，并在 Node.js 中运行，无需无头浏览器。

---

开发与测试

前提条件

• Node.js >= 20
• npm >= 10

设置与构建

npm install
npm run build

运行测试

npm test

开发模式

npm run dev

---

npm 可信发布

推送匹配 v* 标签时，publish.yml GitHub Actions 工作流会暂存一个软件包。该软件包必须已存在于 npm 上。此工作流通过 npm 可信发布使用 GitHub OIDC，无需 npm 令牌。暂存的软件包在维护者于 npm 上完成审核并通过双重身份验证批准之前，不会公开发布。

使用 GitHub Actions 配置 npm 软件包的可信发布者，仓库为 ParkerDiamond/ChatPPT，工作流文件名为 publish.yml，并启用 npm stage publish 操作。暂存任务使用 Node.js 24 和 npm 11.15.0 或更高版本。

MCP Registry 发布

推送 v* 版本标签时，同一个 publish.yml 工作流会将 server.json 发布到 MCP Registry。该工作流通过 GitHub OIDC 进行身份验证，无需注册表密钥。注册表任务会等待 npm 暂存完成，但 MCP Registry 验证要求所引用的 npm 版本已公开发布。如果工作流运行时 npm 审批仍在等待中，请批准暂存的 npm 发布，然后重新运行失败的注册表任务。

---

许可证

MIT