jh-presentation

jh-presentation

让 AI 将演示文稿制作成真正的网页。 jh-presentation 是一个 MCP 服务和轻量、无依赖的幻灯片引擎。你的 AI 客户端（Claude Desktop、Claude Code、VS Code、……）负责撰写内容；jh-presentation 会将其转换为单个自包含的 HTML 文件，包含实时图表、逐步动画、就地编辑和 PDF 导出功能，还能通过布局审核和截图让 AI 检查自己的成果。

无需 API 密钥：思考工作由你已在使用的 AI 客户端完成。

日本語の説明はこちら

为什么用 HTML，而不是 PowerPoint？

AI 模型在编写 HTML/CSS/JS 方面远胜于操作 PPTX。因此，可以实现一些幻灯片工具难以做到的功能：

• 逐步呈现的图表，数据沿着箭头流动
• 可点击缩放的系统概览，揭示内部组成部分
• 根据数据生成的 ER 图和时序图
• 带动画的图表、逐行高亮的代码，以及可实际运行的演示
• 所有内容都在一个 HTML 文件中，离线也能使用——可通过邮件发送、放到共享空间，或用浏览器进行演示

点击方框即可缩放查看其内部结构	点击表格即可突出显示其关联关系和连接键
带增长动画和图例切换的图表	以 3D 方式展开的分层架构

功能

• 单文件幻灯片——引擎、主题、品牌信息和图片均已嵌入。无需构建步骤、无需 CDN，可通过 file:// 打开
• 图表组件（输入数据，输出动效）——流程图／缩放地图、ER 图、时序图、图表（柱状图、折线图、饼图、圆环图）、3D 分层图、前后对比滑块、终端回放。AI 编写 JSON；布局、动画、点击交互和静态 PDF 视图均由工具处理
• 层级地图——逐层点击查看大型系统图（面包屑导航、边界框、按层汇总的箭头），沿各层追踪命名数据流，在数据库框中打开表和外键，并逐步查看状态机
• 地图文档——将同一地图制作为无幻灯片的单文件文档：可折叠目录、搜索、可分享的 URL、平移／缩放／缩略图、主题选择器，以及每层一页的打印布局
• 步骤——使用方向键逐步显示内容；组件也可接入相同步骤
• 主题——内置五种主题（默认、暗色、企业、活力、单色）、实时主题库，以及 AI 生成的自定义主题
• 品牌标识——在页眉／页脚栏中显示你的姓名、徽标和标签（例如 DRAFT）
• 自我检查 AI——audit_deck 可检测溢出、裁切、文本重叠、对比度过低、图片缺失和外部请求；screenshot_deck 可返回幻灯片图片供 AI 查看并修正
• 无需 AI 即可编辑——双击任意文本框即可就地编辑，按 Ctrl+S 直接保存回文件（只替换已编辑的文本）
• 演示——提供带备注、下一张幻灯片和计时器的演讲者视图；总览；黑屏；全屏窗口
• 安全保存——原子写入、并发编辑修订检查，以及支持恢复的 20 版历史记录
• 请求模板——技术演讲、闪电演讲、进度报告、技术提案（作为 MCP 提示词）

要求

• Node.js 20 或更高版本
• Google Chrome 或 Microsoft Edge（用于审核、截图和 PDF 导出；如果安装位置特殊，请设置 CHROME_PATH）

快速开始

Claude Desktop

打开 设置 → 开发者 → 编辑配置，并添加：

{
  "mcpServers": {
    "jh-presentation": {
      "command": "npx",
      "args": ["-y", "jh-presentation"],
      "env": { "JH_PRESENTATION_HOME": "C:/Users/you/Documents/decks" }
    }
  }
}

从托盘图标退出 Claude Desktop，然后重新启动。接着可以提出这样的请求：

制作一份 15 分钟的演示文稿，讲解 Git 分支策略，包含图表和逐步展示效果。

Claude Code

claude mcp add jh-presentation -e JH_PRESENTATION_HOME=~/decks -- npx -y jh-presentation

VS Code（.vscode/mcp.json）

{
  "servers": {
    "jh-presentation": {
      "command": "npx",
      "args": ["-y", "jh-presentation"],
      "env": { "JH_PRESENTATION_HOME": "${userHome}/Documents/decks" }
    }
  }
}

每次调用时决定演示文稿的保存位置——无需更改 MCP 设置即可另存到其他位置：

1. 工具收到的 dir（“放到此项目的 slides 文件夹中”），
2. AI 客户端当前工作区的 decks/ 文件夹（Claude Code、VS Code 和其他会报告 MCP 根目录的客户端），
3. 对于没有工作区的客户端（Claude Desktop），使用工作区：JH_PRESENTATION_HOME（默认值为 ~/jh-presentation）或 --workspace <dir>。

工作区还存放供所有项目共用的品牌设置、自定义主题和请求模板；项目自己的 brand/ 或 themes/ 文件夹优先。 --decks-dir <name>（JH_PRESENTATION_DECKS_DIR）可重命名 decks/，而 --no-roots（JH_PRESENTATION_ROOTS=off）则始终将文件保存到工作区。

AI 可以做什么（MCP 工具）

