@piagent/platform 1.1.9 → 1.2.1

package/packages/piagent-core/mcp/mcp-import-kinds.js

@@ -0,0 +1,240 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+// Defined here rather than imported from the layer module, which imports this
+// one: a cycle between the two would resolve, but only by accident of ordering.
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+// The adapter accepts an `imports` key that pulls server definitions out of
+// other coding tools' config files. Those definitions land in a session without
+// ever appearing in any of the four scopes this platform manages, so anything
+// the approval gate is meant to cover has to be resolved here too.
+//
+// Each kind is described by two independent sets of locations. One is where the
+// adapter looks today; the other is where the tool actually keeps its config.
+// They disagree for three of the six kinds, and the gate has to hold under both:
+// reading only the adapter's location misses a definition the moment the adapter
+// is corrected, and reading only the real location misses what loads right now.
+// The union is the safe direction to be wrong in — a server listed here that
+// never loads costs one approval prompt, a server that loads without being
+// listed costs the gate.
+//
+// Only `vscode` resolves inside the project. That one distinction is what makes
+// it dangerous: a cloned repository carries the file it points at, so the
+// servers it defines travel with the clone exactly like `.mcp.json` does.
+
+/**
+ * @typedef {{
+ *   adapterPaths: (home: string, projectPath: string) => string[],
+ *   actualPaths: (home: string, projectPath: string) => string[],
+ *   serverKeys: string[],
+ *   repositoryRelative: boolean,
+ *   parsedAsJson: boolean
+ * }} ImportKind
+ */
+
+/** @type {Record<string, ImportKind>} */
+export const IMPORT_KINDS = {
+  cursor: {
+    adapterPaths: (home) => [path.join(home, ".cursor", "mcp.json")],
+    actualPaths: (home) => [path.join(home, ".cursor", "mcp.json")],
+    serverKeys: ["mcpServers", "mcp-servers"],
+    repositoryRelative: false,
+    parsedAsJson: true
+  },
+  "claude-code": {
+    adapterPaths: (home) => [
+      path.join(home, ".claude", "mcp.json"),
+      path.join(home, ".claude.json"),
+      path.join(home, ".claude", "claude_desktop_config.json")
+    ],
+    // Servers added at user scope sit at the top level of `~/.claude.json`;
+    // servers added at local scope are nested per project and are not read by
+    // either side, which is worth knowing but changes nothing here.
+    actualPaths: (home) => [path.join(home, ".claude.json")],
+    serverKeys: ["mcpServers"],
+    repositoryRelative: false,
+    parsedAsJson: true
+  },
+  "claude-desktop": {
+    adapterPaths: (home) => [
+      path.join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json")
+    ],
+    actualPaths: (home) => [
+      path.join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json")
+    ],
+    serverKeys: ["mcpServers"],
+    repositoryRelative: false,
+    parsedAsJson: true
+  },
+  codex: {
+    adapterPaths: (home) => [path.join(home, ".codex", "config.json")],
+    // The real file is TOML under a `mcp_servers` table, and nothing here parses
+    // TOML. Enumeration is therefore incomplete for this kind, which is what
+    // `canEnumerateImportKind` reports: a repository that declares it is refused
+    // on the declaration, because listing the servers that happen to be readable
+    // says nothing about the ones that are not.
+    actualPaths: (home) => [path.join(home, ".codex", "config.toml")],
+    serverKeys: ["mcpServers", "mcp_servers"],
+    repositoryRelative: false,
+    parsedAsJson: false
+  },
+  windsurf: {
+    adapterPaths: (home) => [path.join(home, ".windsurf", "mcp.json")],
+    actualPaths: (home) => [path.join(home, ".codeium", "windsurf", "mcp_config.json")],
+    serverKeys: ["mcpServers", "mcp-servers"],
+    repositoryRelative: false,
+    parsedAsJson: true
+  },
+  vscode: {
+    adapterPaths: (_home, projectPath) => [path.join(projectPath, ".vscode", "mcp.json")],
+    actualPaths: (_home, projectPath) => [path.join(projectPath, ".vscode", "mcp.json")],
+    // The adapter reads `mcpServers`; the documented format uses `servers`. Both
+    // are read so the gate covers a hand-written file either way.
+    serverKeys: ["mcpServers", "mcp-servers", "servers"],
+    repositoryRelative: true,
+    parsedAsJson: true
+  }
+};
+
+/** Import kinds whose file a repository carries, and which therefore need approval. */
+export const REPOSITORY_RELATIVE_KINDS = new Set(
+  Object.entries(IMPORT_KINDS)
+    .filter(([, kind]) => kind.repositoryRelative)
+    .map(([name]) => name)
+);
+
+/**
+ * Whether every server this kind can contribute is visible to this platform.
+ *
+ * False means the answer from `importedServers` is a subset of unknown size, not
+ * a list. A caller deciding what to block needs to know the difference: blocking
+ * what came back would look like coverage while saying nothing about the rest.
+ *
+ * @param {string} kindName
+ * @returns {boolean}
+ */
+export function canEnumerateImportKind(kindName) {
+  return IMPORT_KINDS[kindName]?.parsedAsJson === true;
+}
+
+/**
+ * The `imports` a config document declares, as a list of known kind names. An
+ * unknown kind is dropped rather than rejected: the adapter ignores it too, and
+ * a name this version does not recognise is not evidence of anything.
+ * @param {unknown} value
+ * @returns {string[]}
+ */
+export function declaredImports(value) {
+  if (!Array.isArray(value)) return [];
+  const kinds = [];
+  for (const entry of value) {
+    if (typeof entry !== "string") continue;
+    const kind = entry.trim();
+    if (Object.hasOwn(IMPORT_KINDS, kind) && !kinds.includes(kind)) kinds.push(kind);
+  }
+  return kinds;
+}
+
+/**
+ * Every file an import kind can be read from, adapter location and real location
+ * alike. Exported because "does this kind actually resolve to anything on this
+ * machine" is a question two callers ask, and each answering it from its own
+ * copy of the path list is how the two answers drift apart.
+ *
+ * @param {string} kindName
+ * @param {{projectPath?: string, home?: string}} [options]
+ * @returns {string[]}
+ */
+export function importKindFiles(kindName, options = {}) {
+  const kind = IMPORT_KINDS[kindName];
+  if (!kind) return [];
+  const home = options.home ?? os.homedir();
+  const projectPath = options.projectPath ?? process.cwd();
+  return [...new Set([...kind.adapterPaths(home, projectPath), ...kind.actualPaths(home, projectPath)])];
+}
+
+/**
+ * Every server an import kind can put into a session, from either location and
+ * under any of the keys that location might use. Files that are missing
+ * contribute nothing; a file that exists but cannot be parsed is reported by
+ * `unreadableImportTargets`, because "no servers" and "servers nobody could
+ * read" are the two answers an operator most needs told apart.
+ *
+ * @param {string} kindName
+ * @param {{projectPath?: string, home?: string}} [options]
+ * @returns {{name: string, file: string, entry: Record<string, unknown>}[]}
+ */
+export function importedServers(kindName, options = {}) {
+  const kind = IMPORT_KINDS[kindName];
+  if (!kind) return [];
+  const files = importKindFiles(kindName, options);
+
+  const found = [];
+  const seen = new Set();
+  for (const file of files) {
+    if (!kind.parsedAsJson && !file.endsWith(".json")) continue;
+    let document;
+    try {
+      document = JSON.parse(fs.readFileSync(file, "utf8"));
+    } catch {
+      continue;
+    }
+    if (!isRecord(document)) continue;
+    for (const key of kind.serverKeys) {
+      const servers = document[key];
+      if (!isRecord(servers)) continue;
+      for (const [name, entry] of Object.entries(servers)) {
+        // A name defined under two keys of the same file is one server; a name
+        // defined in two files is reported once, keyed by the first file seen,
+        // because approving it twice would ask the same question twice.
+        const dedupe = `${name}\u0000${file}`;
+        if (seen.has(dedupe) || !isRecord(entry)) continue;
+        seen.add(dedupe);
+        found.push({ name, file, entry });
+      }
+    }
+  }
+  return found;
+}
+
+/**
+ * Import targets that exist but cannot be read into servers. `importedServers`
+ * skips these, which is right for a listing and wrong for a diagnosis: the
+ * caller cannot otherwise tell a tool that defines no servers from a tool whose
+ * config nothing could parse, and only one of those two is a gap in the gate.
+ *
+ * @param {string} kindName
+ * @param {{projectPath?: string, home?: string}} [options]
+ * @returns {{kind: string, file: string, detail: string}[]}
+ */
+export function unreadableImportTargets(kindName, options = {}) {
+  const kind = IMPORT_KINDS[kindName];
+  if (!kind) return [];
+  const problems = [];
+  for (const file of importKindFiles(kindName, options)) {
+    if (!kind.parsedAsJson && !file.endsWith(".json")) continue;
+    let raw;
+    try {
+      raw = fs.readFileSync(file, "utf8");
+    } catch (error) {
+      // Absent is the normal case for five of six kinds and is not a problem.
+      if (error && typeof error === "object" && error.code === "ENOENT") continue;
+      problems.push({ kind: kindName, file, detail: `cannot read ${file}` });
+      continue;
+    }
+    let document;
+    try {
+      document = JSON.parse(raw);
+    } catch (error) {
+      problems.push({ kind: kindName, file, detail: `cannot parse ${file}: ${error instanceof Error ? error.message : String(error)}` });
+      continue;
+    }
+    if (!isRecord(document)) problems.push({ kind: kindName, file, detail: `${file} is not a JSON object` });
+  }
+  return problems;
+}

