@piagent/platform 1.2.0 → 1.2.1

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

@@ -202,6 +202,24 @@ export function parseRemoteUrl(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(
@@ -209,6 +227,35 @@ export function parseRemoteUrl(value) {
   );
 }
 
+/**
+ * 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();
@@ -236,6 +283,10 @@ export function maskServerEntry(entry) {
       );
       continue;
     }
+    if (key === "url") {
+      out[key] = maskUrlCredentials(value);
+      continue;
+    }
     out[key] = value;
   }
   return out;

package/packages/piagent-core/mcp/mcp-session-view.js

@@ -1,6 +1,12 @@
-import { REPOSITORY_SCOPES, SCOPES, collectServers } from "./mcp-config-layers.js";
+import {
+  SCOPES,
+  collectServers,
+  repositoryImportDeclarations,
+  unreadableLayers,
+  unverifiableMcpConfig
+} from "./mcp-config-layers.js";
 import { approvalState } from "./mcp-approval-store.js";
-import { maskServerEntry } from "./mcp-server-entry.js";
+import { maskServerEntry, maskUrlCredentials } from "./mcp-server-entry.js";
 import { evaluateServerReadiness } from "./mcp-auth-readiness.js";
 import { CATALOG_PREREQUISITES } from "./mcp-server-catalog.js";
 
@@ -24,7 +30,9 @@ export class McpViewError extends Error {}
  * @returns {string}
  */
 export function describeTarget(entry, limit = 56) {
-  if (typeof entry.url === "string") return entry.url;
+  // Masked here as well as in the detail view. This is the string that goes in
+  // the `list` table, which is the output most likely to be screenshotted.
+  if (typeof entry.url === "string") return String(maskUrlCredentials(entry.url));
   const argv = [entry.command, ...(Array.isArray(entry.args) ? entry.args : [])].filter((item) => typeof item === "string");
   const text = argv.join(" ");
   return text.length > limit ? `${text.slice(0, limit - 3)}...` : text;
@@ -58,6 +66,39 @@ export function blockedRows(rows) {
   return rows.filter((row) => row.readiness.state !== "ready" && row.readiness.state !== "oauth");
 }
 
+/**
+ * Everything any surface needs to answer "what is MCP doing here right now".
+ *
+ * The three surfaces — the guard, `/piagent-mcp`, and the terminal CLI — used to
+ * assemble this themselves out of four separate calls, and each one picked a
+ * different subset. That is how `list` came to print "No MCP servers configured"
+ * and exit 0 in a session where the guard was refusing every tool call: the
+ * listing was reading rows, and the thing that made the answer wrong was not a
+ * row. Everything that decides whether MCP works is gathered here once.
+ *
+ * `blockingConfig` is the part that outranks per-server state. While any of it
+ * stands, no server is usable whatever its own readiness says, so a caller that
+ * reports readiness without reporting this is giving an answer that is locally
+ * true and globally wrong.
+ *
+ * @param {{projectPath: string, scopes?: string[]}} options
+ */
+export function sessionMcpState(options) {
+  const { projectPath, scopes } = options;
+  const rows = collectServerRows({ projectPath, scopes });
+  const blockingConfig = unverifiableMcpConfig({ projectPath });
+  return {
+    rows,
+    blocked: blockedRows(rows),
+    blockingConfig,
+    unreadable: unreadableLayers({ projectPath }),
+    imports: repositoryImportDeclarations({ projectPath }),
+    // One boolean rather than each caller re-deriving the rule. `list --json`
+    // read `servers: []` as success while this was true.
+    usable: blockingConfig.length === 0
+  };
+}
+
 /**
  * One named server, resolved to a single scope. `listHint` is the caller's own
  * way of listing servers, so the error names a command the reader can actually
@@ -81,7 +122,11 @@ export function describeServer(options) {
     );
   }
   const row = matches[0];
-  const approval = REPOSITORY_SCOPES.has(row.scope)
+  // `requiresApproval`, not the scope. A server imported into a `global` config
+  // from a repository-relative kind carries the scope of the file that declared
+  // the import and still needs a decision here, so keying off the scope showed
+  // no approval line for exactly the servers whose approval is least obvious.
+  const approval = row.requiresApproval
     ? approvalState({ projectPath, name, entry: row.entry })
     : undefined;
   return { ...row, masked: maskServerEntry(row.entry), approval };
@@ -134,6 +179,12 @@ export function formatServerDetail(detail, options = {}) {
     detail.name,
     `  scope: ${detail.scope}`,
     `  file: ${detail.file}`,
+    // Only for a server that came through `imports`. Without it the `scope` and
+    // `file` lines read as a config this tool can edit, and every write command
+    // suggested against them fails or edits the wrong file.
+    ...(detail.origin?.startsWith("import:")
+      ? [`  origin: ${detail.origin} (declared by the ${detail.scope} config; edit ${detail.file} directly)`]
+      : []),
     `  transport: ${detail.transport}`
   ];
   for (const key of DETAIL_FIELDS) {

package/packages/piagent-core/mcp/mcp-tool-naming.js

@@ -0,0 +1,90 @@
+// How the adapter names the tools it exposes, mirrored here so a tool call can
+// be traced back to the server behind it.
+//
+// The adapter builds a prefix from the server name and joins it to the tool name
+// with an underscore. With the default `toolPrefix: "server"` a server called
+// `github` exposes `github_create_issue`. There is no `mcp__` anywhere in that
+// scheme, which is why a gate written against `mcp__<server>__<tool>` never
+// fired: it was watching for a name shape nothing produces.
+//
+// `none` is the case with no answer. It strips the prefix entirely, so the tool
+// arrives under whatever name the server gave it and carries no evidence of
+// where it came from. Attribution is impossible by construction, which makes the
+// combination of that setting with `directTools` in a repository-carried config
+// something to refuse rather than something to parse.
+
+/** Prefix modes the adapter accepts. */
+export const TOOL_PREFIX_MODES = new Set(["server", "none", "short"]);
+
+/**
+ * The prefix a server's tools carry under one mode, matching the adapter's own
+ * derivation. An empty string means the mode erases the origin.
+ * @param {string} serverName
+ * @param {string} mode
+ * @returns {string}
+ */
+export function serverPrefix(serverName, mode) {
+  if (mode === "none") return "";
+  if (mode === "short") {
+    const short = serverName.replace(/-?mcp$/i, "").replace(/-/g, "_");
+    return short || "mcp";
+  }
+  return serverName.replace(/-/g, "_");
+}
+
+/**
+ * Every prefix a server's tools could arrive under. All prefixing modes are
+ * covered rather than just the configured one, because the setting lives in the
+ * same file as the servers: a repository that wants a different mode can simply
+ * declare it, so trusting the declared value to decide what to inspect would
+ * hand the choice back to the thing being gated.
+ * @param {string} serverName
+ * @returns {string[]}
+ */
+export function serverPrefixes(serverName) {
+  const prefixes = new Set();
+  for (const mode of ["server", "short"]) {
+    const prefix = serverPrefix(serverName, mode);
+    if (prefix) prefixes.add(prefix);
+  }
+  return [...prefixes];
+}
+
+/**
+ * Which of the given servers exposes this tool, or undefined when the name
+ * carries no prefix belonging to any of them.
+ *
+ * The longest match wins. Servers named `db` and `db_admin` both prefix
+ * `db_admin_query`, and answering `db` there would check the wrong server's
+ * approval — the more specific prefix is the one that actually produced it.
+ *
+ * @param {string} toolName
+ * @param {Iterable<string>} serverNames
+ * @returns {string|undefined}
+ */
+export function attributeDirectTool(toolName, serverNames) {
+  if (typeof toolName !== "string" || toolName.length === 0) return undefined;
+  let best;
+  let bestLength = 0;
+  for (const name of serverNames) {
+    for (const prefix of serverPrefixes(name)) {
+      if (prefix.length <= bestLength) continue;
+      if (!toolName.startsWith(`${prefix}_`)) continue;
+      best = name;
+      bestLength = prefix.length;
+    }
+  }
+  return best;
+}
+
+/**
+ * Whether a config's settings put tools on the model under names that cannot be
+ * traced to a server. Both halves are required: without `directTools` every call
+ * goes through the proxy, which names its server explicitly.
+ * @param {Record<string, unknown>} settings
+ * @returns {boolean}
+ */
+export function erasesToolOrigin(settings) {
+  if (!settings || typeof settings !== "object") return false;
+  return settings.directTools === true && settings.toolPrefix === "none";
+}

package/packages/piagent-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piagent/core",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "type": "module",
   "private": true,
   "license": "MIT",

package/scripts/configure-model-scope.sh

@@ -34,18 +34,34 @@ DEFAULT_MODEL="openai-codex/gpt-5.5:xhigh"
 SETTINGS_PATH="${PI_CODING_AGENT_DIR:-"${HOME}/.pi/agent"}/settings.json"
 DRY_RUN=false
 
+# A flag whose value is missing swallows the next flag instead. `--settings
+# --dry-run` used to set the settings path to the string "--dry-run", leave
+# DRY_RUN false, then write a file by that name and report success — a run that
+# both skipped the dry run it was asked for and never touched the real settings.
+require_value() {
+  local option="$1"
+  local value="${2:-}"
+  if [[ -z "$value" || "$value" == --* ]]; then
+    echo "Missing value for $option" >&2
+    exit 2
+  fi
+}
+
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --preset)
-      PRESET="${2:-}"
+      require_value "$1" "${2:-}"
+      PRESET="$2"
       shift 2
       ;;
     --default-model)
