htmlhost-mcp 1.4.0 → 1.6.0

package/README.md

@@ -4,6 +4,12 @@ An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that l
 
 Works with **Cursor**, **Claude Desktop**, **Windsurf**, **Cline**, **Zed**, and any MCP-compatible tool.
 
+## 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
@@ -88,7 +94,7 @@ htmlhost-mcp
 |---|---|
 | `deploy` | Deploy a local file or directory to htmlhost.co |
 | `deploy_html` | Deploy raw HTML content directly (no local files needed) |
-| `list_sites` | List all your sites |
+| `list_sites` | List your sites and the ones shared with you |
 | `get_site` | Get details about a specific site (pages, assets, version) |
 | `pull_site` | Download a site's files to a local directory |
 | `delete_site` | Permanently delete a site |
@@ -126,7 +132,7 @@ ttl       (optional)  Time-to-live: 1d, 7d, 30d, or never
 
 ### `list_sites`
 
-Returns all sites, their URLs, sizes, TTLs, and plan usage.
+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.
 
 ### `get_site`
 
@@ -206,3 +212,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. Collaborators can publish with confirmation; only owners can unpublish. 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,7 +1,7 @@
 {
   "name": "htmlhost-mcp",
-  "version": "1.4.0",
-  "description": "MCP server for htmlhost.co — deploy, list, and manage sites from AI coding tools",
+  "version": "1.6.0",
+  "description": "MCP server for htmlhost.co \u2014 deploy, list, and manage sites from AI coding tools",
   "type": "module",
   "bin": {
     "htmlhost-mcp": "bin/htmlhost-mcp.mjs"
@@ -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

@@ -5,7 +5,7 @@
  * so signing in once (the `login` tool or `htmlhost login`) covers both.
  */
 import { readFileSync, writeFileSync, statSync, readdirSync, mkdirSync, existsSync } from "node:fs";
-import { join, basename, dirname, resolve } from "node:path";
+import { join, basename, dirname, resolve, sep } from "node:path";
 import { homedir } from "node:os";
 import { createHash } from "node:crypto";
 
@@ -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.4.0";
+export const CLIENT_VERSION = "1.6.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}`);
 }
@@ -161,7 +161,8 @@ export function findAllFiles(baseDir, currentDir) {
     } else if (entry.isFile()) {
       let size;
       try { size = statSync(fullPath).size; } catch { continue; }
-      results.push({ filePath: fullPath, relativePath: fullPath.slice(baseDir.length + 1), size });
+      // Always with "/" (Windows paths have "\", an address no browser can ask for).
+      results.push({ filePath: fullPath, relativePath: fullPath.slice(baseDir.length + 1).split(sep).join("/"), size });
     }
   }
   return results;
@@ -181,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);
 
@@ -247,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;
@@ -261,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. 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,8 +135,9 @@ export function createServer() {
     {
       title: "List sites",
       description:
-        "List all sites owned by the authenticated user on htmlhost.co. " +
-        "Returns slug, URL, title, size, TTL, and expiration for each site.",
+        "List the authenticated user's sites on htmlhost.co, and the sites shared with them as a collaborator (`shared`). " +
+        "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.",
       inputSchema: z.object({}),
     },
     wrap(async () => {
@@ -137,6 +151,19 @@ export function createServer() {
         size: s.size,
         ttl: s.ttl,
         isMultiPage: s.isMultiPage,
+        isPublished: s.isPublished,
+        draftVersion: s.draftVersion,
+        expiresAt: s.expiresAt || null,
+      }));
+
+      const shared = (data.shared || []).map((s) => ({
+        slug: s.slug,
+        url: `https://${s.slug}.htmlhost.co`,
+        title: s.title || null,
+        owner: s.owner || null,
+        isMultiPage: s.isMultiPage,
+        isPublished: s.isPublished,
+        draftVersion: s.draftVersion,
         expiresAt: s.expiresAt || null,
       }));
 
@@ -144,6 +171,7 @@ export function createServer() {
         count: sites.length,
         usage: data.usage,
         sites,
+        ...(shared.length && { shared }),
       };
     })
   );
@@ -172,6 +200,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),
@@ -194,20 +225,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
@@ -245,6 +278,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,
@@ -322,18 +358,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;
@@ -341,7 +379,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,
@@ -372,6 +412,16 @@ export function createServer() {
     })
   );
 
+  server.registerTool("unpublish_site", {
+    title: "Unpublish a website",
+    description: "Owner only: 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
   // -------------------------------------------------------------------
@@ -386,13 +436,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`,