package/packages/piagent-core/mcp/mcp-server-catalog.js

@@ -0,0 +1,150 @@
+// The servers this platform ships a pinned definition for, and the presets that
+// group them. Pinned by version or digest because an MCP server is code that runs
+// on the operator's machine with the operator's credentials; a floating tag would
+// make every session a fresh supply-chain decision nobody is present to make.
+//
+// Nothing here is a secret. Every credential is referenced as an environment
+// variable, so the config can be read, diffed and committed without leaking one.
+
+/** @typedef {{description: string, config: Record<string, unknown>}} CatalogServer */
+
+/** @type {Record<string, CatalogServer>} */
+export const CATALOG_SERVERS = {
+  context7: {
+    description: "Official Context7 MCP server for up-to-date library/framework docs.",
+    config: {
+      command: "npx",
+      args: ["-y", "@upstash/context7-mcp@3.2.4"],
+      env: {
+        CONTEXT7_API_KEY: "${CONTEXT7_API_KEY}"
+      },
+      lifecycle: "lazy",
+      directTools: false
+    }
+  },
+  "chrome-devtools": {
+    description: "Chrome DevTools MCP for runtime browser inspection, console logs, screenshots, and performance checks.",
+    config: {
+      command: "npx",
+      args: ["-y", "chrome-devtools-mcp@1.6.0", "--no-performance-crux"],
+      env: {
+        CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS: "1",
+        CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS: "1"
+      },
+      lifecycle: "lazy",
+      directTools: false
+    }
+  },
+  playwright: {
+    description: "Playwright MCP for browser automation and UI verification workflows.",
+    config: {
+      command: "npx",
+      args: ["-y", "@playwright/mcp@0.0.78"],
+      lifecycle: "lazy",
+      directTools: false
+    }
+  },
+  github: {
+    description: "Official GitHub MCP server via Docker. Requires Docker and GITHUB_PERSONAL_ACCESS_TOKEN when used.",
+    config: {
+      command: "docker",
+      args: [
+        "run",
+        "-i",
+        "--rm",
+        "-e",
+        "GITHUB_PERSONAL_ACCESS_TOKEN",
+        "-e",
+        "GITHUB_READ_ONLY=1",
+        "-e",
+        "GITHUB_LOCKDOWN_MODE=1",
+        "ghcr.io/github/github-mcp-server@sha256:2b0c48b070f61e9d3969269ead600f62d00fb237b60ac849ef3d166ee7de9ad3"
+      ],
+      env: {
+        GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_PERSONAL_ACCESS_TOKEN}"
+      },
+      lifecycle: "lazy",
+      directTools: false
+    }
+  },
+  figma: {
+    description: "Figma remote MCP server. Requires Figma OAuth from the MCP panel when first used.",
+    config: {
+      url: "https://mcp.figma.com/mcp",
+      auth: "oauth",
+      lifecycle: "lazy",
+      directTools: false
+    }
+  },
+  "figma-desktop": {
+    description: "Figma desktop/local MCP server. Requires Figma desktop Dev Mode MCP enabled.",
+    config: {
+      url: "http://127.0.0.1:3845/mcp",
+      lifecycle: "lazy",
+      directTools: false
+    }
+  }
+};
+
+// Writing a server definition does not make it usable. What each one still needs
+// from the operator is stated here so it can be printed at the moment the
+// definition is written, rather than living only in a description string that
+// shows up under --list.
+/** @type {Record<string, string[]>} */
+export const CATALOG_PREREQUISITES = {
+  context7: ["optional: export CONTEXT7_API_KEY for a higher documentation quota"],
+  "chrome-devtools": ["a local Chrome installation"],
+  github: [
+    "Docker running",
+    "export GITHUB_PERSONAL_ACCESS_TOKEN with the scopes you intend to use"
+  ],
+  playwright: ["browsers installed on first use (npx playwright install)"],
+  figma: ["Figma OAuth, completed from the Pi MCP panel on first use"],
+  "figma-desktop": ["Figma desktop running with Dev Mode MCP enabled"]
+};
+
+// Variables a pinned server references but works without. Context7 answers
+// without a key and the key only raises the quota, so reporting it as missing
+// would put a line in front of the operator every session about something that
+// is not wrong. A server somebody adds by hand has no entry here: they typed the
+// reference, so it is treated as one they meant.
+/** @type {Record<string, string[]>} */
+export const CATALOG_OPTIONAL_ENV = {
+  context7: ["CONTEXT7_API_KEY"]
+};
+
+/** @type {Record<string, string[]>} */
+export const CATALOG_PRESETS = {
+  minimal: [],
+  docs: ["context7"],
+  browser: ["chrome-devtools", "playwright"],
+  github: ["github"],
+  design: ["figma"],
+  "design-local": ["figma-desktop"],
+  web: ["context7", "chrome-devtools", "playwright"],
+  core: ["context7", "chrome-devtools", "github"],
+  popular: ["context7", "chrome-devtools", "playwright", "github", "figma"],
+  all: ["context7", "chrome-devtools", "playwright", "github", "figma", "figma-desktop"]
+};
+
+/** @param {string} name @returns {boolean} */
+export function isCatalogPreset(name) {
+  return Object.hasOwn(CATALOG_PRESETS, name);
+}
+
+/**
+ * The servers a preset installs, with their definitions resolved. Throws on an
+ * unknown preset so a typo is refused before anything is written.
+ * @param {string} name
+ * @returns {{name: string, config: Record<string, unknown>, requires: string[]}[]}
+ */
+export function resolvePreset(name) {
+  if (!isCatalogPreset(name)) {
+    throw new Error(`unknown preset: ${name}. Available presets: ${Object.keys(CATALOG_PRESETS).join(", ")}`);
+  }
+  return CATALOG_PRESETS[name].map((serverName) => {
+    const server = CATALOG_SERVERS[serverName];
+    if (!server) throw new Error(`preset ${name} references missing server ${serverName}`);
+    return { name: serverName, config: server.config, requires: CATALOG_PREREQUISITES[serverName] ?? [] };
+  });
+}