-      DEFAULT_MODEL="${2:-}"
+      require_value "$1" "${2:-}"
+      DEFAULT_MODEL="$2"
       shift 2
       ;;
     --settings)
-      SETTINGS_PATH="${2:-}"
+      require_value "$1" "${2:-}"
+      SETTINGS_PATH="$2"
       shift 2
       ;;
     --dry-run)

package/scripts/configure-subagents.sh

@@ -38,22 +38,35 @@ MODEL_SCOPE="none"
 DRY_RUN=false
 LIST=false
 
+require_value() {
+  local option="$1"
+  local value="${2:-}"
+  if [[ -z "$value" || "$value" == --* ]]; then
+    echo "Missing value for $option" >&2
+    exit 2
+  fi
+}
+
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --preset)
-      PRESET="${2:-}"
+      require_value "$1" "${2:-}"
+      PRESET="$2"
       shift 2
       ;;
     --config)
-      CONFIG_PATH="${2:-}"
+      require_value "$1" "${2:-}"
+      CONFIG_PATH="$2"
       shift 2
       ;;
     --settings)
-      SETTINGS_PATH="${2:-}"
+      require_value "$1" "${2:-}"
+      SETTINGS_PATH="$2"
       shift 2
       ;;
     --model-scope)
-      MODEL_SCOPE="${2:-}"
+      require_value "$1" "${2:-}"
+      MODEL_SCOPE="$2"
       shift 2
       ;;
     --dry-run)

