htmlhost-mcp 1.2.0 → 1.4.0

package/README.md

@@ -12,9 +12,19 @@ Works with **Cursor**, **Claude Desktop**, **Windsurf**, **Cline**, **Zed**, and
 npm install -g htmlhost-mcp
 ```
 
+Or skip installing and use `npx -y htmlhost-mcp@latest` as the command, which fetches the newest version each
+time your AI tool starts the server.
+
+**Updates:** the server checks npm once a day. A global install updates itself in the background (restart your
+AI tool to load it), and the first tool result of a session tells your AI tool when a newer version exists. With
+npx, keep `@latest` in the command: a bare `npx -y htmlhost-mcp` keeps reusing its cached copy. Set
+`HTMLHOST_NO_UPDATE_CHECK=1` to turn the check off.
+
 ### 2. Authenticate
 
-The MCP server reuses the same token as the CLI. If you've already run `htmlhost login`, you're set.
+Nothing to do up front: the first time your AI tool needs your account, it calls the `login` tool, which opens an
+approval page in your browser. Check the code matches and click Approve. The server shares its token with the CLI, so
+if you've already run `htmlhost login`, you're set. You can also sign in from a terminal:
 
 ```bash
 npx htmlhost-cli login
@@ -82,6 +92,7 @@ htmlhost-mcp
 | `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 |
+| `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) |
@@ -141,6 +152,11 @@ slug      (required)  The site slug to delete
 confirm   (required)  Must be true — safety check
 ```
 
+### `login`
+
+Signs in to your htmlhost.co account. Opens an approval page in your browser and waits briefly; if you haven't
+approved yet, it returns the link and code, and your AI tool calls it again once you have.
+
 ### `whoami`
 
 Returns the authenticated user's email, name, handle, and plan.

package/package.json

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

package/src/api.mjs

@@ -2,7 +2,7 @@
  * API client for the htmlhost MCP server.
  *
  * Reuses the same ~/.htmlhostrc token and API base as the CLI,
- * so `htmlhost login` is the only setup step needed.
+ * 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";
@@ -13,9 +13,11 @@ import { createHash } from "node:crypto";
 // Config (mirrors packages/cli/src/config.mjs)
 // ---------------------------------------------------------------------------
 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";
 const DEFAULT_API = "https://htmlhost.co";
 
-function readConfig() {
+export function readConfig() {
   try {
     return JSON.parse(readFileSync(CONFIG_PATH, "utf8"));
   } catch {
@@ -23,6 +25,13 @@ function readConfig() {
   }
 }
 
+/** Merge keys into ~/.htmlhostrc (shared with the CLI), keeping it readable by its owner only. */
+export function writeConfig(data) {
+  try {
+    writeFileSync(CONFIG_PATH, JSON.stringify({ ...readConfig(), ...data }, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
+  } catch { /* a read-only home: the check just runs again next time */ }
+}
+
 export function getToken() {
   return readConfig().token || null;
 }
@@ -47,8 +56,8 @@ class ApiError extends Error {
 
 function headers(extra = {}) {
   const token = getToken();
-  if (!token) throw new ApiError("Not logged in. Run `htmlhost login` in a terminal first.", 0);
-  return { Authorization: `Bearer ${token}`, "X-HTMLHost-Client": "mcp", ...extra };
+  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);
+  return { Authorization: `Bearer ${token}`, "X-HTMLHost-Client": "mcp", "X-HTMLHost-Client-Version": CLIENT_VERSION, ...extra };
 }
 
 async function withRetry(fn, label = "request", retries = 3) {

package/src/login.mjs

@@ -0,0 +1,93 @@
+/**
+ * The `login` tool: browser-approved sign-in, the same flow as `htmlhost login`
+ * in htmlhost-cli (keep the two in step). It opens the approval page in the
+ * user's browser and waits a little; if they haven't approved yet it returns
+ * the link and code for the AI to show, and the next call picks the same
+ * sign-in up. The token lands in ~/.htmlhostrc, shared with the CLI.
+ * Never writes to stdout (the MCP channel).
+ */
+import { hostname } from "node:os";
+import { exec } from "node:child_process";
+import { readConfig, writeConfig, getApi, getToken, CLIENT_VERSION } from "./api.mjs";
+
+/** How long one call waits for the approval before handing the link back. */
+const CALL_WAIT_MS = 25_000;
+
+function openBrowser(url) {
+  const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? 'start ""' : "xdg-open";
+  exec(`${cmd} "${url}"`, () => {});
+}
+
+async function currentUser() {
+  const token = getToken();
+  if (!token) return null;
+  try {
+    const res = await fetch(`${getApi()}/api/tokens/me`, { headers: { Authorization: `Bearer ${token}`, "X-HTMLHost-Client": "mcp", "X-HTMLHost-Client-Version": CLIENT_VERSION } });
+    return res.ok ? await res.json() : null;
+  } catch {
+    return null;
+  }
+}
+
+async function startLogin() {
+  const res = await fetch(`${getApi()}/api/cli-login`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", "X-HTMLHost-Client": "mcp", "X-HTMLHost-Client-Version": CLIENT_VERSION },
+    body: JSON.stringify({ client: "mcp", deviceName: hostname() }),
+  });
+  if (res.status === 404 || res.status === 405) return null;
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(data.error || `Couldn't start sign-in (HTTP ${res.status}).`);
+  const pending = {
+    deviceCode: data.deviceCode,
+    userCode: data.userCode,
+    verifyUrl: data.verifyUrl,
+    interval: data.interval || 3,
+    expiresAt: Date.now() + (data.expiresIn || 600) * 1000,
+    api: getApi(),
+  };
+  writeConfig({ pendingLogin: pending });
+  openBrowser(pending.verifyUrl);
+  return pending;
+}
+
+/** One call of the tool: the message for the AI. */
+export async function loginStep() {
+  const user = await currentUser();
+  if (user) return `Already signed in to htmlhost as ${user.email}.`;
+
+  const saved = readConfig().pendingLogin;
+  let pending = saved && saved.api === getApi() && saved.expiresAt > Date.now() + 5_000 ? saved : null;
+  if (!pending) {
+    pending = await startLogin();
+    if (!pending) return `This htmlhost server doesn't offer browser sign-in yet. Ask the user to run \`npx htmlhost-cli login\` in a terminal.`;
+  }
+
+  const until = Math.min(pending.expiresAt, Date.now() + CALL_WAIT_MS);
+  let interval = pending.interval * 1000;
+  while (Date.now() < until) {
+    await new Promise((r) => setTimeout(r, interval));
+    let data;
+    try {
+      const res = await fetch(`${getApi()}/api/cli-login/poll`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ deviceCode: pending.deviceCode }),
+      });
+      data = await res.json();
+    } catch {
+      continue;
+    }
+    if (data.status === "approved") {
+      writeConfig({ token: data.token, api: getApi(), pendingLogin: undefined });
+      return `Signed in to htmlhost as ${data.email || "the user's account"}. You can use the htmlhost tools now.`;
+    }
+    if (data.status === "slow_down") interval += 1000;
+    else if (data.status === "denied" || data.status === "expired" || data.status === "too_many_tokens") {
+      writeConfig({ pendingLogin: undefined });
+      if (data.status === "too_many_tokens") return `The user's account has 10 API keys. Ask them to remove one at ${getApi()}/settings#keys, then call login again.`;
+      return data.status === "denied" ? "The user cancelled the sign-in." : "That sign-in expired. Call login again for a new link.";
+    }
+  }
+  return `Not signed in yet. The approval page opened in the user's browser. Ask them to open ${pending.verifyUrl} if it didn't, check it shows the code ${pending.userCode}, and click Approve. Then call login again.`;
+}

