@ian-pascoe/pi-mcp 0.1.1 → 0.3.0

package/README.md

@@ -119,11 +119,12 @@ Global and project `mcp` objects merge top-level timeout and retry fields. A pro
 | `auth <server> [--no-open] [--callback URL \| --code CODE --state STATE]` | both    | Run an explicit OAuth authorization flow.                                                                                                               |
 | `logout <server>` / `logout --all --force`                                | both    | Remove one server's credentials, or explicitly reset corrupt auth storage.                                                                              |
 | `test <server> \| --all [--json]`                                         | both    | Connect temporary clients and close them without disturbing live connections; `--json` is standalone-only.                                              |
-| `status`                                                                  | `/mcp`  | Show live connection state.                                                                                                                             |
+| `help`                                                                    | `/mcp`  | Show concise runtime command help without querying an MCP Server.                                                                                       |
+| `status`                                                                  | `/mcp`  | Show live connection state, retry details, and active Resource subscriptions.                                                                           |
 | `reconnect <server>`                                                      | `/mcp`  | Reconnect one live server.                                                                                                                              |
 | `prompt <server> <prompt> [--arg NAME=VALUE]…`                            | `/mcp`  | Run an MCP Prompt.                                                                                                                                      |
 | `subscribe <server> <uri>` / `unsubscribe <server> <uri>`                 | `/mcp`  | Manage Resource subscriptions.                                                                                                                          |
-| `logs [server] [--level LEVEL]`                                           | `/mcp`  | Read retained server logs.                                                                                                                              |
+| `logs [server]`                                                           | `/mcp`  | Read retained server logs without sending an MCP logging-level request.                                                                                 |
 
 Mutations default to global scope. `-l` or `--local` selects project scope and is allowed only when Pi has saved trust for that project. The standalone CLI also accepts `--approve`/`-a` or `--no-approve`/`-na` to override project trust for one invocation. In a running Pi session, add/enable persists first and then connects in the background; disable/remove persists first and then disconnects. A failed connection never rolls back the setting.
 
