@showly/mcp-server 0.4.2 → 0.4.4

package/dist/cli.d.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 export type Target = "claude-code" | "codex" | "stdout";
+export type LoginTarget = Target | "openclaw" | "hermes";
 /**
  * The host that will RECEIVE a token printed to stdout.
  *
@@ -88,7 +89,7 @@ export declare const LOGIN_CLIENT_ID = "showly-mcp-cli";
  * names; lookalikes stay neutral.
  */
 export declare const LOGIN_AGENT_CLIENT_IDS: Record<LoginAgent, string>;
-export declare function loginClientId(target: Target, agent?: LoginAgent): string;
+export declare function loginClientId(target: LoginTarget, agent?: LoginAgent): string;
 /** The env var name emitted into config snippets that must not hold a secret. */
 export declare const TOKEN_ENV_VAR = "SHOWLY_TOKEN";
 export type DeviceStart = {
@@ -138,6 +139,40 @@ export declare function buildCodexAuthSnippet(opts: {
     url: string;
     tokenEnvVar?: string;
 }): string;
+/** Secrets used by the two remote-agent targets the Hero prompt exercises. */
+export declare const OPENCLAW_TOKEN_ENV_VAR = "SHOWLY_MCP_TOKEN";
+export declare const HERMES_TOKEN_ENV_VAR = "MCP_SHOWLY_API_KEY";
+/**
+ * Give every OpenClaw credential its own environment variable name.
+ *
+ * A managed Gateway can keep the old process environment alive while its
+ * user config is reloaded. With one fixed SHOWLY_MCP_TOKEN name, that stale
+ * process value wins over the freshly-written env.vars value and a successful
+ * re-login immediately fails with token_revoked until the whole instance is
+ * restarted. The token fingerprint is not a credential, but makes the new
+ * config reference a name the old process cannot already contain.
+ */
+export declare function openClawTokenEnvVar(token: string): string;
+/**
+ * Merge Showly into OpenClaw's user config without disturbing other Gateway
+ * settings. The token lives in the Gateway-owned env.vars store; the MCP entry
+ * contains only an environment placeholder. `auth: oauth` is removed because
+ * header auth and native OAuth are alternative modes in OpenClaw.
+ */
+export declare function buildOpenClawAuthConfig(opts: {
+    existing: Record<string, unknown>;
+    url: string;
+    token: string;
+}): Record<string, unknown>;
+/** Replace one dotenv assignment, remove duplicates, and preserve other lines. */
+export declare function mergeDotEnvCredential(existing: string, name: string, token: string): string;
+/**
+ * Update Hermes YAML through a real YAML document rather than `hermes config
+ * set`, whose secret masking corrupts the literal ${MCP_SHOWLY_API_KEY}
+ * placeholder. Parse errors are terminal: never replace a user's unreadable
+ * config with a guessed one.
+ */
+export declare function buildHermesAuthConfig(existing: string, url: string): string;
 export type LoginDeps = {
     fetchImpl?: typeof fetch;
     /**
@@ -240,11 +275,12 @@ export declare function pollForDeviceToken(input: {
     clientId?: string;
 }, deps?: LoginDeps): Promise<DeviceToken>;
 export type LoginResult = {
-    target: Target;
+    target: LoginTarget;
     token: string;
     scope: string;
     expiresAt: Date | null;
     path: string | null;
+    credentialPath?: string;
     wrote: boolean;
     snippet: string;
 };
@@ -259,7 +295,7 @@ export type LoginResult = {
  * and out of every `ps` listing on the machine.
  */
 export declare function performLogin(opts: {
-    target: Target;
+    target: LoginTarget;
     agent?: LoginAgent;
     env?: NodeJS.ProcessEnv;
 }, deps?: LoginDeps): Promise<LoginResult>;

package/dist/cli.js

@@ -34,6 +34,8 @@ import { readFileSync, readdirSync, mkdirSync, rmSync, writeFileSync, existsSync
 import { dirname, join } from "node:path";
 import { homedir } from "node:os";
 import { pathToFileURL } from "node:url";
+import { createHash } from "node:crypto";
+import { parseDocument } from "yaml";
 import { loadManifest } from "./index.js";
 import { SHOWLY_HOSTING_SKILL_DIRECTORY, SHOWLY_HOSTING_SKILL_NAME, SHOWLY_LEGACY_SKILL_NAME, } from "./showly-hosting-skill.js";
 /**
@@ -83,20 +85,22 @@ function usage() {
         "",
         "Usage:",
         "  showly-mcp install --to <claude-code|codex|stdout> [--with-skill]",
-        "  showly-mcp login   [--to <claude-code|codex|stdout>] [--agent <host>] [--print-token]",
+        "  showly-mcp login   [--to <claude-code|codex|openclaw|hermes|stdout>] [--agent <host>] [--print-token]",
         "  showly-mcp manifest",
         "  showly-mcp --version",
         "",
         "login authorizes this machine without a browser on it: it prints a short",
         "code, you approve it on any device, and the credential lands in your host",
-        "config. --to codex writes a config that reads the token from SHOWLY_TOKEN,",
+        "config. --to openclaw and --to hermes safely merge the credential into",
+        "those hosts' user config; --to codex prints the SHOWLY_TOKEN export its",
+        "config reads,",
         "so login also prints the export line that sets it. --print-token writes",
         "ONLY the token to stdout (everything else goes to stderr) so CI can",
         "capture it without it touching a file. When that token is for another",
         "host, pass --agent <cursor|openclaw|hermes|cline> so My Agents can name it.",
         "",
         "Environment overrides:",
-        "  SHOWLY_MCP_URL    full URL to your MCP endpoint (default https://mcp.showly.ai)",
+        "  SHOWLY_MCP_URL    full URL to your MCP endpoint (default https://mcp.showly.ai/mcp)",
         "  SHOWLY_API_URL    full URL to your API (default https://api.showly.ai)",
         "",
         "--with-skill installs a reusable showly-hosting skill for Claude Code or Codex.",
@@ -309,6 +313,24 @@ function safeReadJson(path) {
         return {};
     }
 }
+/**
+ * Read a host's primary config without the install helper's empty fallback.
+ * Login is about to add a live credential, so treating malformed JSON as `{}`
+ * would overwrite the user's whole Gateway after they had already approved.
+ */
+function readHostJson(path, label) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`Could not update ${label}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`Could not update ${label}: the root must be a JSON object.`);
+    }
+    return parsed;
+}
 /**
  * Write a file that holds (or will hold) a credential, 0600 on creation.
  *
@@ -466,6 +488,110 @@ export function buildCodexAuthSnippet(opts) {
         "",
     ].join("\n");
 }
+/** Secrets used by the two remote-agent targets the Hero prompt exercises. */
+export const OPENCLAW_TOKEN_ENV_VAR = "SHOWLY_MCP_TOKEN";
+export const HERMES_TOKEN_ENV_VAR = "MCP_SHOWLY_API_KEY";
+/**
+ * Give every OpenClaw credential its own environment variable name.
+ *
+ * A managed Gateway can keep the old process environment alive while its
+ * user config is reloaded. With one fixed SHOWLY_MCP_TOKEN name, that stale
+ * process value wins over the freshly-written env.vars value and a successful
+ * re-login immediately fails with token_revoked until the whole instance is
+ * restarted. The token fingerprint is not a credential, but makes the new
+ * config reference a name the old process cannot already contain.
+ */
+export function openClawTokenEnvVar(token) {
+    const fingerprint = createHash("sha256")
+        .update(token)
+        .digest("hex")
+        .slice(0, 12)
+        .toUpperCase();
+    return `${OPENCLAW_TOKEN_ENV_VAR}_${fingerprint}`;
+}
+function asRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : {};
+}
+/**
+ * Merge Showly into OpenClaw's user config without disturbing other Gateway
+ * settings. The token lives in the Gateway-owned env.vars store; the MCP entry
+ * contains only an environment placeholder. `auth: oauth` is removed because
+ * header auth and native OAuth are alternative modes in OpenClaw.
+ */
+export function buildOpenClawAuthConfig(opts) {
+    const env = asRecord(opts.existing.env);
+    const vars = asRecord(env.vars);
+    const mcp = asRecord(opts.existing.mcp);
+    const servers = asRecord(mcp.servers);
+    const currentShowly = asRecord(servers.showly);
+    const currentHeaders = asRecord(currentShowly.headers);
+    const { auth: _nativeOauth, ...showlyWithoutOauth } = currentShowly;
+    const tokenEnvVar = openClawTokenEnvVar(opts.token);
+    const varsWithoutOldShowlyTokens = Object.fromEntries(Object.entries(vars).filter(([name]) => name !== OPENCLAW_TOKEN_ENV_VAR &&
+        !name.startsWith(`${OPENCLAW_TOKEN_ENV_VAR}_`)));
+    return {
+        ...opts.existing,
+        env: {
+            ...env,
+            vars: { ...varsWithoutOldShowlyTokens, [tokenEnvVar]: opts.token },
+        },
+        mcp: {
+            ...mcp,
+            servers: {
+                ...servers,
+                showly: {
+                    ...showlyWithoutOauth,
+                    url: opts.url,
+                    transport: "streamable-http",
+                    headers: {
+                        ...currentHeaders,
+                        Authorization: `Bearer \${${tokenEnvVar}}`,
+                    },
+                },
+            },
+        },
+    };
+}
+/** Replace one dotenv assignment, remove duplicates, and preserve other lines. */
+export function mergeDotEnvCredential(existing, name, token) {
+    const assignment = `${name}=${token}`;
+    const matcher = new RegExp(`^(?:export\\s+)?${name}=`);
+    const lines = existing.split(/\r?\n/);
+    if (lines.at(-1) === "")
+        lines.pop();
+    const merged = [];
+    let wrote = false;
+    for (const line of lines) {
+        if (!matcher.test(line)) {
+            merged.push(line);
+            continue;
+        }
+        if (!wrote)
+            merged.push(assignment);
+        wrote = true;
+    }
+    if (!wrote)
+        merged.push(assignment);
+    return `${merged.join("\n")}\n`;
+}
+/**
+ * Update Hermes YAML through a real YAML document rather than `hermes config
+ * set`, whose secret masking corrupts the literal ${MCP_SHOWLY_API_KEY}
+ * placeholder. Parse errors are terminal: never replace a user's unreadable
+ * config with a guessed one.
+ */
+export function buildHermesAuthConfig(existing, url) {
+    const doc = parseDocument(existing.trim().length > 0 ? existing : "{}\n");
+    if (doc.errors.length > 0) {
+        throw new Error(`Could not update ~/.hermes/config.yaml: ${doc.errors[0].message}`);
+    }
+    doc.setIn(["mcp_servers", "showly", "url"], url);
+    doc.deleteIn(["mcp_servers", "showly", "auth"]);
+    doc.setIn(["mcp_servers", "showly", "headers", "Authorization"], `Bearer \${${HERMES_TOKEN_ENV_VAR}}`);
+    return doc.toString({ lineWidth: 0 });
+}
 /**
  * How long ONE HTTP request may take before it is abandoned.
  *
@@ -763,6 +889,22 @@ export async function performLogin(opts, deps = {}) {
     const env = opts.env ?? process.env;
     const { url, apiUrl } = resolveUrls(env);
     const log = deps.log ?? ((line) => console.error(line));
+    // Validate destination files before asking a human to approve anything.
+    // Re-read them after approval before merging, so a change made during the
+    // device wait is preserved too.
+    const openClawPath = opts.target === "openclaw"
+        ? join(homedir(), ".openclaw", "openclaw.json")
+        : null;
+    if (openClawPath && existsSync(openClawPath)) {
+        readHostJson(openClawPath, "~/.openclaw/openclaw.json");
+    }
+    const hermesDirectory = opts.target === "hermes" ? join(homedir(), ".hermes") : null;
+    const hermesConfigPath = hermesDirectory
+        ? join(hermesDirectory, "config.yaml")
+        : null;
+    if (hermesConfigPath && existsSync(hermesConfigPath)) {
+        buildHermesAuthConfig(readFileSync(hermesConfigPath, "utf8"), url);
+    }
     const clientId = loginClientId(opts.target, opts.agent);
     const started = await startDeviceFlow(apiUrl, deps, clientId);
     const expiresAt = new Date(Date.now() + started.expires_in * 1000);
@@ -854,6 +996,54 @@ export async function performLogin(opts, deps = {}) {
             snippet,
         };
     }
+    if (opts.target === "openclaw") {
+        const path = openClawPath;
+        const existing = existsSync(path)
+            ? readHostJson(path, "~/.openclaw/openclaw.json")
+            : {};
+        const merged = buildOpenClawAuthConfig({
+            existing,
+            url,
+            token: token.access_token,
+        });
+        mkdirSync(dirname(path), { recursive: true });
+        writeCredentialFile(path, JSON.stringify(merged, null, 2) + "\n");
+        return {
+            target: opts.target,
+            token: token.access_token,
+            scope: token.scope,
+            expiresAt: tokenExpiresAt,
+            path,
+            wrote: true,
+            snippet: JSON.stringify(merged, null, 2),
+        };
+    }
+    if (opts.target === "hermes") {
+        const directory = hermesDirectory;
+        const path = hermesConfigPath;
+        const credentialPath = join(directory, ".env");
+        const existingConfig = existsSync(path) ? readFileSync(path, "utf8") : "";
+        const existingEnv = existsSync(credentialPath)
+            ? readFileSync(credentialPath, "utf8")
+            : "";
+        // Build both outputs before touching either file. In particular, malformed
+        // YAML must not leave a fresh secret behind beside an unchanged config.
+        const config = buildHermesAuthConfig(existingConfig, url);
+        const dotenv = mergeDotEnvCredential(existingEnv, HERMES_TOKEN_ENV_VAR, token.access_token);
+        mkdirSync(directory, { recursive: true });
+        writeCredentialFile(credentialPath, dotenv);
+        writeCredentialFile(path, config);
+        return {
+            target: opts.target,
+            token: token.access_token,
+            scope: token.scope,
+            expiresAt: tokenExpiresAt,
+            path,
+            credentialPath,
+            wrote: true,
+            snippet: config,
+        };
+    }
     return {
         target: opts.target,
         token: token.access_token,
@@ -916,7 +1106,10 @@ export function buildLoginOutput(result, opts = {}) {
         return [{ stream: "out", line: result.token }];
     const lines = [];
     if (result.wrote) {
-        lines.push({ stream: "err", line: `Connected. Wrote ${result.path}` });
+        const written = [result.path, result.credentialPath]
+            .filter((path) => Boolean(path))
+            .join(" and ");
+        lines.push({ stream: "err", line: `Connected. Wrote ${written}` });
     }
     else if (result.path) {
         lines.push({
@@ -931,7 +1124,15 @@ export function buildLoginOutput(result, opts = {}) {
         });
         lines.push({ stream: "out", line: result.snippet });
     }
-    for (const name of envVarsReferencedBy(result.snippet)) {
+    // OpenClaw and Hermes have already received the value in their protected
+    // user-level credential store. Printing an export for them is both false
+    // (the variable is set) and needlessly exposes the token in terminal/chat
+    // logs. Codex and stdout are the two handoff targets whose config really
+    // does depend on the human setting the referenced environment variable.
+    const handoffEnvVars = result.target === "codex" || result.target === "stdout"
+        ? envVarsReferencedBy(result.snippet)
+        : [];
+    for (const name of handoffEnvVars) {
         lines.push({
             stream: "err",
             line: `That config reads the token from ${name}, and nothing sets it yet. Put this in the environment your agent starts in:`,
@@ -1029,12 +1230,13 @@ export function parseCommandArgs(command, rest) {
     }
     return { ok: true, help, flags, values };
 }
-function parseTarget(parsed, fallback) {
+function parseLoginTarget(parsed, fallback) {
     const value = parsed.values.get("--to");
     if (value === undefined)
         return fallback;
-    if (!["claude-code", "codex", "stdout"].includes(value))
+    if (!["claude-code", "codex", "openclaw", "hermes", "stdout"].includes(value)) {
         return null;
+    }
     return value;
 }
 function parseLoginAgent(parsed) {
@@ -1098,9 +1300,9 @@ export async function runCli(argv, io = consoleIo, env = process.env) {
     if (command === "login") {
         // --to defaults to stdout: printing a snippet can never corrupt a config
         // file the user did not ask us to touch.
-        const target = parseTarget(parsed, "stdout");
+        const target = parseLoginTarget(parsed, "stdout");
         if (!target) {
-            io.err("login: --to must be claude-code, codex or stdout");
+            io.err("login: --to must be claude-code, codex, openclaw, hermes or stdout");
             return 2;
         }
         const agent = parseLoginAgent(parsed);

package/manifest.json

@@ -2,7 +2,7 @@
   "$schema": "https://showly.ai/schemas/skill-manifest-v1.json",
   "name": "showly",
   "displayName": "Showly",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "Deploy and manage Showly sites from inside Claude Code / Codex.",
   "homepage": "https://showly.ai/docs/mcp/overview",
   "publisher": "Showly",
@@ -26,7 +26,7 @@
     },
     "endpoints": {
       "url_env": "SHOWLY_MCP_URL",
-      "default_url": "https://mcp.showly.ai",
+      "default_url": "https://mcp.showly.ai/mcp",
       "api_url_env": "SHOWLY_API_URL"
     }
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@showly/mcp-server",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "Connect Claude Code / Codex to the Showly MCP server — preview and deploy sites from your agent.",
   "license": "UNLICENSED",
   "type": "module",
@@ -52,11 +52,11 @@
   },
   "claude-code-skill": {
     "name": "showly",
-    "version": "0.4.2",
+    "version": "0.4.4",
     "description": "Deploy and manage Showly sites from inside Claude Code.",
     "mcp-server": {
       "url-env": "SHOWLY_MCP_URL",
-      "default-url": "https://mcp.showly.ai",
+      "default-url": "https://mcp.showly.ai/mcp",
       "auth": "oauth",
       "api-url-env": "SHOWLY_API_URL"
     },
@@ -65,10 +65,13 @@
   },
   "codex-plugin": {
     "name": "showly",
-    "version": "0.4.2",
+    "version": "0.4.4",
     "type": "mcp-server",
     "manifest": "manifest.json"
   },
+  "dependencies": {
+    "yaml": "^2.9.0"
+  },
   "devDependencies": {
     "@showly/eslint-config": "workspace:^",
     "@types/node": "^26.2.0",