
UFO 项目 PowerPointCOMExecutor 服务器实战基于 COM 的 PPT 背景设置与导出自动化【免费下载链接】UFOUFO³: Weaving the Digital Agent Galaxy项目地址: https://gitcode.com/GitHub_Trending/uf/UFO导读本文以 PowerPointCOMExecutor 服务器文档 为核心深入讲解 UFO 项目中面向 Microsoft PowerPoint 的本地 COM 自动化 MCP 服务器。读者将掌握set_background_color与save_as两个 Action 工具的完整参数语义、调用方式与配置方法理解其底层源码实现原理并能将它与 AppUIExecutor 组合构建高效的 PPT 演示文稿批量处理与导出流程。服务器概述PowerPointCOMExecutor是 UFO 项目为 Microsoft PowerPointPOWERPNT.EXE提供的 COM 接口自动化 MCP 服务器用于高效完成演示文稿操作。属性值服务器类型Action动作执行服务器部署方式本地进程内in-process服务 AgentAppAgent目标应用Microsoft PowerPointPOWERPNT.EXELLM 可选✅ 是由 LLM 根据工具描述自主选择调用命名空间PowerPointCOMExecutor平台Windows前置条件安装 Microsoft PowerPoint提供 COM 接口工具类型action从源码结构看该服务器通过MCPRegistry.register_factory_decorator(PowerPointCOMExecutor)注册为命名工厂见 mcp_registry.py实际实现位于 ppt_wincom_mcp_server.py其运行依赖 Windows 平台——模块开头即检测platform.system() ! Windows并在非 Windows 环境下跳过初始化。服务器内部基于 FastMCP 构建同时持有AppPuppeteer实例与ActionExecutor用于将 MCP 工具调用转换为底层 UI 动作指令ActionCommandInfo并交由 COM 接收器执行。工具一set_background_color设置幻灯片背景色参数说明参数类型必填默认值说明colorstr✅ 是-Hex 颜色代码RGB 格式如FFFFFFslide_indexList[int]否None幻灯片索引列表从 1 开始。None表示全部幻灯片返回值str— 成功/失败消息。调用示例# 将第 1 张幻灯片背景设置为白色 await computer.run_actions([ MCPToolCall( tool_keyaction::set_background_color, tool_nameset_background_color, parameters{ color: FFFFFF, slide_index: [1] } ) ]) # 将第 1、3、5 张幻灯片背景设置为蓝色 await computer.run_actions([ MCPToolCall( tool_keyaction::set_background_color, tool_nameset_background_color, parameters{ color: 0000FF, slide_index: [1, 3, 5] } ) ]) # 将所有幻灯片背景设置为红色 await computer.run_actions([ MCPToolCall( tool_keyaction::set_background_color, tool_nameset_background_color, parameters{ color: FF0000, slide_index: None # 全部幻灯片 } ) ])颜色格式使用不带#前缀的 6 位十六进制 RGB 编码颜色Hex 编码白FFFFFF黑000000红FF0000绿00FF00蓝0000FF黄FFFF00灰808080底层实现原理从源码 powerpointclient.py 可以还原其实现细节BGR 转换COM 接口的ForeColor.RGB使用 BGR 格式因此代码将 6 位 Hex 拆分为 R/G/B 三个字节后通过(blue 16) (green 8) red重新组合。例如0000FF纯蓝会转换为 BGR 值0xFF0000。全部幻灯片当slide_index为空或None时使用range(1, self.com_object.Slides.Count 1)遍历全部幻灯片。越界保护索引小于 1 或大于幻灯片总数时直接continue跳过不会抛错。母版覆盖每个幻灯片设置FollowMasterBackground False、Background.Fill.Visible True并调用Fill.Solid()确保独立于母版背景生效。命令注册该工具对应SetBackgroundColorCommand通过PowerPointWinCOMReceiver.register注册到PowerPointWinCOMReceiver的命令注册表名称set_background_color与 MCP 工具名一致。工具二save_as保存/导出演示文稿参数说明参数类型必填默认值说明file_dirstr否保存目录路径file_namestr否不含扩展名的文件名file_extstr否扩展名默认.pptxcurrent_slide_onlybool否False图片格式下仅保存当前幻灯片或全部幻灯片支持的文件扩展名演示文稿格式.pptx— PowerPoint 演示文稿默认.ppt— PowerPoint 97-2003.pdf— PDF 格式图片格式由current_slide_only控制.jpg、.jpeg— JPEG 图片.png— PNG 图片.gif— GIF 图片.bmp— 位图图片.tiff— TIFF 图片返回值str— 成功/失败消息。调用示例# 保存为 PPTX await computer.run_actions([ MCPToolCall( tool_keyaction::save_as, tool_namesave_as, parameters{ file_dir: C:\\Presentations, file_name: Q4_Report, file_ext: .pptx } ) ]) # 导出为 PDF await computer.run_actions([ MCPToolCall( tool_keyaction::save_as, tool_namesave_as, parameters{ file_ext: .pdf } ) ]) # 将当前幻灯片保存为 PNG await computer.run_actions([ MCPToolCall( tool_keyaction::save_as, tool_namesave_as, parameters{ file_name: slide_1, file_ext: .png, current_slide_only: True } ) ]) # 将全部幻灯片导出为 PNG 图片自动创建目录 await computer.run_actions([ MCPToolCall( tool_keyaction::save_as, tool_namesave_as, parameters{ file_dir: C:\\Exports\\Slides, file_ext: .png, current_slide_only: False # 保存全部幻灯片 } ) ])图片导出行为current_slide_only行为True仅导出当前幻灯片的单个图片文件False创建目录其中包含每张幻灯片对应的多个图片文件底层实现原理从源码 powerpointclient.py 可以看出默认值推断file_dir为空时默认保存到当前文档所在目录os.path.dirname(self.com_object.FullName)file_name为空时使用当前文档文件名去扩展名file_ext为空时默认.pptx。扩展名映射代码内置了ppt_ext_to_fileformat字典将扩展名映射为 PowerPoint 的FileFormat枚举值如.pptx→24、.ppt→0、.pdf→32、.png→18、.mp4→39 等并调用SaveAs(file_path, FileFormat...)。文档中列出的格式是其子集实际源码还支持.xps、.potx、.pot、.ppsx、.pps、.odp、.rtf、.html、.mp4、.wmv、.xml等更多格式。图片导出路径图片格式通过ppt_ext_to_formatstr映射如.png→PNG并调用Slides(i).Export(file_path, format_str)。特殊逻辑若演示文稿只有 1 张幻灯片无论current_slide_only值如何都直接导出第 1 张若current_slide_onlyTrue则通过SlideShowWindow.View.Slide.SlideIndex获取当前放映中的幻灯片索引进行导出。路径安全校验保存路径经 path_validator.py 的validate_save_file_path校验阻止路径穿越CWE-22、敏感系统目录C:\Windows、C:\Program Files等以及非法文件名保留设备名、控制字符、结尾空格/点等。配置方法在 mcp.yaml 中启用官方文档给出的配置片段AppAgent: POWERPNT.EXE: action: - namespace: AppUIExecutor type: local - namespace: PowerPointCOMExecutor type: local reset: true # 推荐对应的完整示例见仓库 config/ufo/mcp.yamlPOWERPNT.EXE的 action 列表同时挂载了AppUIExecutor与PowerPointCOMExecutor两个本地服务器data_collection侧则挂载UICollectorPOWERPNT.EXE: data_collection: - namespace: UICollector type: local start_args: [] reset: false action: - namespace: AppUIExecutor type: local start_args: [] reset: false - namespace: PowerPointCOMExecutor type: local start_args: [] reset: true关键配置项配置项说明namespace服务器命名空间PowerPointCOMExecutor对应 ppt_wincom_mcp_server.py 中注册的工厂名type服务器类型local表示进程内本地部署in-processstart_argsstdio 类型服务器的启动参数本地 COM 服务器一般留空[]reset是否在切换文档/上下文时重置服务器状态。COM 类服务器是有状态工具推荐设为true防止状态在不同文档间泄漏reset: true的语义在 configuration.md 中有明确说明对于有状态的工具如 COM 执行器设置reset: true可防止上下文例如不同文档之间的状态泄漏。最佳实践1. 批量设置背景色# ✅ 推荐一次调用设置多张幻灯片 await computer.run_actions([ MCPToolCall( tool_keyaction::set_background_color, parameters{color: FFFFFF, slide_index: [1, 2, 3, 4, 5]} ) ]) # ❌ 不推荐每张幻灯片调用一次 for i in range(1, 6): await computer.run_actions([ MCPToolCall( tool_keyaction::set_background_color, parameters{color: FFFFFF, slide_index: [i]} ) ])批量调用大幅减少进程间通信与 COM 交互开销这是该工具存在的核心价值——正如 MCP 服务器源码中工具 docstring 所写You should use this API to save your work since it is more efficient than using UI相比 UI 操作更高效。2. 使用 save_as 进行导出# ✅ 推荐单条命令快速导出 await computer.run_actions([ MCPToolCall( tool_keyaction::save_as, parameters{file_ext: .pdf} ) ]) # ❌ 不推荐手动 UI 导航 await computer.run_actions([ MCPToolCall(tool_keyaction::keyboard_input, parameters{keys: {VK_MENU}f}) # AltF ]) # ... 逐级导航文件菜单 ...3. 校验 Hex 颜色def validate_hex_color(color: str) - bool: 校验 Hex 颜色格式 return bool(re.match(r^[0-9A-Fa-f]{6}$, color)) color FFFFFF if validate_hex_color(color): await computer.run_actions([ MCPToolCall( tool_keyaction::set_background_color, parameters{color: color, slide_index: [1]} ) ])颜色校验很重要实现中按 2 位一组截取color[0:2]、color[2:4]、color[4:6]并执行int(..., 16)若传入的 Hex 字符串长度不足 6 位或包含非法字符将导致转换异常并抛出RuntimeError(Failed to set the background color...)。使用场景场景一演示文稿品牌化Presentation Branding# 应用公司配色方案 brand_color 003366 # 公司蓝 # 将所有幻灯片背景设置为品牌色 await computer.run_actions([ MCPToolCall( tool_keyaction::set_background_color, tool_nameset_background_color, parameters{ color: brand_color, slide_index: None # 全部幻灯片 } ) ]) # 导出 PDF 用于分发 await computer.run_actions([ MCPToolCall( tool_keyaction::save_as, tool_namesave_as, parameters{ file_dir: C:\\Distribution, file_name: Company_Presentation, file_ext: .pdf } ) ])场景二为文档导出幻灯片图片# 将每张幻灯片导出为 PNG 用于文档编写 await computer.run_actions([ MCPToolCall( tool_keyaction::save_as, tool_namesave_as, parameters{ file_dir: C:\\Docs\\Images, file_name: presentation_slides, file_ext: .png, current_slide_only: False # 导出全部 } ) ])局限性与组合建议已知限制工具集有限仅包含 2 个工具背景色设置与保存/导出。不支持内容创建无法通过 COM 添加文本、形状或图片需使用 UI 自动化。不支持幻灯片管理无法添加、删除或重排幻灯片需使用 UI 自动化。与 AppUIExecutor 组合建议与AppUIExecutor组合使用实现完整的 PowerPoint 自动化PowerPointCOMExecutor负责背景色设置与文件导出高效、确定性操作。AppUIExecutor负责添加幻灯片、插入文本/形状、制作动画灵活、UI 驱动的创作操作。这一分工也体现在仓库配置 config/ufo/mcp.yaml 中POWERPNT.EXE的 action 服务器列表同时包含两个执行器LLM 可以根据任务性质在两者之间自主选择。相关模式的更多说明可参见 hybrid_actions.md混合动作机制与 mcp_reference.md。相关文档WordCOMExecutor — Word COM 自动化ExcelCOMExecutor — Excel COM 自动化AppUIExecutor — 基于 UI 的 PowerPoint 自动化MCP 总览 — MCP 服务器体系概览MCP 配置指南 — 服务器配置与 reset 语义详解参考实现路径服务器入口ppt_wincom_mcp_server.py —PowerPointCOMExecutor工厂注册与两个 MCP 工具定义COM 接收器与命令实现powerpointclient.py —PowerPointWinCOMReceiver、SetBackgroundColorCommand、SaveAsCommand基类实现basic.py —WinCOMReceiverBasic/WinCOMCommand通用 COM 封装路径安全path_validator.py — 保存路径的穿越与敏感目录校验配置示例config/ufo/mcp.yaml —POWERPNT.EXE的完整 MCP 服务器配置【免费下载链接】UFOUFO³: Weaving the Digital Agent Galaxy项目地址: https://gitcode.com/GitHub_Trending/uf/UFO创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考