区域	工具
指南	get_guide — 编写规则、组件目录、工作流
主题	list_themes、open_theme_gallery、preview_themes、get_theme_guide、create_theme
模板	list_templates（也作为 MCP 提示词公开）
演示文稿	list_decks、create_deck、read_deck、write_deck、replace_slide、add_asset、upgrade_deck、list_history、restore_history、repair_deck
思维导图	create_map、read_map（整个思维导图、outline 或单个 node）、write_map（整个思维导图，或单个 node 和 part）
检查	audit_deck、screenshot_deck（演示文稿和思维导图）
输出	open_deck（可选全屏）、export_deck（PDF）

演示

按键	操作
→ / Space / Enter	下一页（包括步骤）
←	上一页
S	演讲者视图（备注、下一页、计时器）
E / 双击方框	就地编辑文本（Ctrl+S 保存，按 Esc 或“✕”退出）
O	总览
F	全屏
B	黑屏
数字 + Enter	跳转到指定页
?	帮助

请勿使用浏览器的“另存为网页…”功能——它会保存渲染后的页面，导致演示文稿损坏。请在演示文稿中按 Ctrl+S。如果还是发生了，repair_deck 可以恢复文件。

在此仓库中工作

npm install
npm run dev        # http://localhost:4000 — deck list, theme gallery, feature sample
npm test

命令	说明
npm run dev	带实时重载的预览服务器（仅限本地，127.0.0.1）
npm run new -- <name> "Title" [--theme <t>] [--brand footer] [--fullscreen]	在 decks/ 中新建演示文稿
npm run upgrade [-- <name>]	重新嵌入最新的引擎、主题和品牌设置
npm run pdf -- <name>	将 PDF 导出到 dist/
npm run repair -- <name>	修复因浏览器“另存为网页”而损坏的演示文稿
npm run gallery	构建主题图库
npm run mcp	启动 MCP 服务（工作区 .workspace/）

功能示例位于 examples/sample.html。供 AI 作者使用的规则位于 CLAUDE.md（Claude Code）、AGENTS.md（Codex、Cursor 和其他 Agent）以及 docs/authoring-guide.md 中；宿主应用的编辑协议位于 docs/edit-protocol.md 中。

编写指南、模板和工具说明目前使用日语编写。无论你用哪种语言交流，大模型都能很好地遵循这些内容；演示文稿也可以使用任何语言。

安全

所有操作都在你的计算机上运行：不收集遥测数据、不发送外部请求，预览/保存服务器仅绑定到 127.0.0.1，文件也只会写入工作区。演示文稿包含由 AI 客户端编写、并在浏览器中运行的 JavaScript。请参阅 SECURITY.md。

许可证

MIT。每份演示文稿生成的部分都会附带嵌入式引擎、组件和主题的 MIT 声明，因此可以直接分享演示文稿。幻灯片内容归你所有。

---

日本語

AI にプレゼンを「Web ページ」として作らせる MCP サーバーです。Claude Desktop・Claude Code・VS Code などの AI クライアントが内容を書き、jh-presentation が1 ファイルの HTML デッキにします。動く図・段階表示・その場での文字編集・PDF 出力に対応し、AI は検査とスクリーンショットで自分の出来を確認して直せます。API キーは不要です (考えるのは普段使っている AI クライアント)。

• 動く図の部品: 関連図・ズームマップ・ER 図・シーケンス図・グラフ・3D 分解図・ビフォー・アフター・ターミナル再生 (AI は JSON を書くだけ)
• 階層マップ: 大きなシステムの関連図をクリックで何段でも中へ。階層をまたぐデータの流れ、DB の中のテーブルと外部キー、状態遷移図 (遷移させて確かめる)
• マップ文書: スライドなしで全体から細部へたどって読む 1 ファイルの資料 (開閉できる目次・検索・URL での共有・拡大縮小・テーマの切り替え・階層ごとの印刷)
• テーマ 5 種 + 自作テーマ、名前・ロゴの帯、依頼文テンプレート (技術解説・LT・進捗報告・技術提案)
• 枠をダブルクリックして文字を直し、Ctrl+S で元のファイルに保存 (ブラウザの「名前を付けて保存」は使わない)
• 発表者ビュー・一覧・全画面、保存履歴と復元、壊れたデッキの復旧

使い方 (Claude Desktop)

設定 → 開発者 → 「構成を編集」で次を追加し、タスクトレイから終了して再起動します。

{
  "mcpServers": {
    "jh-presentation": {
      "command": "npx",
      "args": ["-y", "jh-presentation"],
      "env": { "JH_PRESENTATION_HOME": "C:/Users/you/Documents/decks" }
    }
  }
}

あとは「jh-presentation で、Git のブランチ戦略を 15 分で説明するプレゼン資料を、図とステップ表示を多めに作って」のように頼むだけです。 依頼の書き方 (道具の名前を書くべきクライアント・依頼文に入れるとよいこと・直し方) は docs/usage.md にまとめています。 詳しい設定 (Claude Code・VS Code) は mcp/README.md を参照してください。 このリポジトリで AI に作業させる場合のルールは CLAUDE.md (Claude Code) / AGENTS.md (Codex・Cursor など)、スライドの書き方は docs/authoring-guide.md にあります。

ライセンスは MIT です。デッキには埋め込んだエンジン・部品・テーマの MIT 表記が自動で入るので、そのまま配布できます。スライドの内容は作成者のものです。