package/scripts/init-project.sh

@@ -49,21 +49,28 @@ FORCE_SETTINGS=false
 SKIP_AGENTS=false
 SKIP_REVIEW=false
 
+# Checking only that a value is present lets the next flag serve as the value.
+# `--profile --force-profile` used to name a profile "--force-profile" and leave
+# the force off, so init failed on an unknown profile while the flag the operator
+# actually typed went nowhere.
+require_value() {
+  local option="$1"
+  local value="${2:-}"
+  if [[ -z "$value" || "$value" == --* ]]; then
+    echo "Missing value for $option" >&2
+    exit 2
+  fi
+}
+
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --profile)
-      if [[ $# -lt 2 ]]; then
-        echo "Missing value for --profile" >&2
-        exit 2
-      fi
+      require_value "$1" "${2:-}"
       PROFILE_INPUT="$2"
       shift 2
       ;;
     --package-source)
-      if [[ $# -lt 2 ]]; then
-        echo "Missing value for --package-source" >&2
-        exit 2
-      fi
+      require_value "$1" "${2:-}"
       PACKAGE_SOURCE="$2"
       shift 2
       ;;

package/scripts/mcp-manage.mjs

@@ -10,6 +10,7 @@ import {
   collectServers,
   configPathForScope,
   isRecord,
+  mergedServerEntry,
   readMcpConfig,
   writeMcpConfig
 } from "../packages/piagent-core/mcp/mcp-config-layers.js";
@@ -28,18 +29,18 @@ import {
 } from "../packages/piagent-core/mcp/mcp-server-entry.js";
 import {
   approvalState,
+  approvalStorePath,
   clearApproval,
   recordApproval
 } from "../packages/piagent-core/mcp/mcp-approval-store.js";
 import { evaluateServerReadiness } from "../packages/piagent-core/mcp/mcp-auth-readiness.js";
 import {
   McpViewError,
-  blockedRows,
-  collectServerRows,
   describeServer,
   formatDoctorReport,
   formatServerDetail,
   formatServerTable,
+  sessionMcpState,
   usesDocker
 } from "../packages/piagent-core/mcp/mcp-session-view.js";
 
@@ -214,6 +215,25 @@ function locateServer(name, flags) {
   return servers[0];
 }
 
+/**
+ * A server this command has no file of its own to edit: it was read out of
+ * another tool's config through `imports`. `located.file` is that other tool's
+ * config, and writing it back through `writeMcpConfig` would rewrite somebody's
+ * Cursor or VS Code file in this platform's format -- adding a `settings` block
+ * it does not use and dropping every key this shape does not carry.
+ *
+ * @param {{name: string, origin?: string, scope: string, file: string}} located
+ * @param {string} action
+ */
+function assertOwnedByThisTool(located, action) {
+  if (!located.origin?.startsWith("import:")) return;
+  const kind = located.origin.slice("import:".length);
+  throw new UsageError(
+    `${located.name} is not defined by any config this command owns. The ${located.scope} config imports ${kind}, ` +
+    `and the definition lives in ${located.file}. Edit that file to ${action} it, or drop "${kind}" from its imports list.`
+  );
+}
+
 // --- commands ---------------------------------------------------------------
 
 /** @param {ReturnType<typeof parseArgs>} args */
@@ -277,12 +297,21 @@ function commandRemove(args) {
   const name = args.positionals[0];
   if (!name) throw new UsageError("remove needs a server name");
   const located = locateServer(name, args.flags);
+  assertOwnedByThisTool(located, "remove");
   const config = readMcpConfig(located.file);
   delete config.mcpServers[name];
   writeMcpConfig(located.file, config);
-  clearApproval({ projectPath: projectPath(args.flags), name });
   process.stdout.write(`Removed MCP server ${name} from ${located.scope} scope\n`);
   process.stdout.write(`File modified: ${located.file}\n`);
+  // The definition is gone either way; the decision about it is a separate
+  // record, and leaving one behind for a name that no longer exists means a
+  // later server reusing the name would meet an approval nobody granted it.
+  if (!clearApproval({ projectPath: projectPath(args.flags), name })) {
+    process.stdout.write(
+      `Warning: could not update ${approvalStorePath() ?? "the approval store"}, ` +
+      `so the recorded decision for ${name} is still there. Run \`piagent-mcp reset ${name}\` once it is writable.\n`
+    );
+  }
   return 0;
 }
 
@@ -318,33 +347,51 @@ function commandGet(args) {
 function commandList(args) {
   const scopeFilter = value(args.flags, "--scope");
   const project = projectPath(args.flags);
-  const rows = collectServerRows({ projectPath: project, scopes: scopeFilter ? [scopeFilter] : undefined });
+  // Listing nothing is the correct answer only when nothing is reaching the
+  // session. A config the gate cannot verify reaches it with an unknown set of
+  // servers, and telling somebody to seed a baseline in that state sends them
+  // to the wrong file entirely.
+  const state = sessionMcpState({ projectPath: project, scopes: scopeFilter ? [scopeFilter] : undefined });
+  const { rows } = state;
 
   if (args.flags.get("--json") === true) {
+    // The same fields the human output carries. A caller scripting against this
+    // read `servers: []` as "nothing configured" while every tool call was being
+    // refused, and an exit code of 0 agreed with it.
     process.stdout.write(`${JSON.stringify({
       project,
+      usable: state.usable,
+      blockingConfig: state.blockingConfig,
       servers: rows.map((row) => ({
         name: row.name,
         scope: row.scope,
+        origin: row.origin,
+        requiresApproval: row.requiresApproval,
         file: row.file,
         state: row.readiness.state,
         detail: row.readiness.detail,
         entry: maskServerEntry(row.entry)
       }))
     }, null, 2)}\n`);
-    return 0;
+    return state.usable ? 0 : 1;
   }
 
+  for (const problem of state.blockingConfig) process.stdout.write(`BLOCKED every tool call: ${problem.detail}\n`);
+
   if (rows.length === 0) {
-    process.stdout.write("No MCP servers configured.\n");
-    process.stdout.write("Seed the pinned baseline with: piagent-mcp --preset core --scope global\n");
-    return 0;
+    if (state.usable) {
+      process.stdout.write("No MCP servers configured.\n");
+      process.stdout.write("Seed the pinned baseline with: piagent-mcp --preset core --scope global\n");
+    }
+  } else {
+    process.stdout.write(`${formatServerTable(rows)}\n`);
+    if (state.blocked.length > 0) {
+      process.stdout.write(`\n${state.blocked.length} server(s) not usable yet. Run \`piagent-mcp doctor\`.\n`);
+    }
   }
-
-  process.stdout.write(`${formatServerTable(rows)}\n`);
-  const blocked = blockedRows(rows);
-  if (blocked.length > 0) process.stdout.write(`\n${blocked.length} server(s) not usable yet. Run \`piagent-mcp doctor\`.\n`);
-  return 0;
+  // Out of the no-rows branch: the exit code answers "can MCP work here", and
+  // that question does not depend on how many rows happened to print.
+  return state.usable ? 0 : 1;
 }
 
 /** @param {ReturnType<typeof parseArgs>} args @param {boolean} enabled */
@@ -352,6 +399,7 @@ function commandToggle(args, enabled) {
   const name = args.positionals[0];
   if (!name) throw new UsageError(`${enabled ? "enable" : "disable"} needs a server name`);
   const located = locateServer(name, args.flags);
+  assertOwnedByThisTool(located, enabled ? "enable" : "disable");
   const config = readMcpConfig(located.file);
   const entry = { ...(isRecord(config.mcpServers[name]) ? config.mcpServers[name] : {}) };
   if (enabled) delete entry.enabled;
@@ -384,9 +432,19 @@ function commandDecide(args, decision) {
   if (decision === "approved" && before.state === "pending" && args.flags.get("--force") !== true) {
     // Approving without reading it is the failure this gate exists to prevent, so
     // the definition is put in front of the operator before the decision lands.
-    process.stdout.write(`${JSON.stringify(maskServerEntry(server.entry), null, 2)}\n`);
+    // The merged entry, not this layer's fragment: the adapter merges a
+    // same-named server key by key across layers, so a repository declaring only
+    // `{"args": [...]}` runs with a command it never showed the operator.
+    process.stdout.write(`${JSON.stringify(
+      maskServerEntry(mergedServerEntry({ projectPath: project, name, entry: server.entry })), null, 2
+    )}\n`);
+  }
+  // A decision that was not written is not a decision. Printing "Approved" while
+  // the store rejected the write would leave the operator waiting for a gate that
+  // is still blocking, with nothing on screen to explain why.
+  if (!recordApproval({ projectPath: project, name, entry: server.entry, decision })) {
+    throw new UsageError(`could not write ${approvalStorePath() ?? "the approval store"}; ${name} is still ${before.state}`);
   }
-  recordApproval({ projectPath: project, name, entry: server.entry, decision });
   const after = approvalState({ projectPath: project, name, entry: server.entry });
   process.stdout.write(`${decision === "approved" ? "Approved" : "Rejected"} MCP server ${name} (${server.scope}) for ${project}\n`);
   process.stdout.write(`Pinned to this definition: ${after.digest}\n`);
@@ -398,7 +456,9 @@ function commandDecide(args, decision) {
 function commandReset(args) {
   const project = projectPath(args.flags);
   const name = args.positionals[0];
-  clearApproval({ projectPath: project, name });
+  if (!clearApproval({ projectPath: project, name })) {
+    throw new UsageError(`could not write ${approvalStorePath() ?? "the approval store"}; nothing was forgotten`);
+  }
   process.stdout.write(name
     ? `Forgot the decision for ${name} in ${project}\n`
     : `Forgot every MCP approval decision for ${project}\n`);
@@ -408,7 +468,12 @@ function commandReset(args) {
 /** @param {ReturnType<typeof parseArgs>} args */
 function commandDoctor(args) {
   const project = projectPath(args.flags);
-  const rows = collectServerRows({ projectPath: project });
+  // Resolved before the no-servers shortcut below. A layer nobody can parse
+  // produces no rows, so reporting "no servers configured" and stopping would
+  // answer the question exactly backwards. The guard refuses every tool call
+  // under `blockingConfig`, and this is where somebody comes to find out why.
+  const state = sessionMcpState({ projectPath: project });
+  const { rows, unreadable: broken, imports, blockingConfig: unverifiable } = state;
 
   // The one check too slow for a session start: a daemon that is installed but
   // not running looks exactly like one that is running until something asks it.
@@ -422,22 +487,46 @@ function commandDoctor(args) {
     process.stdout.write(`${JSON.stringify({
       project,
       dockerRunning,
-      servers: rows.map((row) => ({ name: row.name, scope: row.scope, state: row.readiness.state, detail: row.readiness.detail, remedy: row.readiness.remedy }))
+      servers: rows.map((row) => ({ name: row.name, scope: row.scope, state: row.readiness.state, detail: row.readiness.detail, remedy: row.readiness.remedy })),
+      unreadableLayers: broken,
+      repositoryImports: imports.map((layer) => ({ scope: layer.scope, kinds: layer.kinds })),
+      unverifiableConfig: unverifiable
     }, null, 2)}\n`);
-    return blockedRows(rows).length > 0 ? 1 : 0;
+    return state.blocked.length > 0 || broken.length > 0 || unverifiable.length > 0 ? 1 : 0;
   }
 
+  for (const layer of broken) process.stdout.write(`Unreadable ${layer.scope} config: ${layer.detail}\n`);
+  for (const problem of unverifiable) process.stdout.write(`BLOCKED every tool call: ${problem.detail}\n`);
+
   if (rows.length === 0) {
+    if (unverifiable.length > 0 || broken.length > 0) {
+      process.stdout.write(`\n${unverifiable.length + broken.length} MCP config problem(s) need attention.\n`);
+      return 1;
+    }
     process.stdout.write("No MCP servers configured.\n");
     return 0;
   }
 
   const report = formatDoctorReport(rows, { dockerRunning, rerun: "piagent-mcp doctor" });
   for (const line of report.lines) process.stdout.write(`${line}\n`);
-  process.stdout.write(report.problems === 0
+
+  // A layer nothing can parse hides whatever it defines and reads as empty, so
+  // it is counted (and already printed above). An import is named but not
+  // counted: the servers it brings in are in the report above with their own
+  // state, and this line says where they came from, which reading the
+  // repository's own config would not reveal.
+  for (const layer of imports) {
+    process.stdout.write(
+      `${layer.file} imports servers from ${layer.kinds.join(", ")} config; ` +
+      "they need approval here like any server the repository defines.\n"
+    );
+  }
+
+  const problems = report.problems + broken.length + unverifiable.length;
+  process.stdout.write(problems === 0
     ? "\nPASS: every configured MCP server can be reached.\n"
-    : `\n${report.problems} MCP server(s) need attention.\n`);
-  return report.problems === 0 ? 0 : 1;
+    : `\n${problems} MCP problem(s) need attention.\n`);
+  return problems === 0 ? 0 : 1;
 }
 
 /** @param {ReturnType<typeof parseArgs>} args */

package/scripts/pi-model-catalog.sh

@@ -22,6 +22,15 @@ USAGE
 FORMAT="text"
 PROVIDER=""
 
+require_value() {
+  local option="$1"
+  local value="${2:-}"
+  if [[ -z "$value" || "$value" == --* ]]; then
+    echo "Missing value for $option" >&2
+    exit 2
+  fi
+}
+
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --json)
@@ -29,7 +38,8 @@ while [[ $# -gt 0 ]]; do
       shift
       ;;
     --provider)
-      PROVIDER="${2:-}"
+      require_value "$1" "${2:-}"
+      PROVIDER="$2"
       shift 2
       ;;
     -h|--help)