AI导哈

PowerPoint服务器

PowerPoint MCP服务器提供双引擎支持，用于管理和操作PowerPoint演示文稿。

  • by Yans14
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 Yans14/powerpoint_mcp

使用说明

PowerPoint MCP服务器（v1）

支持双引擎的PowerPoint MCP服务器：

  • COM 安装了Microsoft PowerPoint的Windows上的模式（最高保真度）
  • OOXML 通过其他方式 python-pptx 以及安全的OOXML助手

TypeScript MCP服务器通过stdio JSON-RPC与本地Python桥通信。

状态

已实施v1第1-2阶段表面：

  • 会话工具
  • 发现工具
  • 滑动工具
  • 占位符工具
  • 幻灯片快照工具
  • 用于演示文稿/幻灯片/布局/母版/主题/快照的MCP资源

仅注册已实施的工具。

运行时目标

  • Node.js >=22
  • python >=3.12

注意：本地开发可以使用兼容的较低补丁/次要版本运行，但Node 22/Python 3.12是声明的基线。

安装

npm install
python3 -m pip install -r requirements.txt -r requirements-dev.txt
pre-commit install --install-hooks

你可以用以下方式做同样的事情：

make install
make precommit-install

跑

npm run dev
# or
npm run build && npm start

创建快捷方式：

make mcp
make mcp-start

Web UI（本地测试控制台）

该仓库包括一个轻量级的FastAPI+静态HTML UI，用于对工具、会话和日志进行交互式测试。

从项目根目录运行它：

python3 -m uvicorn web_ui:app --app-dir python --host 127.0.0.1 --port 8000 --reload

然后打开：

  • http://127.0.0.1:8000

它揭示了什么：

  • 按类别分组的工具目录浏览器(GET /api/tools)
  • 发动机信息(GET /api/engine)
  • 开放会话列表(GET /api/sessions)
  • 通用方法调度器(POST /api/dispatch)
  • 通过WebSocket进行实时后端日志记录(/ws/logs)

相关文件：

  • python/web_ui.py （FastAPI应用程序+API路由+WebSocket日志广播）
  • python/tool_catalog.py （面向UI的工具元数据/目录整形）
  • web/index.html （单页测试UI）

建筑

  • src/index.ts：MCP标准输入点
  • src/server.ts：MCP工具/资源注册和验证
  • src/bridge/client.ts：持久Python子进程客户端
  • src/tools/catalog.ts：所有v1工具的扁平zod模式
  • python/bridge.py：以行分隔的JSON-RPC调度程序
  • python/service.py：发动机选择+方法路线
  • python/engines/ooxml_engine.py：跨平台实施
  • python/engines/com_engine.py：Windows COM实现
  • python/com_worker.py：STA线程COM调用隔离

已实施的工具

  • pptx_get_engine_info
  • pptx_create_presentation
  • pptx_open_presentation
  • pptx_save_presentation
  • pptx_close_presentation
  • pptx_list_open_presentations
  • pptx_get_presentation_state
  • pptx_get_layouts
  • pptx_get_layout_detail
  • pptx_get_masters
  • pptx_get_theme
  • pptx_get_slide
  • pptx_add_slide
  • pptx_duplicate_slide
  • pptx_delete_slide
  • pptx_reorder_slides
  • pptx_move_slide
  • pptx_set_slide_background
  • pptx_get_slide_snapshot
  • pptx_get_placeholders
  • pptx_set_placeholder_text
  • pptx_set_placeholder_image
  • pptx_clear_placeholder
  • pptx_get_placeholder_text

所有变异操作返回 success 加上更新 presentation_state （close除外，它返回关闭确认）。

文件安全模型

  • 打开/创建的演示文稿将在临时工作副本中编辑。
  • 在明确之前，原始文件不会被修改 pptx_save_presentation.
  • 会话在内存中，无法在进程重启后继续运行。

快照

  • COM模式：本机 Slide.Export
  • OOXML模式： soffice --headless + pdftoppm
  • 如果OOXML模式中缺少依赖项，快照将返回 dependency_missing 带有安装提示。

测试

npm test
npm run test:py

基于笔记本电脑的验证（Windows）

以Windows为中心的Jupyter笔记本可在 notebooks/ 对于第1/2阶段验证：

  1. notebooks/01_engine_session_smoke.ipynb
  2. notebooks/02_discovery_and_slide_management.ipynb
  3. notebooks/03_placeholders_background.ipynb
  4. notebooks/04_snapshot_and_reports.ipynb

看 notebooks/README.md 用于运行指导和预期输出。

质量和格式

# Python lint and formatting
npm run lint:py
npm run format:check:py

# Full validation suite
npm run check

# Run all pre-commit hooks manually
npm run precommit:run

等效制造目标：

make check
make lint-py
make format-check-py
make precommit-run

Python工具配置集中在 pyproject.toml:

  • black 用于格式化
  • ruff 用于分拣/导入排序规则
  • pytest 测试执行的默认值

安全和秘密保护

  • 预提交秘密扫描：
    • detect-secrets 随着 .secrets.baseline
    • detect-private-key 钩子
  • CI秘密扫描 gitleaks (.github/workflows/security.yml)
  • 建议的GitHub设置：
    • 启用分支保护 main
    • 要求 ci + security 合并前检查
    • 启用秘密扫描和推送保护

切勿提交真实凭证。使用 .env.example 作为唯一跟踪的env模板。

依赖自动化

  • Dependabot 配置在 .github/dependabot.yml 用于npm、pip和GitHub操作更新。

Windows COM烟雾运行程序

在安装了PowerPoint的许可Windows计算机上运行此程序，以快速验证COM奇偶校验。

PowerShell包装器：

.\scripts\run_windows_com_smoke.ps1

Python直接调用：

PYTHONPATH=python python scripts/windows_com_smoke.py --output-dir /abs/path/to/artifacts/com-smoke

创建快捷方式：

make com-smoke
make com-smoke-ooxml

有用的选项：

  • --input-pptx <absolute_path>：对现有甲板进行烟雾检查
  • --layout-name \"Title Slide\"：强制添加幻灯片的特定布局
  • --skip-snapshot：跳过图像快照验证
  • --allow-ooxml：调试非Windows主机上的脚本流（不是COM奇偶校验）

输出被写入 artifacts/com-smoke/ 默认情况下：

  • com_smoke_output_<timestamp>.pptx
  • com_smoke_snapshot_<timestamp>.jpg （除非跳过）
  • com_smoke_report_<timestamp>.json
  • com_smoke_report_<timestamp>.md （自动状态+手动检查表）

相关 MCP