@hue-run/sdk 0.11.1 → 0.11.3

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";
@@ -16,7 +17,7 @@ const MAX_CONFIG_BYTES = 1024 * 1024;
  * lists them, after which each call takes `project_id`. It reads what needs attention and falls
  * back to recent traces, so a project without errors still proves the read path.
  */
-export const MCP_VERIFY_PROMPT = "Use the Hue MCP: call list_projects and confirm which project to inspect. Then call get_project_context and show that project's traces from the last 24 hours that need attention or have errors, with links; if there are none, show its 5 most recent traces. For an organization connection, pass the project's id as project_id on each call after list_projects.";
+export const MCP_VERIFY_PROMPT = "Use the Hue MCP: call list_projects and confirm which project to inspect. Then call get_project_context and show that project's traces from the last 24 hours that need attention or have errors, with links; if there are none, show its 5 most recent traces. For an organization connection, pass the project's id or slug as project_id on each call after list_projects.";
 const CLIENT_IDS = [
     "claude-code",
     "codex",
@@ -37,13 +38,19 @@ const CLIENT_LABELS = {
 };
 /** Clients whose browser sign-in with Hue works against the deployed server. */
 const OAUTH_CLIENTS = ["claude-code", "codex", "conductor"];
-/** Toolset names Hue's MCP server accepts: `all`, its catalog groups and the `observe` profile. */
+/** Toolset names Hue's MCP server accepts: `all`, its catalog groups and its curated profiles. */
 export const MCP_TOOLSETS = [
     "all",
     "observe",
+    "author",
+    "evaluate",
     "project",
     "traces",
-    "evals",
+    "eval_sets",
+    "runs",
+    "judges",
+    "cases",
+    "runners",
     "environments",
     "intents",
     "docs",
@@ -53,6 +60,8 @@ export const MCP_TOOLSETS = [
  * keep that URL bare; every other configuration carries the selection in its URL.
  */
 export const TOOLSETS_HEADER = "X-Hue-MCP-Toolsets";
+/** The header form of `?project=`, used by the sign-in Codex TOML to keep its URL bare. */
+export const PROJECT_HEADER = "X-Hue-MCP-Project";
 /**
  * Toolsets a client's configuration selects unless `--toolsets` says otherwise. Claude Code,
  * Codex and Conductor's agents defer MCP tools behind their own tool search, so listing every tool
@@ -69,7 +78,8 @@ const DEFAULT_TOOLSETS = {
 /** Codex runs a server's tool calls one at a time without it; each Hue call is independent. */
 const CODEX_PARALLEL = "supports_parallel_tool_calls = true";
 export const MCP_USAGE = `Usage: hue mcp install --client <claude-code|codex|conductor|cursor|vscode|windsurf|gemini>
-                       [--auth key|oauth] [--read-only] [--toolsets NAMES] [--url URL]
+                       [--auth key|oauth] [--read-only] [--project ID-OR-SLUG]
+                       [--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
@@ -84,10 +94,13 @@ Options:
                   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
+  --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
-                  Tools to list, comma-separated: all, observe (production reads),
-                  project, traces, evals, environments, intents or docs, added to the
-                  URL as ?toolsets=. Defaults: all for claude-code, codex and conductor,
+                  Tools to list, comma-separated: all; the observe, author or evaluate
+                  profiles; or project, traces, eval_sets, runs, judges, cases, runners,
+                  environments, intents or docs. Added to the URL as ?toolsets=.
+                  Defaults: all for claude-code, codex and conductor,
                   which search their own tools; observe for cursor. Without a selection
                   Hue lists the production reads and search_hue_tools, which reaches
                   every other tool
@@ -114,7 +127,7 @@ export function shellWord(value) {
  * Canonical Hue client snippets for a key configuration; the JSON values are also the merge
  * entries for config files.
  */
-export function renderMcpSnippets(url) {
+export function renderMcpSnippets(url, serverName = SERVER_NAME) {
     const bearer = (reference) => `Bearer ${reference}`;
     const claudeCodeServer = {
         type: "http",
@@ -139,7 +152,7 @@ export function renderMcpSnippets(url) {
     };
     return {
         claudeCodeServer,
-        claudeCodeProjectJson: json({ mcpServers: { [SERVER_NAME]: claudeCodeServer } }),
+        claudeCodeProjectJson: json({ mcpServers: { [serverName]: claudeCodeServer } }),
         claudeCodeCli: {
             args: [
                 "mcp",
@@ -148,25 +161,25 @@ export function renderMcpSnippets(url) {
                 "http",
                 "--scope",
                 "user",
-                SERVER_NAME,
+                serverName,
                 url,
                 "--header",
                 `Authorization: Bearer \${${ENV_VAR}}`,
             ],
-            display: `claude mcp add --transport http --scope user ${SERVER_NAME} ${shellWord(url)} --header 'Authorization: Bearer \${${ENV_VAR}}'`,
+            display: `claude mcp add --transport http --scope user ${serverName} ${shellWord(url)} --header 'Authorization: Bearer \${${ENV_VAR}}'`,
         },
         cursorServer,
-        cursorJson: json({ mcpServers: { [SERVER_NAME]: cursorServer } }),
+        cursorJson: json({ mcpServers: { [serverName]: cursorServer } }),
         codexCli: {
-            args: ["mcp", "add", SERVER_NAME, "--url", url, "--bearer-token-env-var", ENV_VAR],
-            display: `codex mcp add ${SERVER_NAME} --url ${shellWord(url)} --bearer-token-env-var ${ENV_VAR}`,
+            args: ["mcp", "add", serverName, "--url", url, "--bearer-token-env-var", ENV_VAR],
+            display: `codex mcp add ${serverName} --url ${shellWord(url)} --bearer-token-env-var ${ENV_VAR}`,
         },
-        codexToml: `[mcp_servers.${SERVER_NAME}]\nurl = "${url}"\nbearer_token_env_var = "${ENV_VAR}"\n${CODEX_PARALLEL}\n`,
+        codexToml: `[mcp_servers.${serverName}]\nurl = "${url}"\nbearer_token_env_var = "${ENV_VAR}"\n${CODEX_PARALLEL}\n`,
         vscodeServer,
         vscodeInput,
-        vscodeJson: json({ servers: { [SERVER_NAME]: vscodeServer }, inputs: [vscodeInput] }),
+        vscodeJson: json({ servers: { [serverName]: vscodeServer }, inputs: [vscodeInput] }),
         windsurfServer,
-        windsurfJson: json({ mcpServers: { [SERVER_NAME]: windsurfServer } }),
+        windsurfJson: json({ mcpServers: { [serverName]: windsurfServer } }),
         geminiCli: {
             args: [
                 "mcp",
@@ -175,38 +188,44 @@ export function renderMcpSnippets(url) {
                 "user",
                 "--transport",
                 "http",
-                SERVER_NAME,
+                serverName,
                 url,
                 "--header",
                 `Authorization: Bearer \${${ENV_VAR}}`,
             ],
             // Single quotes keep the reference literal when a person runs this in a shell where the
             // key is exported; Gemini CLI expands ${HUE_MCP_KEY} from its settings at connection time.
-            display: `gemini mcp add --scope user --transport http ${SERVER_NAME} ${shellWord(url)} --header 'Authorization: Bearer \${${ENV_VAR}}'`,
+            display: `gemini mcp add --scope user --transport http ${serverName} ${shellWord(url)} --header 'Authorization: Bearer \${${ENV_VAR}}'`,
         },
     };
 }
 /**
  * Sign-in snippets: the server URL and nothing secret. The client discovers Hue's OAuth metadata
  * from it and sends it, query included, on every request; the token's resource ignores the query,
- * so `?toolsets=` selects tools here as it does for a key.
+ * so `?toolsets=` and `?project=` select tools and a project here as they do for a key.
  */
-export function renderMcpSignInSnippets(url) {
-    const toolsets = new URL(url).searchParams.get("toolsets");
+export function renderMcpSignInSnippets(url, serverName = SERVER_NAME) {
+    const parsed = new URL(url);
+    const toolsets = parsed.searchParams.get("toolsets");
+    const project = parsed.searchParams.get("project");
+    const headers = [
+        toolsets ? `"${TOOLSETS_HEADER}" = "${toolsets}"` : null,
+        project ? `"${PROJECT_HEADER}" = "${project}"` : null,
+    ].filter((value) => value !== null);
     const claudeCodeServer = { type: "http", url };
     return {
         claudeCodeServer,
-        claudeCodeProjectJson: json({ mcpServers: { [SERVER_NAME]: claudeCodeServer } }),
+        claudeCodeProjectJson: json({ mcpServers: { [serverName]: claudeCodeServer } }),
         claudeCodeCli: {
-            args: ["mcp", "add", "--transport", "http", "--scope", "user", SERVER_NAME, url],
-            display: `claude mcp add --transport http --scope user ${SERVER_NAME} ${shellWord(url)}`,
+            args: ["mcp", "add", "--transport", "http", "--scope", "user", serverName, url],
+            display: `claude mcp add --transport http --scope user ${serverName} ${shellWord(url)}`,
         },
         codexCli: {
-            args: ["mcp", "add", SERVER_NAME, "--url", url],
-            display: `codex mcp add ${SERVER_NAME} --url ${shellWord(url)}`,
+            args: ["mcp", "add", serverName, "--url", url],
+            display: `codex mcp add ${serverName} --url ${shellWord(url)}`,
         },
-        // The header form of the same selection, for a TOML entry that keeps its URL bare.
-        codexToml: `[mcp_servers.${SERVER_NAME}]\nurl = "${toolsetsMcpUrl(url, undefined)}"\n${toolsets ? `http_headers = { "${TOOLSETS_HEADER}" = "${toolsets}" }\n` : ""}${CODEX_PARALLEL}\n`,
+        // Header forms of the selections, for a TOML entry that keeps its URL bare.
+        codexToml: `[mcp_servers.${serverName}]\nurl = "${projectMcpUrl(toolsetsMcpUrl(url, undefined), undefined)}"\n${headers.length ? `http_headers = { ${headers.join(", ")} }\n` : ""}${CODEX_PARALLEL}\n`,
     };
 }
 /**
@@ -237,6 +256,25 @@ export function toolsetsMcpUrl(url, toolsets) {
     parsed.search = `${query ? `${query}&` : ""}toolsets=${toolsets}`;
     return parsed.href;
 }
+/** Parses the id or slug used to pin a connection and derives its coexisting server name. */
+export function parseProject(value) {
+    const project = value.trim();
+    if (!project)
+        return { error: "--project is empty. Name a project id or slug, or remove the option." };
+    if (project.length > 256 || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/iu.test(project))
+        return {
+            error: "--project takes a project id or slug, using letters, numbers and hyphens.",
+        };
+    return { project, serverName: `${SERVER_NAME}-${project.toLowerCase()}` };
+}
+/** Replaces `?project=` while preserving the URL's other selections. */
+export function projectMcpUrl(url, project) {
+    const parsed = new URL(url);
+    parsed.searchParams.delete("project");
+    if (project)
+        parsed.searchParams.append("project", project);
+    return parsed.href;
+}
 /** `?read_only=true` hides and rejects Hue's write tools for any key. */
 export function readOnlyMcpUrl(url) {
     const parsed = new URL(url);
@@ -252,15 +290,15 @@ class ConfigError extends Error {
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-/** Replaces only the `hue` entry under `key`, keeping every other server and top-level field. */
-function mergeServerEntry(existing, key, entry, display) {
+/** Replaces only the selected server entry under `key`, keeping every other server and field. */
+function mergeServerEntry(existing, key, entry, display, serverName = SERVER_NAME) {
     if (existing !== undefined && !isRecord(existing))
         throw new ConfigError(`${display} must contain a JSON object.`);
     const root = existing ?? {};
     const servers = root[key];
     if (servers !== undefined && !isRecord(servers))
         throw new ConfigError(`${display}: "${key}" must be a JSON object.`);
-    return { ...root, [key]: { ...(servers ?? {}), [SERVER_NAME]: entry } };
+    return { ...root, [key]: { ...(servers ?? {}), [serverName]: entry } };
 }
 function mergeVscodeInput(root, input, display) {
     const inputs = root.inputs;
@@ -269,6 +307,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 {
@@ -276,7 +315,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())
@@ -287,40 +326,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);
     }
@@ -329,6 +432,147 @@ 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 or false) 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)$/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);
+}
 async function findExecutable(name, env) {
     const searchPath = env.PATH ?? env.Path ?? "";
     const extensions = process.platform === "win32" ? (env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";") : [""];
@@ -398,6 +642,7 @@ function parseMcpArguments(argv) {
             client: { type: "string" },
             auth: { type: "string" },
             "read-only": { type: "boolean", default: false },
+            project: { type: "string" },
             toolsets: { type: "string" },
             url: { type: "string" },
             scope: { type: "string" },
@@ -413,10 +658,10 @@ function displayPath(cwd, path) {
 }
 const notOnPath = (executable, label) => `${executable} is not on PATH. Run this where ${label} is installed:`;
 /** `auth: "oauth"` is only planned for {@link OAUTH_CLIENTS}; the caller refuses the others. */
-function planFor(client, auth, scope, url) {
-    const snippets = renderMcpSnippets(url);
+function planFor(client, auth, scope, url, serverName) {
+    const snippets = renderMcpSnippets(url, serverName);
     // Claude Code and Codex take the same plan shape with or without a key.
-    const shared = auth === "oauth" ? renderMcpSignInSnippets(url) : snippets;
+    const shared = auth === "oauth" ? renderMcpSignInSnippets(url, serverName) : snippets;
     const claudeUser = {
         executable: "claude",
         label: "Claude Code",
@@ -487,21 +732,23 @@ function planFor(client, auth, scope, url) {
         }
     }
 }
-function nextSteps(client, auth) {
+function nextSteps(client, auth, serverName, project) {
     const label = CLIENT_LABELS[client];
-    const approve = "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.";
+    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.";
     let lines;
     if (auth === "oauth")
         lines =
             client === "claude-code"
-                ? [`In Claude Code, run /mcp, select ${SERVER_NAME} and choose Authenticate. ${approve}`]
+                ? [`In Claude Code, run /mcp, select ${serverName} and choose Authenticate. ${approve}`]
                 : client === "codex"
                     ? [
-                        `If Codex did not open Hue in your browser, run: codex mcp login ${SERVER_NAME}`,
+                        `If Codex did not open Hue in your browser, run: codex mcp login ${serverName}`,
                         approve,
                     ]
                     : [
-                        `In Conductor, open MCP status from the plug icon or /mcp-status, refresh, and use ${SERVER_NAME}'s authentication action. ${approve}`,
+                        `In Conductor, open MCP status from the plug icon or /mcp-status, refresh, and use ${serverName}'s authentication action. ${approve}`,
                         "Start a new agent session if the Hue tools do not appear. Hue has not yet verified signed-in Conductor end to end; if the tools still do not load, rerun with --auth key.",
                     ];
     else if (client === "vscode")
@@ -520,8 +767,13 @@ function nextSteps(client, auth) {
         ];
     // `codex mcp add` has no option for it, so a registered server gets the line by hand.
     if (client === "codex" || client === "conductor")
-        lines.push(`If codex mcp add registered ${SERVER_NAME}, add this line under [mcp_servers.${SERVER_NAME}] in ~/.codex/config.toml so Codex runs Hue's tool calls in parallel:`, `  ${CODEX_PARALLEL}`);
-    return [...lines, "Then ask your agent:", `  ${MCP_VERIFY_PROMPT}`];
+        lines.push(`If codex mcp add registered ${serverName}, add this line under [mcp_servers.${serverName}] in ~/.codex/config.toml so Codex runs Hue's tool calls in parallel:`, `  ${CODEX_PARALLEL}`);
+    if (project)
+        lines.push(`If this connection returns HTTP 404, ${project} is not an active project this credential can reach. Change or remove --project; signing in again will not fix it.`);
+    const verify = project
+        ? `Use the Hue MCP: call list_projects and confirm it returns only the pinned project ${project} with connection.pinned true. Then call get_project_context and show that project's traces from the last 24 hours that need attention or have errors, with links; if there are none, show its 5 most recent traces. Do not pass project_id: this connection is pinned.`
+        : MCP_VERIFY_PROMPT;
+    return [...lines, "Then ask your agent:", `  ${verify}`];
 }
 /**
  * Runs `hue mcp install` and returns the process exit code: 0 done or printed, 1 failed, 2 usage
@@ -578,6 +830,25 @@ export async function runMcpCommand(argv, io = {}) {
         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;
+    if (projectValue === undefined && urlProjects.length) {
+        const trimmed = urlProjects.map((value) => value.trim());
+        if (trimmed.some((value) => !value) || new Set(trimmed).size !== 1)
+            return fail("In --url: ?project= must name one project id or slug. Remove empty or conflicting values.", 2);
+        projectValue = trimmed[0];
+    }
+    let project;
+    let serverName = SERVER_NAME;
+    if (projectValue !== undefined) {
+        const selected = parseProject(projectValue);
+        if ("error" in selected)
+            return fail(`${parsed.values.project === undefined ? "In --url: " : ""}${selected.error}\n\n${MCP_USAGE}`, 2);
+        project = selected.project;
+        serverName = selected.serverName;
+    }
+    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.
     const requested = parsed.values.toolsets ?? new URL(url).searchParams.get("toolsets");
@@ -589,12 +860,15 @@ export async function runMcpCommand(argv, io = {}) {
         toolsets = selected.toolsets;
     }
     url = toolsetsMcpUrl(url, toolsets);
-    const plan = planFor(clientId, auth, scope, url);
+    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);
+    const steps = nextSteps(clientId, auth, serverName, project);
     if (plan.kind === "manual") {
         out(plan.hint);
         stdout.write(plan.snippet);
@@ -605,7 +879,7 @@ 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;
@@ -617,10 +891,10 @@ export async function runMcpCommand(argv, io = {}) {
                 out(command.display);
                 continue;
             }
-            out(`Running: ${command.display}`);
+            out(`Running: ${shownCommand(command)}`);
             const code = await runClientCli(executable, command.args, { cwd, env, stdout, stderr });
             if (code === 0) {
-                out(`Registered the "${SERVER_NAME}" MCP server (${url}) with ${command.label}.`);
+                out(`Registered the "${serverName}" MCP server (${shownUrl}) with ${command.label}.`);
                 continue;
             }
             failed = true;
@@ -634,10 +908,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);
+        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);
@@ -648,17 +926,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 "${SERVER_NAME}" MCP server (${url}).`);
+    out(`Wrote ${display} with the "${serverName}" MCP server (${shownUrl}).`);
     for (const line of steps)
         out(line);
     return 0;