htmlhost-mcp 1.6.0 → 1.8.0

package/README.md

@@ -4,6 +4,8 @@ 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.
@@ -95,13 +97,15 @@ 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 your sites and the ones shared with you |
-| `get_site` | Get details about a specific site (pages, assets, version) |
+| `get_site` | Get details about a specific site (pages, assets, version, keys, secure calls, collections) |
 | `pull_site` | Download a site's files to a local directory |
 | `delete_site` | Permanently delete a site |
 | `login` | Sign in: opens an approval page in your browser |
 | `whoami` | Show the current authenticated user |
 | `list_versions` | List a site's published versions and what each changed |
 | `restore_version` | Make an earlier version live again (Pro) |
+| `set_site_key` | Save a key the user gave you to a site's Keys (public or secret) |
+| `remove_site_key` | Remove a key from a site's Keys |
 
 ### `deploy`
 
@@ -132,7 +136,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`
 
@@ -140,7 +144,37 @@ Returns all your sites, their URLs, sizes, TTLs, and plan usage, plus `shared`:
 slug      (required)  The site slug
 ```
 
-Returns version, page routes, asset paths and sizes.
+Returns version, page routes, asset paths and sizes. When the site has them, also:
+
+- `keys`: the keys its owner saved for the services it uses, each with its `name`, `kind` (`public` or `secret`) and note. Only public keys carry a `value`; a secret key's value is never sent.
+- `secureCalls`: how a page uses a secret key. Each has a `name`, the `path` a page POSTs to (`/__hh/call/<name>`), the `fields` it may send and the parts of the answer it `returns`.
+- `collections`: the site's own data. Each has a `name`, its `path` (`/__hh/data/<name>`), its `fields` and its `read`/`add` rules. Records are never listed.
+
+For questions about sign-in, members or private pages, the [agent guide](https://htmlhost.co/agents.md) has a Sign-in and access control section: htmlhost has a whole-site password (Pro) and team accounts, and individual visitor accounts use a browser sign-in service.
+
+Secure calls and collections are set up in the site's dashboard (Keys and Data tabs). Keys can also be saved from your AI tool (below). See [Site keys](https://htmlhost.co/agents.md) in the agent guide, and the guides on [payments](https://htmlhost.co/guides/accept-payments-on-your-website), [API keys](https://htmlhost.co/guides/use-api-keys-safely-on-your-website) and [collections](https://htmlhost.co/guides/add-a-database-to-your-website).
+
+### `set_site_key`
+
+```
+slug          (required)  The site slug
+name          (required)  The key's name, e.g. STRIPE_SECRET_KEY
+value         (required)  The key's value, exactly as the user gave it
+kind          (optional)  public or secret: only if the user said which
+note          (optional)  What it's for
+confirmPublic (optional)  Only after the user confirms a secret-looking value should be public
+```
+
+Adds the key, or replaces the value of a key with that name. Without `kind`, htmlhost works it out from the value (`sk_…` secret, `pk_…` public, and similar formats) or the name. When it can't tell, it refuses with `KEY_KIND_UNKNOWN`, and the tool asks the user. Saving a secret-looking value as public is refused with `KEY_LOOKS_SECRET` until the user confirms. The site's owner or an Admin only, on Pro. The result never contains the value.
+
+### `remove_site_key`
+
+```
+slug   (required)  The site slug
+name   (required)  The key's name
+```
+
+Removes the key. Refused while a secure call uses it.
 
 ### `pull_site`
 
@@ -149,7 +183,7 @@ slug      (required)  The site slug to pull
 directory (required)  Absolute path to write files into
 ```
 
-Downloads all pages and assets into the specified directory.
+Downloads all pages and assets into the specified directory. The result includes the same `keys`, `secureCalls` and `collections` as `get_site`.
 
 ### `delete_site`
 
@@ -216,7 +250,7 @@ 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.
+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.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "htmlhost-mcp",
-  "version": "1.6.0",
-  "description": "MCP server for htmlhost.co \u2014 deploy, list, and manage sites from AI coding tools",
+  "version": "1.8.0",
+  "description": "MCP server for htmlhost.co — deploy, list, and manage sites from AI coding tools",
   "type": "module",
   "bin": {
     "htmlhost-mcp": "bin/htmlhost-mcp.mjs"

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.6.0";
+export const CLIENT_VERSION = "1.8.0";
 const DEFAULT_API = "https://htmlhost.co";
 
 export function readConfig() {
@@ -54,6 +54,13 @@ class ApiError extends Error {
   }
 }
 
+/** An error's message for the AI tool: a key refusal carries its code (KEY_KIND_UNKNOWN…), which the tool descriptions name. */
+function errorText(data, status) {
+  if (data.code === "PUBLICATION_CONFIRMATION_REQUIRED") return `${data.error} Ask the user for explicit permission before retrying with confirmPublish: true, or use isDraft: true.`;
+  if (typeof data.code === "string" && /^KEYS?_/.test(data.code)) return `${data.code}: ${data.error}`;
+  return data.error || `HTTP ${status}`;
+}
+
 function headers(extra = {}) {
   const token = getToken();
   if (!token) throw new ApiError("Not signed in to htmlhost. Call the `login` tool: it opens an approval page in the user's browser.", 0);
@@ -79,7 +86,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.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);
+    if (!res.ok) throw new ApiError(errorText(data, res.status), res.status);
     return data;
   }, `GET ${path}`);
 }
@@ -92,7 +99,7 @@ export async function apiPost(path, body) {
       body: JSON.stringify(body),
     });
     const data = await res.json();
-    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);
+    if (!res.ok) throw new ApiError(errorText(data, res.status), res.status);
     return data;
   }, `POST ${path}`, body?.confirmPublish === true ? 1 : 3);
 }
@@ -104,7 +111,7 @@ export async function apiDelete(path) {
       headers: headers(),
     });
     const data = await res.json();
-    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);
+    if (!res.ok) throw new ApiError(errorText(data, res.status), res.status);
     return data;
   }, `DELETE ${path}`);
 }

package/src/server.mjs

@@ -41,6 +41,37 @@ const VERSION = CLIENT_VERSION;
 let updateNotice = null;
 let updateNoticeShown = false;
 
+/**
+ * The keys a site's owner saved for the services it uses, as the server sends
+ * them: every key's name and kind, and the value of public keys only. A
+ * secret's value is never sent. Nothing is added for a site without keys.
+ */
+export function siteKeys(data) {
+  const keys = Array.isArray(data?.keys) ? data.keys : [];
+  const calls = Array.isArray(data?.calls) ? data.calls : [];
+  const collections = Array.isArray(data?.collections) ? data.collections : [];
+  if (!keys.length && !calls.length && !collections.length) return {};
+  return {
+    keys,
+    ...(calls.length ? {
+      secureCalls: calls,
+      secureCallsNote:
+        "A secure call is how page code uses a secret key: htmlhost makes the call. From a page of the site, fetch(call.path, { method: \"POST\", headers: { \"Content-Type\": \"application/json\" }, body: JSON.stringify({ ...its fields }) }) " +
+        "and read { ok, status, data, error }. Calls work on the published site only. See https://htmlhost.co/agents.md (Secure calls).",
+    } : {}),
+    ...(collections.length ? {
+      collections,
+      collectionsNote:
+        "The site's own data. A page reads a collection whose read rule is public with fetch(collection.path) → { ok, records, next }, and adds to one whose add rule is public with " +
+        "POST JSON of its fields → { ok, record, error }. Records are never listed here. Collections work on the published site only. See https://htmlhost.co/agents.md (Collections).",
+    } : {}),
+    keysNote:
+      "A public key's value may be written into the site's pages exactly as given. " +
+      "Never write, guess or ask the user to paste a secret key's value into any site file: every visitor can read a site's files. Refer to a secret key by its name only, " +
+      "and say plainly when a request needs a step that can't run from the page. When the user gives you a key, save it with set_site_key (htmlhost works out public or secret, and asks you to check with the user only when it can't).",
+  };
+}
+
 function wrap(fn) {
   return async (args) => {
     try {
@@ -69,8 +100,10 @@ export function createServer() {
       "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.",
+      "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. " +
+      "get_site and pull_site list the site's keys (payment, mailing-list and other service keys its owner saved) and its secure calls: use a public key's value as given, never put a secret key's value in a site file, use a secret key only through a secure call, and use the site's collections only as their read/add rules allow. " +
+      "For questions about login, members or private pages, answer from the agent guide's Sign-in and access control section: htmlhost has a whole-site password (Pro) and team accounts, not individual visitor accounts; those use a browser sign-in service such as Clerk, Auth0, Firebase Authentication or Supabase Auth.",
   });
 
   // -------------------------------------------------------------------
@@ -135,9 +168,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 () => {
@@ -161,6 +196,9 @@ 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,
@@ -184,7 +222,7 @@ export function createServer() {
     {
       title: "Get site details",
       description:
-        "Get detailed information about a specific site including its pages and assets.",
+        "Get detailed information about a specific site including its pages and assets, the keys its owner saved for the services it uses (names, and the values of public keys only), its secure calls, and its collections (shapes and rules, never records).",
       inputSchema: z.object({
         slug: z.string().describe("The site slug (e.g. 'my-site')"),
       }),
@@ -212,6 +250,7 @@ export function createServer() {
           mimeType: a.mimeType,
           sizeBytes: a.sizeBytes,
         })),
+        ...siteKeys(data),
       };
     })
   );
@@ -284,6 +323,7 @@ export function createServer() {
         directory: destDir,
         version: data.version,
         files: written,
+        ...siteKeys(data),
       };
     })
   );
@@ -313,6 +353,62 @@ export function createServer() {
     })
   );
 
+  // -------------------------------------------------------------------
+  // Tools: set_site_key, remove_site_key (the site's Keys; site-keys.ts)
+  // -------------------------------------------------------------------
+  server.registerTool(
+    "set_site_key",
+    {
+      title: "Save site key",
+      description:
+        "Save a key the user gave you (a payment gateway's, a mailing list's, an analytics ID) to a site's Keys, by name, so its pages and secure calls can use it. " +
+        "Adds it, or replaces the value of a key with that name. Leave kind out unless the user said which it is: htmlhost works it out from the value " +
+        "(sk_… secret, pk_… public, and similar) and, when it can't, refuses with KEY_KIND_UNKNOWN: then ask the user whether it's public or secret and call again with kind. " +
+        "A secret-looking value saved as public is refused with KEY_LOOKS_SECRET unless the user confirms (confirmPublic: true). " +
+        "The site's owner or an Admin only, on Pro. The result never holds the value: never repeat a secret back to the user, and never write one into a site file.",
+      inputSchema: z.object({
+        slug: z.string().describe("The site slug"),
+        name: z.string().describe("The key's name, e.g. STRIPE_SECRET_KEY (stored in UPPER_SNAKE_CASE)"),
+        value: z.string().describe("The key's value, exactly as the user gave it"),
+        kind: z.enum(["public", "secret"]).optional().describe("Only if the user said which it is; otherwise leave out and htmlhost decides or asks you to check"),
+        note: z.string().optional().describe("What the key is for, in a few words"),
+        confirmPublic: z.boolean().optional().describe("Only after the user confirms a secret-looking value should be public"),
+      }),
+    },
+    wrap(async ({ slug, name, value, kind, note, confirmPublic }) => {
+      if (!isLoggedIn()) return NOT_SIGNED_IN;
+      const cleanSlug = slug.replace(/\.htmlhost\.co$/, "");
+      const data = await apiPost(`/api/sites/${encodeURIComponent(cleanSlug)}/keys`, { name, value, kind, note, confirmPublic });
+      return {
+        slug: cleanSlug,
+        name: data.key.name,
+        kind: data.key.kind,
+        created: data.created,
+        message: data.key.kind === "secret"
+          ? `Saved ${data.key.name} as a secret key. Its value is never shown again; pages use it only through a secure call.`
+          : `Saved ${data.key.name} as a public key. Pages may use its value as given.`,
+      };
+    })
+  );
+
+  server.registerTool(
+    "remove_site_key",
+    {
+      title: "Remove site key",
+      description: "Remove a key from a site's Keys by name, when the user asks. Refused while a secure call uses it. The site's owner or an Admin only.",
+      inputSchema: z.object({
+        slug: z.string().describe("The site slug"),
+        name: z.string().describe("The key's name"),
+      }),
+    },
+    wrap(async ({ slug, name }) => {
+      if (!isLoggedIn()) return NOT_SIGNED_IN;
+      const cleanSlug = slug.replace(/\.htmlhost\.co$/, "");
+      const data = await apiDelete(`/api/sites/${encodeURIComponent(cleanSlug)}/keys?name=${encodeURIComponent(name)}`);
+      return { slug: cleanSlug, name, removed: data.removed, message: data.removed ? `Removed ${name}.` : `${cleanSlug} has no key named ${name}.` };
+    })
+  );
+
   // -------------------------------------------------------------------
   // Tool: whoami
   // -------------------------------------------------------------------
@@ -414,7 +510,7 @@ 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.",
+    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;