pi-mcp-client 0.7.0 → 0.8.1

package/README.md

@@ -1,9 +1,7 @@
 # 🔌 Pi MCP Client
 
-Connect Pi to MCP servers. The assistant discovers tools and resources on demand,
-reads resources as context, and calls tools natively through the official
-TypeScript SDK. You can also select, preview, and use server-provided prompts.
-No bridge process or invocation proxy.
+Connect Pi to MCP servers so the model can use their tools and read their
+resources. You can also browse, preview, and use server-provided prompts.
 
 ## 🚀 Installation
 
@@ -23,15 +21,15 @@ This server doesn't require credentials. Ask Pi:
 
 > Search Cloudflare's documentation for how to deploy a Worker.
 
-You configure servers and manage authentication. The assistant discovers
-capabilities, reads resources, and activates tools as needed. You don't need to
-type tool calls or select tools before asking a question.
+You configure servers and sign in when needed. The model finds and uses
+relevant tools and resources—you don't need to select tools before asking a
+question.
 
 Use these commands in Pi to manage your connections:
 
 | Command | Purpose |
 | --- | --- |
-| `/mcp` | Inspect server status and loaded-tool counts. Idle connections are normal; servers connect on demand. |
+| `/mcp` | Check connection status, available-tool counts, and tools loaded for the model when troubleshooting or checking your setup. |
 | `/mcp login <server>` | Sign in to an HTTP server. Only this command opens the login browser. |
 | `/mcp prompt <server> [name] [argument=value ...]` | Browse prompts or open one by name, then review a preview before using it. |
 | `/mcp reload` | Apply changes after editing your MCP configuration files. |
@@ -43,10 +41,12 @@ permissions. Tool activation isn't a per-call approval prompt. See
 ## ⚙️ Configuration
 
 Store server definitions in `~/.pi/agent/mcp.json` or a trusted project's