package/src/server.mjs

@@ -24,18 +24,32 @@ import {
   findAllFiles,
   pagePathForFile,
   mimeFromExt,
+  CLIENT_VERSION,
 } from "./api.mjs";
+import { checkForUpdate } from "./update.mjs";
+import { loginStep } from "./login.mjs";
 
-const VERSION = "1.2.0";
+/** What every tool says before the user has signed in: the login tool does it, no terminal needed. */
+const NOT_SIGNED_IN = "Not signed in to htmlhost. Call the `login` tool: it opens an approval page in the user's browser.";
+
+const VERSION = CLIENT_VERSION;
 
 /**
  * Helper: wraps a handler to return proper MCP content and catch errors.
  */
+/** An update notice (update.mjs), shown once: with the first tool result after the check finishes. */
+let updateNotice = null;
+let updateNoticeShown = false;
+
 function wrap(fn) {
   return async (args) => {
     try {
       const result = await fn(args);
-      const text = typeof result === "string" ? result : JSON.stringify(result, null, 2);
+      let text = typeof result === "string" ? result : JSON.stringify(result, null, 2);
+      if (updateNotice && !updateNoticeShown) {
+        updateNoticeShown = true;
+        text += `\n\nNote for the user: ${updateNotice}`;
+      }
       return { content: [{ type: "text", text }] };
     } catch (e) {
       return { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true };
@@ -44,6 +58,8 @@ function wrap(fn) {
 }
 
 export function createServer() {
+  // In the background: never delays starting up or a tool call.
+  void checkForUpdate(VERSION).then((notice) => { updateNotice = notice; }).catch(() => {});
   const server = new McpServer({
     name: "htmlhost",
     version: VERSION,
@@ -69,7 +85,7 @@ export function createServer() {
       }),
     },
     wrap(async ({ path, slug, title, ttl }) => {
-      if (!isLoggedIn()) return "Not logged in. Run `htmlhost login` in a terminal first.";
+      if (!isLoggedIn()) return NOT_SIGNED_IN;
 
       const resolvedPath = resolve(path);
       if (!existsSync(resolvedPath)) return `Path not found: ${path}`;
@@ -111,7 +127,7 @@ export function createServer() {
       inputSchema: z.object({}),
     },
     wrap(async () => {
-      if (!isLoggedIn()) return "Not logged in. Run `htmlhost login` in a terminal first.";
+      if (!isLoggedIn()) return NOT_SIGNED_IN;
 
       const data = await apiGet("/api/sites");
       const sites = (data.sites || []).map((s) => ({
@@ -146,7 +162,7 @@ export function createServer() {
       }),
     },
     wrap(async ({ slug }) => {
-      if (!isLoggedIn()) return "Not logged in. Run `htmlhost login` in a terminal first.";
+      if (!isLoggedIn()) return NOT_SIGNED_IN;
 
       const cleanSlug = slug.replace(/\.htmlhost\.co$/, "");
       const data = await apiGet(`/api/sites/pull?slug=${encodeURIComponent(cleanSlug)}&meta=true`);
@@ -185,7 +201,7 @@ export function createServer() {
       }),
     },
     wrap(async ({ slug, directory }) => {
-      if (!isLoggedIn()) return "Not logged in. Run `htmlhost login` in a terminal first.";
+      if (!isLoggedIn()) return NOT_SIGNED_IN;
 
       const cleanSlug = slug.replace(/\.htmlhost\.co$/, "");
       const destDir = resolve(directory);
@@ -251,7 +267,7 @@ export function createServer() {
       }),
     },
     wrap(async ({ slug, confirm }) => {
-      if (!isLoggedIn()) return "Not logged in. Run `htmlhost login` in a terminal first.";
+      if (!isLoggedIn()) return NOT_SIGNED_IN;
       if (!confirm) return "Deletion not confirmed. Set confirm to true to proceed.";
 
       const cleanSlug = slug.replace(/\.htmlhost\.co$/, "");
@@ -264,6 +280,19 @@ export function createServer() {
   // -------------------------------------------------------------------
   // Tool: whoami
   // -------------------------------------------------------------------
+  server.registerTool(
+    "login",
+    {
+      title: "Sign in to htmlhost",
+      description:
+        "Sign in to the user's htmlhost.co account. Opens an approval page in their browser and waits briefly; " +
+        "if they haven't approved yet, it returns the link and code to show them. Call it again after they approve. " +
+        "Use it when another htmlhost tool says you're not signed in.",
+      inputSchema: z.object({}),
+    },
+    wrap(async () => loginStep())
+  );
+
   server.registerTool(
     "whoami",
     {
@@ -272,7 +301,7 @@ export function createServer() {
       inputSchema: z.object({}),
     },
     wrap(async () => {
-      if (!isLoggedIn()) return "Not logged in. Run `htmlhost login` in a terminal first.";
+      if (!isLoggedIn()) return NOT_SIGNED_IN;
 
       const data = await apiGet("/api/tokens/me");
       return {
@@ -302,7 +331,7 @@ export function createServer() {
       }),
     },
     wrap(async ({ html, slug, title, ttl }) => {
-      if (!isLoggedIn()) return "Not logged in. Run `htmlhost login` in a terminal first.";
+      if (!isLoggedIn()) return NOT_SIGNED_IN;
 
       const body = { html };
       if (slug) body.slug = slug;
@@ -337,7 +366,7 @@ export function createServer() {
       }),
     },
     wrap(async ({ slug }) => {
-      if (!isLoggedIn()) return "Not logged in. Run `htmlhost login` in a terminal first.";
+      if (!isLoggedIn()) return NOT_SIGNED_IN;
       const cleanSlug = slug.replace(/\.htmlhost\.co$/, "");
       return apiGet(`/api/sites/${encodeURIComponent(cleanSlug)}/versions`);
     })
@@ -360,7 +389,7 @@ export function createServer() {
       }),
     },
     wrap(async ({ slug, version, confirm }) => {
-      if (!isLoggedIn()) return "Not logged in. Run `htmlhost login` in a terminal first.";
+      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`, {});

package/src/update.mjs

@@ -0,0 +1,118 @@
+/**
+ * Keeping htmlhost-mcp current, like the CLI's update check.
+ *
+ * An MCP server is a child process of the AI tool, talking over stdio, so it
+ * can't swap itself out while running and must never print to stdout. On
+ * start it checks the npm registry (at most once a day, cached in the shared
+ * ~/.htmlhostrc). When a newer version exists:
+ *
+ * - installed globally (`htmlhost-mcp` command): it installs the new version
+ *   in the background, so the next start of the AI tool uses it;
+ * - run with `npx -y htmlhost-mcp@latest`: npx fetches it on the next start;
+ * - run with a bare `npx -y htmlhost-mcp`: npx keeps reusing its cached copy,
+ *   so the notice asks for `@latest` in the MCP config.
+ *
+ * The first tool result of the session carries a one-line notice, so the AI
+ * tells the user. Set HTMLHOST_NO_UPDATE_CHECK to turn all of this off.
+ */
+import { spawn } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { sep } from "node:path";
+import { readConfig, writeConfig } from "./api.mjs";
+
+const PACKAGE_NAME = "htmlhost-mcp";
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+
+/** True when a is a newer x.y.z than b. */
+export function isNewer(a, b) {
+  const pa = String(a).split(".").map(Number);
+  const pb = String(b).split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] || 0) > (pb[i] || 0)) return true;
+    if ((pa[i] || 0) < (pb[i] || 0)) return false;
+  }
+  return false;
+}
+
+/** How this server was started: "npx" (from npx's cache), "global", or "local" (a project's node_modules, or a checkout). */
+export function installKind(entry = process.argv[1] || "", globalRoot = null) {
+  let real = entry;
+  try { real = realpathSync(entry); } catch { /* keep the path as given */ }
+  if (real.includes(`${sep}_npx${sep}`)) return "npx";
+  if (globalRoot && real.startsWith(globalRoot + sep)) return "global";
+  return "local";
+}
+
+/** `npm root -g`, or null. */
+function npmGlobalRoot() {
+  return new Promise((resolve) => {
+    try {
+      const child = spawn(process.platform === "win32" ? "npm.cmd" : "npm", ["root", "-g"], { stdio: ["ignore", "pipe", "ignore"] });
+      let out = "";
+      child.stdout.on("data", (d) => (out += d));
+      child.on("error", () => resolve(null));
+      child.on("close", () => resolve(out.trim() || null));
+      setTimeout(() => { child.kill(); resolve(null); }, 5000).unref();
+    } catch {
+      resolve(null);
+    }
+  });
+}
+
+/** The newest published version, from the cache when it's less than a day old. */
+async function latestVersion() {
+  const config = readConfig();
+  if (config.mcpLatestVersion && Date.now() - (config.mcpLastUpdateCheck || 0) < CHECK_INTERVAL_MS) {
+    return config.mcpLatestVersion;
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 5000);
+  try {
+    const res = await fetch(`https://registry.npmjs.org/${PACKAGE_NAME}/latest`, { signal: controller.signal, headers: { Accept: "application/json" } });
+    if (!res.ok) return null;
+    const data = await res.json();
+    if (!data?.version) return null;
+    writeConfig({ mcpLastUpdateCheck: Date.now(), mcpLatestVersion: data.version });
+    return data.version;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** Install the latest version globally, detached and silent (stdout belongs to MCP). */
+function installInBackground() {
+  try {
+    const child = spawn(process.platform === "win32" ? "npm.cmd" : "npm", ["install", "-g", `${PACKAGE_NAME}@latest`], {
+      stdio: "ignore",
+      detached: true,
+    });
+    child.on("error", () => {});
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check for a newer version and act on it. Resolves to a one-line notice for
+ * the AI to pass on, or null. Never throws, never writes to stdout.
+ */
+export async function checkForUpdate(currentVersion) {
+  if (process.env.HTMLHOST_NO_UPDATE_CHECK || process.env.CI) return null;
+  const latest = await latestVersion();
+  if (!latest || !isNewer(latest, currentVersion)) return null;
+  const kind = installKind(process.argv[1], await npmGlobalRoot());
+  const head = `htmlhost-mcp ${latest} is available (this is ${currentVersion}).`;
+  if (kind === "global") {
+    return installInBackground()
+      ? `${head} It's being installed now; restart your AI tool (or its MCP servers) to use it.`
+      : `${head} Update with: npm install -g ${PACKAGE_NAME}@latest, then restart your AI tool.`;
+  }
+  if (kind === "npx") {
+    return `${head} Restart your AI tool to load it. If it still reports ${currentVersion}, change the MCP config to run "npx -y ${PACKAGE_NAME}@latest" so npx always fetches the newest version.`;
+  }
+  return `${head} Update the htmlhost-mcp package this server runs from, then restart your AI tool.`;
+}