package/packages/piagent-core/mcp/mcp-server-entry.js

@@ -0,0 +1,293 @@
+import { containsSensitiveText } from "../security/sensitive-data.js";
+
+// Building a server definition from what someone typed. The rule this file
+// exists to hold: a credential never reaches the config file.
+//
+// MCP config is read by several clients, lives in the operator's home or in a
+// repository, and in the `project` scope is meant to be committed. A token typed
+// into `--env` would land in all of those. So a value whose name says credential
+// has to be an environment reference, and the error says which form to use rather
+// than only that the input was refused.
+
+const SERVER_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+
+// A whole-value reference, `${VAR}`. A value that merely contains one — say
+// `Bearer ${TOKEN}` — is handled separately, because a header legitimately needs
+// the scheme in front of the reference.
+const ENV_REFERENCE = /^\$\{[A-Za-z_][A-Za-z0-9_]*\}$/;
+const CONTAINS_ENV_REFERENCE = /\$\{[A-Za-z_][A-Za-z0-9_]*\}/;
+
+const CREDENTIAL_NAME_TERMS = [
+  "token", "secret", "password", "passwd", "passphrase", "credential",
+  "apikey", "api_key", "accesskey", "access_key", "privatekey", "private_key",
+  "authorization", "auth", "session", "cookie", "signature", "pat"
+];
+
+export class McpEntryError extends Error {}
+
+/**
+ * Whether a name says the value beside it is a credential. Deliberately broad:
+ * a false positive costs one `${VAR}` indirection, a false negative writes a
+ * live token into a file somebody commits.
+ * @param {string} name
+ * @returns {boolean}
+ */
+export function credentialLikeName(name) {
+  const normalized = String(name).toLowerCase().replace(/[^a-z0-9]+/g, "_");
+  return CREDENTIAL_NAME_TERMS.some((term) => {
+    const bare = term.replace(/[^a-z0-9]+/g, "_");
+    return normalized === bare || normalized.startsWith(`${bare}_`) || normalized.endsWith(`_${bare}`) || normalized.includes(`_${bare}_`);
+  });
+}
+
+/**
+ * @param {string} raw `KEY=VALUE`
+ * @param {"env"|"header"} kind
+ * @returns {[string, string]}
+ */
+export function parseAssignment(raw, kind) {
+  const separator = kind === "header" ? ":" : "=";
+  const index = String(raw).indexOf(separator);
+  if (index <= 0) {
+    throw new McpEntryError(
+      kind === "header"
+        ? `--header expects "Name: value", received: ${raw}`
+        : `--env expects KEY=value, received: ${raw}`
+    );
+  }
+  const name = raw.slice(0, index).trim();
+  const value = raw.slice(index + 1).trim();
+  if (!name) throw new McpEntryError(`${kind} name cannot be empty`);
+  return [name, value];
+}
+
+/**
+ * Refuse a literal credential, and say what to type instead. `kind` only shapes
+ * the message; both channels are held to the same rule.
+ * @param {string} name
+ * @param {string} value
+ * @param {"env"|"header"} kind
+ * @returns {void}
+ */
+export function assertNoLiteralSecret(name, value, kind) {
+  const referenced = kind === "header" ? CONTAINS_ENV_REFERENCE.test(value) : ENV_REFERENCE.test(value);
+  if (referenced) return;
+
+  const suggestion = kind === "header"
+    ? `--header '${name}: Bearer \${${suggestedVariable(name)}}'`
+    : `--env '${name}=\${${suggestedVariable(name)}}'`;
+
+  if (credentialLikeName(name)) {
+    throw new McpEntryError(
+      `${name} names a credential, so its value cannot be written into MCP config. ` +
+      `Export it in your shell and reference it instead: ${suggestion}`
+    );
+  }
+  // The name gave nothing away, so the value is read on its own. This catches a
+  // token pasted under a neutral name such as `--env CONFIG=ghp_...`.
+  if (containsSensitiveText(`${name}=${value}`)) {
+    throw new McpEntryError(
+      `the value given for ${name} looks like a credential, so it cannot be written into MCP config. ` +
+      `Export it in your shell and reference it instead: ${suggestion}`
+    );
+  }
+}
+
+/** @param {string} name @returns {string} */
+function suggestedVariable(name) {
+  const upper = String(name).toUpperCase().replace(/[^A-Z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+  return upper || "TOKEN";
+}
+
+/** @param {string} name @returns {string} */
+export function assertServerName(name) {
+  if (!SERVER_NAME.test(String(name ?? ""))) {
+    throw new McpEntryError(
+      `invalid server name: ${name}. Use letters, digits, dot, dash or underscore, up to 64 characters.`
+    );
+  }
+  return name;
+}
+
+/**
+ * @typedef {object} BuildEntryInput
+ * @property {string} name
+ * @property {string} [url]
+ * @property {string[]} [command] argv, first element is the executable
+ * @property {string[]} [env] raw `KEY=value`
+ * @property {string[]} [header] raw `Name: value`
+ * @property {string} [bearerTokenEnvVar]
+ * @property {string} [oauthClientId]
+ * @property {string} [oauthScopes]
+ * @property {boolean} [directTools]
+ */
+
+/**
+ * @param {BuildEntryInput} input
+ * @returns {Record<string, unknown>}
+ */
+export function buildServerEntry(input) {
+  assertServerName(input.name);
+  const hasUrl = typeof input.url === "string" && input.url.length > 0;
+  const hasCommand = Array.isArray(input.command) && input.command.length > 0;
+  if (hasUrl === hasCommand) {
+    throw new McpEntryError("give either --url for a remote server or -- <command> for a local one, not both and not neither");
+  }
+
+  /** @type {Record<string, unknown>} */
+  const entry = { lifecycle: "lazy", directTools: input.directTools === true };
+
+  if (hasUrl) {
+    const url = parseRemoteUrl(input.url ?? "");
+    entry.url = url.href;
+    if (input.oauthClientId || input.oauthScopes) {
+      /** @type {Record<string, unknown>} */
+      const oauth = {};
+      if (input.oauthClientId) oauth.clientId = input.oauthClientId;
+      if (input.oauthScopes) oauth.scopes = input.oauthScopes;
+      entry.auth = "oauth";
+      entry.oauth = oauth;
+    }
+    if (input.bearerTokenEnvVar) {
+      // The variable name, never the token. Whoever reads the config learns which
+      // variable to export and nothing else.
+      entry.bearerTokenEnvVar = assertEnvVarName(input.bearerTokenEnvVar);
+    }
+    const headers = collectAssignments(input.header ?? [], "header");
+    if (Object.keys(headers).length > 0) entry.headers = headers;
+  } else {
+    const argv = input.command ?? [];
+    entry.command = argv[0];
+    if (argv.length > 1) entry.args = argv.slice(1);
+    const env = collectAssignments(input.env ?? [], "env");
+    if (Object.keys(env).length > 0) entry.env = env;
+    if (input.header?.length) throw new McpEntryError("--header applies to remote servers; a local server takes --env");
+    if (input.bearerTokenEnvVar) throw new McpEntryError("--bearer-token-env-var applies to remote servers only");
+  }
+
+  return entry;
+}
+
+/** @param {string[]} raw @param {"env"|"header"} kind @returns {Record<string, string>} */
+function collectAssignments(raw, kind) {
+  /** @type {Record<string, string>} */
+  const out = {};
+  for (const item of raw) {
+    const [name, value] = parseAssignment(item, kind);
+    assertNoLiteralSecret(name, value, kind);
+    out[name] = value;
+  }
+  return out;
+}
+
+/** @param {string} value @returns {string} */
+function assertEnvVarName(value) {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(value)) {
+    throw new McpEntryError(`--bearer-token-env-var expects a variable name, received: ${value}`);
+  }
+  return value;
+}
+
+/**
+ * A remote server has to be reachable over a transport this platform is willing
+ * to describe as one. `http://` is allowed only on the loopback address, where
+ * there is no network to intercept — Figma's desktop server is exactly that case.
+ * @param {string} value
+ * @returns {URL}
+ */
+export function parseRemoteUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new McpEntryError(`--url is not a valid URL: ${value}`);
+  }
+  // The same rule the rest of this file applies to `--env` and `--header`. An
+  // address is not a safer place to keep a token than a header is: it goes into
+  // the same committed file, and it additionally tends to reach request logs and
+  // shell history. The refusal is masked so the error itself does not repeat it.
+  if (url.username || url.password) {
+    throw new McpEntryError(
+      "--url must not carry credentials in the address. Use --bearer-token-env-var, " +
+      `or --header with a \${VAR} reference. Received: ${maskUrlCredentials(url.href)}`
+    );
+  }
+  for (const [name, item] of url.searchParams) {
+    if (credentialLikeName(name) && !ENV_REFERENCE.test(item)) {
+      throw new McpEntryError(
+        `--url query parameter ${name} looks like a credential. Use --bearer-token-env-var, ` +
+        `or give it a \${VAR} reference.`
+      );
+    }
+  }
+  if (url.protocol === "https:") return url;
+  if (url.protocol === "http:" && isLoopbackHost(url.hostname)) return url;
+  throw new McpEntryError(
+    `--url must be https, or http on localhost. Received: ${url.protocol}//${url.hostname}`
+  );
+}
+
+/**
+ * A URL with anything credential-shaped in it replaced. `add` refuses to write
+ * such a URL, but a config written by hand or by an older version can still hold
+ * one, and display is exactly where it would leak: `list` and `get` output is
+ * meant to be pasteable into an issue.
+ *
+ * A value that does not parse as a URL is returned untouched. Guessing at the
+ * structure of something that is not a URL would be a way to mangle a value
+ * without protecting anything.
+ *
+ * @param {unknown} value
+ * @returns {unknown}
+ */
+export function maskUrlCredentials(value) {
+  if (typeof value !== "string") return value;
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return value;
+  }
+  if (url.password) url.password = "*****";
+  if (url.username) url.username = "*****";
+  for (const [name, item] of [...url.searchParams]) {
+    if (credentialLikeName(name) && !ENV_REFERENCE.test(item)) url.searchParams.set(name, "*****");
+  }
+  return url.href;
+}
+
+/** @param {string} hostname @returns {boolean} */
+function isLoopbackHost(hostname) {
+  const host = hostname.replace(/^\[|\]$/g, "").toLowerCase();
+  return host === "localhost" || host === "127.0.0.1" || host === "::1";
+}
+
+/**
+ * A server entry with every value that could be a credential replaced. Used for
+ * display, so `list` and `get` can be pasted into an issue.
+ * @param {Record<string, unknown>} entry
+ * @returns {Record<string, unknown>}
+ */
+export function maskServerEntry(entry) {
+  /** @type {Record<string, unknown>} */
+  const out = {};
+  for (const [key, value] of Object.entries(entry)) {
+    if ((key === "env" || key === "headers") && value && typeof value === "object" && !Array.isArray(value)) {
+      out[key] = Object.fromEntries(
+        Object.entries(/** @type {Record<string, unknown>} */ (value)).map(([name, item]) => [
+          name,
+          // An environment reference is the name of a variable, not its contents,
+          // so showing it is the point. Anything else is treated as a value.
+          typeof item === "string" && ENV_REFERENCE.test(item) ? item : "*****"
+        ])
+      );
+      continue;
+    }
+    if (key === "url") {
+      out[key] = maskUrlCredentials(value);
+      continue;
+    }
+    out[key] = value;
+  }
+  return out;
+}