-`.mcp.json`. Project definitions replace same-named global definitions in full.
+`.mcp.json`. Project servers load only after an explicit
+[trust decision](docs/behavior.md#project-trust). Project definitions replace
+same-named global definitions in full.
 You can edit these files or use `/mcp add` and `/mcp remove`. To reuse a
 Claude/Cursor JSON or Codex TOML file, run `/mcp import --scope global <path>` and
-review the selected connections before saving. No conversion file is needed.
+review the selected connections before saving.
 
 Detailed guides:
 
@@ -57,14 +57,15 @@ Detailed guides:
 - [Commands](docs/commands.md): Server management, tool browsing, prompt selection,
   and resource watches. These are commands **you** run in Pi.
 - [Tool reference](docs/tool-reference.md): Discovery, activation, resource reads,
-  and argument completions. This is the **assistant's** interface, not a user API.
-- [Behavior](docs/behavior.md): Sessions, caching, result display, and permissions.
+  and argument completions. This is the **model's** interface, not a user API.
+- [Behavior](docs/behavior.md): When servers connect, when tools become available,
+  and what permissions they have.
 - [Troubleshooting](docs/troubleshooting.md): Error codes, recovery, and large
   results.
 
 ## 🧰 Requirements
 
-- Pi 0.85.1 or later, with additive dynamic tool loading.
+- Pi 0.85.1 or later.
 - Node.js 22 or later.
 - The server executable for stdio connections.
 - An available OS credential store for OAuth. Linux requires a working Secret

package/dist/index.js

@@ -1,4 +1,5 @@
 // src/index.ts
+import { existsSync } from "node:fs";
 import { join as join4 } from "node:path";
 import {
   BorderedLoader as BorderedLoader2,
@@ -2329,7 +2330,7 @@ async function inspectConfigScopes(agentDir, cwd, trusted) {
 async function updateServerConfig(agentDir, cwd, trusted, mutation, validate) {
   const scoped = mutation.action !== "toggle";
   if (scoped && mutation.scope === "project" && !trusted)
-    throw new ConfigMutationError("Project configuration requires a trusted project. Use global scope or trust the project first.");
+    throw new ConfigMutationError("Project configuration requires a trusted project. Use global scope, or run /trust to trust this folder first.");
   const paths = [join(agentDir, "mcp.json"), ...trusted ? [join(cwd, ".mcp.json")] : []];
   const targets = await Promise.all(paths.map(configTarget));
   if (scoped && targets.length === 2 && targets[0] === targets[1])
@@ -3973,16 +3974,16 @@ function importAction(name, scope, scopes) {
   if (scope === "project" && Object.hasOwn(scopes.global, name)) return "Override global definition";
   return `Add ${scope} definition`;
 }
-async function runImportCommand(input, ctx, agentDir, signal, assertCurrent, save) {
+async function runImportCommand(input, ctx, agentDir, projectTrusted, signal, assertCurrent, save) {
   if (!ctx.hasUI) throw new ConfigMutationError("Configuration imports require an interactive session (TUI or RPC).");
   const { scope, path } = parseImportCommand(input);
-  const trusted = ctx.isProjectTrusted();
+  const trusted = projectTrusted();
   if (scope === "project" && !trusted)
-    throw new ConfigMutationError("Project configuration requires a trusted project. Use global scope or trust the project first.");
+    throw new ConfigMutationError("Project configuration requires a trusted project. Use global scope, or run /trust to trust this folder first.");
   const guard = () => {
     signal.throwIfAborted();
     assertCurrent();
-    if (ctx.isProjectTrusted() !== trusted)
+    if (projectTrusted() !== trusted)
       throw new ConfigMutationError("Project trust changed during the preview. Run /mcp import again; nothing was saved.");
   };
   const select = async (title, choices) => {
@@ -4541,33 +4542,61 @@ async function authenticate(identity, open2, signal, store, options = {}) {
 }
 
 // src/management.ts
-import { truncateToWidth as truncateToWidth2 } from "@earendil-works/pi-tui";
+import { truncateToWidth as truncateToWidth2, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
 var serverStates = {
-  disconnected: { glyph: "\u25CB", label: "idle" },
-  connected: { glyph: "\u25CF", label: "connected" },
-  connecting: { glyph: "\u25B6\uFE0E", label: "connecting" },
-  failed: { glyph: "\u2718\uFE0E", label: "error" },
-  disabled: { glyph: "\u25CB", label: "disabled" }
+  disconnected: { glyph: "\u25CB", label: "idle", color: "muted" },
+  connected: { glyph: "\u25CF", label: "connected", color: "success" },
+  connecting: { glyph: "\u25B6\uFE0E", label: "connecting", color: "warning" },
+  failed: { glyph: "\u2718\uFE0E", label: "error", color: "error" },
+  disabled: { glyph: "\u25CB", label: "disabled", color: "dim" }
 };
-function serverMatrix(servers, loaded, width = 80) {
+function serverMatrix(servers, loaded, width = 80, theme) {
   if (width <= 0) return "";
-  const fit = (text) => plain(truncateToWidth2(text, width));
-  if (!servers.length) return fit("No MCP servers configured.");
-  const nameWidth = Math.min(40, Math.max(6, ...servers.map(({ name }) => name.length)));
-  const heading = `  ${"Server".padEnd(nameWidth)}  ${"State".padEnd(10)}  ${"Tools".padStart(5)}  ${"Loaded".padStart(6)}`;
-  const rows = servers.map((server) => {
+  const fg = (color, text) => theme ? theme.fg(color, text) : text;
+  const bold = (text) => theme ? theme.bold(text) : text;
+  const fit = (text) => {
+    const fitted = truncateToWidth2(text, width, "\u2026");
+    return theme ? fitted : plain(fitted);
+  };
+  const wrap = (text) => wrapTextWithAnsi(text, width).map(fit);
+  const rows = [];
+  if (!servers.length) return wrap(fg("muted", "No MCP servers configured.")).join("\n");
+  const toolsWidth = Math.max(5, ...servers.map((server) => String(server.catalogSize ?? "\u2014").length));
+  const loadedWidth = Math.max(6, ...servers.map((server) => String(loaded.get(server.name) ?? 0).length));
+  const fixedWidth = 18 + toolsWidth + loadedWidth;
+  const compact = width < fixedWidth + 12;
+  const nameWidth = Math.max(0, Math.min(
+    40,
+    width - fixedWidth,
+    Math.max(6, ...servers.map(({ name }) => visibleWidth(line(name))))
+  ));
+  const padName = (name) => {
+    const text = plain(truncateToWidth2(line(name), nameWidth, "\u2026"));
+    return text + " ".repeat(Math.max(0, nameWidth - visibleWidth(text)));
+  };
+  if (!compact) rows.push(fg("muted", bold(
+    `  ${"Server".padEnd(nameWidth)}  ${"State".padEnd(10)}  ${"Tools".padStart(toolsWidth)}  ${"Loaded".padStart(loadedWidth)}`
+  )));
+  for (const server of servers) {
     const state = serverStates[server.state];
-    const name = plain(truncateToWidth2(line(server.name), nameWidth)).padEnd(nameWidth);
-    return `${state.glyph} ${name}  ${state.label.padEnd(10)}  ${String(server.catalogSize ?? "\u2014").padStart(5)}  ${String(loaded.get(server.name) ?? 0).padStart(6)}`;
-  });
-  const errors = servers.filter((server) => server.state === "failed" && server.error).map((server) => `\u2718\uFE0E ${line(server.name)}: [${server.error.code}] ${line(server.error.message)}`);
-  return [
-    heading,
-    ...rows,
-    "",
-    "Connections open on demand. \u2014 = catalog not fetched.",
-    ...errors
-  ].map(fit).join("\n");
+    const count = loaded.get(server.name) ?? 0;
+    const tools = String(server.catalogSize ?? "\u2014");
+    const name = fg(server.state === "disabled" ? "dim" : "text", bold(compact ? line(server.name) : padName(server.name)));
+    const glyph = fg(state.color, state.glyph);
+    if (compact) {
+      rows.push(...wrap(`${glyph} ${name}`));
+      rows.push(...wrap(`  ${fg(state.color, state.label)} \xB7 ${fg("muted", `${tools} tools \xB7 ${count} loaded`)}`));
+    } else {
+      rows.push(`${glyph} ${name}  ${fg(state.color, state.label.padEnd(10))}  ` + fg(server.catalogSize === void 0 ? "dim" : "text", tools.padStart(toolsWidth)) + "  " + fg(count ? "accent" : "dim", String(count).padStart(loadedWidth)));
+    }
+  }
+  rows.push("", ...wrap(fg("dim", "Connections open on demand. \u2014 = catalog not fetched.")));
+  const errors = servers.filter((server) => server.state === "failed" && server.error);
+  if (errors.length) rows.push("");
+  for (const server of errors) {
+    rows.push(...wrap(fg("error", `\u2718\uFE0E ${line(server.name)}: [${line(server.error.code)}]`) + fg("muted", ` ${line(server.error.message)}`)));
+  }
+  return rows.map(fit).join("\n");
 }
 function toolPickerLabel(tool, index, columns = 80) {
   const width = Math.max(0, columns - 4);
@@ -5913,6 +5942,58 @@ function renderResult(result, options, theme, isError) {
   };
 }
 
+// src/status-panel.ts
+var STATUS_ENTRY = "mcp-status";
+function statusPanel(snapshot, theme) {
+  const loaded = new Map(snapshot.loaded);
+  return {
+    render(width) {
+      if (width <= 0) return [];
+      const padding = width > 2 ? 1 : 0;
+      const prefix = " ".repeat(padding);
+      return serverMatrix(snapshot.servers, loaded, width - padding * 2, theme).split("\n").map((row) => prefix + row);
+    },
+    // Styling and layout are recomputed on every render, including theme changes.
+    invalidate() {
+    }
+  };
+}
+
+// src/trust.ts
+import {
+  hasTrustRequiringProjectResources,
+  ProjectTrustStore,
+  SettingsManager
+} from "@earendil-works/pi-coding-agent";
+var CHOICES = /* @__PURE__ */ new Map([
+  ["Trust", { trusted: true, save: true }],
+  ["Trust (this session only)", { trusted: true, save: false }],
+  ["Do not trust", { trusted: false, save: true }],
+  ["Do not trust (this session only)", { trusted: false, save: false }]
+]);
+function projectTrustDecision(agentDir, cwd, piTrusted) {
+  if (!piTrusted) return false;
+  if (hasTrustRequiringProjectResources(cwd)) return true;
+  const saved = new ProjectTrustStore(agentDir).get(cwd);
+  if (saved !== null) return saved;
+  const policy = SettingsManager.create(cwd, agentDir, { projectTrusted: false }).getDefaultProjectTrust();
+  return policy === "ask" ? void 0 : policy === "always";
+}
+async function askProjectTrust(agentDir, cwd, select, signal) {
+  const answer = await select(
+    `Trust project folder?
+${cwd}
+
+Its .mcp.json defines MCP servers, which can run local commands with your permissions. Saved decisions use Pi's project trust and also apply to Pi project resources.`,
+    [...CHOICES.keys()],
+    { signal }
+  );
+  const choice = answer === void 0 ? void 0 : CHOICES.get(answer);
+  if (!choice || signal.aborted) return void 0;
+  if (choice.save) new ProjectTrustStore(agentDir).set(cwd, choice.trusted);
+  return choice.trusted;
+}
+
 // src/index.ts
 var CommandUsageError = class extends Error {
 };
@@ -5941,6 +6022,12 @@ function mcpClient(pi, options = {}) {
   let loginController;
   let promptController;
   let importController;
+  let trustController;
+  let sessionTrust;
+  pi.registerEntryRenderer(
+    STATUS_ENTRY,
+    (entry, _options, theme) => statusPanel(entry.data ?? { servers: [], loaded: [] }, theme)
+  );
   pi.registerMessageRenderer("mcp-prompt", (message, { expanded, outputPad }, theme) => {
     const details = object(message.details) ? message.details : {};
     const count = Number(details.count ?? 0);
@@ -6004,6 +6091,35 @@ Text output is limited to 2000 lines or 50 KiB; larger results are saved to a pr
       }
     });
   }
+  const trustDecision = (ctx) => projectTrustDecision(agentDir, ctx.cwd, ctx.isProjectTrusted()) ?? (sessionTrust?.cwd === ctx.cwd ? sessionTrust.trusted : void 0);
+  const projectTrusted = (ctx) => trustDecision(ctx) ?? false;
+  async function resolveProjectTrust(ctx) {
+    let trusted = trustDecision(ctx);
+    if (!existsSync(join4(ctx.cwd, ".mcp.json"))) return trusted ?? false;
+    let answered = false;
+    if (trusted === void 0 && ctx.hasUI) {
+      const controller = new AbortController();
+      trustController = controller;
+      try {
+        trusted = await askProjectTrust(
+          agentDir,
+          ctx.cwd,
+          ctx.ui.select.bind(ctx.ui),
+          AbortSignal.any([controller.signal, ...ctx.signal ? [ctx.signal] : []])
+        );
+      } finally {
+        if (trustController === controller) trustController = void 0;
+      }
+      if (controller.signal.aborted) return false;
+      if (trusted !== void 0) {
+        sessionTrust = { cwd: ctx.cwd, trusted };
+        answered = true;
+      }
+    }
+    if (!trusted && !answered && ctx.hasUI && ctx.isProjectTrusted())
+      ctx.ui.notify("Project .mcp.json ignored: this folder isn't trusted for MCP servers. Run /trust to save a decision, then /mcp reload.", "warning");
+    return trusted ?? false;
+  }
   const restore = (ctx) => {
     const tools = restoredTools(ctx.sessionManager.getBranch()).filter((tool) => {
       try {
@@ -6038,14 +6154,15 @@ Text output is limited to 2000 lines or 50 KiB; larger results are saved to a pr
       }
     };
     ctx.signal?.throwIfAborted();
+    const trusted = mutation ? projectTrusted(ctx) : await resolveProjectTrust(ctx);
     const update = mutation && await updateServerConfig(
       agentDir,
       ctx.cwd,
-      ctx.isProjectTrusted(),
+      trusted,
       mutation,
       validate
     );
-    const nextConfig = update ? update.config : await loadConfig(agentDir, ctx.cwd, ctx.isProjectTrusted());
+    const nextConfig = update ? update.config : await loadConfig(agentDir, ctx.cwd, trusted);
     validate(nextConfig);
     const next = new McpRuntime(
       nextConfig,
@@ -6073,15 +6190,18 @@ Text output is limited to 2000 lines or 50 KiB; larger results are saved to a pr
     return update?.scope;
   }
   pi.on("session_start", async (_event, ctx) => {
-    sessionGeneration++;
+    const generation = ++sessionGeneration;
     promptController?.abort();
     importController?.abort();
+    trustController?.abort();
     await runtime?.close();
     runtime = void 0;
     config = {};
     configError = void 0;
     try {
-      config = await loadConfig(agentDir, ctx.cwd, ctx.isProjectTrusted());
+      const trusted = await resolveProjectTrust(ctx);
+      if (generation !== sessionGeneration) return;
+      config = await loadConfig(agentDir, ctx.cwd, trusted);
       runtime = new McpRuntime(config, ctx.cwd, join4(agentDir, "cache", "pi-mcp-client"), createSdkConnector(storeFactory));
       resourceNotifications(runtime, ctx);
     } catch (error) {
@@ -6101,6 +6221,7 @@ Text output is limited to 2000 lines or 50 KiB; larger results are saved to a pr
     loginController?.abort();
     promptController?.abort();
     importController?.abort();
+    trustController?.abort();
     const old = runtime;
     runtime = void 0;
     await old?.close();
@@ -6331,7 +6452,7 @@ Variables: ${(candidate.variables ?? []).join(", ") || "none"}. Supply known val
     }
   });
   pi.registerCommand("mcp", {
-    description: "Manage MCP servers: add|remove|import --scope global|project, list, status, reload, enable|disable|get|tools|login|logout|reconnect|refresh <server>; prompt <server> [name] [argument=value ...]; subscriptions; subscribe|unsubscribe <server> <uri>",
+    description: "Show MCP server status; manage servers: add|remove|import --scope global|project, reload, enable|disable|get|tools|login|logout|reconnect|refresh <server>; prompt <server> [name] [argument=value ...]; subscriptions; subscribe|unsubscribe <server> <uri>",
     getArgumentCompletions(prefix) {
       const serverActions = ["enable", "disable", "get", "tools", "prompt", "login", "logout", "reconnect", "refresh", "subscribe", "unsubscribe"];
       const input = prefix.trimStart();
@@ -6339,7 +6460,7 @@ Variables: ${(candidate.variables ?? []).join(", ") || "none"}. Supply known val
       if (configuration !== void 0) return configuration;
       const match = /^(\S+)\s+(.*)$/s.exec(input);
       if (!match) {
-        return ["list", "status", "reload", "subscriptions", "add", "remove", "import", ...serverActions].filter((action2) => action2.startsWith(input)).map((action2) => ({ value: action2, label: action2 }));
+        return ["reload", "subscriptions", "add", "remove", "import", ...serverActions].filter((action2) => action2.startsWith(input)).map((action2) => ({ value: action2, label: action2 }));
       }
       const [, action, partialServer] = match;
       if (action === "login") {
@@ -6355,7 +6476,7 @@ Variables: ${(candidate.variables ?? []).join(", ") || "none"}. Supply known val
     async handler(args, ctx) {
       const generation = sessionGeneration;
       await ctx.waitForIdle();
-      let [action = "status", server, ...extra] = args.trim().split(/\s+/).filter(Boolean);
+      let [action = "", server, ...extra] = args.trim().split(/\s+/).filter(Boolean);
       try {
         if (generation !== sessionGeneration)
           throw new CommandUsageError("The Pi session changed while waiting for idle.");
@@ -6370,6 +6491,7 @@ Variables: ${(candidate.variables ?? []).join(", ") || "none"}. Supply known val
               args,
               ctx,
               agentDir,
+              () => projectTrusted(ctx),
               AbortSignal.any([controller.signal, ...ctx.signal ? [ctx.signal] : []]),
               () => {
                 if (sessionGeneration !== generation || runtime !== activeRuntime)
@@ -6429,7 +6551,7 @@ ${snapshot.body}`,
           server = mutation.server;
           await reloadConfiguration(ctx, mutation);
           const remaining = Object.hasOwn(config, server);
-          const message = mutation.action === "add" ? `\u2714\uFE0E ${server}: saved in ${mutation.scope} configuration. Connections, authentication, and tool discovery remain on demand.` + (mutation.scope === "global" && ctx.isProjectTrusted() ? " Trusted project definitions take precedence over global definitions." : "") : `\u2714\uFE0E ${server}: removed from ${mutation.scope} configuration. Credentials were retained.` + (remaining ? " A definition from the other scope remains effective; connections reopen on demand." : " Its connection is closed and its tools are no longer active.");
+          const message = mutation.action === "add" ? `\u2714\uFE0E ${server}: saved in ${mutation.scope} configuration. Connections, authentication, and tool discovery remain on demand.` + (mutation.scope === "global" && projectTrusted(ctx) ? " Trusted project definitions take precedence over global definitions." : "") : `\u2714\uFE0E ${server}: removed from ${mutation.scope} configuration. Credentials were retained.` + (remaining ? " A definition from the other scope remains effective; connections reopen on demand." : " Its connection is closed and its tools are no longer active.");
           if (ctx.hasUI) ctx.ui.notify(message, "info");
           return;
         }
@@ -6495,19 +6617,23 @@ ${snapshot.body}`,
           );
           return;
         }
-        if ((action === "status" || action === "list") && !server) {
+        if (!action) {
           const statuses = current().serverStatuses();
           const loaded = /* @__PURE__ */ new Map();
           for (const name of pi.getActiveTools()) {
             const tool = exposure.definitions.get(name);
             if (tool) loaded.set(tool.server, (loaded.get(tool.server) ?? 0) + 1);
           }
-          if (ctx.hasUI) ctx.ui.notify(serverMatrix(statuses, loaded), "info");
+          if (ctx.mode === "tui") {
+            pi.appendEntry(STATUS_ENTRY, { servers: statuses, loaded: [...loaded] });
+          } else if (ctx.hasUI) {
+            ctx.ui.notify(serverMatrix(statuses, loaded), "info");
+          }
           return;
         }
         if (!server || extra.length > 0 && !(action === "login" && extra.length === 1 && extra[0] === "--no-browser") || !Object.hasOwn(config, server) || config[server].disabled)
           throw new CommandUsageError(
-            "Usage: /mcp list|status|reload, /mcp enable|disable|get|tools|login|logout|reconnect|refresh <server>, or /mcp add|remove|import --scope global|project ... . Disabled servers accept enable, disable, get, logout, and scoped removal."
+            "Usage: /mcp, /mcp reload, /mcp enable|disable|get|tools|login|logout|reconnect|refresh <server>, or /mcp add|remove|import --scope global|project ... . Disabled servers accept enable, disable, get, logout, and scoped removal."
           );
         if (action === "tools") {
           if (!ctx.hasUI)
@@ -6618,7 +6744,7 @@ Opening browser. Esc to cancel.`
           await current().promptCatalog(server, ctx.signal, true);
         } else
           throw new CommandUsageError(
-            "Unknown MCP command. Use /mcp list|status|reload or /mcp enable|disable|get|tools|login|logout|reconnect|refresh <server>, or /mcp add|remove|import --scope global|project ... ."
+            "Unknown MCP command. Use /mcp, /mcp reload, or /mcp enable|disable|get|tools|login|logout|reconnect|refresh <server>, or /mcp add|remove|import --scope global|project ... ."
           );
         if (ctx.hasUI)
           ctx.ui.notify(

package/docs/authentication.md

@@ -2,7 +2,7 @@
 
 [Back to the README](../README.md)
 
-You manage authentication through `/mcp login` and `/mcp logout`. The assistant
+You manage authentication through `/mcp login` and `/mcp logout`. The model
 can't initiate an OAuth login: only your explicit login command opens the browser.
 For externally managed bearer tokens, use
 [headers and secret commands](configuration.md#secret-commands) instead.

package/docs/behavior.md

@@ -3,7 +3,7 @@
 [Back to the README](../README.md)
 
 This page explains how the extension manages state and displays results. For the
-assistant's tool-call interface, see the [tool reference](tool-reference.md).
+model's tool-call interface, see the [tool reference](tool-reference.md).
 
 ## Sessions
 
@@ -15,7 +15,7 @@ assistant's tool-call interface, see the [tool reference](tool-reference.md).
   Other providers receive the expanded tool list normally.
 - Discovery respects server filters; activation also respects Pi's tool exclusions.
   An explicit tool allowlist must include both `mcp_tools` and the native tools
-  the assistant needs to load.
+  the model needs to load.
 
 ## Resource snapshots
 
@@ -88,7 +88,7 @@ reconnection or configuration reload.
 When a connected server reports a tool-list change, the extension invalidates its
 memory and disk catalogs. The next discovery or activation fetches the current
 list, including new or removed tools. Notifications don't replace active tool
-definitions: the assistant must activate changed schemas again before use. Calls
+definitions: the model must activate changed schemas again before use. Calls
 validate the live catalog before execution and refuse removed or changed tools.
 Disconnected, cache-only searches can't receive notifications and still use the
 24-hour disk-cache expiry.
@@ -115,7 +115,7 @@ indentation and syntax highlighting. Explicit JSON resource MIME types (includin
 `application/*+json`) and structured content identify JSON without guessing.
 Other explicit MIME types stay plain text; unlabeled text is checked for JSON.
 
-Formatting changes only the display, not the response sent to the assistant.
+Formatting changes only the display, not the response sent to the model.
 Invalid or truncated JSON stays plain text. Results that would exceed formatting
 limits also stay plain text. Resource-link MIME types describe the linked content,
 not the displayed link label. Supported images use the existing result display;
@@ -125,7 +125,8 @@ see [large results](troubleshooting.md#large-results) for size limits.
 
 Only load configuration you trust. Server executables and secret commands run
 with your user permissions; trusted project configuration can replace global
-connections and settings.
+connections and settings. See [project trust](#project-trust) for when a
+project's `.mcp.json` loads.
 
 Configuration imports require an explicit file, scope, selection, and final
 confirmation. Import previews hide connection values; review the source file
@@ -148,3 +149,28 @@ Pi's tool restrictions to prevent discovery and resource operations. Already act
 native tools have their own tool restrictions. Per-resource permission policies
 aren't implemented. Prompt selection uses explicit user commands, not the
 model-facing tool allowlist; disable the server to prevent prompt access.
+
+## Project trust
+
+A project's `.mcp.json` can start local commands, so it loads only after an
+explicit trust decision for the folder. Pi asks for trust only in folders with Pi
+project resources, such as `.pi/settings.json` or `.agents/skills`, and trusts
+other folders implicitly. The extension doesn't rely on that implicit trust:
+
+- **Folders with Pi project resources:** Pi's decision applies, including
+  `--approve` and session-only trust.
+- **Other folders:** a saved decision for the folder or a parent folder applies.
+  Without one, Pi's `defaultProjectTrust` setting applies: `always` loads project
+  servers and `never` ignores them. With the default `ask`, interactive sessions
+  ask when a `.mcp.json` exists, and headless sessions ignore the file.
+- **Untrusted folders:** `--no-approve` or a refusal in Pi always ignores project
+  servers.
+
+Saved answers go to Pi's project trust store, so they also apply to Pi project
+resources. Use Pi's `/trust` command to save or change a decision, then run
+`/mcp reload`; MCP servers don't require a restart. In folders without Pi project
+resources, `--approve` doesn't trust `.mcp.json`; save a decision instead.
+
+Only session start and `/mcp reload` ask. Other configuration commands, such as
+`/mcp add` and `/mcp import`, use the current decision. Untrusted project files
+are neither read nor changed.

package/docs/commands.md

@@ -2,15 +2,15 @@
 
 [Back to the README](../README.md)
 
-These are commands **you run in Pi**, not tools the assistant calls. Use them to
-manage servers, inspect capabilities, use prompts, and watch resource changes. The assistant's
-separate interface is documented in the [tool reference](tool-reference.md).
+These are commands **you run in Pi**, not tools the model calls. Use them to
+manage servers, inspect capabilities, use prompts, and watch resource changes.
+The model's separate interface is documented in the [tool reference](tool-reference.md).
 
 ## Command reference
 
 | Command | Purpose |
 | --- | --- |
-| `/mcp`, `/mcp list`, `/mcp status` | Show a server status matrix with catalog and loaded-tool counts. |
+| `/mcp` | Check server status, catalog tool counts, and tools loaded for the model. |
 | `/mcp add --scope <scope> [options] <server> <url>` | Save an HTTP server without connecting. For stdio, use `<server> -- <command> [args...]`. |
 | `/mcp remove --scope <scope> <server>` | Remove a definition from the selected scope, retaining credentials. |
 | `/mcp import --scope <scope> <path>` | Preview and select servers from Claude/Cursor JSON or Codex TOML, then confirm a scoped import. |
@@ -33,11 +33,16 @@ See [Authentication](authentication.md) for login and logout procedures, and
 
 ## Inspect servers and tools
 
-The `/mcp` status matrix distinguishes idle (`○`), connected (`●`), connecting
-(`▶︎`), disabled (`○`), and failed (`✘︎`) servers. Idle is normal: connections open
-on demand. A dash (`—`) means the catalog hasn't been fetched, not that the server
-has no tools. The **Loaded** column counts tools currently active for the
-assistant.
+Use `/mcp` to check your setup or investigate a connection problem. It reports
+whether each server is idle, connected, connecting, disabled, or in an error
+state, along with catalog tool counts and tools loaded for the model.
+
+Idle is normal: connections open on demand. A dash (`—`) means the catalog hasn't
+been fetched, not that the server has no tools. **Loaded** counts tools currently
+active for the model.
+
+Checking status doesn't open connections or send information to the model.
+The result stays in your transcript; run the command again for updated status.
 
 Use `/mcp get <server>` to check the effective transport, protocol, filters,
 and connection status without connecting or running secret commands. Connection
@@ -48,15 +53,14 @@ unavailable credential store is reported separately from missing tokens. Header
 and stdio credentials are identified as externally managed; inspection never
 executes them.
 
-Use `/mcp tools <server>` to fetch the current catalog and browse a scrollable
-list. Rows show tool names and descriptions, trimmed to the terminal width with
-an ellipsis. Select a tool to see a multiline signature and parameter details,
-with each parameter in a separate paragraph. Browsing respects your include and
-exclude filters and doesn't activate tools or add their schemas to the assistant's
-context. This command requires an interactive UI.
+Use `/mcp tools <server>` to find out what a server can do. It fetches the current
+catalog so you can inspect tool descriptions, parameters, and required inputs.
+Browsing respects your include and exclude filters and doesn't activate tools
+or add their schemas to the model's context. This command requires an
+interactive UI.
 
 Refreshing a catalog doesn't replace active tool definitions. After a schema
-change, ask the assistant to activate the exact tool again. See
+change, ask the model to activate the exact tool again. See
 [tool changes and caching](behavior.md#discovery-and-caching). Failed tool calls
 aren't retried automatically; verify whether an interrupted operation completed
 before trying again.
@@ -108,7 +112,7 @@ Both commands wait for active agent work to finish, then
 [apply the configuration](configuration.md#apply-changes).
 
 Disabling removes the server from discovery and deactivates its tools. Enabling
-doesn't connect, authenticate, or load tools; ask the assistant to discover the
+doesn't connect, authenticate, or load tools; ask the model to discover the
 capabilities you need.
 
 ## Add and remove servers
@@ -116,8 +120,9 @@ capabilities you need.
 Both commands require an explicit `--scope global` or `--scope project`:
 
 - **Global:** `~/.pi/agent/mcp.json`.
-- **Project:** `.mcp.json` in the current trusted project. Untrusted project files
-  are neither read nor changed.
+- **Project:** `.mcp.json` in the current
+  [trusted project](behavior.md#project-trust). Untrusted project files are
+  neither read nor changed.
 
 Add an HTTP server by URL, or a stdio server after `--`:
 
@@ -190,7 +195,8 @@ automatically; no conversion file is needed:
 ```
 
 The command requires an interactive TUI or RPC session and an explicit
-`--scope global` or `--scope project`. Project scope requires a trusted project.
+`--scope global` or `--scope project`. Project scope requires a
+[trusted project](behavior.md#project-trust).
 Relative source paths resolve against Pi's current directory; `~/` is supported.
 The path isn't evaluated by a shell, and no application settings are scanned.
 
@@ -282,7 +288,7 @@ streams. It never opens the URI as a file or generic URL.
 An update marks the watch as changed (`↻`) and shows a UI notification. Repeated
 updates coalesce into that marker until you unsubscribe. No content is fetched,
 no model turn starts, and existing resource results remain unchanged. Ask the
-assistant to read the resource for a new snapshot; unsubscribe and subscribe again
+model to read the resource for a new snapshot; unsubscribe and subscribe again
 to reset the change marker.
 
 Watches are memory-only, limited to 50 per server connection, and require an

package/docs/configuration.md

@@ -2,10 +2,11 @@
 
 [Back to the README](../README.md)
 
-You configure which servers the assistant can access. Add connections to
-`~/.pi/agent/mcp.json`, or `.mcp.json` in a trusted project. For command-based
-setup, see [Add and remove servers](commands.md#add-and-remove-servers). To reuse
-an existing Claude/Cursor JSON or Codex TOML file, see
+You configure which servers the model can access. Add connections to
+`~/.pi/agent/mcp.json`, or `.mcp.json` in a
+[trusted project](behavior.md#project-trust). For command-based setup, see
+[Add and remove servers](commands.md#add-and-remove-servers). To reuse an
+existing Claude/Cursor JSON or Codex TOML file, see
 [Import server definitions](commands.md#import-server-definitions).
 
 ## Files and transports
@@ -16,8 +17,10 @@ MCP configuration standard. Live configuration must use JSON, not VS Code's
 this format. `PI_CODING_AGENT_DIR` overrides the global Pi directory.
 Project definitions replace same-named global definitions in full; fields and
 filters aren't merged. Untrusted project definitions aren't loaded or edited.
-An explicitly named import source is read as data for review; saving into project
-scope still requires project trust.
+Project servers need an explicit trust decision even in folders that Pi trusts
+implicitly; see [project trust](behavior.md#project-trust). An explicitly named
+import source is read as data for review; saving into project scope still
+requires project trust.
 
 ```json
 {
@@ -44,13 +47,24 @@ scope still requires project trust.
 | `type` | Optional `stdio` or `http`. If omitted, inferred from `command` or `url`. A conflicting type is rejected. |
 | `command`, `args` | Executable and arguments for a stdio server. No shell is used. |
 | `cwd` | Working directory for stdio; defaults to Pi's current directory. Relative paths resolve there. |
-| `env` | Additional environment variables for stdio. |
+| `env` | Environment variables for stdio, in addition to a minimal inherited set. |
 | `url` | Streamable HTTP endpoint; mutually exclusive with `command`. |
 | `headers` | HTTP request headers, including optional bearer authentication. |
 
 Strings in `command`, `args`, `cwd`, `env`, `url`, and `headers` support `${VAR}`
 interpolation. Missing variables prevent that server from connecting.
 
+Stdio servers don't inherit Pi's environment. They receive only the MCP SDK's
+default set (`HOME`, `LOGNAME`, `PATH`, `SHELL`, `TERM`, and `USER` on Unix, and
+similar system variables on Windows) plus `env`. Pass other variables a server
+needs explicitly, for example a custom browser location:
+
+```json
+"env": {
+  "PLAYWRIGHT_BROWSERS_PATH": "${PLAYWRIGHT_BROWSERS_PATH}"
+}
+```
+
 Only stdio and Streamable HTTP are supported. The extension rejects `type: "sse"`
 and unsupported connection fields rather than silently changing their meaning.
 
@@ -119,7 +133,7 @@ server definition:
 
 | Field | Purpose |
 | --- | --- |
-| `description` | Short capability description for the assistant's server directory. |
+| `description` | Short capability description for the model's server directory. |
 | `oauthClientId` | Optional pre-registered public client ID. Supports `${ENV_VAR}` interpolation, not secret commands. |
 | `oauthScopes` | Optional array of 1–100 unique OAuth scope tokens to request at login. Omitted scopes use SDK/server defaults. Values are literal, without interpolation. |
 | `oauthCallbackPort` | Optional loopback callback port, from 1 to 65535. Defaults to `19847`. |

package/docs/tool-reference.md

@@ -1,22 +1,22 @@
-# Assistant tool reference
+# Model tool reference
 
 [Back to the README](../README.md)
 
-This page documents **the assistant's interface**. The examples illustrate tool
-calls the assistant makes; they aren't slash commands or JavaScript for you to
+This page documents **the model's interface**. The examples illustrate tool
+calls the model makes; they aren't slash commands or JavaScript for you to
 run. Describe your task in natural language. For operations you control directly,
 see [Commands](commands.md).
 
 The `mcp_tools` tool supports four mutually exclusive operations:
 
-| Operation | What the assistant can do | What it doesn't do |
+| Operation | What the model can do | What it doesn't do |
 | --- | --- | --- |
 | `query` | Discover tool, resource, and prompt metadata. | Read content or activate tools. |
 | `activate` | Load full schemas for exact tool identifiers. | Invoke tools. |
 | `read` | Fetch one resource as conversation context. | Activate tools or follow links automatically. |
 | `complete` | Request server suggestions for a template variable. | Read resources, activate tools, or select a value. |
 
-The assistant passes exactly one of `query`, `activate`, `read`, or `complete`.
+The model passes exactly one of `query`, `activate`, `read`, or `complete`.
 The optional `kind`, `server`, and `limit` fields are query-only; reads and
 completions carry their server inside their respective objects.
 
@@ -40,7 +40,7 @@ content type when supplied. Concrete resources and tools include exact next-call
 arguments; templates include a read-call shape and variable names.
 
 Prompt candidates show the owning server, name, description, argument metadata,
-and a user-only command such as `/mcp prompt docs explain`. The assistant can
+and a user-only command such as `/mcp prompt docs explain`. The model can
 recommend this command but can't retrieve or run prompts through `mcp_tools`.
 Only you can [select, preview, and use a prompt](commands.md#use-server-prompts).
 
@@ -62,7 +62,7 @@ mcp_tools({ activate: ["linear.list_teams", "linear.get_team"] })
 
 Activation accepts 1–50 exact `server.tool` or `mcp__server__tool` identifiers,
 ignores duplicates, and works without a prior search. Typos never activate fuzzy
-matches: failures list nearby catalog names when available so the assistant can
+matches: failures list nearby catalog names when available so the model can
 retry with an exact identifier. Each identifier reports `loaded`, `already loaded`,
 or `not loaded` with a reason. Partial success keeps the tools that loaded.
 
@@ -74,7 +74,7 @@ tool. There is no invocation proxy. Previously loaded tools remain available;
 ## Read resources as context
 
 For a request such as “Use the authentication guide to explain this API,” the
-assistant can discover and read relevant context:
+model can discover and read relevant context:
 
 ```js
 mcp_tools({ query: "authentication guide", kind: "resources" })
@@ -87,7 +87,7 @@ request, even for `file:` or `https:` URIs. There is no fallback when the server
 can't read the URI. The server still controls which data it returns.
 
 Tool-returned resource links include an exact `mcp_tools({read: ...})` call. The
-assistant can read such links directly, without prior discovery or activation;
+model can read such links directly, without prior discovery or activation;
 linked resources don't have to appear in the catalog.
 
 Reading attaches content as the tool result itself, not as a second message. The
@@ -100,7 +100,7 @@ limits and private spill files.
 
 Discovery also lists URI templates, such as `schema://tables/{table}`, without
 enumerating every possible table. Templates have a `[template]` label, variable
-names, and a read-call shape. The assistant supplies known argument values:
+names, and a read-call shape. The model supplies known argument values:
 
 ```js
 mcp_tools({ query: "table schema", server: "warehouse", kind: "resources" })
@@ -117,7 +117,7 @@ The `read` object accepts either `uri` or `template` plus `arguments`, never bot
 The selected server must advertise the exact template. The official SDK expands
 strings or string arrays into a concrete URI, then reads it through that same
 server. Template variables aren't an input schema: no required fields or allowed
-values are inferred. The assistant should use values from your request or prior
+values are inferred. The model should use values from your request or prior
 results and ask you when a needed value is unknown rather than inventing an
 identifier.
 
@@ -128,7 +128,7 @@ content; see [result display](behavior.md#result-display).
 
 ## Complete resource arguments
 
-The assistant can ask a server for suggested values for one advertised template
+The model can ask a server for suggested values for one advertised template
 variable:
 
 ```js
@@ -142,7 +142,7 @@ mcp_tools({
 ```
 
 `value` is the current prefix and can be empty. For dependent suggestions, the
-assistant can add `arguments: { knownVariable: "value" }` inside `complete`.
+model can add `arguments: { knownVariable: "value" }` inside `complete`.
 These context values must be strings, not arrays. The server must advertise
 completion support and the exact template; the variable must occur in that
 template.

package/docs/troubleshooting.md

@@ -27,16 +27,16 @@ unavailable server isn't an empty catalog.
 | `connection_failed` | Server executable, working directory, endpoint, network, and TLS configuration. |
 | `timeout` | Server responsiveness and the applicable request, secret-command, or OAuth time limit. |
 | `protocol_error` | Server compatibility and the `protocol` setting. |
-| `tool_changed` | Check server filters and ask the assistant to activate the exact tool again for its current schema. Run `/mcp reload` if connection configuration changed. |
+| `tool_changed` | Check server filters and ask the model to activate the exact tool again for its current schema. Run `/mcp reload` if connection configuration changed. |
 | `tool_error` | The server's tool result and inputs; verify the outcome before retrying. |
-| `resource_invalid` | The assistant needs an exact absolute resource URI from discovery or a tool-returned link. |
+| `resource_invalid` | The model needs an exact absolute resource URI from discovery or a tool-returned link. |
 | `resource_not_found` | Refresh resource metadata or obtain a new link. |
-| `resources_unsupported` | Ask the assistant to use the server's tools instead, or choose a resource-capable server. |
-| `completions_unsupported` | Supply known template values; the assistant should ask you if a value is missing. |
-| `completion_invalid` | The assistant needs an advertised template variable and a string prefix. |
-| `subscriptions_unsupported` | Choose a server with subscription support, or ask the assistant to read when needed. |
+| `resources_unsupported` | Ask the model to use the server's tools instead, or choose a resource-capable server. |
+| `completions_unsupported` | Supply known template values; the model should ask you if a value is missing. |
+| `completion_invalid` | The model needs an advertised template variable and a string prefix. |
+| `subscriptions_unsupported` | Choose a server with subscription support, or ask the model to read when needed. |
 | `subscription_limit` | Remove a watch before adding another; the limit is 50 per connection. |
-| `catalog_changed` | Ask the assistant to retry discovery after the server catalog settles. |
+| `catalog_changed` | Ask the model to retry discovery after the server catalog settles. |
 | `oauth_failed` | An unclassified OAuth failure. Check the service's requirements and `/mcp get <server>` for the client type, scopes, and callback URL. Only public/PKCE clients are supported, not clients requiring a secret. |
 | `oauth_client_required` | The server doesn't support dynamic registration. Configure `oauthClientId` for a registered public/PKCE client and register the exact callback URL. Reload, then log in again. |
 | `oauth_registration_rejected` | The server rejected dynamic registration. Check public/native client eligibility and the callback URL, or configure an approved public client ID. |
@@ -69,6 +69,21 @@ remain visible as content, even when the tool reports an error; they aren't
 sanitized transport diagnostics. Tool-call failures aren't replayed automatically;
 verify the outcome before retrying.
 
+## Missing project servers
+
+A project's `.mcp.json` loads only after an explicit trust decision, even in
+folders that Pi otherwise trusts implicitly. Headless sessions ignore it when no
+decision exists. Run Pi's `/trust` command to save a decision, then run
+`/mcp reload`. See [project trust](behavior.md#project-trust).
+
+## Missing server dependencies
+
+If a stdio server reports a missing browser, SDK, credential, or configuration
+file that works in your shell, it probably reads an environment variable that
+it doesn't receive. Servers don't inherit Pi's environment; pass the variable
+through `env`, for example `PLAYWRIGHT_BROWSERS_PATH`. See
+[files and transports](configuration.md#files-and-transports).
+
 ## Large results
 
 Text output is limited to 2,000 lines or 50 KiB, including resource reads and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mcp-client",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "MCP tools for Pi, discovered on demand and called natively through the official SDK.",
   "type": "module",
   "license": "MIT",