@@ -131,6 +132,18 @@ For a remote server, `add` accepts repeated `--header NAME=VALUE`, `--transport
 
 OAuth is always explicit: the authorization URL is printed before a best-effort browser launch. Use `--no-open` for remote/headless use, then provide a full callback URL with `--callback`, or a verified `--code` and `--state` pair. The host permits one active authorization flow per process and validates callback state, issuer, resource, and loopback redirect values.
 
+## MCP Observer UI
+
+The MCP Transcript Presentation gives every Server Tool and fixed Resource tool a compact row with its original MCP Server and operation names, argument previews, content counts, and text-backed success, warning, failure, or cancellation state. Expanding a row shows bounded structured arguments, model-visible text, stored-content metadata, output-schema failures, and Result Spill paths. Progress replaces the current row instead of adding transcript entries. Pi still renders native result images separately.
+
+Prompt messages show their MCP Server, Prompt name, message roles, text, and image metadata. Resource Update Notices show their MCP Server and URI, and state that the Resource remains unread until the agent explicitly reads it. These renderers use the existing persisted content and details. They do not invoke a Prompt, read a Resource, or change replay and next-turn delivery.
+
+In TUI mode, the MCP Observer UI uses Pi's footer status to show connected, connecting, retrying, authentication, registration, and failed counts. It sends one MCP Attention Notice when invalid settings, authentication, client registration, or terminal failure needs a command. `/mcp status` reports invalid settings separately from an empty configuration and includes attempts, retry timing, redacted causes, and sorted active Resource subscriptions.
+
+Interactive TUI and HTML exports use the semantic tool renderers. Prompt and Resource Update custom rendering, footer health, and Attention Notices are TUI-only. Print, JSON, and RPC modes receive no Observer-only output. HTML custom messages keep their durable content-based representation.
+
+Observer copy strips terminal controls and applies exact-value redaction for values resolved from settings. It does not guess secrets from field names, and arbitrary Server Tool data remains faithful in model-visible content and stored session data.
+
 ## What the model can use
 
 Every advertised MCP **Server Tool** becomes an individual Pi tool named:
@@ -176,7 +189,7 @@ Catalog lists are cached for the session, aggregate at most 1,000 pages, reject
 
 Text and images map to Pi-native content. Embedded text Resources and Resource Links become provenance-labelled text. Structured content is visible as labelled JSON and retained in tool details. Unsupported audio and binary Resources are saved as private, mode-safe session files rather than discarded.
 
-All model-facing text uses Pi's 2,000-line / 50-KB limit. Oversized complete output is retained in a private Result Spill and the returned content includes its path. Per-server stderr and MCP logging retain only the newest 256 KB. Stdio stdout is protocol framing only; stderr and MCP logs do not write directly to TUI, JSON, or RPC output.
+All model-facing text uses Pi's 2,000-line / 50-KB limit. Oversized complete output is retained in a private Result Spill and the returned content includes its path. Per-server stderr and MCP logging retain only the newest 256 KB. `/mcp logs` keeps the newest combined text within Pi's display limit and identifies the private retained-log path when it truncates. Stdio stdout is protocol framing only; stderr and MCP logs do not write directly to TUI, JSON, or RPC output.
 
 Desired Resource subscriptions and expanded Prompt messages are persisted as versioned Pi custom entries and replay only on the active session branch. Connections and logs are ephemeral. Reload closes the old session generation and its dormant tool definitions, then creates a clean generation; shutdown awaits owned cleanup.
 

package/dist/pi-mcp-cli.js

@@ -28,8 +28,42 @@ var MCP_COMMAND_NAMES = [
   "prompt",
   "subscribe",
   "unsubscribe",
-  "logs"
+  "logs",
+  "help"
 ];
+var MCP_ADD_LOCAL_VALUE_OPTIONS = ["cwd", "environment"];
+var MCP_ADD_OAUTH_VALUE_OPTIONS = [
+  "client-id",
+  "client-secret",
+  "redirect-uri",
+  "scope"
+];
+var MCP_ADD_REMOTE_VALUE_OPTIONS = [
+  "auth",
+  ...MCP_ADD_OAUTH_VALUE_OPTIONS,
+  "header",
+  "token"
+];
+var MCP_COMMAND_OPTIONS = {
+  add: {
+    flags: ["local"],
+    values: [...MCP_ADD_LOCAL_VALUE_OPTIONS, ...MCP_ADD_REMOTE_VALUE_OPTIONS, "transport"]
+  },
+  auth: { flags: ["no-open"], values: ["callback", "code", "state"] },
+  disable: { flags: ["local"], values: [] },
+  enable: { flags: ["local"], values: [] },
+  help: { flags: [], values: [] },
+  list: { flags: ["json"], values: [] },
+  logout: { flags: ["all", "force"], values: [] },
+  logs: { flags: [], values: [] },
+  prompt: { flags: [], values: ["arg"] },
+  reconnect: { flags: [], values: [] },
+  remove: { flags: ["local", "logout"], values: [] },
+  status: { flags: [], values: [] },
+  subscribe: { flags: [], values: [] },
+  test: { flags: ["all", "json"], values: [] },
+  unsubscribe: { flags: [], values: [] }
+};
 var MCP_STANDALONE_COMMAND_NAMES = MCP_COMMAND_NAMES.slice(0, 8);
 var EXIT_CODES = {
   authentication: 4,
@@ -41,19 +75,6 @@ var EXIT_CODES = {
 };
 var GENERAL_USAGE = `Usage: pi-mcp <command> [options]
 Commands: ${MCP_STANDALONE_COMMAND_NAMES.join(", ")}`;
-var MCP_LOG_LEVELS = [
-  "debug",
-  "info",
-  "notice",
-  "warning",
-  "error",
-  "critical",
-  "alert",
-  "emergency"
-];
-function isMcpLoggingLevel(value) {
-  return MCP_LOG_LEVELS.some((candidate) => candidate === value);
-}
 var RUNTIME_HELP = `Commands: ${MCP_COMMAND_NAMES.join(", ")}`;
 var COMMAND_USAGE = {
   add: "Usage: pi-mcp add [-l|--local] <name> <url> [options]\n       pi-mcp add [-l|--local] <name> [options] -- <command> [args...]",
@@ -62,7 +83,8 @@ var COMMAND_USAGE = {
   enable: "Usage: pi-mcp enable [-l|--local] <server>",
   list: "Usage: pi-mcp list [--json]",
   logout: "Usage: pi-mcp logout <server> | --all --force",
-  logs: "Usage: /mcp logs [server] [--level LEVEL]",
+  logs: "Usage: /mcp logs [server]",
+  help: "Usage: /mcp help",
   prompt: "Usage: /mcp prompt <server> <prompt> [--arg NAME=VALUE]...",
   reconnect: "Usage: /mcp reconnect <server>",
   remove: "Usage: pi-mcp remove [-l|--local] [--logout] <server>",
@@ -90,16 +112,19 @@ function normalizeOptionName(rawName) {
       return rawName.replace(/^--/, "");
   }
 }
-function parseOptions(tokens, flagNames, valueNames, allowDelimiter = false) {
+function scanMcpCommandOptions(tokens, command, mode) {
   const flags = /* @__PURE__ */ new Set();
   const positionals = [];
   const values = /* @__PURE__ */ new Map();
+  const accepted = MCP_COMMAND_OPTIONS[command];
+  const flagNames = new Set(accepted.flags);
+  const valueNames = new Set(accepted.values);
   for (let index = 0; index < tokens.length; index += 1) {
     const token = tokens[index];
     if (token === void 0) continue;
     if (token === "--") {
-      if (!allowDelimiter) return "unexpected -- delimiter";
-      return { flags, positionals, tail: tokens.slice(index + 1), values };
+      if (command !== "add") return { message: "unexpected -- delimiter", ok: false };
+      return { ok: true, options: { flags, positionals, tail: tokens.slice(index + 1), values } };
     }
     if (!token.startsWith("-")) {
       positionals.push(token);
@@ -109,20 +134,28 @@ function parseOptions(tokens, flagNames, valueNames, allowDelimiter = false) {
     const rawName = equalsIndex < 0 ? token : token.slice(0, equalsIndex);
     const name = normalizeOptionName(rawName);
     if (flagNames.has(name)) {
-      if (equalsIndex >= 0) return `option ${rawName} does not accept a value`;
+      if (equalsIndex >= 0)
+        return { message: `option ${rawName} does not accept a value`, ok: false };
       flags.add(name);
       continue;
     }
-    if (!valueNames.has(name)) return `unknown option ${rawName}`;
+    if (!valueNames.has(name)) return { message: `unknown option ${rawName}`, ok: false };
     const value = equalsIndex < 0 ? tokens[index + 1] : token.slice(equalsIndex + 1);
     if (value === void 0 || equalsIndex < 0 && value.startsWith("--")) {
-      return `option ${rawName} requires a value`;
+      return mode === "completion" && value === void 0 ? {
+        ok: true,
+        options: { flags, pendingValue: name, positionals, tail: void 0, values }
+      } : { message: `option ${rawName} requires a value`, ok: false };
     }
     if (equalsIndex < 0) index += 1;
     const existing = values.get(name) ?? [];
     values.set(name, [...existing, value]);
   }
-  return { flags, positionals, tail: void 0, values };
+  return { ok: true, options: { flags, positionals, tail: void 0, values } };
+}
+function parseOptions(tokens, command) {
+  const result = scanMcpCommandOptions(tokens, command, "strict");
+  return result.ok ? result.options : result.message;
 }
 function oneValue(options, name) {
   return options.values.get(name)?.at(-1);
@@ -152,31 +185,50 @@ function isHttpUrl(value) {
     return false;
   }
 }
-function parseRemoteAuth(options) {
+function classifyMcpAddAuthentication(options, mode) {
   const configuredType = oneValue(options, "auth");
+  const token = oneValue(options, "token");
+  const oauth = MCP_ADD_OAUTH_VALUE_OPTIONS.some((name) => options.values.has(name));
+  const type = configuredType ?? (token !== void 0 ? "bearer" : oauth ? "oauth" : void 0);
+  if (type === void 0) return { ok: true, type };
+  if (type === "none") {
+    return token === void 0 && !oauth ? { ok: true, type } : { message: "auth type none cannot include credential options", ok: false };
+  }
+  if (type === "bearer") {
+    if (mode === "strict" && (token === void 0 || token.length === 0))
+      return { message: "bearer auth requires --token", ok: false };
+    if (oauth) return { message: "bearer auth cannot include OAuth options", ok: false };
+    return { ok: true, type };
+  }
+  if (type === "oauth") {
+    return token === void 0 ? { ok: true, type } : { message: "OAuth auth cannot include --token", ok: false };
+  }
+  return { message: "--auth must be none, bearer, or oauth", ok: false };
+}
+function classifyMcpAddTransportMode(options) {
+  const transport = oneValue(options, "transport");
+  if (transport !== void 0 && transport !== "http" && transport !== "sse" && transport !== "stdio")
+    return "invalid";
+  if (options.positionals.length > 2) return "invalid";
+  const local = options.tail !== void 0 || transport === "stdio" || MCP_ADD_LOCAL_VALUE_OPTIONS.some((name) => options.values.has(name));
+  const remote = options.positionals.length > 1 || transport === "http" || transport === "sse" || MCP_ADD_REMOTE_VALUE_OPTIONS.some((name) => options.values.has(name));
+  return local && remote ? "invalid" : local ? "local" : remote ? "remote" : "both";
+}
+function parseRemoteAuth(options) {
   const token = oneValue(options, "token");
   const clientId = oneValue(options, "client-id");
   const clientSecret = oneValue(options, "client-secret");
   const redirectUri = oneValue(options, "redirect-uri");
   const scopes = options.values.get("scope") ?? [];
-  const inferredType = token !== void 0 ? "bearer" : clientId !== void 0 || clientSecret !== void 0 || redirectUri !== void 0 || scopes.length > 0 ? "oauth" : void 0;
-  const type = configuredType ?? inferredType;
+  const compatibility = classifyMcpAddAuthentication(options, "strict");
+  if (!compatibility.ok) return compatibility.message;
+  const type = compatibility.type;
   if (type === void 0) return void 0;
-  if (type === "none") {
-    if (token !== void 0 || clientId !== void 0 || clientSecret !== void 0 || redirectUri !== void 0 || scopes.length > 0) {
-      return "auth type none cannot include credential options";
-    }
-    return { type: "none" };
-  }
+  if (type === "none") return { type: "none" };
   if (type === "bearer") {
-    if (token === void 0 || token.length === 0) return "bearer auth requires --token";
-    if (clientId !== void 0 || clientSecret !== void 0 || redirectUri !== void 0 || scopes.length > 0) {
-      return "bearer auth cannot include OAuth options";
-    }
+    if (token === void 0) return "bearer auth requires --token";
     return { token, type: "bearer" };
   }
-  if (type !== "oauth") return "--auth must be none, bearer, or oauth";
-  if (token !== void 0) return "OAuth auth cannot include --token";
   return {
     ...clientId === void 0 ? {} : { clientId },
     ...clientSecret === void 0 ? {} : { clientSecret },
@@ -186,47 +238,24 @@ function parseRemoteAuth(options) {
   };
 }
 function parseAdd(args) {
-  const options = parseOptions(
-    args,
-    /* @__PURE__ */ new Set(["local"]),
-    /* @__PURE__ */ new Set([
-      "auth",
-      "client-id",
-      "client-secret",
-      "cwd",
-      "environment",
-      "header",
-      "redirect-uri",
-      "scope",
-      "token",
-      "transport"
-    ]),
-    true
-  );
+  const options = parseOptions(args, "add");
   if (typeof options === "string") return usageFailure("add", options);
   const name = options.positionals[0];
   if (name === void 0 || name.length === 0)
     return usageFailure("add", "server name is required");
+  const transportMode = classifyMcpAddTransportMode(options);
   if (options.tail !== void 0) {
     if (options.positionals.length !== 1)
       return usageFailure("add", "a local add cannot also include a URL");
     const command = options.tail[0];
     if (command === void 0 || command.length === 0)
       return usageFailure("add", "local command is required after --");
-    for (const remoteOption of [
-      "auth",
-      "client-id",
-      "client-secret",
-      "header",
-      "redirect-uri",
-      "scope",
-      "token"
-    ]) {
+    for (const remoteOption of MCP_ADD_REMOTE_VALUE_OPTIONS) {
       if (options.values.has(remoteOption))
         return usageFailure("add", `local add cannot include --${remoteOption}`);
     }
     const transport2 = oneValue(options, "transport");
-    if (transport2 !== void 0 && transport2 !== "stdio") {
+    if (transport2 !== void 0 && transportMode !== "local") {
       return usageFailure("add", "local transport must be stdio");
     }
     const environment = parseAssignments(options.values.get("environment") ?? [], "environment");
@@ -251,13 +280,13 @@ function parseAdd(args) {
   }
   if (options.positionals.length !== 2)
     return usageFailure("add", "remote add requires a name and URL");
-  if (options.values.has("cwd") || options.values.has("environment")) {
+  if (MCP_ADD_LOCAL_VALUE_OPTIONS.some((name2) => options.values.has(name2))) {
     return usageFailure("add", "remote add cannot include local process options");
   }
   const url = options.positionals[1] ?? "";
   if (!isHttpUrl(url)) return usageFailure("add", "remote URL must be absolute HTTP or HTTPS");
   const transport = oneValue(options, "transport") ?? "http";
-  if (transport !== "http" && transport !== "sse")
+  if (transportMode !== "remote" || transport !== "http" && transport !== "sse")
     return usageFailure("add", "remote transport must be http or sse");
   const headers = parseAssignments(options.values.get("header") ?? [], "header");
   if (typeof headers === "string") return usageFailure("add", headers);
@@ -280,11 +309,7 @@ function parseAdd(args) {
   };
 }
 function parseScopedServer(kind, args) {
-  const options = parseOptions(
-    args,
-    new Set(kind === "remove" ? ["local", "logout"] : ["local"]),
-    /* @__PURE__ */ new Set()
-  );
+  const options = parseOptions(args, kind);
   if (typeof options === "string") return usageFailure(kind, options);
   if (options.positionals.length !== 1)
     return usageFailure(kind, "exactly one server name is required");
@@ -311,7 +336,7 @@ function parseMcpCommand(args, surface) {
   if (commandName === "remove" || commandName === "enable" || commandName === "disable")
     return parseScopedServer(commandName, rest);
   if (commandName === "list") {
-    const options2 = parseOptions(rest, /* @__PURE__ */ new Set(["json"]), /* @__PURE__ */ new Set());
+    const options2 = parseOptions(rest, "list");
     if (typeof options2 === "string" || options2.positionals.length > 0)
       return usageFailure(
         "list",
@@ -322,11 +347,7 @@ function parseMcpCommand(args, surface) {
     return { command: { json: options2.flags.has("json"), kind: "list" }, ok: true };
   }
   if (commandName === "auth") {
-    const options2 = parseOptions(
-      rest,
-      /* @__PURE__ */ new Set(["no-open"]),
-      /* @__PURE__ */ new Set(["callback", "code", "state"])
-    );
+    const options2 = parseOptions(rest, "auth");
     if (typeof options2 === "string") return usageFailure("auth", options2);
     if (options2.positionals.length !== 1)
       return usageFailure(
@@ -353,7 +374,7 @@ function parseMcpCommand(args, surface) {
     };
   }
   if (commandName === "logout") {
-    const options2 = parseOptions(rest, /* @__PURE__ */ new Set(["all", "force"]), /* @__PURE__ */ new Set());
+    const options2 = parseOptions(rest, "logout");
     if (typeof options2 === "string") return usageFailure("logout", options2);
     const all = options2.flags.has("all");
     const force = options2.flags.has("force");
@@ -368,7 +389,7 @@ function parseMcpCommand(args, surface) {
     };
   }
   if (commandName === "test") {
-    const options2 = parseOptions(rest, /* @__PURE__ */ new Set(["all", "json"]), /* @__PURE__ */ new Set());
+    const options2 = parseOptions(rest, "test");
     if (typeof options2 === "string") return usageFailure("test", options2);
     if (surface === "runtime" && options2.flags.has("json"))
       return usageFailure("test", "--json is standalone-only");
@@ -389,12 +410,16 @@ function parseMcpCommand(args, surface) {
     if (rest.length > 0) return usageFailure("status", "status accepts no arguments");
     return { command: { includeHelp: false, kind: "status" }, ok: true };
   }
+  if (commandName === "help") {
+    if (rest.length > 0) return usageFailure("help", "help accepts no arguments");
+    return { command: { kind: "help" }, ok: true };
+  }
   if (commandName === "reconnect") {
     if (rest.length !== 1) return usageFailure("reconnect", "exactly one server name is required");
     return { command: { kind: "reconnect", server: rest[0] ?? "" }, ok: true };
   }
   if (commandName === "prompt") {
-    const options2 = parseOptions(rest, /* @__PURE__ */ new Set(), /* @__PURE__ */ new Set(["arg"]));
+    const options2 = parseOptions(rest, "prompt");
     if (typeof options2 === "string") return usageFailure("prompt", options2);
     if (options2.positionals.length !== 2)
       return usageFailure("prompt", "server and prompt names are required");
@@ -414,20 +439,15 @@ function parseMcpCommand(args, surface) {
     if (rest.length !== 2) return usageFailure(commandName, "server and resource URI are required");
     return { command: { kind: commandName, server: rest[0] ?? "", uri: rest[1] ?? "" }, ok: true };
   }
-  const options = parseOptions(rest, /* @__PURE__ */ new Set(), /* @__PURE__ */ new Set(["level"]));
+  const options = parseOptions(rest, "logs");
   if (typeof options === "string" || options.positionals.length > 1)
     return usageFailure(
       "logs",
       typeof options === "string" ? options : "logs accepts at most one server name"
     );
-  const level = oneValue(options, "level");
-  if (level !== void 0 && !isMcpLoggingLevel(level)) {
-    return usageFailure("logs", `unknown logging level ${level}`);
-  }
   return {
     command: {
       kind: "logs",
-      ...level === void 0 ? {} : { level },
       ...options.positionals[0] === void 0 ? {} : { server: options.positionals[0] }
     },
     ok: true
@@ -550,12 +570,11 @@ async function executeMcpCommand(command, adapters, surface = "standalone") {
       case "logs": {
         const live = liveAdapter(adapters);
         if ("exitCode" in live) return live;
-        result = await live.logs({
-          ...command.level === void 0 ? {} : { level: command.level },
-          ...command.server === void 0 ? {} : { server: command.server }
-        });
+        result = await live.logs(command.server === void 0 ? {} : { server: command.server });
         break;
       }
+      case "help":
+        return successResult({ message: RUNTIME_HELP, ok: true }, false);
     }
     if (!result.ok) return adapterFailure(result.category, result.message);
     const json = (command.kind === "list" || command.kind === "test") && command.json;
@@ -9961,6 +9980,10 @@ var DEFAULT_REQUEST_TIMEOUT_MS = 6e4;
 var MCP_SHUTDOWN_TIMEOUT_MS = 5e3;
 var JsonValueSchema = typebox_exports.Any();
 var NonEmptyStringSchema = typebox_exports.String({ minLength: 1 });
+var McpServerIdSchema = typebox_exports.String({
+  minLength: 1,
+  pattern: "^[^\\u0000-\\u001F\\u007F-\\u009F]+$"
+});
 var PositiveSafeIntegerSchema = typebox_exports.Integer({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER });
 var RetryCountSchema = typebox_exports.Integer({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER });
 var BackoffFactorSchema = typebox_exports.Number({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER });
@@ -10005,7 +10028,7 @@ var McpLayerWireSchema = typebox_exports.Object(
     requestTimeoutMs: typebox_exports.Optional(PositiveSafeIntegerSchema),
     retry: typebox_exports.Optional(McpRetryWireSchema),
     servers: typebox_exports.Optional(
-      typebox_exports.Record(typebox_exports.String(), typebox_exports.Union([McpServerDefinitionWireSchema, typebox_exports.Null()]))
+      typebox_exports.Record(McpServerIdSchema, typebox_exports.Union([McpServerDefinitionWireSchema, typebox_exports.Null()]))
     )
   },
   { additionalProperties: false }
@@ -10109,6 +10132,20 @@ function parseMcpLayer(document, scope) {
       value: {}
     };
   }
+  if (Object.keys(document.mcp.servers ?? {}).some(
+    (serverId) => !value_exports.Check(McpServerIdSchema, serverId)
+  )) {
+    return {
+      errors: [
+        new McpSettingsError(
+          `${scope} mcp.servers`,
+          "Server Definition names must be non-empty and contain no terminal controls"
+        )
+      ],
+      scope,
+      value: {}
+    };
+  }
   return { errors: [], scope, value: document.mcp };
 }
 function parseRemoteUrl(value, path) {
@@ -10270,9 +10307,7 @@ function mergeServerDefinitions(globalLayer, projectLayer, environment, secrets)
   const masks = /* @__PURE__ */ new Map();
   const errors = [];
   for (const [id, wire] of Object.entries(globalLayer.value.servers ?? {})) {
-    if (id.length === 0) {
-      errors.push(new McpSettingsError("global mcp.servers", "Server Definition ID is empty"));
-    } else if (wire === null || wire.enabled === false && Object.keys(wire).length === 1) {
+    if (wire === null || wire.enabled === false && Object.keys(wire).length === 1) {
       errors.push(
         new McpSettingsError(
           `global mcp.servers.${id}`,
@@ -10287,9 +10322,7 @@ function mergeServerDefinitions(globalLayer, projectLayer, environment, secrets)
     const inherited = definitions.has(id);
     definitions.delete(id);
     masks.delete(id);
-    if (id.length === 0) {
-      errors.push(new McpSettingsError("project mcp.servers", "Server Definition ID is empty"));
-    } else if (wire === null || wire.enabled === false && Object.keys(wire).length === 1) {
+    if (wire === null || wire.enabled === false && Object.keys(wire).length === 1) {
       masks.set(id, { id, inherited, provenance: "project" });
     } else {
       definitions.set(id, { scope: "project", wire });
@@ -10687,7 +10720,7 @@ async function listStandaloneServers(state) {
       transport: definition.transport
     });
     messages.push(
-      `${definition.id} (${definition.provenance}, ${definition.enabled ? "enabled" : "disabled"})`
+      `${definition.id} (provenance=${definition.provenance}, ${definition.enabled ? "enabled" : "disabled"}, transport=${definition.transport}, auth=${definition.transport === "stdio" ? "none" : definition.auth?.type ?? "anonymous"}, stored-auth=${storedAuth ? "present" : "absent"})`
     );
   }
   for (const mask of settings2.masks.values()) {
@@ -10698,7 +10731,9 @@ async function listStandaloneServers(state) {
       name: mask.id,
       provenance: mask.provenance
     });
-    messages.push(`${mask.id} (${mask.provenance}, disabled mask)`);
+    messages.push(
+      `${mask.id} (provenance=${mask.provenance}, masked, inherited=${mask.inherited ? "yes" : "no"})`
+    );
   }
   const message = messages.length === 0 ? "No MCP Server Definitions configured" : messages.join("\n");
   return commandSuccess(message, { servers });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ian-pascoe/pi-mcp",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "private": false,
   "description": "A complete Model Context Protocol Host for Pi",
   "keywords": [
@@ -26,6 +26,7 @@
   },
   "files": [
     "src",
+    "skills",
     "dist",
     "README.md",
     "LICENSE"
@@ -35,12 +36,6 @@
     "access": "public",
     "provenance": true
   },
-  "scripts": {
-    "build:cli": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && esbuild src/pi-mcp-cli.ts --bundle --platform=node --format=esm --target=node22 --outfile=dist/pi-mcp-cli.js --external:@modelcontextprotocol/client --external:@modelcontextprotocol/client/*",
-    "prepack": "pnpm build:cli",
-    "test": "vitest run --config ../../vitest.config.ts --root .",
-    "typecheck": "tsc --noEmit -p tsconfig.json"
-  },
   "dependencies": {
     "@modelcontextprotocol/client": "^2.0.0"
   },
@@ -51,6 +46,7 @@
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
     "typebox": "*"
   },
   "engines": {
@@ -59,6 +55,14 @@
   "pi": {
     "extensions": [
       "./src/index.ts"
+    ],
+    "skills": [
+      "./skills"
     ]
+  },
+  "scripts": {
+    "build:cli": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && esbuild src/pi-mcp-cli.ts --bundle --platform=node --format=esm --target=node22 --outfile=dist/pi-mcp-cli.js --external:@modelcontextprotocol/client --external:@modelcontextprotocol/client/*",
+    "test": "vitest run --config ../../vitest.config.ts --root .",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
   }
-}
+}

package/skills/pi-mcp/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: pi-mcp
+description: Configure or diagnose Pi MCP when settings are invalid, Servers fail to connect, authentication fails, or dynamic tools are missing.
+license: MIT
+---
+
+# Pi MCP
+
+Keep edits scoped to `mcp`. Store secrets behind `${NAME}` environment references and redact resolved values. Treat `/mcp` as human-operated: when unavailable, request one exact command and wait for its output. Use `/mcp test` for connectivity instead of invoking Server Tools, Prompts, or Resources.
+
+1. Read the relevant settings, authentication, or connection section of [`../../README.md`](../../README.md).
+2. Run `/mcp list`, then `/mcp status`. Stop when either identifies a decisive settings or state failure.
+3. For a runtime failure, inspect `/mcp logs <server>`, then use `/mcp test <server>` after the cause is repaired.
+4. Use `/mcp reconnect <server>` only for a repaired live definition.
+5. Prefer the MCP Command Surface for requested mutations, then repeat `list`, `status`, and an approved `test`.
+6. Finish when provenance is correct and the Server reaches its intended connected, disabled, or authentication-required state without exposing a secret.