htmlbook

htmlbook

将 AI 生成的 HTML 和 Markdown 发布到托管且可分享的 URL。 htmlbook 是一款 MCP 服务和 REST API，可接收编码 Agent 刚刚生成的文档——HTML 报告、数据仪表板、规范、会议记录、交互式页面等——并将其转换为整洁的链接，你可以在手机上打开或发送给他人，而不是让它成为埋在项目文件夹中的本地 .html 文件。

可从 Claude Code、Cursor、Codex 或 claude.ai 推送。htmlbook 会存储文档，针对各种设备优化主题，让阅读更舒适（纸张／棕褐／深色），将每次编辑保存为一个版本，并为每份文档提供一个分享链接，支持三种模式——公开（任何人都可访问，无需登录）、密码保护（任何知道密码的人都可访问，无需登录），或仅你和你的工作区可以打开的私密秘密链接。

以链接分享输出内容，而不是文件。 Agent 生成 HTML 后，麻烦的是接下来的一切：如何把它从笔记本电脑上传、在手机上打开，或展示给其他人。htmlbook 就是用来存放这些内容的架子。

• 🌐 网站： https://htmlbook.io
• 🔌 MCP 端点： https://htmlbook.io/api/mcp
• 📡 REST 发布： POST https://htmlbook.io/api/docs
• 💬 社区： Discord

---

快速入门

1. 连接你的 Agent

在 https://htmlbook.io → Settings 获取 API 密钥，然后添加 MCP 服务。

Claude Code（浏览器登录，无需密钥）：

claude mcp add --transport http htmlbook https://htmlbook.io/api/mcp
# then run `claude` and approve the htmlbook login

Claude Code（使用 API 密钥）：

claude mcp add --transport http htmlbook https://htmlbook.io/api/mcp \
  --header "Authorization: Bearer $HTMLBOOK_API_KEY"

Cursor — ~/.cursor/mcp.json：

{
  "mcpServers": {
    "htmlbook": {
      "url": "https://htmlbook.io/api/mcp",
      "headers": { "Authorization": "Bearer hb_live_REPLACE_WITH_YOUR_KEY" }
    }
  }
}

Codex CLI — ~/.codex/config.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。

2. 发布文档

直接向你的 Agent 提出请求即可。连接 MCP 服务后，它会调用 publish 工具：

You: Write up the Q3 numbers as a dashboard and put it on htmlbook.

Agent: htmlbook → publish
       ✓ shelved (hbdoc) · acme/q3-dashboard · v1 · read: https://htmlbook.io/app/p/acme/q3-dashboard

对于文字内容（报告、计划、笔记），使用 Markdown 最简单——htmlbook 会将 .md 保留为事实来源，并据此生成带主题的阅读视图：

{
  "tool": "publish",
  "project": "acme",
  "markdown": "# Q3 Review\n\nRevenue is up 8% QoQ...\n\n## Highlights\n- ..."
}

3. 分享文档

文档默认设为私密。将文档设为公开，即可获得任何人都能打开的链接：

Agent: htmlbook → set_access  (visibility: public)
       ✓ acme/q3-dashboard is now public · https://htmlbook.io/d/a1b2c3

整个流程就是：生成 → 发布 → 分享。

---

可发布的内容

格式	适用场景	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/hb-doc-contract.md。

---

为什么选择 htmlbook

• 脱离笔记本电脑。 Agent 生成的 HTML 输出会留在生成它的设备上。 htmlbook 可将其发送到手机，并生成可分享的链接。
• 随处可读。 hb-doc 不包含自己的 CSS，因此由阅读者选择主题——同一份文档在夜间的手机和白天的桌面设备上都能呈现得恰到好处。
• 版本管理。 每次发布和阅读器内的每次编辑都会生成一个新的不可变版本。 历史记录面板会显示更改者及其更改内容；任何版本都可恢复。
• Markdown 始终是 Markdown。 推送 Markdown 时不会将其有损转换为 HTML—— 原始 .md 文件才是唯一可信来源，下载时也会还原为原格式。
• 默认私密。 除非你主动更改设置，否则内容不会公开。提供三种分享模式： 公开（任何人均可访问）、密码保护（任何知道密码的人均可访问，无需登录——更改密码会撤销此前的访问权限），或仅限工作区会话访问的私密链接。
• 节省 Token。 通过 REST API 将大型文档作为文件推送，这样文件内容就不会传回 Agent 的上下文中。请参阅 docs/rest-api.md。

---

MCP 工具

htmlbook MCP 服务提供 10 个工具。完整参考： docs/mcp-tools.md。

工具	用途
publish	将文档（HTML 或 Markdown）存入资料库并生成托管 URL；如果文档已存在，则创建新版本
guide	在手动编写 HTML 前，获取编写规范（hb-doc 类、令牌、组件）
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 客户端	Streamable HTTP + Bearer 密钥或 OAuth 2.1

---

文档

• 入门指南 — 连接各类客户端并获取密钥
• 发布 — 三种格式、publish 工具和示例
• Markdown — 唯一可信来源、前置元数据、文件夹同步
• hb-doc 规范 — 类、令牌和组件
• 分享与访问 — 公开、密码、私密链接和工作区
• MCP 工具参考 — 全部 10 个工具及调用示例
• REST API — POST /api/docs，节省 Token 的文件推送
• examples/ — 报告、仪表板和文件夹同步配置

---

由 Streamize 制作。文档采用 MIT 许可； htmlbook 本身是托管服务，网址为 htmlbook.io。