htmlhost-mcp 1.7.0 → 1.8.0

package/README.md

@@ -97,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`
 
@@ -142,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`
 
@@ -151,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`
 

package/package.json

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

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.7.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 {
@@ -70,7 +101,9 @@ export function createServer() {
       "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.",
+      "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.",
   });
 
   // -------------------------------------------------------------------
@@ -189,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')"),
       }),
@@ -217,6 +250,7 @@ export function createServer() {
           mimeType: a.mimeType,
           sizeBytes: a.sizeBytes,
         })),
+        ...siteKeys(data),
       };
     })
   );
@@ -289,6 +323,7 @@ export function createServer() {
         directory: destDir,
         version: data.version,
         files: written,
+        ...siteKeys(data),
       };
     })
   );
@@ -318,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
   // -------------------------------------------------------------------