@showly/mcp-server 0.4.1 → 0.4.3

package/dist/cli.d.ts

@@ -1,15 +1,16 @@
 #!/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.
  *
  * `--to` describes where this CLI writes the credential; `--agent` describes
  * which host will use it. They are the same for the two hosts we can write
  * directly, but intentionally separate for `--print-token`, where another
- * agent (OpenClaw / Cursor / Cline) receives the value after this process
+ * agent (OpenClaw / Cursor / Hermes / Cline) receives the value after this process
  * exits.
  */
-export declare const LOGIN_AGENTS: readonly ["claude-code", "codex", "cursor", "openclaw", "cline"];
+export declare const LOGIN_AGENTS: readonly ["claude-code", "codex", "cursor", "openclaw", "hermes", "cline"];
 export type LoginAgent = (typeof LOGIN_AGENTS)[number];
 /**
  * The version of THIS copy of the package, read from the manifest that ships
@@ -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,29 @@ 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";
+/**
+ * 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 +264,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 +284,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,7 @@ import { readFileSync, readdirSync, mkdirSync, rmSync, writeFileSync, existsSync
 import { dirname, join } from "node:path";
 import { homedir } from "node:os";
 import { pathToFileURL } from "node:url";
+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";
 /**
@@ -42,7 +43,7 @@ import { SHOWLY_HOSTING_SKILL_DIRECTORY, SHOWLY_HOSTING_SKILL_NAME, SHOWLY_LEGAC
  * `--to` describes where this CLI writes the credential; `--agent` describes
  * which host will use it. They are the same for the two hosts we can write
  * directly, but intentionally separate for `--print-token`, where another
- * agent (OpenClaw / Cursor / Cline) receives the value after this process
+ * agent (OpenClaw / Cursor / Hermes / Cline) receives the value after this process
  * exits.
  */
 export const LOGIN_AGENTS = [
@@ -50,6 +51,7 @@ export const LOGIN_AGENTS = [
     "codex",
     "cursor",
     "openclaw",
+    "hermes",
     "cline",
 ];
 /**
@@ -82,17 +84,19 @@ 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|cline> so My Agents can name it.",
+        "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)",
@@ -308,6 +312,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.
  *
@@ -352,6 +374,7 @@ export const LOGIN_AGENT_CLIENT_IDS = {
     codex: `${LOGIN_CLIENT_ID}/codex`,
     cursor: `${LOGIN_CLIENT_ID}/cursor`,
     openclaw: `${LOGIN_CLIENT_ID}/openclaw`,
+    hermes: `${LOGIN_CLIENT_ID}/hermes`,
     cline: `${LOGIN_CLIENT_ID}/cline`,
 };
 export function loginClientId(target, agent) {
@@ -464,6 +487,89 @@ 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";
+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;
+    return {
+        ...opts.existing,
+        env: {
+            ...env,
+            vars: { ...vars, [OPENCLAW_TOKEN_ENV_VAR]: opts.token },
+        },
+        mcp: {
+            ...mcp,
+            servers: {
+                ...servers,
+                showly: {
+                    ...showlyWithoutOauth,
+                    url: opts.url,
+                    transport: "streamable-http",
+                    headers: {
+                        ...currentHeaders,
+                        Authorization: `Bearer \${${OPENCLAW_TOKEN_ENV_VAR}}`,
+                    },
+                },
+            },
+        },
+    };
+}
+/** 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.
  *
@@ -761,6 +867,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);
@@ -852,6 +974,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,
@@ -914,7 +1084,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({
@@ -1027,12 +1200,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) {
@@ -1096,14 +1270,14 @@ 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);
         if (agent === null) {
-            io.err("login: --agent must be claude-code, codex, cursor, openclaw or cline");
+            io.err("login: --agent must be claude-code, codex, cursor, openclaw, hermes or cline");
             return 2;
         }
         if (target !== "stdout" && agent !== undefined && agent !== target) {

package/manifest.json

@@ -2,7 +2,7 @@
   "$schema": "https://showly.ai/schemas/skill-manifest-v1.json",
   "name": "showly",
   "displayName": "Showly",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "Deploy and manage Showly sites from inside Claude Code / Codex.",
   "homepage": "https://showly.ai/docs/mcp/overview",
   "publisher": "Showly",

package/package.json

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