{
  "markdown": "# htmlbook\n\n**Publish AI-generated HTML and Markdown to a hosted, shareable URL.** htmlbook is\nan [MCP](https://modelcontextprotocol.io) server and REST API that takes a document\nyour coding agent just generated — an HTML report, a data dashboard, a spec, meeting\nnotes, an interactive page — and turns it into a clean link you can open on your\nphone or send to someone, instead of leaving it as a local `.html` file buried in a\nproject folder.\n\nPush from **Claude Code, Cursor, Codex, or claude.ai**. htmlbook stores the document,\nre-themes it for comfortable reading on any device (paper / sepia / dark), keeps every\nedit as a version, and gives each document one share link with three modes — public\n(anyone, no login), password-protected (anyone with the password, no login), or a\nprivate secret link only you and your workspace can open.\n\n> **Share the output as a link, not a file.** When an agent makes HTML, the awkward\n> part is everything after: getting it off your laptop, onto your phone, in front of\n> someone else. htmlbook is the shelf that part lives on.\n\n- 🌐 **Website:** <https://htmlbook.io>\n- 🔌 **MCP endpoint:** `https://htmlbook.io/api/mcp`\n- 📡 **REST publish:** `POST https://htmlbook.io/api/docs`\n- 💬 **Community:** [Discord](https://discord.gg/hqMkDFPR)\n\n---\n\n## Quickstart\n\n### 1. Connect your agent\n\nGet an API key at <https://htmlbook.io> → Settings, then add the MCP server.\n\n**Claude Code** (browser login, no key needed):\n\n```bash\nclaude mcp add --transport http htmlbook https://htmlbook.io/api/mcp\n# then run `claude` and approve the htmlbook login\n```\n\n**Claude Code** (with an API key):\n\n```bash\nclaude mcp add --transport http htmlbook https://htmlbook.io/api/mcp \\\n  --header \"Authorization: Bearer $HTMLBOOK_API_KEY\"\n```\n\n**Cursor** — `~/.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"htmlbook\": {\n      \"url\": \"https://htmlbook.io/api/mcp\",\n      \"headers\": { \"Authorization\": \"Bearer hb_live_REPLACE_WITH_YOUR_KEY\" }\n    }\n  }\n}\n```\n\n**Codex CLI** — `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.htmlbook]\nurl = \"https://htmlbook.io/api/mcp\"\nbearer_token_env_var = \"HTMLBOOK_API_KEY\"\n```\n\n**claude.ai / Claude Desktop** — add a custom connector with URL\n`https://htmlbook.io/api/mcp` (OAuth — no key to paste).\n\nSee [docs/getting-started.md](docs/getting-started.md) for every client.\n\n### 2. Publish a document\n\nJust ask your agent. With the MCP server connected, it calls the `publish` tool:\n\n```text\nYou: Write up the Q3 numbers as a dashboard and put it on htmlbook.\n\nAgent: htmlbook → publish\n       ✓ shelved (hbdoc) · acme/q3-dashboard · v1 · read: https://htmlbook.io/app/p/acme/q3-dashboard\n```\n\nProse (a report, a plan, notes) is easiest as **Markdown** — htmlbook keeps the `.md`\nas the source of truth and renders a themed reader view from it:\n\n```json\n{\n  \"tool\": \"publish\",\n  \"project\": \"acme\",\n  \"markdown\": \"# Q3 Review\\n\\nRevenue is up 8% QoQ...\\n\\n## Highlights\\n- ...\"\n}\n```\n\n### 3. Share it\n\nDocuments are **private by default**. Make one public to get a link anyone can open:\n\n```text\nAgent: htmlbook → set_access  (visibility: public)\n       ✓ acme/q3-dashboard is now public · https://htmlbook.io/d/a1b2c3\n```\n\nThat's the whole loop: **generate → publish → share**.\n\n---\n\n## What you can publish\n\n| Format | When | What htmlbook does |\n|--------|------|--------------------|\n| **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 |\n| **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) |\n| **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. Can be **multi-file** (index.html + sub-pages + assets, ≤10MB) for a small static site with working relative links |\n\nThe format is auto-detected at publish. You never have to declare it — push Markdown,\npush an hb-doc fragment, or push a full standalone HTML page and htmlbook routes it.\n\nSee [docs/publishing.md](docs/publishing.md) and\n[docs/hb-doc-contract.md](docs/hb-doc-contract.md).\n\n---\n\n## Why htmlbook\n\n- **Off your laptop.** An agent's HTML output is stuck on the machine that made it.\n  htmlbook gets it onto your phone and into a shareable link.\n- **Readable everywhere.** Because an hb-doc carries no CSS of its own, the reader\n  themes it — the same document looks right on a phone in the dark and a desktop in\n  daylight.\n- **Versioned.** Every publish and every in-reader edit is a new immutable version.\n  The History panel shows who changed what; any version restores.\n- **Markdown stays Markdown.** A Markdown push is not lossily converted to HTML — the\n  original `.md` is the source of truth and round-trips on download.\n- **Private by default.** Nothing is public until you flip it. Three share modes:\n  public (anyone), password-protected (anyone with the password, no login —\n  changing it revokes prior access), or a secret link session-gated to your workspace.\n- **Token-cheap.** Push a large document as a file over the REST API so its bytes\n  never pass back through your agent's context. See [docs/rest-api.md](docs/rest-api.md).\n\n---\n\n## The MCP tools\n\nThe htmlbook MCP server exposes 10 tools. Full reference:\n[docs/mcp-tools.md](docs/mcp-tools.md).\n\n| Tool | Purpose |\n|------|---------|\n| `publish` | Shelve a document (HTML or Markdown) to a hosted URL; new version if it exists |\n| `guide` | Get the authoring contract (hb-doc classes, tokens, components) before composing HTML by hand |\n| `list` | Browse your library, optionally filtered by project |\n| `get` | Fetch a document's metadata + current body (for markdown, the `.md` source) |\n| `search` | Full-text search across everything you've shelved (recall before re-deriving) |\n| `organize` | Set title / tags / path, move between projects, rename |\n| `set_access` | Make a document public, password-protected, or private |\n| `cite` | Get a shareable deep-link to a specific section (heading) of a document |\n| `restore` | Roll a document back to an earlier version |\n| `delete` | Move a document to the trash |\n\n---\n\n## Supported clients\n\n| Client | Auth |\n|--------|------|\n| Claude Code | API key over MCP, or browser login; also REST |\n| Cursor | API key over MCP |\n| Codex CLI | API key over MCP; also REST |\n| claude.ai | OAuth (custom connector) |\n| Claude Desktop | OAuth (custom connector) |\n| Any MCP client | Streamable HTTP + Bearer key or OAuth 2.1 |\n\n---\n\n## Documentation\n\n- [Getting started](docs/getting-started.md) — connect every client, get a key\n- [Publishing](docs/publishing.md) — the three formats, the `publish` tool, examples\n- [Markdown](docs/markdown.md) — source of truth, frontmatter, folder sync\n- [The hb-doc contract](docs/hb-doc-contract.md) — classes, tokens, components\n- [Sharing & access](docs/sharing.md) — public, password, secret links, workspaces\n- [MCP tools reference](docs/mcp-tools.md) — all 10 tools with example calls\n- [REST API](docs/rest-api.md) — `POST /api/docs`, token-cheap file pushes\n- [examples/](examples/) — a report, a dashboard, a folder-sync setup\n\n---\n\nMade by [Streamize](https://github.com/Streamize-llc). Documentation is MIT-licensed;\nhtmlbook itself is a hosted service at [htmlbook.io](https://htmlbook.io).\n",
  "bytes": 7535,
  "sha": "4a1e91c99b83ffd3804340533949976a7d5b7305c2fa566f066a68f9287d0e53",
  "repo_slug": "streamize-llc/htmlbook",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_streamize_llc_htmlbook_4e893ad1/readme"
}