内容
# htmlbook
**将 AI 生成的 HTML 和 Markdown 发布到托管的、可分享的 URL。** htmlbook 是一个 [MCP](https://modelcontextprotocol.io) 服务器和 REST API，它可以将您的编码代理刚刚生成的文档——HTML 报告、数据仪表板、规格、会议笔记、交互式页面——转换为一个干净的链接，您可以在手机上打开或发送给他人，而不是将其留在项目文件夹中的本地 `.html` 文件。
从 **Claude Code, Cursor, Codex, 或 claude.ai** 推送。htmlbook 存储文档，为舒适地在任何设备上阅读（纸张 / 褐色 / 黑暗）重新主题化每个编辑版本，并为每个文档提供一个分享链接，包含三种模式——公开（任何人，无需登录）、密码保护（任何人拥有密码，无需登录），或仅您可以和您的 工作空间 打开的私人秘密链接。
> **将输出分享为链接，而不是文件。** 当代理生成 HTML 时，之后的部分很尴尬：从您的笔记本电脑上获取它，放到您的手机上，让其他人看到。htmlbook 就是放置该部分内容的架子。
- 🌐 **网站：** <https://htmlbook.io>
- 🔌 **MCP 端点：** `https://htmlbook.io/api/mcp`
- 📡 **REST 发布：** `POST https://htmlbook.io/api/docs`
- 💬 **社区：** [Discord](https://discord.gg/hqMkDFPR)
---
## 快速入门
### 1. 连接您的代理
在 <https://htmlbook.io> → 设置中获取 API 密钥，然后添加 MCP 服务器。
**Claude Code** （浏览器登录，无需密钥）：
```bash
claude mcp add --transport http htmlbook https://htmlbook.io/api/mcp
# 然后运行 `claude` 并批准 htmlbook 登录
```
**Claude Code** （使用 API 密钥）：
```bash
claude mcp add --transport http htmlbook https://htmlbook.io/api/mcp \
--header "Authorization: Bearer $HTMLBOOK_API_KEY"
```
**Cursor** — `~/.cursor/mcp.json`:
```json
{
"mcpServers": {
"htmlbook": {
"url": "https://htmlbook.io/api/mcp",
"headers": { "Authorization": "Bearer hb_live_REPLACE_WITH_YOUR_KEY" }
}
}
}
```
**Codex CLI** — `~/.codex/config.toml`:
```toml
[mcp_servers.htmlbook]
url = "https://htmlbook.io/api/mcp"
bearer_token_env_var = "HTMLBOOK_API_KEY"
```
**claude.ai / Claude Desktop** — 使用 URL `https://htmlbook.io/api/mcp` 添加自定义连接器（OAuth — 无需粘贴密钥）。
参见 [docs/getting-started.md](docs/getting-started.md) 以获取每个客户端的信息。
### 2. 发布文档
只需询问您的代理。连接 MCP 服务器后，它将调用 `publish` 工具：
```text
您：编写 Q3 数字仪表板并将其放在 htmlbook 上。
代理：htmlbook → publish
✓ 已归档 (hbdoc) · acme/q3-dashboard · v1 · 读取：https://htmlbook.io/app/p/acme/q3-dashboard
```
散文（报告、计划、笔记）最容易作为 **Markdown** —— htmlbook 将 `.md` 保留为真实来源，并从中渲染主题阅读器视图：
```json
{
"tool": "publish",
"project": "acme",
"markdown": "# Q3 回顾\n\n收入环比增长 8%...\n\n## 亮点\n- ..."
}
```
### 3. 分享它
文档**默认私有**。制作一个公开的文档以获取任何人都可以打开的链接：
```text
代理：htmlbook → set_access （可见性：public）
✓ acme/q3-dashboard 现在公开 · https://htmlbook.io/d/a1b2c3
```
这就是整个循环：**生成 → 发布 → 分享**。
---
## 您 can 发布的内容
| 格式 | 何时 | htmlbook 执行的操作 |
|--------|------|--------------------|
| **Markdown** | 散文：报告、计划、笔记、规格 | 将 `.md` 保留为真实来源，渲染主题阅读器视图（目录、表格、标注、任务列表），保持可下载 + 可编辑为 Markdown |
| **hb-doc HTML** | 丰富文档：仪表板、KPI、内联 SVG 图表 | 一个 `<article class="hb-doc">` 片段，仅使用 `hb-*` 类和 `--hb-*` 令牌进行样式化 — 阅读器提供样式表并重新主题化它（纸张 / 褐色 / 黑暗，宽度，字体大小） |
| **Bundle** | 自包含页面，带有自己的 CSS/JS | 原样存储并在沙盒 iframe 中渲染 — 您的脚本运行，您的样式保留。可以是 **多文件** （index.html + 子页面 + 资产，≤10MB）用于带有工作相对链接的小型静态站点 |
发布时自动检测格式。您无需声明它 — 推送 Markdown，推送 hb-doc 片段，或推送完整的独立 HTML 页面，htmlbook 会将其路由。
参见 [docs/publishing.md](docs/publishing.md) 和 [docs/hb-doc-contract.md](docs/hb-doc-contract.md)。
---
## 为什么是 htmlbook
- **从您的笔记本电脑上解放出来。** 代理的 HTML 输出卡在生成它的机器上。htmlbook 将其放到您的手机上并变成可分享的链接。
- **在任何地方都可读。** 由于 hb-doc 不携带自己的 CSS，因此读者对其进行主题化 — 相同的文档在黑暗的手机和阳光下的桌面上看起来都很好。
- **版本控制。** 每次发布和每次在阅读器中编辑都是一个新的不可变版本。历史面板显示了谁更改了什么；任何版本都可以恢复。
- **Markdown 保留为 Markdown。** Markdown 推送不会丢失转换为 HTML — 原始 `.md` 是真实来源，并在下载时循环。
- **默认私有。** 除非您打开，否则没有任何内容是公开的。三种分享模式：公开（任何人），密码保护（任何人拥有密码，无需登录 — 更改后撤销访问），或仅您可以和您的 工作空间 打开的秘密链接会话。
- **令牌便宜。** 通过 REST API 将大文档作为文件推送，以便其字节永远不会通过代理的上下文传递。参见 [docs/rest-api.md](docs/rest-api.md)。
---
## MCP 工具
htmlbook MCP 服务器暴露了 10 种工具。完整参考：[docs/mcp-tools.md](docs/mcp-tools.md)。
| 工具 | 目的 |
|------|---------|
| `publish` | 将文档（HTML 或 Markdown）存档到托管的 URL；如果存在，则为新版本 |
| `guide` | 获取作者合同（hb-doc 类、令牌、组件）在手动编写 HTML 之前 |
| `list` | 浏览您的库，可选按项目过滤 |
| `get` | 获取文档的元数据 + 当前正文（对于 Markdown，`.md` 源） |
| `search` | 跨您存档的所有内容进行全文搜索（在重新派生之前回忆） |
| `organize` | 设置标题 / 标签 / 路径，在项目之间移动，重新命名 |
| `set_access` | 使文档公开，密码保护或私有 |
| `cite` | 获取到文档特定部分（标题）的可分享深层链接 |
| `restore` | 将文档回滚到早期版本 |
| `delete` | 将文档移动到回收站 |
---
## 支持的客户端
| 客户端 | 认证 |
|--------|------|
| Claude Code | MCP 上的 API 密钥，或浏览器登录；也是 REST |
| Cursor | MCP 上的 API 密钥 |
| Codex CLI | MCP 上的 API 密钥；也是 REST |
| claude.ai | OAuth（自定义连接器） |
| Claude Desktop | OAuth（自定义连接器） |
| 任何 MCP 客户端 | 可流式 HTTP + Bearer 密钥或 OAuth 2.1 |
---
## 文档
- [快速入门](docs/getting-started.md) — 连接每个客户端，获取密钥
- [发布](docs/publishing.md) — 三种格式，`publish` 工具，示例
- [Markdown](docs/markdown.md) — 真实来源，元数据，文件夹同步
- [hb-doc 合同](docs/hb-doc-contract.md) — 类，令牌，组件
- [分享和访问](docs/sharing.md) — 公开，密码，秘密链接，工作区
- [MCP 工具参考](docs/mcp-tools.md) — 所有 10 种工具，示例调用
- [REST API](docs/rest-api.md) — `POST /api/docs`，令牌廉价的文件推送
- [示例](examples/) — 报告，仪表板，文件夹同步设置
---
由 [Streamize](https://github.com/Streamize-llc) 制作。文档采用 MIT 许可；htmlbook 本身是 [htmlbook.io](https://htmlbook.io) 上的托管服务。
