htmlhost-mcp 1.5.0 → 1.7.0

package/README.md

@@ -4,6 +4,14 @@ An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that l
 
 Works with **Cursor**, **Claude Desktop**, **Windsurf**, **Cline**, **Zed**, and any MCP-compatible tool.
 
+**Using Claude with saved htmlhost projects?** Open [htmlhost in Claude’s directory](https://claude.ai/directory/htmlhost), choose **Connect**, then sign in to htmlhost and approve. Enable htmlhost in your chat; the same connection works on web and mobile. No npm install or server URL is needed. The setup below is for coding tools working with local files.
+
+## Editing contract
+
+The server sends clients instructions to follow **inspect → stage → validate → repair → deploy**, with matching guidance on its pull and deploy tools. Read the [agent guide](https://htmlhost.co/agents.md) before editing. Preserve separate project files and shared header/footer markers, inherit the existing design on new pages, and validate desktop/mobile rendering with the client's own tools. Report checks that could not run.
+
+MCP tools manage hosting; they do not execute the browser editor's validation loop. Update an existing project by deploying its complete folder with its slug, rather than sending one generated HTML file.
+
 ## Setup
 
 ### 1. Install
@@ -126,7 +134,7 @@ ttl       (optional)  Time-to-live: 1d, 7d, 30d, or never
 
 ### `list_sites`
 
-Returns all your sites, their URLs, sizes, TTLs, and plan usage, plus `shared`: the sites shared with you as a collaborator, with their owner. You can pull, deploy to and restore those with your own key; only the owner can delete them.
+Returns all your sites, their URLs, sizes, TTLs, and plan usage, plus `shared`: the sites shared with you, with their owner and your `role` (`admin`, `editor`, `contributor` or `viewer`). Admins and Editors pull, deploy to and restore those with your own key; Contributors pull and save drafts but can't publish; Viewers can't change them. Only the owner can delete a site.
 
 ### `get_site`
 
@@ -206,3 +214,15 @@ echo '{"jsonrpc":"2.0","method":"initialize","params":{"capabilities":{}},"id":1
 ## License
 
 MIT
+
+
+## Unpublished sites and drafts
+
+Unpublished websites remain private until publishing is explicitly confirmed. Admins and Editors on a shared site can publish with confirmation and unpublish; Contributors save drafts only. The server also cancels deployments still running when someone unpublishes.
+
+- `deploy` / `deploy_html`: use `isDraft: true` to save without changing publication. To publish an unpublished site, obtain the user's explicit agreement to make it public, then pass `confirmPublish: true`.
+- `restore_version` also requires `confirmPublish: true` for an unpublished website; its general `confirm` argument is insufficient.
+- Never automatically retry a publication refusal with confirmation enabled. Older clients are safely blocked by the server.
+- `unpublish_site`: owner only; pass `confirm: true` after agreement to take the site offline.
+- `list_sites` returns `isPublished` and `draftVersion` for owned and shared sites.
+- `pull_site` defaults to `source: "working"` (including the saved draft). Use `source: "published"` only to deliberately retrieve last-deployed files, or `source: "draft"` to require a draft.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "htmlhost-mcp",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "MCP server for htmlhost.co — deploy, list, and manage sites from AI coding tools",
   "type": "module",
   "bin": {
@@ -33,5 +33,8 @@
   "dependencies": {
     "@modelcontextprotocol/server": "^2.1.0",
     "zod": "^4.6.5"
+  },
+  "scripts": {
+    "test": "node --experimental-test-module-mocks --test test/"
   }
 }

package/src/api.mjs

@@ -14,7 +14,7 @@ import { createHash } from "node:crypto";
 // ---------------------------------------------------------------------------
 const CONFIG_PATH = join(homedir(), ".htmlhostrc");
 /** Sent with every request, so the API can tell which version is calling. Kept in step with server.mjs. */
-export const CLIENT_VERSION = "1.5.0";
+export const CLIENT_VERSION = "1.7.0";
 const DEFAULT_API = "https://htmlhost.co";
 
 export function readConfig() {
@@ -79,7 +79,7 @@ export async function apiGet(path) {
   return withRetry(async () => {
     const res = await fetch(`${getApi()}${path}`, { headers: headers() });
     const data = await res.json();
-    if (!res.ok) throw new ApiError(data.error || `HTTP ${res.status}`, res.status);
+    if (!res.ok) throw new ApiError(data.code === "PUBLICATION_CONFIRMATION_REQUIRED" ? `${data.error} Ask the user for explicit permission before retrying with confirmPublish: true, or use isDraft: true.` : data.error || `HTTP ${res.status}`, res.status);
     return data;
   }, `GET ${path}`);
 }
@@ -92,9 +92,9 @@ export async function apiPost(path, body) {
       body: JSON.stringify(body),
     });
     const data = await res.json();
-    if (!res.ok) throw new ApiError(data.error || `HTTP ${res.status}`, res.status);
+    if (!res.ok) throw new ApiError(data.code === "PUBLICATION_CONFIRMATION_REQUIRED" ? `${data.error} Ask the user for explicit permission before retrying with confirmPublish: true, or use isDraft: true.` : data.error || `HTTP ${res.status}`, res.status);
     return data;
-  }, `POST ${path}`);
+  }, `POST ${path}`, body?.confirmPublish === true ? 1 : 3);
 }
 
 export async function apiDelete(path) {
@@ -104,7 +104,7 @@ export async function apiDelete(path) {
       headers: headers(),
     });
     const data = await res.json();
