reveal.js-mcp

一个对 reveal.js（6.0.1，通过 npm 依赖引入）的薄封装 MCP 服务：让 Codex / Claude Code 等 MCP 客户端用自然语言创建 reveal.js 演示文稿，并立即通过内置 HTTP 服务在浏览器中查看。

• 三种传输：stdio（默认，供本地客户端拉起）、http（streamable HTTP，/mcp）、sse（ legacy SSE，/sse + /messages）
• 内置静态服务：/revealjs/* 提供 reveal.js 资源，/p/<id>/ 提供生成的演示文稿（stdio 模式下同样会启动，方便浏览器查看）
• npx 直接接入、本地直接运行或 Docker 运行

快速接入（npx，无需安装）

在 MCP 客户端配置中：

{
	"type": "stdio",
	"command": "npx",
	"args": ["revealjs-mcp@latest"]
}

也可以直接跑一个 HTTP 服务：npx revealjs-mcp@latest --transport http --port 8000

从源码安装与构建

npm install
npm run build    # 输出到 dist/

运行

# stdio（MCP 客户端通常以这种方式拉起）
node dist/index.js

# streamable HTTP
node dist/index.js --transport http --port 8000

# legacy SSE
node dist/index.js --transport sse --port 8000

开发模式（免构建）：npm run dev -- --transport http --port 8000

配置项

CLI 参数	环境变量	默认值	说明
--transport	REVEALJS_TRANSPORT	stdio	stdio / sse / http
--port	REVEALJS_PORT	8000	HTTP 端口（0 = 随机端口）
--host	REVEALJS_HOST	127.0.0.1	监听地址
--data-dir	REVEALJS_DATA_DIR	./presentations	演示文稿存储目录
--public-url	REVEALJS_PUBLIC_URL	http://localhost:<port>	工具返回 URL 使用的基础地址（反向代理时设置）

MCP 工具

工具	说明
create_presentation	从 slides 数组（HTML 或 markdown）创建演示文稿，返回可浏览的 URL
list_presentations	列出已创建的演示文稿
get_presentation_url	按 id 获取演示文稿 URL
delete_presentation	按 id 删除演示文稿
list_themes	列出 reveal.js 内置主题（black、white、dracula……）
list_transitions	列出转场样式（none/fade/slide/convex/concave/zoom）
get_server_info	服务器与 reveal.js 版本信息

create_presentation 支持 theme、transition、controls、progress、center、hash、highlight（语法高亮插件）以及 options（任意 reveal.js 配置透传到 Reveal.initialize()）。

在 Claude Code 中配置

stdio（推荐，无需克隆仓库，直接走 npx；也可复制 examples/claude-code.mcp.json 为项目根的 .mcp.json）：

{
	"mcpServers": {
		"revealjs": {
			"type": "stdio",
			"command": "npx",
			"args": ["revealjs-mcp@latest"]
		}
	}
}

或用命令注册：

claude mcp add revealjs -- npx revealjs-mcp@latest
# 已运行的 HTTP 服务：
claude mcp add --transport http revealjs http://localhost:8000/mcp
claude mcp add --transport sse  revealjs http://localhost:8000/sse

在 Codex 中配置

追加到 ~/.codex/config.toml（完整示例见 examples/codex.config.toml）：

[mcp_servers.revealjs]
command = "npx"
args = ["revealjs-mcp@latest"]
env = { REVEALJS_PORT = "8000" }

# 或连接已运行的 streamable HTTP 服务：
# [mcp_servers.revealjs]
# url = "http://localhost:8000/mcp"

Docker

docker build -t revealjs-mcp .
docker run -d -p 8000:8000 -v "$PWD/presentations:/data" revealjs-mcp
# MCP endpoint: http://localhost:8000/mcp （streamable HTTP）
# 换成 SSE:  -e REVEALJS_TRANSPORT=sse

也可以 docker compose up -d（见 docker-compose.yml）。

容器内默认 --transport http --host 0.0.0.0 --port 8000 --data-dir /data（通过环境变量注入，均可覆盖）。

开发与测试

npm test                 # vitest：单元 + MCP 协议 + 三种传输端到端
npm run build            # tsc 类型检查 + 编译
scripts/docker-smoke.sh  # 构建镜像并对容器跑真实 MCP 会话冒烟测试

结构

src/config.ts         CLI/环境变量解析
src/themes.ts         reveal.js 包定位、主题/转场列表
src/presentations.ts  演示文稿的创建/列表/删除与 HTML 模板
src/mcp.ts            MCP server 与工具注册
src/http.ts           express 应用：/revealjs 静态资源、/p 演示文稿、/mcp 与 /sse 端点
src/index.ts          CLI 入口（三种传输）
test/                 vitest 测试（含三种传输的端到端）