# reveal.js-mcp

一个对 [reveal.js](https://github.com/hakimel/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 客户端配置中：

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

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

## 从源码安装与构建

```bash
npm install
npm run build    # 输出到 dist/
```

## 运行

```bash
# 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`）：

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

或用命令注册：

```bash
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`）：

```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

```bash
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`（通过环境变量注入，均可覆盖）。

## 开发与测试

```bash
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 测试（含三种传输的端到端）
```