-    if (!res.ok) throw new ApiError(data.error || `HTTP ${res.status}`, res.status);
+    if (!res.ok) throw new ApiError(data.code === "PUBLICATION_CONFIRMATION_REQUIRED" ? `${data.error} Ask the user for explicit permission before retrying with confirmPublish: true, or use isDraft: true.` : data.error || `HTTP ${res.status}`, res.status);
     return data;
   }, `DELETE ${path}`);
 }
@@ -182,7 +182,7 @@ export function pagePathForFile(relativePath) {
  * Deploy a directory to htmlhost. Non-interactive version of CLI deploy.
  * Returns { slug, url, version, pageCount }.
  */
-export async function deployDirectory(dirPath, { slug = null, title = null, ttl = null } = {}) {
+export async function deployDirectory(dirPath, { slug = null, title = null, ttl = null, confirmPublish = false, isDraft = false } = {}) {
   const resolvedDir = resolve(dirPath);
   const allFiles = findAllFiles(resolvedDir, resolvedDir);
 
@@ -248,7 +248,7 @@ export async function deployDirectory(dirPath, { slug = null, title = null, ttl
 
   // Final deploy. A root `_redirects` file (Netlify style) replaces the site's
   // redirects from this file; rules added in the dashboard stay. No file, no change.
-  const body = { pages: pagePayloads, assets: assetPayloads };
+  const body = { pages: pagePayloads, assets: assetPayloads, confirmPublish, isDraft };
   const redirectsPath = join(resolvedDir, "_redirects");
   if (existsSync(redirectsPath)) body.redirects = readFileSync(redirectsPath, "utf8");
   if (ttl) body.ttl = ttl;
@@ -262,11 +262,11 @@ export async function deployDirectory(dirPath, { slug = null, title = null, ttl
 /**
  * Deploy a single HTML file. Non-interactive version of CLI deploy.
  */
-export async function deploySingleFile(filePath, { slug = null, title = null, ttl = null } = {}) {
+export async function deploySingleFile(filePath, { slug = null, title = null, ttl = null, confirmPublish = false, isDraft = false } = {}) {
   const resolvedPath = resolve(filePath);
   const html = readFileSync(resolvedPath, "utf8");
 
-  const body = { html };
+  const body = { html, confirmPublish, isDraft };
   if (ttl) body.ttl = ttl;
   if (slug) body.slug = slug;
   if (title) body.title = title;

package/src/server.mjs

@@ -63,6 +63,14 @@ export function createServer() {
   const server = new McpServer({
     name: "htmlhost",
     version: VERSION,
+  }, {
+    instructions: "Read https://htmlhost.co/agents.md before building or editing a site. " +
+      "For existing sites: pull current files into a safe working directory, inspect source and the existing design, stage precise edits, validate, repair failures, then deploy. " +
+      "For focused edits, inspect the element, parent layout and relevant styles first; expand investigation as needed without skipping validation. " +
+      "When resuming staged work, verify the original project is unchanged and retain validation failures; never treat a pause as successful completion. " +
+      "Keep HTML/CSS/JS as separate files. New pages inherit the site's design, header, footer and dependencies; preserve shared markers and synchronize shared copies. " +
+      "Check references, forms and desktop/mobile rendering with your own tools, and disclose unavailable checks. A frozen static render cannot verify animation playback. These hosting tools do not run the editor's validation loop. " +
+      "Deploy the complete project folder with the existing slug when updating; do not replace a multi-file site with deploy_html or a lone HTML file.",
   });
 
   // -------------------------------------------------------------------
@@ -75,6 +83,7 @@ export function createServer() {
       description:
         "Deploy a file or directory to htmlhost.co. " +
         "Pass an absolute path to a directory (deploys all files) or a single HTML file. " +
+        "Inspect and validate changes before deploying. For an existing multi-file site, deploy its complete folder with slug to preserve its pages and assets. " +
         "Optionally set slug (to update an existing site), title, and ttl. " +
         "A `_redirects` file at the directory's root (one `/old /new [301|302]` per line) sets the site's redirects and isn't published.",
       inputSchema: z.object({
@@ -82,16 +91,18 @@ export function createServer() {
         slug: z.string().optional().describe("Existing site slug to update (omit to create a new site)"),
         title: z.string().optional().describe("Title for the site"),
         ttl: z.string().optional().describe("Time-to-live: 1d, 7d, 30d, or never"),
+        isDraft: z.boolean().optional().describe("Save files as a draft without publishing. Does not unpublish a live site."),
+        confirmPublish: z.boolean().optional().describe("Set true ONLY after the user explicitly agrees to make an unpublished website public. Ordinary editing or deploy instructions are not confirmation."),
       }),
     },
-    wrap(async ({ path, slug, title, ttl }) => {
+    wrap(async ({ path, slug, title, ttl, isDraft, confirmPublish }) => {
       if (!isLoggedIn()) return NOT_SIGNED_IN;
 
       const resolvedPath = resolve(path);
       if (!existsSync(resolvedPath)) return `Path not found: ${path}`;
 
       const stat = statSync(resolvedPath);
-      const opts = { slug, title, ttl };
+      const opts = { slug, title, ttl, isDraft, confirmPublish };
 
       let data;
       if (stat.isDirectory()) {
@@ -102,7 +113,9 @@ export function createServer() {
 
       const pc = data.pageCount || 1;
       return {
-        message: "Deployed successfully",
+        message: data.isPublished === false ? "Saved as an unpublished draft" : isDraft ? "Draft saved; live site unchanged" : "Deployed successfully",
+        isPublished: data.isPublished,
+        draftVersion: data.draftVersion,
         url: `https://${data.url}`,
         slug: data.slug,
         version: data.version,
@@ -122,9 +135,11 @@ export function createServer() {
     {
       title: "List sites",
       description:
-        "List the authenticated user's sites on htmlhost.co, and the sites shared with them as a collaborator (`shared`). " +
+        "List the authenticated user's sites on htmlhost.co, and the sites shared with them (`shared`, with the user's `role`). " +
         "Returns slug, URL, title, size, TTL, and expiration for each site. " +
-        "Shared sites can be pulled, deployed to and restored with this key like your own, but only their owner can delete them.",
+        "On a shared site the role decides: admin and editor pull, deploy and restore; contributor pulls and saves drafts " +
+        "(isDraft: true) but can't publish, so ask the owner, an admin or an editor to publish; viewer changes nothing. " +
+        "Only the owner can delete a site.",
       inputSchema: z.object({}),
     },
     wrap(async () => {
@@ -138,6 +153,8 @@ export function createServer() {
         size: s.size,
         ttl: s.ttl,
         isMultiPage: s.isMultiPage,
+        isPublished: s.isPublished,
+        draftVersion: s.draftVersion,
         expiresAt: s.expiresAt || null,
       }));
 
@@ -146,7 +163,12 @@ export function createServer() {
         url: `https://${s.slug}.htmlhost.co`,
         title: s.title || null,
         owner: s.owner || null,
+        role: s.role || "editor",
+        canEdit: s.canEdit ?? true,
+        canPublish: s.canPublish ?? true,
         isMultiPage: s.isMultiPage,
+        isPublished: s.isPublished,
+        draftVersion: s.draftVersion,
         expiresAt: s.expiresAt || null,
       }));
 
@@ -183,6 +205,9 @@ export function createServer() {
         url: `https://${cleanSlug}.htmlhost.co`,
         version: data.version,
         updatedAt: data.updatedAt,
+        isPublished: data.isPublished,
+        draftVersion: data.draftVersion,
+        source: data.source,
         pages: (data.pages || []).map((p) => ({
           path: p.path,
           sizeBytes: p.sizeBytes || (p.html ? Buffer.byteLength(p.html) : 0),
@@ -205,20 +230,22 @@ export function createServer() {
       title: "Pull site to local directory",
       description:
         "Download all pages and assets from a deployed htmlhost site into a local directory. " +
-        "Creates the directory if it doesn't exist.",
+        "Creates the directory if it doesn't exist; existing files may be overwritten, so use a fresh directory when local work must be preserved. " +
+        "Read https://htmlhost.co/agents.md, inspect the downloaded source and design, then validate staged edits before deploying the complete folder.",
       inputSchema: z.object({
         slug: z.string().describe("The site slug to pull"),
         directory: z.string().describe("Absolute path to the local directory to write files into"),
+        source: z.enum(["working", "draft", "published"]).optional().describe("Default working includes the latest saved draft. published explicitly retrieves the last deployed files."),
       }),
     },
-    wrap(async ({ slug, directory }) => {
+    wrap(async ({ slug, directory, source = "working" }) => {
       if (!isLoggedIn()) return NOT_SIGNED_IN;
 
       const cleanSlug = slug.replace(/\.htmlhost\.co$/, "");
       const destDir = resolve(directory);
       mkdirSync(destDir, { recursive: true });
 
-      const data = await apiGet(`/api/sites/pull?slug=${encodeURIComponent(cleanSlug)}`);
+      const data = await apiGet(`/api/sites/pull?slug=${encodeURIComponent(cleanSlug)}&source=${source}`);
       const written = [];
 
       // Write pages
@@ -256,6 +283,9 @@ export function createServer() {
 
       return {
         message: `Pulled ${written.length} files from ${cleanSlug}.htmlhost.co`,
+        source: data.source,
+        isPublished: data.isPublished,
+        draftVersion: data.draftVersion,
         directory: destDir,
         version: data.version,
         files: written,
@@ -333,18 +363,20 @@ export function createServer() {
       title: "Deploy HTML content",
       description:
         "Deploy raw HTML content directly (no local files needed). " +
-        "Useful when an AI generates HTML and wants to deploy it immediately.",
+        "For standalone single-page output after validation. Do not use this to edit an existing multi-page or multi-asset project: pull_site, edit and validate locally, then deploy the complete folder with its slug.",
       inputSchema: z.object({
         html: z.string().describe("The HTML content to deploy"),
         slug: z.string().optional().describe("Existing site slug to update (omit to create new)"),
         title: z.string().optional().describe("Title for the site"),
         ttl: z.string().optional().describe("Time-to-live: 1d, 7d, 30d, or never"),
+        isDraft: z.boolean().optional().describe("Save files as a draft without publishing. Does not unpublish a live site."),
+        confirmPublish: z.boolean().optional().describe("Set true ONLY after the user explicitly agrees to make an unpublished website public. Ordinary editing or deploy instructions are not confirmation."),
       }),
     },
-    wrap(async ({ html, slug, title, ttl }) => {
+    wrap(async ({ html, slug, title, ttl, isDraft, confirmPublish }) => {
       if (!isLoggedIn()) return NOT_SIGNED_IN;
 
-      const body = { html };
+      const body = { html, isDraft, confirmPublish };
       if (slug) body.slug = slug;
       if (title) body.title = title;
       if (ttl) body.ttl = ttl;
@@ -352,7 +384,9 @@ export function createServer() {
       const data = await apiPost("/api/sites", body);
 
       return {
-        message: "Deployed successfully",
+        message: data.isPublished === false ? "Saved as an unpublished draft" : isDraft ? "Draft saved; live site unchanged" : "Deployed successfully",
+        isPublished: data.isPublished,
+        draftVersion: data.draftVersion,
         url: `https://${data.url}`,
         slug: data.slug,
         version: data.version,
@@ -383,6 +417,16 @@ export function createServer() {
     })
   );
 
+  server.registerTool("unpublish_site", {
+    title: "Unpublish a website",
+    description: "For the owner, an admin or an editor: stop public serving while retaining files, saved drafts and history. Obtain the user's explicit confirmation first.",
+    inputSchema: z.object({ slug: z.string(), confirm: z.boolean().describe("True only after the user agrees to take this website offline") }),
+  }, wrap(async ({ slug, confirm }) => {
+    if (!isLoggedIn()) return NOT_SIGNED_IN;
+    if (confirm !== true) return "Unpublish not confirmed.";
+    return apiPost(`/api/sites/${encodeURIComponent(slug.replace(/\.htmlhost\.co$/, ""))}/unpublish`, {});
+  }));
+
   // -------------------------------------------------------------------
   // Tool: restore_version
   // -------------------------------------------------------------------
@@ -397,13 +441,14 @@ export function createServer() {
         slug: z.string().describe("The site slug"),
         version: z.number().int().positive().describe("The version number to restore (from list_versions)"),
         confirm: z.boolean().describe("Must be true to confirm replacing the live site"),
+        confirmPublish: z.boolean().optional().describe("For unpublished sites, set true only after the user explicitly agrees to make the website public again."),
       }),
     },
-    wrap(async ({ slug, version, confirm }) => {
+    wrap(async ({ slug, version, confirm, confirmPublish }) => {
       if (!isLoggedIn()) return NOT_SIGNED_IN;
       if (!confirm) return "Restore not confirmed. Set confirm to true to proceed.";
       const cleanSlug = slug.replace(/\.htmlhost\.co$/, "");
-      const data = await apiPost(`/api/sites/${encodeURIComponent(cleanSlug)}/versions/${version}/restore`, {});
+      const data = await apiPost(`/api/sites/${encodeURIComponent(cleanSlug)}/versions/${version}/restore`, { confirmPublish });
       return {
         message: `Restored v${version}; it's live as v${data.version}.`,
         url: data.url ? (String(data.url).startsWith("http") ? data.url : `https://${data.url}`) : `https://${cleanSlug}.htmlhost.co`,