@hue-run/sdk 0.11.2 → 0.11.4

package/dist/cli/mcp.js

@@ -1,10 +1,11 @@
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { constants } from "node:fs";
-import { access, chmod, lstat, mkdir, open, readFile, rename, stat, unlink, } from "node:fs/promises";
-import { basename, delimiter, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { access, lstat, mkdir, open, readFile, rename, stat, unlink } from "node:fs/promises";
+import { basename, delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { parseArgs } from "node:util";
 import { isLoopbackHost } from "../config.js";
+import { isCredentialKey, scrubCredentialText } from "../tool-definitions.js";
 export const DEFAULT_MCP_URL = "https://mcp.hue.run/mcp";
 const SERVER_NAME = "hue";
 const ENV_VAR = "HUE_MCP_KEY";
@@ -81,18 +82,21 @@ export const MCP_USAGE = `Usage: hue mcp install --client <claude-code|codex|con
                        [--toolsets NAMES] [--url URL]
                        [--scope project|user] [--dry-run] [--print]
 
-Configure a coding agent to use the Hue MCP server. A key configuration references the
-${ENV_VAR} environment variable; a key value is never written. A sign-in configuration holds
-only the URL: the client opens Hue in a browser, where you approve access to the projects of
-one organization.
+Configure a coding agent to use the Hue MCP server. A sign-in configuration holds only the
+URL: the client opens Hue in a browser, where you approve access to the projects of one
+organization. A key configuration references the ${ENV_VAR} environment variable; a key value
+is never written.
 
 Options:
   --client NAME   Coding agent to configure (required)
-  --auth MODE     key: reference ${ENV_VAR} (the default, except for conductor)
-                  oauth: URL only, sign in with Hue in the client (claude-code, codex and
-                  conductor; the default for conductor)
-  --read-only     key only: add ?read_only=true to the URL so write tools are hidden. A
-                  sign-in connection has Read and write access; use a Read key for read-only
+  --auth MODE     oauth: URL only, sign in with Hue in the client (claude-code, codex and
+                  conductor; their default)
+                  key: reference ${ENV_VAR} (the default for the other clients and with
+                  --read-only). Without --auth, claude-code and codex keep the choice of
+                  an existing entry, and use a key for a new one when ${ENV_VAR} is set
+  --read-only     Add ?read_only=true to a key configuration's URL so write tools are
+                  hidden; selects a key without --auth. A sign-in connection has Read and
+                  write access; use a Read key for read-only
   --project VALUE Pin the connection to one project by id or slug. Its tools omit project_id,
                   and the server is named hue-<value> so it can coexist with an unpinned hue
   --toolsets NAMES
@@ -113,7 +117,9 @@ Options:
 Files: claude-code .mcp.json, cursor .cursor/mcp.json, vscode .vscode/mcp.json (relative to the
 current directory). codex and gemini use their own CLI when it is on PATH; windsurf prints the
 snippet for its user configuration file. conductor registers the server for its Claude Code
-(user scope) and Codex agents with their CLIs, printing the command for a CLI not on PATH.`;
+(user scope) and Codex agents with their CLIs, printing the command for a CLI not on PATH.
+codex mcp add signs in at once and waits up to 5 minutes for the browser, so without --auth
+and outside a terminal the command prints it instead of running it.`;
 const json = (value) => `${JSON.stringify(value, null, 2)}\n`;
 /**
  * A URL as a POSIX shell word for printed commands: `?` is a zsh glob and `&` ends a command, so a
@@ -280,6 +286,10 @@ export function readOnlyMcpUrl(url) {
     parsed.searchParams.set("read_only", "true");
     return parsed.href;
 }
+/** Whether Hue treats the URL as read-only: it honors only `read_only=true` or `read_only=1`. */
+function isReadOnlyUrl(url) {
+    return ["true", "1"].includes(new URL(url).searchParams.get("read_only") ?? "");
+}
 class ConfigError extends Error {
     constructor(message) {
         super(message);
@@ -306,6 +316,7 @@ function mergeVscodeInput(root, input, display) {
     const others = (inputs ?? []).filter((item) => !(isRecord(item) && item.id === INPUT_ID));
     return { ...root, inputs: [...others, input] };
 }
+/** The parsed file, if any, and the file it was read from, so the write can replace that one. */
 async function readJsonConfig(path, display) {
     let info;
     try {
@@ -313,7 +324,7 @@ async function readJsonConfig(path, display) {
     }
     catch (error) {
         if (error.code === "ENOENT")
-            return undefined;
+            return { config: undefined };
         throw new ConfigError(`Cannot read ${display}: ${error.message}`);
     }
     if (info.isSymbolicLink())
@@ -324,40 +335,104 @@ async function readJsonConfig(path, display) {
         throw new ConfigError(`Refusing to use ${display}: it is larger than 1 MiB.`);
     const text = await readFile(path, "utf8");
     if (!text.trim())
-        return undefined;
+        return { config: undefined, file: info };
     try {
-        return JSON.parse(text);
+        return { config: JSON.parse(text), file: info };
     }
     catch {
         throw new ConfigError(`${display} is not valid JSON (comments are not supported); fix it or add the snippet by hand.`);
     }
 }
+/**
+ * Refuses a symbolic link, or anything but a directory, between the working directory and the file
+ * (`.cursor` or `.vscode`), as the file itself is refused. The working directory and its ancestors
+ * are not checked: on macOS `/tmp` and `/var` are links, and a home directory can be one. This runs
+ * before the file is read and again before the rename. Node has no `openat`, so it cannot pin the
+ * directory against an account that can write the project and swaps a link in after the last check.
+ */
+async function rejectLinkedParents(cwd, path, display) {
+    let current = cwd;
+    for (const part of relative(cwd, dirname(path)).split(sep).filter(Boolean)) {
+        current = join(current, part);
+        let info;
+        try {
+            info = await lstat(current);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return;
+            throw error;
+        }
+        const shown = displayPath(cwd, current);
+        if (info.isSymbolicLink())
+            throw new ConfigError(`Refusing to use ${display}: ${shown} is a symbolic link.`);
+        if (!info.isDirectory())
+            throw new ConfigError(`Refusing to use ${display}: ${shown} is not a directory.`);
+    }
+}
+/** The file's status, or undefined when there is none; a symbolic link is refused. */
 async function rejectSymlink(path, display) {
+    let info;
     try {
-        if ((await lstat(path)).isSymbolicLink())
-            throw new ConfigError(`Refusing to write ${display}: it is a symbolic link.`);
+        info = await lstat(path);
     }
     catch (error) {
         if (error.code === "ENOENT")
-            return;
+            return undefined;
         throw error;
     }
+    if (info.isSymbolicLink())
+        throw new ConfigError(`Refusing to write ${display}: it is a symbolic link.`);
+    return info;
 }
-/** Atomic write for a secret-free config file: temporary file, fsync, rename; mode 0644. */
-async function writeConfigFile(path, text, display) {
+/**
+ * Atomic write: temporary file, fsync, rename. A file it replaces keeps its permission bits, so one
+ * kept at 0600 because it holds other servers' tokens is never widened, except that other accounts
+ * lose write access; it keeps its group (or, when the group cannot be kept, its group and other
+ * accounts get only the access both had), and its owner when root runs the command. A new file is
+ * created owner-only, 0600 narrowed by the umask: people and clients add literal tokens to these
+ * files.
+ */
+async function writeConfigFile(cwd, path, text, display, read) {
     await mkdir(dirname(path), { recursive: true });
-    await rejectSymlink(path, display);
+    const existing = await rejectSymlink(path, display);
+    // The file replaced must be the one read: the content merged it, and its mode and group are kept.
+    // Another file in its place, such as one in a directory swapped in meanwhile, is refused.
+    if (existing?.dev !== read?.dev || existing?.ino !== read?.ino)
+        throw new ConfigError(`Refusing to write ${display}: it changed while the command ran.`);
     const temporary = join(dirname(path), `.${basename(path)}.${randomUUID()}.tmp`);
     try {
-        const handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o644);
+        const handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
         try {
             await handle.writeFile(text, "utf8");
+            if (existing) {
+                // Other accounts never keep write access: they could add a server command to run.
+                let mode = existing.mode & 0o775;
+                // The new file has the process's group (the directory's on macOS), which may differ. When
+                // the group cannot be kept, its members and everyone else get only what both had.
+                const created = await handle.stat();
+                if (created.gid !== existing.gid) {
+                    try {
+                        await handle.chown(-1, existing.gid);
+                    }
+                    catch {
+                        const shared = (mode >> 3) & mode & 0o007;
+                        mode = (mode & 0o700) | (shared << 3) | shared;
+                    }
+                }
+                await handle.chmod(mode);
+                // Root also gives the file back to its owner, last: changing the mode of another account's
+                // file would need CAP_FOWNER. If it cannot, the write fails and the old file stays in place,
+                // rather than leaving one its owner cannot read.
+                if (process.geteuid?.() === 0 && created.uid !== existing.uid)
+                    await handle.chown(existing.uid, -1);
+            }
             await handle.sync();
         }
         finally {
             await handle.close();
         }
-        await chmod(temporary, 0o644);
+        await rejectLinkedParents(cwd, path, display);
         await rejectSymlink(path, display);
         await rename(temporary, path);
     }
@@ -366,6 +441,149 @@ async function writeConfigFile(path, text, display) {
         throw error;
     }
 }
+const REDACTED = "[redacted]";
+/**
+ * Only references a client resolves (`${NAME}`, `${env:NAME}`, `${input:id}`), after an optional
+ * `Bearer`, `Basic` or `Token` scheme: no credential. A reference with a default does not match.
+ */
+const REFERENCE_ONLY = /^(?:(?:bearer|basic|token)[ \t]+)?(?:\$\{(?:input:[\w.-]+|(?:env:)?[A-Za-z_]\w*)\})+$/iu;
+/** Names `isCredentialKey` leaves out that configurations use for a credential field or option. */
+const CREDENTIAL_NAMES = new Set(["auth", "pat", "bearer", "env"]);
+/** `isCredentialKey`, `CREDENTIAL_NAMES`, or a name ending in `key`, `keys`, `header` or `headers`. */
+function isCredentialName(name) {
+    const normalized = name.toLowerCase().replace(/[-_]/g, "");
+    return (isCredentialKey(name) ||
+        CREDENTIAL_NAMES.has(normalized) ||
+        /(?:keys?|headers?)$/u.test(normalized));
+}
+/**
+ * An `args` option whose next item is its value and names a credential: `--api-key`, `--header`,
+ * or `-H`, the header option of curl and `mcp-remote`.
+ */
+function isCredentialOption(item) {
+    if (item === "-H")
+        return true;
+    const name = typeof item === "string" ? /^--?([A-Za-z][\w-]*)$/u.exec(item)?.[1] : undefined;
+    return name !== undefined && isCredentialName(name);
+}
+/** `--name=value`, or `NAME=value` as `env` takes it, as an `args` item. */
+const OPTION_VALUE = /^(-{0,2}([A-Za-z][\w-]*)=)(.*)$/su;
+/**
+ * The item after Docker's `-e` or `--env`, as an environment value is shown: a variable name alone
+ * (passed through from the environment) as is, `NAME=VALUE` with its value redacted. Anything else,
+ * such as the script after `node -e`, can hold a literal credential in any shape and is redacted.
+ */
+function redactEnvironmentItem(item) {
+    if (/^[A-Za-z_]\w*$/u.test(item))
+        return item;
+    const assignment = /^([A-Za-z_]\w*)=(.*)$/su.exec(item);
+    if (!assignment)
+        return REDACTED;
+    return REFERENCE_ONLY.test(assignment[2]) ? item : `${assignment[1]}=${REDACTED}`;
+}
+/** A URL path segment long and mixed enough to be a token, as some servers put their key there. */
+const TOKEN_SEGMENT = /^(?=[^/]*[A-Za-z])(?=[^/]*\d)[^/]{16,}$/u;
+/** Whether a URL path segment is token-like, or a credential `scrubCredentialText` knows. */
+function isTokenSegment(segment) {
+    return TOKEN_SEGMENT.test(segment) || scrubCredentialText(segment) !== segment;
+}
+/** A URL with each token-like path segment replaced; any other string is returned as is. */
+function redactUrlPath(value) {
+    if (!/^(?:https?|wss?):\/\//iu.test(value))
+        return value;
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        return value;
+    }
+    const segments = parsed.pathname.split("/");
+    if (!segments.some(isTokenSegment))
+        return value;
+    parsed.pathname = segments
+        .map((segment) => (isTokenSegment(segment) ? REDACTED : segment))
+        .join("/");
+    return parsed.href;
+}
+/** A query parameter name shown before its redacted value; any other becomes `[redacted]` whole. */
+const PARAMETER_NAME = /^[A-Za-z_][\w.-]{0,31}$/u;
+/**
+ * The URL this command writes, as its output shows it: the selections it validated (`toolsets`,
+ * `project`, and `read_only` when true, false, 1 or 0) are kept; any other query value, and a
+ * token-like path segment, becomes `[redacted]`. `parseMcpUrl` has already refused userinfo and a
+ * fragment. Commands printed for a person to run keep the URL as given.
+ */
+function displayMcpUrl(url) {
+    const parsed = new URL(url);
+    const query = parsed.search
+        .slice(1)
+        .split("&")
+        .filter(Boolean)
+        .map((pair) => {
+        const [name = "", value = ""] = pair.split("=", 2);
+        const selection = name === "toolsets" ||
+            name === "project" ||
+            (name === "read_only" && /^(?:true|false|1|0)$/u.test(value));
+        if (selection)
+            return pair;
+        return PARAMETER_NAME.test(name) &&
+            !TOKEN_SEGMENT.test(name) &&
+            scrubCredentialText(name) === name
+            ? `${name}=${REDACTED}`
+            : REDACTED;
+    });
+    return redactUrlPath(`${parsed.origin}${parsed.pathname}${query.length ? `?${query.join("&")}` : ""}`);
+}
+/**
+ * A merged configuration as `--dry-run` prints it. Header and `env` values, strings and numbers
+ * under a key naming a credential, the value of a credential option in `args` (`--api-key VALUE`,
+ * `--key=VALUE`) and token-like URL path segments become `[redacted]` unless they only reference a
+ * variable or input; other strings lose what `scrubCredentialText` finds (a known token prefix, a
+ * `token=` pair, a URL's userinfo and query values). The server names under `serversKey` are not
+ * read as field names. `url`, the address this command writes, is shown as `shownUrl`.
+ */
+function redactConfig(root, serversKey, url, shownUrl) {
+    const redact = (value, secret, depth, names) => {
+        if (depth > 256)
+            return REDACTED;
+        if (typeof value === "number")
+            return secret ? REDACTED : value;
+        if (typeof value === "string") {
+            if (value === url)
+                return shownUrl;
+            if (REFERENCE_ONLY.test(value))
+                return value;
+            if (secret)
+                return REDACTED;
+            const option = OPTION_VALUE.exec(value);
+            if (!option)
+                return scrubCredentialText(redactUrlPath(value));
+            if (REFERENCE_ONLY.test(option[3]))
+                return value;
+            const shown = isCredentialName(option[2])
+                ? REDACTED
+                : scrubCredentialText(redactUrlPath(option[3]));
+            return `${option[1]}${shown}`;
+        }
+        if (Array.isArray(value))
+            return value.map((item, index) => {
+                const previous = value[index - 1];
+                if (!secret && typeof item === "string" && (previous === "-e" || previous === "--env"))
+                    return redactEnvironmentItem(item);
+                return redact(item, secret || isCredentialOption(previous), depth + 1, false);
+            });
+        if (!isRecord(value))
+            return value;
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+            key,
+            redact(item, secret || (!(names && isRecord(item)) && isCredentialName(key)), depth + 1, depth === 0 && key === serversKey),
+        ]));
+    };
+    return redact(root, false, 0, false);
+}
+/** Whether a person is likely watching: login.ts opens a browser on the same test. */
+const isTerminal = (stream) => stream.isTTY === true;
 async function findExecutable(name, env) {
     const searchPath = env.PATH ?? env.Path ?? "";
     const extensions = process.platform === "win32" ? (env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";") : [""];
@@ -411,6 +629,102 @@ function runClientCli(executable, args, options) {
         }
     });
 }
+/**
+ * A client CLI's exit code and output within ten seconds, none of it shown; null when it could not
+ * start or ran out of time.
+ */
+function readClientCli(executable, args, options) {
+    return new Promise((resolveRun) => {
+        try {
+            const child = spawn(executable, args, { ...options, stdio: ["ignore", "pipe", "pipe"] });
+            const collect = () => {
+                const chunks = [];
+                let size = 0;
+                return {
+                    add: (chunk) => {
+                        size += chunk.length;
+                        if (size <= MAX_CONFIG_BYTES)
+                            chunks.push(chunk);
+                    },
+                    text: () => (size <= MAX_CONFIG_BYTES ? Buffer.concat(chunks).toString() : null),
+                };
+            };
+            const out = collect();
+            const err = collect();
+            let timedOut = false;
+            const timer = setTimeout(() => {
+                timedOut = true;
+                child.kill();
+            }, 10_000);
+            child.stdout.on("data", out.add);
+            child.stderr.on("data", err.add);
+            child.once("error", () => {
+                clearTimeout(timer);
+                resolveRun(null);
+            });
+            child.once("close", (code) => {
+                clearTimeout(timer);
+                const stdout = out.text();
+                const stderr = err.text();
+                resolveRun(timedOut || code === null || stdout === null || stderr === null
+                    ? null
+                    : { code, stdout, stderr });
+            });
+        }
+        catch {
+            resolveRun(null);
+        }
+    });
+}
+const hasAuthorization = (headers) => isRecord(headers) && Object.keys(headers).some((name) => name.toLowerCase() === "authorization");
+/** The server's HTTP entry in `./.mcp.json`; an unreadable file is reported by the write. */
+async function readClaudeProjectEntry(cwd, serverName) {
+    let config;
+    try {
+        ({ config } = await readJsonConfig(resolve(cwd, ".mcp.json"), ".mcp.json"));
+    }
+    catch {
+        return undefined;
+    }
+    const servers = isRecord(config) ? config.mcpServers : undefined;
+    const entry = isRecord(servers) ? servers[serverName] : undefined;
+    if (!isRecord(entry) || typeof entry.url !== "string" || !parseMcpUrl(entry.url))
+        return undefined;
+    const auth = hasAuthorization(entry.headers) ? "key" : "oauth";
+    return { url: entry.url, auth, source: ".mcp.json" };
+}
+/**
+ * The server's entry in Codex's configuration, as `codex mcp get --json` reports it: `found` with
+ * its exact output, `none` when Codex says it has no such server (or holds one that is not an HTTP
+ * Hue entry), or `unknown` when Codex could not be asked or answered otherwise, which is never
+ * taken for `none`.
+ */
+async function readCodexEntry(executable, serverName, options) {
+    const result = await readClientCli(executable, ["mcp", "get", serverName, "--json"], options);
+    if (!result)
+        return { state: "unknown" };
+    if (result.code !== 0)
+        return result.stderr.includes(`No MCP server named '${serverName}' found`)
+            ? { state: "none" }
+            : { state: "unknown" };
+    let transport;
+    try {
+        transport = JSON.parse(result.stdout).transport;
+    }
+    catch {
+        return { state: "unknown" };
+    }
+    if (!isRecord(transport) || typeof transport.url !== "string" || !parseMcpUrl(transport.url))
+        return { state: "none" };
+    const key = Boolean(transport.bearer_token_env_var) ||
+        hasAuthorization(transport.http_headers) ||
+        hasAuthorization(transport.env_http_headers);
+    return {
+        state: "found",
+        entry: { url: transport.url, auth: key ? "key" : "oauth", source: "Codex's configuration" },
+        raw: result.stdout,
+    };
+}
 /** Validates the MCP endpoint: HTTPS, or HTTP for loopback test servers; no credentials or hash. */
 export function parseMcpUrl(value) {
     let url;
@@ -525,20 +839,69 @@ function planFor(client, auth, scope, url, serverName) {
         }
     }
 }
-function nextSteps(client, auth, serverName, project) {
+/**
+ * The authentication used without `--auth`, and the line saying why. A client that can sign in
+ * does, unless a key is asked for: read-only access (`--read-only`, or `read_only=true` in
+ * `--url`), which a sign-in connection does not have. For Claude Code and Codex, an existing entry
+ * keeps its choice, so rerunning the command, to change `--toolsets` for instance, never swaps a
+ * working setup; a key keeps its `read_only`. A new entry uses a key when `HUE_MCP_KEY` is set in
+ * `env`; only the variable's presence is checked. Conductor signed in by default before and keeps
+ * doing so: its agents read the login-shell environment Conductor captures, not this shell's. The
+ * other clients only take a key, so they get no line.
+ */
+function defaultAuth(client, readOnly, existing, env) {
+    if (!OAUTH_CLIENTS.includes(client))
+        return { auth: "key" };
+    if (readOnly)
+        return {
+            auth: "key",
+            note: `Using a key: ${readOnly} needs one, since a sign-in connection has Read and write access.`,
+        };
+    if (existing?.auth === "key") {
+        const keepReadOnly = isReadOnlyUrl(existing.url);
+        return {
+            auth: "key",
+            keepReadOnly,
+            note: keepReadOnly
+                ? `Keeping a read-only key, as the existing entry in ${existing.source} has; pass --auth key to drop read_only, or --auth oauth to sign in with Hue instead.`
+                : `Keeping a key, as the existing entry in ${existing.source} has; pass --auth oauth to sign in with Hue instead.`,
+        };
+    }
+    if (existing)
+        return {
+            auth: "oauth",
+            note: `Keeping sign-in with Hue, as the existing entry in ${existing.source} has; pass --auth key to use a key instead.`,
+        };
+    if (client !== "conductor" && env[ENV_VAR])
+        return {
+            auth: "key",
+            note: `Using a key (${ENV_VAR} is set); pass --auth oauth to sign in with Hue instead.`,
+        };
+    return {
+        auth: "oauth",
+        note: `Using sign-in with Hue (${client === "conductor" ? "Conductor's default" : `${ENV_VAR} is not set`}); pass --auth key to use a key instead.`,
+    };
+}
+function nextSteps(client, auth, serverName, project, scope, readOnly) {
     const label = CLIENT_LABELS[client];
     const approve = project
         ? `Sign in to Hue and approve the connection. It acts only on the pinned project ${project}, within your role; for read-only access, use a Read project key with --auth key.`
-        : "Sign in to Hue and approve the connection. It can read and write every active project in the organization you choose, within your role; for read-only access, use a Read project key with --auth key.";
+        : "Sign in to Hue and approve the connection. It can read and write every active project in the organization the consent page names, within your role; for read-only access, use a Read project key with --auth key.";
+    // A read-only configuration needs a key: plain hue login refuses a Read key.
+    const stored = readOnly
+        ? "hue login --keys coding-agent stores it in .env.hue and accepts a Read key"
+        : "hue login stores it in .env.hue";
     let lines;
     if (auth === "oauth")
         lines =
             client === "claude-code"
-                ? [`In Claude Code, run /mcp, select ${serverName} and choose Authenticate. ${approve}`]
+                ? [
+                    `Restart Claude Code (for example claude --continue)${scope === "project" ? ` and approve ${serverName} from .mcp.json` : ""}, then run /mcp, select ${serverName} and choose Authenticate. ${approve}`,
+                ]
                 : client === "codex"
                     ? [
                         `If Codex did not open Hue in your browser, run: codex mcp login ${serverName}`,
-                        approve,
+                        `${approve} Then start a new Codex session, which loads ${serverName}.`,
                     ]
                     : [
                         `In Conductor, open MCP status from the plug icon or /mcp-status, refresh, and use ${serverName}'s authentication action. ${approve}`,
@@ -550,13 +913,13 @@ function nextSteps(client, auth, serverName, project) {
         ];
     else if (client === "conductor")
         lines = [
-            `Conductor agents read ${ENV_VAR} from the login-shell environment Conductor captures, so export it there, not only in a terminal; hue login stores it in .env.hue. Sign-in (--auth oauth) needs no variable.`,
+            `Conductor agents read ${ENV_VAR} from the login-shell environment Conductor captures, so export it there, not only in a terminal; ${stored}.${readOnly ? "" : " Sign-in (--auth oauth) needs no variable."}`,
         ];
     else
         lines = [
-            `Export ${ENV_VAR} in the shell that starts ${label}; hue login stores it in .env.hue:`,
+            `Export ${ENV_VAR} in the shell that starts ${label}; ${stored}:`,
             "  set -a; . ./.env.hue; set +a",
-            `An app started from the Dock or a launcher does not see that shell's variables; start ${label} from the shell${OAUTH_CLIENTS.includes(client) ? ", or sign in instead with --auth oauth" : ""}.`,
+            `An app started from the Dock or a launcher does not see that shell's variables; start ${label} from the shell${OAUTH_CLIENTS.includes(client) && !readOnly ? ", or sign in instead with --auth oauth" : ""}.`,
         ];
     // `codex mcp add` has no option for it, so a registered server gets the line by hand.
     if (client === "codex" || client === "conductor")
@@ -602,10 +965,10 @@ export async function runMcpCommand(argv, io = {}) {
     if (!client || !CLIENT_IDS.includes(client))
         return fail(`${client ? `Unknown client: ${client}.` : "--client is required."} Choose one of ${CLIENT_IDS.join(", ")}.\n\n${MCP_USAGE}`, 2);
     const clientId = client;
-    const auth = parsed.values.auth ?? (clientId === "conductor" ? "oauth" : "key");
-    if (auth !== "key" && auth !== "oauth")
+    const explicitAuth = parsed.values.auth;
+    if (explicitAuth !== undefined && explicitAuth !== "key" && explicitAuth !== "oauth")
         return fail(`--auth must be key or oauth.\n\n${MCP_USAGE}`, 2);
-    if (auth === "oauth" && !OAUTH_CLIENTS.includes(clientId))
+    if (explicitAuth === "oauth" && !OAUTH_CLIENTS.includes(clientId))
         return fail(clientId === "cursor"
             ? "--auth oauth is not available for cursor: Hue does not yet accept Cursor's sign-in callback. Use a key (the default), or sign in from claude-code or codex."
             : `--auth oauth is available for ${OAUTH_CLIENTS.join(", ")}. Use a key (the default) for ${clientId}.`, 2);
@@ -617,12 +980,6 @@ export async function runMcpCommand(argv, io = {}) {
     let url = parseMcpUrl(parsed.values.url ?? DEFAULT_MCP_URL);
     if (!url)
         return fail("--url must be an HTTPS URL such as https://mcp.hue.run/mcp (plain HTTP is accepted for loopback test servers only).", 2);
-    // A sign-in connection's access is chosen when it is approved; read_only is not part of it.
-    if (auth === "oauth" &&
-        (parsed.values["read-only"] || new URL(url).searchParams.has("read_only")))
-        return fail("A sign-in connection has Read and write access and cannot be made read-only by its URL. For read-only access, use a Read project key (--auth key), or add --read-only to a key configuration.", 2);
-    if (parsed.values["read-only"])
-        url = readOnlyMcpUrl(url);
     // --project replaces a pin already in --url. Without it, validate and keep the URL's pin.
     const urlProjects = new URL(url).searchParams.getAll("project");
     let projectValue = parsed.values.project;
@@ -641,6 +998,40 @@ export async function runMcpCommand(argv, io = {}) {
         project = selected.project;
         serverName = selected.serverName;
     }
+    const urlReadOnly = new URL(url).searchParams.has("read_only");
+    const readOnly = parsed.values["read-only"]
+        ? "--read-only"
+        : isReadOnlyUrl(url)
+            ? "read_only in --url"
+            : undefined;
+    // Without --auth or read_only, an existing entry keeps its choice. A user-scope `claude mcp add`
+    // refuses a name it already has, and Conductor keeps its default, so only these two are read.
+    let existing;
+    if (explicitAuth === undefined && !parsed.values["read-only"] && !urlReadOnly) {
+        if (clientId === "claude-code" && scope === "project")
+            existing = await readClaudeProjectEntry(cwd, serverName);
+        else if (clientId === "codex") {
+            // Without codex on PATH nothing is run, so nothing Codex holds is replaced. With it, an
+            // entry that cannot be read may hold either a key or a sign-in, so the command does not
+            // guess which to keep.
+            const codex = await findExecutable("codex", env);
+            const lookup = codex ? await readCodexEntry(codex, serverName, { cwd, env }) : undefined;
+            if (lookup?.state === "unknown")
+                return fail(`Could not read Codex's "${serverName}" entry (codex mcp get failed), so the command will not guess whether to keep a key or sign-in. Pass --auth oauth or --auth key.`, 2);
+            if (lookup?.state === "found")
+                existing = lookup.entry;
+        }
+    }
+    const { auth, keepReadOnly, note } = explicitAuth === undefined
+        ? defaultAuth(clientId, readOnly, existing, env)
+        : { auth: explicitAuth };
+    // A sign-in connection's access is chosen when it is approved; read_only is not part of it.
+    if (auth === "oauth" && readOnly)
+        return fail("A sign-in connection has Read and write access and cannot be made read-only by its URL. For read-only access, use a Read project key (--auth key), or add --read-only to a key configuration.", 2);
+    if (auth === "oauth" && urlReadOnly)
+        return fail("Remove read_only from --url: a sign-in URL does not carry it, since a sign-in connection has Read and write access, and Hue reads only read_only=true or 1. For read-only access, use a Read project key (--auth key).", 2);
+    if (parsed.values["read-only"] || keepReadOnly)
+        url = readOnlyMcpUrl(url);
     url = projectMcpUrl(url, project);
     // --toolsets wins over a selection already in --url, which wins over the client's default.
     // Both sources are validated: Hue ignores an unknown name and would list its default.
@@ -653,12 +1044,18 @@ export async function runMcpCommand(argv, io = {}) {
         toolsets = selected.toolsets;
     }
     url = toolsetsMcpUrl(url, toolsets);
+    // On stderr, so --print and --dry-run output stays as it was.
+    if (note)
+        stderr.write(`${note}\n`);
+    const shownUrl = displayMcpUrl(url);
+    // What the command reports doing; a command a person is to run is printed as given.
+    const shownCommand = (command) => command.display.replaceAll(shellWord(url), () => shellWord(shownUrl));
     const plan = planFor(clientId, auth, scope, url, serverName);
     if (parsed.values.print) {
         stdout.write(plan.snippet);
         return 0;
     }
-    const steps = nextSteps(clientId, auth, serverName, project);
+    const steps = nextSteps(clientId, auth, serverName, project, scope, isReadOnlyUrl(url));
     if (plan.kind === "manual") {
         out(plan.hint);
         stdout.write(plan.snippet);
@@ -669,10 +1066,13 @@ export async function runMcpCommand(argv, io = {}) {
     if (plan.kind === "cli") {
         if (parsed.values["dry-run"]) {
             for (const command of plan.commands)
-                out(`Would run: ${command.display}`);
+                out(`Would run: ${shownCommand(command)}`);
             return 0;
         }
         let failed = false;
+        // `codex mcp add` signs in at once and waits up to five minutes for the browser. Outside a
+        // terminal (CI, an agent's shell tool) nobody may finish that, so a default sign-in prints it.
+        const deferCodex = auth === "oauth" && explicitAuth === undefined && !isTerminal(stdout);
         for (const command of plan.commands) {
             const executable = await findExecutable(command.executable, env);
             if (!executable) {
@@ -681,12 +1081,36 @@ export async function runMcpCommand(argv, io = {}) {
                 out(command.display);
                 continue;
             }
-            out(`Running: ${command.display}`);
+            if (deferCodex && command.executable === "codex") {
+                out("Not running codex mcp add: it signs in at once and waits up to 5 minutes for the browser, and no terminal is attached. Run it where you can sign in, or pass --auth oauth to run it here and wait:");
+                out(command.display);
+                continue;
+            }
+            // What Codex held before, so a failed add is not mistaken for this run's registration.
+            const codexSignIn = auth === "oauth" && command.executable === "codex";
+            const before = codexSignIn
+                ? await readCodexEntry(executable, serverName, { cwd, env })
+                : undefined;
+            out(`Running: ${shownCommand(command)}`);
             const code = await runClientCli(executable, command.args, { cwd, env, stdout, stderr });
             if (code === 0) {
-                out(`Registered the "${serverName}" MCP server (${url}) with ${command.label}.`);
+                out(`Registered the "${serverName}" MCP server (${shownUrl}) with ${command.label}.`);
                 continue;
             }
+            // Codex writes its entry before signing in, so a sign-in that timed out or was denied
+            // leaves the server registered; `codex mcp login` signs in again. Only an entry this run
+            // wrote counts: one Codex already held unchanged proves nothing about this add.
+            if (code !== null && codexSignIn) {
+                const after = await readCodexEntry(executable, serverName, { cwd, env });
+                const wrote = after.state === "found" &&
+                    after.entry.auth === "oauth" &&
+                    after.entry.url === url &&
+                    (before?.state === "none" || (before?.state === "found" && before.raw !== after.raw));
+                if (wrote) {
+                    out(`Registered the "${serverName}" MCP server (${shownUrl}) with Codex, but its sign-in did not finish. Run codex mcp login ${serverName} to sign in.`);
+                    continue;
+                }
+            }
             failed = true;
             stderr.write(`${command.executable} ${code === null ? "could not be started" : `exited with code ${code}`}. Run this command yourself:\n${command.display}\n`);
         }
@@ -698,10 +1122,14 @@ export async function runMcpCommand(argv, io = {}) {
     }
     const path = resolve(cwd, plan.file);
     const display = displayPath(cwd, path);
+    let merged;
     let content;
+    let read;
     try {
+        await rejectLinkedParents(cwd, path, display);
         const existing = await readJsonConfig(path, display);
-        let merged = mergeServerEntry(existing, plan.key, plan.entry, display, serverName);
+        read = existing.file;
+        merged = mergeServerEntry(existing.config, plan.key, plan.entry, display, serverName);
         if (plan.input)
             merged = mergeVscodeInput(merged, plan.input, display);
         content = json(merged);
@@ -712,17 +1140,21 @@ export async function runMcpCommand(argv, io = {}) {
         return fail(`Could not read ${display}: ${error.message}`);
     }
     if (parsed.values["dry-run"]) {
-        out(`Would write ${display}:`);
-        stdout.write(content);
+        // Other servers' entries can hold literal tokens; the file keeps them, the output does not.
+        const shown = json(redactConfig(merged, plan.key, url, shownUrl));
+        out(shown === content
+            ? `Would write ${display}:`
+            : `Would write ${display} (credential values shown as ${REDACTED}):`);
+        stdout.write(shown);
         return 0;
     }
     try {
-        await writeConfigFile(path, content, display);
+        await writeConfigFile(cwd, path, content, display, read);
     }
     catch (error) {
         return fail(`Could not write ${display}: ${error.message}`);
     }
-    out(`Wrote ${display} with the "${serverName}" MCP server (${url}).`);
+    out(`Wrote ${display} with the "${serverName}" MCP server (${shownUrl}).`);
     for (const line of steps)
         out(line);
     return 0;