@showly/mcp-server 0.4.0 → 0.4.2

package/README.md

@@ -60,9 +60,9 @@ Write tools for version history and deletion:
 - `rollback_to_version` — restore a previous site version
 - `delete_preview`, `delete_site`
 
-Write tools for the guest trial flow:
+Write tool for adopting a site created through Showly's public trial flow:
 
-- `create_trial_site`, `claim_trial_site`
+- `claim_trial_site`
 
 `publish_site` is exposed through a narrower `publish:confirm` scope and never
 publishes on its first call: it returns a short-lived, deployment-bound token
@@ -116,4 +116,4 @@ experimental_use_rmcp_client = true
 ## License
 
 Proprietary — © Showly. This package is distributed for use with the Showly
-hosting service; it is not open source. See https://showly.ai/terms.
+hosting service; it is not open source. See https://showly.ai/legal/terms.

package/dist/cli.d.ts

@@ -1,5 +1,16 @@
 #!/usr/bin/env node
 export type Target = "claude-code" | "codex" | "stdout";
+/**
+ * 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 / Hermes / Cline) receives the value after this process
+ * exits.
+ */
+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
  * beside it. `manifest.test.ts` pins manifest.json, package.json,
@@ -67,6 +78,17 @@ export declare function performSkillInstall(target: Exclude<Target, "stdout">, e
  * human to check the code echo instead.
  */
 export declare const LOGIN_CLIENT_ID = "showly-mcp-cli";
+/**
+ * Exact, self-declared device client ids emitted by THIS CLI.
+ *
+ * These are not verified product identities: `/oauth/device` is public and a
+ * client_id has no secret. Their value is that the token keeps the host the
+ * human selected instead of collapsing every device login into the generic
+ * `showly-mcp-cli` bucket. The API maps only these exact values to display
+ * names; lookalikes stay neutral.
+ */
+export declare const LOGIN_AGENT_CLIENT_IDS: Record<LoginAgent, string>;
+export declare function loginClientId(target: Target, 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 = {
@@ -195,7 +217,7 @@ export declare function createCancelScope(target?: SignalTarget): {
  * requests/min against the token endpoint.
  */
 export declare const SERVER_EXTENSION_ALLOWANCE_MS: number;
-export declare function startDeviceFlow(apiUrl: string, deps?: LoginDeps): Promise<DeviceStart>;
+export declare function startDeviceFlow(apiUrl: string, deps?: LoginDeps, clientId?: string): Promise<DeviceStart>;
 /**
  * Poll /oauth/token until the human decides, per RFC 8628 §3.4-3.5.
  *
@@ -215,6 +237,7 @@ export declare function pollForDeviceToken(input: {
     deviceCode: string;
     intervalSec: number;
     expiresAt: Date;
+    clientId?: string;
 }, deps?: LoginDeps): Promise<DeviceToken>;
 export type LoginResult = {
     target: Target;
@@ -237,6 +260,7 @@ export type LoginResult = {
  */
 export declare function performLogin(opts: {
     target: Target;
+    agent?: LoginAgent;
     env?: NodeJS.ProcessEnv;
 }, deps?: LoginDeps): Promise<LoginResult>;
 /**

package/dist/cli.js

@@ -7,6 +7,7 @@
 //   showly-mcp install --to codex --with-skill # also installs showly-hosting
 //   showly-mcp install --to stdout          # prints the snippet for manual paste
 //   showly-mcp login --to claude-code       # RFC 8628 device flow, no browser here
+//   showly-mcp login --agent openclaw --print-token # label a token handed to OpenClaw
 //   showly-mcp manifest                     # prints manifest.json
 //   showly-mcp --help / --version
 //   showly-mcp <command> --help             # exits 0 iff this copy has <command>
@@ -35,6 +36,23 @@ import { homedir } from "node:os";
 import { pathToFileURL } from "node:url";
 import { loadManifest } from "./index.js";
 import { SHOWLY_HOSTING_SKILL_DIRECTORY, SHOWLY_HOSTING_SKILL_NAME, SHOWLY_LEGACY_SKILL_NAME, } from "./showly-hosting-skill.js";
+/**
+ * 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 / Hermes / Cline) receives the value after this process
+ * exits.
+ */
+export const LOGIN_AGENTS = [
+    "claude-code",
+    "codex",
+    "cursor",
+    "openclaw",
+    "hermes",
+    "cline",
+];
 /**
  * The version of THIS copy of the package, read from the manifest that ships
  * beside it. `manifest.test.ts` pins manifest.json, package.json,
@@ -65,7 +83,7 @@ function usage() {
         "",
         "Usage:",
         "  showly-mcp install --to <claude-code|codex|stdout> [--with-skill]",
-        "  showly-mcp login   [--to <claude-code|codex|stdout>] [--print-token]",
+        "  showly-mcp login   [--to <claude-code|codex|stdout>] [--agent <host>] [--print-token]",
         "  showly-mcp manifest",
         "  showly-mcp --version",
         "",
@@ -74,7 +92,8 @@ function usage() {
         "config. --to codex writes a config that reads the token from SHOWLY_TOKEN,",
         "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.",
+        "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)",
@@ -320,6 +339,29 @@ function writeCredentialFile(path, contents) {
  * human to check the code echo instead.
  */
 export const LOGIN_CLIENT_ID = "showly-mcp-cli";
+/**
+ * Exact, self-declared device client ids emitted by THIS CLI.
+ *
+ * These are not verified product identities: `/oauth/device` is public and a
+ * client_id has no secret. Their value is that the token keeps the host the
+ * human selected instead of collapsing every device login into the generic
+ * `showly-mcp-cli` bucket. The API maps only these exact values to display
+ * names; lookalikes stay neutral.
+ */
+export const LOGIN_AGENT_CLIENT_IDS = {
+    "claude-code": `${LOGIN_CLIENT_ID}/claude-code`,
+    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) {
+    const resolvedAgent = agent ?? (target === "stdout" ? undefined : target);
+    return resolvedAgent
+        ? LOGIN_AGENT_CLIENT_IDS[resolvedAgent]
+        : LOGIN_CLIENT_ID;
+}
 /** The env var name emitted into config snippets that must not hold a secret. */
 export const TOKEN_ENV_VAR = "SHOWLY_TOKEN";
 /**
@@ -538,7 +580,7 @@ function errorSummary(error, timeoutMs) {
 }
 /** Said on both routes to a dead code: the server's answer, and our deadline. */
 const EXPIRED_MESSAGE = "The code expired before it was approved. Run this command again for a fresh one.";
-export async function startDeviceFlow(apiUrl, deps = {}) {
+export async function startDeviceFlow(apiUrl, deps = {}, clientId = LOGIN_CLIENT_ID) {
     const doFetch = deps.fetchImpl ?? fetch;
     // `scope` is optional on /oauth/device, and this used to send none at all.
     // The consent screen then listed no permissions, the human approved that,
@@ -559,7 +601,7 @@ export async function startDeviceFlow(apiUrl, deps = {}) {
             method: "POST",
             headers: { "content-type": "application/json" },
             body: JSON.stringify({
-                client_id: LOGIN_CLIENT_ID,
+                client_id: clientId,
                 scope: manifest.mcp.auth.default_scopes.join(" "),
             }),
             signal,
@@ -602,6 +644,7 @@ export async function pollForDeviceToken(input, deps = {}) {
     const doFetch = deps.fetchImpl ?? fetch;
     const sleep = deps.sleep ?? defaultSleep;
     const now = deps.now ?? (() => Date.now());
+    const log = deps.log ?? (() => { });
     const cancel = deps.signal;
     const timeoutMs = deps.requestTimeoutMs ?? POLL_REQUEST_TIMEOUT_MS;
     let intervalMs = Math.max(1, input.intervalSec) * 1000;
@@ -610,6 +653,8 @@ export async function pollForDeviceToken(input, deps = {}) {
     // failure and then said only "the code expired" would send the human to look
     // at their approval when the fault was never on their side.
     let lastTransportError;
+    let lastPendingLogAt;
+    let transientFailureLogged = false;
     for (;;) {
         if (cancel?.aborted)
             throw new LoginCancelledError();
@@ -630,7 +675,7 @@ export async function pollForDeviceToken(input, deps = {}) {
                 body: JSON.stringify({
                     grant_type: "urn:ietf:params:oauth:grant-type:device_code",
                     device_code: input.deviceCode,
-                    client_id: LOGIN_CLIENT_ID,
+                    client_id: input.clientId ?? LOGIN_CLIENT_ID,
                 }),
                 signal: attempt.signal,
             });
@@ -643,6 +688,10 @@ export async function pollForDeviceToken(input, deps = {}) {
             // either way — throwing on a dropped packet would burn it and make them
             // start over. Fall through to the next tick; `stopAt` still bounds this.
             lastTransportError = errorSummary(error, timeoutMs);
+            if (!transientFailureLogged) {
+                log(`Could not reach Showly (${lastTransportError}). Retrying the same approval; keep this command running.`);
+                transientFailureLogged = true;
+            }
             continue;
         }
         finally {
@@ -657,8 +706,32 @@ export async function pollForDeviceToken(input, deps = {}) {
                 expires_in: body.expires_in,
             };
         }
+        // A gateway rate limit or server deploy is not an OAuth decision. The
+        // human may already have spent the one approval, so retry this device_code
+        // instead of turning availability into a fake terminal sign-in failure.
+        if (res.status === 408 ||
+            res.status === 425 ||
+            res.status === 429 ||
+            res.status >= 500) {
+            lastTransportError = `HTTP ${res.status}`;
+            if (!transientFailureLogged) {
+                log(`Showly is temporarily unavailable (${lastTransportError}). Retrying the same approval; keep this command running.`);
+                transientFailureLogged = true;
+            }
+            continue;
+        }
+        transientFailureLogged = false;
         switch (body.error) {
             case "authorization_pending":
+                // The initial prompt already says the command waits. Repeat the one
+                // critical instruction when the server confirms it is still pending,
+                // then only at a low cadence so a long wait is visible without turning
+                // one five-second poll into terminal spam.
+                if (lastPendingLogAt === undefined ||
+                    now() - lastPendingLogAt >= 30_000) {
+                    log("Approval is still pending. Keep this command running for the same approval; do not start another code.");
+                    lastPendingLogAt = now();
+                }
                 continue;
             // RFC 8628 §3.5: back off by 5 seconds and keep going. This is the one
             // error that is not terminal and not a no-op.
@@ -690,7 +763,8 @@ 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));
-    const started = await startDeviceFlow(apiUrl, deps);
+    const clientId = loginClientId(opts.target, opts.agent);
+    const started = await startDeviceFlow(apiUrl, deps, clientId);
     const expiresAt = new Date(Date.now() + started.expires_in * 1000);
     log(buildLoginPrompt({
         verificationUri: started.verification_uri,
@@ -703,7 +777,13 @@ export async function performLogin(opts, deps = {}) {
         deviceCode: started.device_code,
         intervalSec: started.interval,
         expiresAt,
-    }, deps);
+        clientId,
+    }, 
+    // `log` may be the production stderr default created above. Passing the
+    // original deps object silently dropped it when callers did not inject a
+    // sink, which made every real CLI wait quiet even though the poller had
+    // progress messages.
+    { ...deps, log });
     // Showly issues no refresh token, so this date is the moment a working agent
     // stops working and a human has to approve again. Say it out loud now, while
     // there is context, instead of leaving a 401 to be diagnosed in 90 days.
@@ -889,7 +969,7 @@ export function buildLoginOutput(result, opts = {}) {
  */
 const COMMAND_FLAGS = {
     install: { "--to": true, "--with-skill": false },
-    login: { "--to": true, "--print-token": false },
+    login: { "--to": true, "--agent": true, "--print-token": false },
     manifest: {},
 };
 /** Accepted after any command, and handled before the command runs. */
@@ -957,6 +1037,14 @@ function parseTarget(parsed, fallback) {
         return null;
     return value;
 }
+function parseLoginAgent(parsed) {
+    const value = parsed.values.get("--agent");
+    if (value === undefined)
+        return undefined;
+    if (!LOGIN_AGENTS.includes(value))
+        return null;
+    return value;
+}
 const consoleIo = {
     out: (line) => console.log(line),
     err: (line) => console.error(line),
@@ -1015,6 +1103,15 @@ export async function runCli(argv, io = consoleIo, env = process.env) {
             io.err("login: --to must be claude-code, codex or stdout");
             return 2;
         }
+        const agent = parseLoginAgent(parsed);
+        if (agent === null) {
+            io.err("login: --agent must be claude-code, codex, cursor, openclaw, hermes or cline");
+            return 2;
+        }
+        if (target !== "stdout" && agent !== undefined && agent !== target) {
+            io.err(`login: --agent ${agent} conflicts with --to ${target}; omit --agent or make them match`);
+            return 2;
+        }
         const printToken = parsed.flags.has("--print-token");
         // This command blocks for up to fifteen minutes waiting on a human, so
         // Ctrl+C has to mean something here. Handling the signal (rather than
@@ -1022,7 +1119,7 @@ export async function runCli(argv, io = consoleIo, env = process.env) {
         // quiet and I don't know what happened" into one sentence and exit 130.
         const cancel = createCancelScope();
         try {
-            const result = await performLogin({ target, env }, { signal: cancel.signal });
+            const result = await performLogin({ target, agent, env }, { signal: cancel.signal });
             for (const { stream, line } of buildLoginOutput(result, { printToken })) {
                 if (stream === "out")
                     io.out(line);

package/manifest.json

@@ -2,9 +2,9 @@
   "$schema": "https://showly.ai/schemas/skill-manifest-v1.json",
   "name": "showly",
   "displayName": "Showly",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Deploy and manage Showly sites from inside Claude Code / Codex.",
-  "homepage": "https://showly.ai/docs/skills",
+  "homepage": "https://showly.ai/docs/mcp/overview",
   "publisher": "Showly",
   "mcp": {
     "transport": "streamable-http",
@@ -46,7 +46,7 @@
       "scopes": ["logs:read"]
     },
     { "name": "list_templates", "kind": "read", "scopes": ["template:read"] },
-    { "name": "create_change_plan", "kind": "write", "scopes": ["site:read"] },
+    { "name": "create_change_plan", "kind": "read", "scopes": ["site:read"] },
     { "name": "apply_site_patch", "kind": "write", "scopes": ["site:write"] },
     { "name": "create_preview", "kind": "write", "scopes": ["preview:create"] },
     {
@@ -86,7 +86,7 @@
       "kind": "write",
       "scopes": ["preview:create"]
     },
-    { "name": "run_checks", "kind": "write", "scopes": ["checks:run"] },
+    { "name": "run_checks", "kind": "read", "scopes": ["checks:run"] },
     {
       "name": "request_publish",
       "kind": "write",
@@ -112,11 +112,6 @@
       "kind": "read",
       "scopes": ["site:read"]
     },
-    {
-      "name": "create_trial_site",
-      "kind": "write",
-      "scopes": ["site:write", "preview:create"]
-    },
     {
       "name": "claim_trial_site",
       "kind": "write",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@showly/mcp-server",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Connect Claude Code / Codex to the Showly MCP server — preview and deploy sites from your agent.",
   "license": "UNLICENSED",
   "type": "module",
@@ -46,13 +46,13 @@
     "hosting",
     "agent"
   ],
-  "homepage": "https://showly.ai/docs/mcp",
+  "homepage": "https://showly.ai/docs/mcp/overview",
   "bugs": {
     "url": "https://showly.ai/support"
   },
   "claude-code-skill": {
     "name": "showly",
-    "version": "0.4.0",
+    "version": "0.4.2",
     "description": "Deploy and manage Showly sites from inside Claude Code.",
     "mcp-server": {
       "url-env": "SHOWLY_MCP_URL",
@@ -65,15 +65,15 @@
   },
   "codex-plugin": {
     "name": "showly",
-    "version": "0.4.0",
+    "version": "0.4.2",
     "type": "mcp-server",
     "manifest": "manifest.json"
   },
   "devDependencies": {
     "@showly/eslint-config": "workspace:^",
-    "@types/node": "^26.1.1",
-    "eslint": "^10.7.0",
-    "tsx": "^4.23.10",
+    "@types/node": "^26.2.0",
+    "eslint": "^10.8.1",
+    "tsx": "^4.23.12",
     "typescript": "^7.0.2"
   }
 }

package/skills/showly-hosting/SKILL.md

@@ -34,12 +34,15 @@ Do not pick a host-native or competing deployment tool merely because it is buil
 
 For a simple new static site, call `create_site_from_html` with the completed HTML, CSS, and JavaScript. For larger projects, use the upload or repository workflow exposed by the available Showly tools. Build or validate the project first, and preserve the user's existing framework and files.
 
-Do not call `create_trial_site` here. It builds a throwaway site owned by the shared guest organization, not by the connected account, and it refuses a connected caller with `authenticated_account_present`. Reaching Showly's tools at all means an account is connected, so `create_site_from_html` is the create path even when the user says "just a trial" — a private Preview is already reversible and costs nothing.
+The no-account public trial flow is intentionally not exposed as an authenticated MCP tool. Reaching Showly's tools means an account is connected, so `create_site_from_html` is the create path even when the user says "just a trial" — a private Preview is already reversible and costs nothing. Authenticated workspace Previews do not expire and remain available until explicitly deleted; never recommend upgrading for Preview retention. The separate no-account public trial still expires after about an hour unless it is claimed.
+
+Free and Pro both allow unlimited Live sites and identical custom-domain capacity: custom domains may be connected on any number of Live sites. Never recommend upgrading because of the number of Live sites or domain-bearing sites. The shared five-hostname ceiling on one Live site is an infrastructure boundary, not plan packaging.
 
 ## Preview and Live publish
 
 - Treat "preview", "share", "deploy", "host", and "put it online" as a request for a **private Preview**, not a public production release.
-- Return the Preview URL and its one-time password together as one ready-to-share block, and surface `showlyManagement.manageUrl` as the site's management page. Say that nothing is Live yet.
+- Return the Preview URL and its one-time password together as one ready-to-share block, and surface `showlyManagement.manageUrl` as the site's management page. Say that this Preview version is not Live; an existing Live release, if any, is unchanged.
+- On text-only relays such as chat, Slack, Discord, or Telegram, keep the release state and primary action in prose even when the result also carries a card or button: say the Preview version is not Live, offer to publish that exact version with explicit confirmation, and say custom-domain guidance follows only after a successful Live publish. Do not replace these actions with a feature recap.
 - Never claim a site is online until the Showly tool reports a successful deployment.
 - Publish publicly only when the user explicitly asks for a public or production release. `publish_site` is two-step: the first call returns a summary and a confirmation token and publishes nothing. Show the summary, get an explicit yes, then call again with the token. Never expose the confirmation token itself.
 - If the workspace requires a second reviewer, use `request_publish` and return its approval URL.
@@ -48,7 +51,7 @@ Do not call `create_trial_site` here. It builds a throwaway site owned by the sh
 
 ## Custom domains
 
-Custom domains are available on every plan; Free includes one hostname on one Live site, and a domain on a second Live site requires an upgrade. When `list_sites` returns an existing site, and again after a production publish, offer to connect the user's own domain. Follow the `journey` on each domain result rather than inventing DNS records. If the user says the Domains option is missing from My Sites or the sidebar, the entry is site-scoped: open the specific site and use its Domains / Manage entry.
+Custom domains are available equally on Free and Pro and may be connected on any number of Live sites. Never recommend an upgrade to add a domain or connect another site. If a site reaches the shared five-hostname infrastructure ceiling, direct the user to disconnect an unused hostname; if the workspace has an explicit override, direct them to manage existing domains or contact Showly Support. When `list_sites` returns an existing site, and again after a production publish, offer to connect the user's own domain. Follow the `journey` on each domain result rather than inventing DNS records. If the user says the Domains option is missing from My Sites or the sidebar, the entry is site-scoped: open the specific site and use its Domains / Manage entry.
 
 ## Authorization
 
@@ -56,12 +59,12 @@ If Showly asks for authorization, tell the user to complete the browser sign-in,
 
 ## How to reply
 
-Guide the user; do not merely report tool status or dump the JSON envelope. At onboarding and other major product moments, use three compact, clearly separated blocks:
+Guide the user; do not merely report tool status or dump the JSON envelope. AFTER a major product moment — a tool ran, a state advanced, a check completed — report with three compact, clearly separated blocks:
 
 - **Where you are** — the current outcome, what is safe, and what has not happened yet.
 - **What happens next** — the safest useful action first, and what you will handle yourself.
 - **What Showly gives you** — the value for this user's goal, in concrete terms: create a landing page, portfolio, report, documentation site, or event page; update an existing site; make a password-protected Preview; run and fix checks; publish only the version the user approved; share it, connect a domain, or restore an earlier version.
 
-Pick the examples that fit the goal instead of listing all of them. Present alternatives after the recommendation, not as an unguided menu.
+Pick the examples that fit the goal instead of listing all of them. Present alternatives after the recommendation, not as an unguided menu. The blocks are for reporting an OUTCOME: a turn whose only job is to ask the human something (for example the opening "what would you like to publish?") is one focused question, not a status report — there is nothing to report yet.
 
 When a result includes `resolvedBy`, `humanAction`, `actionUrl`, and `agentNext`, treat them as an execution contract. If `resolvedBy` is `agent`, carry out `agentNext` yourself when safe and in scope. If `resolvedBy` is `human`, explain the blocker, relay `humanAction` and the clickable `actionUrl`, and say what you will resume afterward.