htmlbook

# htmlbook

**Publish AI-generated HTML and Markdown to a hosted, shareable URL.** htmlbook is
an [MCP](https://modelcontextprotocol.io) server and REST API that takes a document
your coding agent just generated — an HTML report, a data dashboard, a spec, meeting
notes, an interactive page — and turns it into a clean link you can open on your
phone or send to someone, instead of leaving it as a local `.html` file buried in a
project folder.

Push from **Claude Code, Cursor, Codex, or claude.ai**. htmlbook stores the document,
re-themes it for comfortable reading on any device (paper / sepia / dark), keeps every
edit as a version, and gives each document one share link — public for anyone, or a
private secret link only you and your workspace can open.

> **Share the output as a link, not a file.** When an agent makes HTML, the awkward
> part is everything after: getting it off your laptop, onto your phone, in front of
> someone else. htmlbook is the shelf that part lives on.

- 🌐 **Website:** <https://htmlbook.io>
- 🔌 **MCP endpoint:** `https://htmlbook.io/api/mcp`
- 📡 **REST publish:** `POST https://htmlbook.io/api/docs`
- 💬 **Community:** [Discord](https://discord.gg/hqMkDFPR)

---

## Quickstart

### 1. Connect your agent

Get an API key at <https://htmlbook.io> → Settings, then add the MCP server.

**Claude Code** (browser login, no key needed):

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

**Claude Code** (with an API key):

```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** — add a custom connector with URL
`https://htmlbook.io/api/mcp` (OAuth — no key to paste).

See [docs/getting-started.md](docs/getting-started.md) for every client.

### 2. Publish a document

Just ask your agent. With the MCP server connected, it calls the `publish` tool:

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

Prose (a report, a plan, notes) is easiest as **Markdown** — htmlbook keeps the `.md`
as the source of truth and renders a themed reader view from it:

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

### 3. Share it

Documents are **private by default**. Make one public to get a link anyone can open:

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

That's the whole loop: **generate → publish → share**.

---

## What you can publish

| Format | When | What htmlbook does |
|--------|------|--------------------|
| **Markdown** | Prose: reports, plans, notes, specs | Keeps the `.md` as the source of truth, renders a themed reader view (TOC, tables, callouts, task lists), stays downloadable + editable as Markdown |
| **hb-doc HTML** | Rich docs: dashboards, KPIs, inline SVG charts | A `<article class="hb-doc">` fragment styled only with `hb-*` classes + `--hb-*` tokens — the reader supplies the stylesheet and re-themes it (paper / sepia / dark, width, font size) |
| **Bundle** | A self-contained page with its own CSS/JS | Stored verbatim and rendered in a sandboxed iframe — your scripts run, your styling is preserved |

The format is auto-detected at publish. You never have to declare it — push Markdown,
push an hb-doc fragment, or push a full standalone HTML page and htmlbook routes it.

See [docs/publishing.md](docs/publishing.md) and
[docs/hb-doc-contract.md](docs/hb-doc-contract.md).

---

## Why htmlbook

- **Off your laptop.** An agent's HTML output is stuck on the machine that made it.
  htmlbook gets it onto your phone and into a shareable link.
- **Readable everywhere.** Because an hb-doc carries no CSS of its own, the reader
  themes it — the same document looks right on a phone in the dark and a desktop in
  daylight.
- **Versioned.** Every publish and every in-reader edit is a new immutable version.
  The History panel shows who changed what; any version restores.
- **Markdown stays Markdown.** A Markdown push is not lossily converted to HTML — the
  original `.md` is the source of truth and round-trips on download.
- **Private by default.** Nothing is public until you flip it. Secret links are
  session-gated to you and your workspace.
- **Token-cheap.** Push a large document as a file over the REST API so its bytes
  never pass back through your agent's context. See [docs/rest-api.md](docs/rest-api.md).

---

## The MCP tools

The htmlbook MCP server exposes 8 tools. Full reference:
[docs/mcp-tools.md](docs/mcp-tools.md).

| Tool | Purpose |
|------|---------|
| `publish` | Shelve a document (HTML or Markdown) to a hosted URL; new version if it exists |
| `guide` | Get the authoring contract (hb-doc classes, tokens, components) before composing HTML by hand |
| `list` | Browse your library, optionally filtered by project |
| `get` | Fetch a document's metadata + current body |
| `organize` | Set title / tags / path, move between projects, rename |
| `set_access` | Make a document public or private |
| `restore` | Roll a document back to an earlier version |
| `delete` | Move a document to the trash |

---

## Supported clients

| Client | Auth |
|--------|------|
| Claude Code | API key over MCP, or browser login; also REST |
| Cursor | API key over MCP |
| Codex CLI | API key over MCP; also REST |
| claude.ai | OAuth (custom connector) |
| Claude Desktop | OAuth (custom connector) |
| Any MCP client | Streamable HTTP + Bearer key or OAuth 2.1 |

---

## Documentation

- [Getting started](docs/getting-started.md) — connect every client, get a key
- [Publishing](docs/publishing.md) — the three formats, the `publish` tool, examples
- [Markdown](docs/markdown.md) — source of truth, frontmatter, folder sync
- [The hb-doc contract](docs/hb-doc-contract.md) — classes, tokens, components
- [Sharing & access](docs/sharing.md) — public, secret links, workspaces
- [MCP tools reference](docs/mcp-tools.md) — all 8 tools with example calls
- [REST API](docs/rest-api.md) — `POST /api/docs`, token-cheap file pushes
- [examples/](examples/) — a report, a dashboard, a folder-sync setup

---

Made by [Streamize](https://github.com/Streamize-llc). Documentation is MIT-licensed;
htmlbook itself is a hosted service at [htmlbook.io](https://htmlbook.io).