pi-mcp-client 0.1.0 → 0.2.0

package/README.md

@@ -50,11 +50,20 @@ remain available as the conversation continues.
 
 | Command | Purpose |
 | --- | --- |
-| `/mcp` | Show server connection status, catalog sizes, and the loaded tool count. |
+| `/mcp`, `/mcp list`, `/mcp status` | Show a server status matrix with catalog and loaded-tool counts. |
+| `/mcp inspect <server>` | Inspect status and configuration, including disabled servers. Connection values are hidden. |
+| `/mcp tools <server>` | Browse the server's tools and inspect descriptions without activating tools. |
+| `/mcp reload` | Apply configuration changes without restarting Pi. |
 | `/mcp auth <server>` | Authenticate an OAuth-enabled HTTP server. |
 | `/mcp reconnect <server>` | Replace a connection and refresh its catalog. |
 | `/mcp refresh <server>` | Refresh a server's catalog without loading additional tools. |
 
+The status matrix uses glyphs to distinguish 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.
+
 After refreshing a changed schema, search for the tool again to load its current
 definition. Calls validate the live catalog before execution and refuse removed
 or changed tools. The extension does not retry failed tool invocations; after an
@@ -185,8 +194,23 @@ Every definition must include a `url` or `command`, even when `disabled` is true
 These options are specific to Pi MCP Client, not standardized MCP connection
 fields. Other clients may reject them when you copy a definition.
 
-Configuration changes take effect when Pi reloads the extension or starts a new
-session.
+After editing your configuration, run `/mcp reload` to apply it without restarting
+Pi. Reload validates the new configuration before replacing the current setup;
+invalid configuration leaves the previous setup intact. It closes existing
+connections, which reopen on demand, and deactivates tools from changed, removed,
+or disabled server definitions. Unchanged active tools remain available.
+
+Use `/mcp inspect <server>` to check the effective transport, protocol, filters,
+and connection status without connecting or running secret commands. Connection
+values—including commands, arguments, URLs, headers, and environment variables—
+are hidden because any of them can contain credentials.
+
+Use `/mcp tools <server>` to fetch the current catalog and browse a scrollable
+list. Each row shows the tool name and description, 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.
 
 ### Discovery and caching
 
@@ -201,6 +225,12 @@ They contain tool metadata, not configured credentials. Cached search needs no
 connection; invocation refreshes the live catalog before calling the tool.
 Connections remain open until shutdown or explicit reconnection.
 
+When a connected server reports a tool-list change, the extension invalidates its
+memory and disk catalogs. The next search fetches the current list, including new
+or removed tools. Notifications don't replace active tool definitions: changed
+schemas require another `mcp_search` before use. Disconnected, cache-only searches
+can't receive notifications and still use the 24-hour disk-cache expiry.
+
 ### OAuth
 
 Set `"oauth": true` under `mcpServers.<server>` in `mcp.json`, without an

package/dist/index.js

@@ -2354,6 +2354,116 @@ function searchTools(tools, query, server, limit = DEFAULT_SEARCH_LIMIT) {
   return index.search(query).sort((a, b) => b.score - a.score || String(a.id).localeCompare(String(b.id))).slice(0, Math.max(1, Math.min(limit, MAX_SEARCH_LIMIT))).map((result) => byName.get(result.id));
 }
 
+// src/management.ts
+init_config();
+import { truncateToWidth } 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" }
+};
+function serverMatrix(servers, loaded, width = 80) {
+  if (width <= 0) return "";
+  const fit = (text) => plain(truncateToWidth(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 state = serverStates[server.state];
+    const name = plain(truncateToWidth(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");
+}
+function toolPickerLabel(tool, index, columns = 80) {
+  const width = Math.max(0, columns - 4);
+  const text = `${index + 1}. ${line(tool.name)}: ${line(tool.description) || "No description."}`;
+  return plain(truncateToWidth(text, width, "\u2026"));
+}
+function schemaType(schema, depth = 0) {
+  if (!object(schema) || depth > 2) return "unknown";
+  const alternatives = schema.anyOf ?? schema.oneOf;
+  if (Array.isArray(alternatives)) {
+    if (alternatives.length > 4) return "union";
+    return [...new Set(alternatives.map((part) => schemaType(part, depth + 1)))].join(" | ") || "unknown";
+  }
+  if (schema.$ref || schema.allOf) return "unknown";
+  const type = schema.type;
+  if (Array.isArray(type))
+    return type.slice(0, 4).map((part) => schemaType({ ...schema, type: part }, depth + 1)).join(" | ");
+  if (type === "array") return `Array<${schemaType(schema.items, depth + 1)}>`;
+  if (type === "integer") return "integer";
+  if (["string", "number", "boolean", "object", "null"].includes(String(type))) return String(type);
+  return "unknown";
+}
+function toolParameters(tool) {
+  const schema = tool.inputSchema;
+  if (!object(schema)) return [];
+  const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+  return Object.entries(object(schema.properties) ? schema.properties : {}).map(([name, value]) => ({
+    name: line(name).slice(0, 80),
+    required: required.has(name),
+    type: schemaType(value),
+    description: object(value) && typeof value.description === "string" ? line(value.description) : ""
+  }));
+}
+function toolSignature(tool, limit = 40) {
+  const parameters = toolParameters(tool);
+  const args = parameters.slice(0, limit).map(
+    (parameter) => `${parameter.name}${parameter.required ? "" : "?"}: ${parameter.type}`
+  );
+  if (parameters.length > limit) args.push(`\u2026 +${parameters.length - limit} more`);
+  const schema = tool.inputSchema;
+  if (object(schema) && schema.additionalProperties !== false) args.push("\u2026");
+  const name = line(tool.name).slice(0, 160);
+  return args.length ? `${name}(
+${args.map((arg) => `  ${arg},`).join("\n")}
+)` : `${name}()`;
+}
+function inspectTool(tool) {
+  const parameters = toolParameters(tool);
+  return [
+    toolSignature(tool),
+    line(tool.description) || "No description.",
+    ...parameters.length ? ["Parameters:"] : [],
+    ...parameters.slice(0, 40).map(
+      (parameter) => `${parameter.name}: ${parameter.type} (${parameter.required ? "required" : "optional"})${parameter.description ? `
+${parameter.description}` : ""}`
+    ),
+    ...parameters.length > 40 ? [`\u2026 ${parameters.length - 40} more parameters`] : [],
+    "Types are summaries; the full schema may impose additional constraints."
+  ].join("\n\n");
+}
+function inspectServer(name, config, status) {
+  return [
+    status,
+    `Server: ${name}`,
+    `Transport: ${config.command ? "stdio" : "HTTP"}`,
+    `Protocol: ${config.protocol ?? "auto"}`,
+    `OAuth: ${config.oauth ? "enabled" : "disabled"}`,
+    `Timeout: ${config.timeoutMs ? `${config.timeoutMs} ms` : "default"}`,
+    ...config.command ? [
+      "Command and working directory: hidden",
+      `Arguments: ${config.args?.length ?? 0} (values hidden)`,
+      `Environment overrides: ${Object.keys(config.env ?? {}).length} (names and values hidden)`
+    ] : [
+      "URL: hidden",
+      `Headers: ${Object.keys(config.headers ?? {}).length} (names and values hidden)`
+    ],
+    `Include tools: ${config.includeTools ? config.includeTools.map(line).join(", ") : "all"}`,
+    `Exclude tools: ${config.excludeTools?.map(line).join(", ") || "none"}`
+  ].join("\n");
+}
+
 // src/auth.ts
 init_config();
 init_diagnostics();
@@ -2531,7 +2641,7 @@ async function authenticate(url, open, signal, store) {
 
 // src/runtime.ts
 init_config();
-import { mkdir, readFile as readFile2, rename, stat, writeFile } from "node:fs/promises";
+import { mkdir, readFile as readFile2, rename, rm, stat, writeFile } from "node:fs/promises";
 import { join as join2 } from "node:path";
 import { randomUUID as randomUUID2 } from "node:crypto";
 import {
@@ -2565,11 +2675,18 @@ function waitFor(promise, signal) {
     if (signal.aborted) abort();
   });
 }
-var connectSdk = async (_name, config, signal) => {
+var connectSdk = async (_name, config, signal, onToolsChanged) => {
   const timeout = config.timeoutMs ?? 15e3;
   const client = new Client(
     { name: "pi-mcp-client", version: "0.1.0" },
     {
+      listChanged: {
+        tools: {
+          autoRefresh: false,
+          debounceMs: 0,
+          onChanged: () => onToolsChanged?.()
+        }
+      },
       versionNegotiation: {
         mode: config.protocol ?? "auto",
         probe: { timeoutMs: timeout }
@@ -2585,21 +2702,39 @@ var connectSdk = async (_name, config, signal) => {
   }) : new StreamableHTTPClientTransport(new URL(config.url), {
     requestInit: { headers: config.headers },
     authProvider: config.oauth ? new OAuthProvider(config.url, await credentialStore(config.url)) : void 0,
-    // Bound each HTTP request, including OAuth discovery and token refresh.
-    fetch: (input, init) => fetch(input, {
-      ...init,
-      signal: AbortSignal.any([
-        signal,
-        AbortSignal.timeout(timeout),
-        ...init?.signal ? [init.signal] : []
-      ])
-    })
-  });
-  if (transport instanceof StdioClientTransport) transport.stderr?.on("data", () => {
+    // Bound HTTP responses (including OAuth), but not established SSE streams.
+    // The SDK bounds ordinary MCP requests with their request timeout.
+    fetch: async (input, init) => {
+      const deadline = new AbortController();
+      const timer = setTimeout(
+        () => deadline.abort(new Error("HTTP response timed out.")),
+        timeout
+      );
+      timer.unref();
+      try {
+        const response = await fetch(input, {
+          ...init,
+          signal: AbortSignal.any([
+            signal,
+            deadline.signal,
+            ...init?.signal ? [init.signal] : []
+          ])
+        });
+        if (response.headers.get("content-type")?.split(";")[0].trim() === "text/event-stream")
+          clearTimeout(timer);
+        return response;
+      } catch (error) {
+        clearTimeout(timer);
+        throw error;
+      }
+    }
   });
+  if (transport instanceof StdioClientTransport)
+    transport.stderr?.on("data", () => {
+    });
   try {
     await waitFor(
-      client.connect(transport),
+      client.connect(transport, { signal, timeout }),
       AbortSignal.any([signal, AbortSignal.timeout(timeout)])
     );
     signal.throwIfAborted();
@@ -2621,6 +2756,7 @@ var McpRuntime = class {
   }
   states = /* @__PURE__ */ new Map();
   lifetime = new AbortController();
+  closing;
   identity(name) {
     const config = this.definition(name);
     let resolved;
@@ -2643,18 +2779,21 @@ var McpRuntime = class {
   definition(name) {
     const config = Object.hasOwn(this.config, name) ? this.config[name] : void 0;
     if (!config || config.disabled)
-      throw new ToolContractError("MCP server is not configured or is disabled.");
+      throw new ToolContractError(
+        "MCP server is not configured or is disabled."
+      );
     return config;
   }
   state(name) {
     let state = this.states.get(name);
     if (!state) {
-      state = {};
+      state = { catalogGeneration: 0 };
       this.states.set(name, state);
     }
     return state;
   }
   async client(name) {
+    if (this.closing) throw new Error("MCP session ended.");
     this.lifetime.signal.throwIfAborted();
     const state = this.state(name);
     const identity = this.identity(name);
@@ -2666,6 +2805,8 @@ var McpRuntime = class {
     if (state.connecting) return state.connecting;
     const config = resolveServer(this.definition(name), this.cwd);
     state.connectionIdentity = identity;
+    const token = {};
+    state.connectionToken = token;
     state.connecting = (async () => {
       const { client, transport } = await this.connect(
         name,
@@ -2675,9 +2816,28 @@ var McpRuntime = class {
           this.cwd,
           this.lifetime.signal
         ),
-        this.lifetime.signal
+        this.lifetime.signal,
+        () => {
+          if (this.closing || this.lifetime.signal.aborted || state.connectionToken !== token)
+            return;
+          state.catalogGeneration++;
+          state.catalogDirty = true;
+          state.tools = void 0;
+          state.warnings = void 0;
+          const path = join2(this.cacheDir, `${identity}.json`);
+          state.invalidating = withFileMutationQueue(
+            path,
+            () => rm(path, { force: true })
+          ).catch(() => {
+            state.warnings = [
+              `${name}: stale catalog cache could not be removed.`
+            ];
+          });
+        }
       );
-      if (this.lifetime.signal.aborted) {
+      if (this.closing || this.lifetime.signal.aborted) {
+        await client.autoOpenedSubscription?.close().catch(() => {
+        });
         await client.close();
         throw new Error("MCP session ended.");
       }
@@ -2688,10 +2848,12 @@ var McpRuntime = class {
         if (state.client === client) {
           state.client = void 0;
           state.transport = void 0;
+          state.connectionToken = void 0;
         }
       };
       return client;
     })().catch((error) => {
+      if (state.connectionToken === token) state.connectionToken = void 0;
       throw new DiagnosticError(
         diagnose(error, {
           server: name,
@@ -2707,10 +2869,13 @@ var McpRuntime = class {
   }
   async catalog(name, signal, refresh = false) {
     signal?.throwIfAborted();
+    if (this.closing) throw new Error("MCP session ended.");
     this.lifetime.signal.throwIfAborted();
     const state = this.state(name);
     const identity = this.identity(name);
-    if (!refresh && state.tools && state.identity === identity) return state.tools;
+    refresh ||= !!state.catalogDirty;
+    if (!refresh && state.tools && state.identity === identity)
+      return state.tools;
     if (refresh && state.listing && !state.listingLive) {
       await waitFor(state.listing, signal);
       return this.catalog(name, signal, true);
@@ -2718,44 +2883,59 @@ var McpRuntime = class {
     if (!state.listing) {
       state.listingLive = refresh;
       state.listing = (async () => {
-        if (!refresh) {
-          const cached = await this.readCache(name, identity);
-          if (cached) {
-            state.tools = cached;
-            state.identity = identity;
-            return cached;
+        for (let attempt = 0; attempt < 3; attempt++) {
+          const generation = state.catalogGeneration;
+          if (!refresh && !state.catalogDirty) {
+            const cached = await this.readCache(name, identity);
+            if (cached && generation === state.catalogGeneration) {
+              state.tools = cached;
+              state.identity = identity;
+              return cached;
+            }
           }
-        }
-        const client = await this.client(name);
-        const listed = await client.listTools(void 0, {
-          signal: this.lifetime.signal,
-          timeout: this.definition(name).timeoutMs ?? 15e3
-        });
-        const tools = [];
-        const warnings = [];
-        const seen = /* @__PURE__ */ new Set();
-        for (const tool of listed.tools) {
-          if (!allowed(tool.name, this.definition(name))) continue;
-          try {
-            const prepared = prepareTool(name, identity, tool);
-            if (seen.has(prepared.nativeName)) throw new Error("Duplicate tool name.");
-            seen.add(prepared.nativeName);
-            tools.push(prepared);
-          } catch {
-            warnings.push(
-              `${name}: skipped an invalid, duplicate, or unsupported tool schema.`
-            );
+          const client = await this.client(name);
+          const listed = await client.listTools(void 0, {
+            signal: this.lifetime.signal,
+            timeout: this.definition(name).timeoutMs ?? 15e3
+          });
+          const tools = [];
+          const warnings = [];
+          const seen = /* @__PURE__ */ new Set();
+          for (const tool of listed.tools) {
+            if (!allowed(tool.name, this.definition(name))) continue;
+            try {
+              const prepared = prepareTool(name, identity, tool);
+              if (seen.has(prepared.nativeName))
+                throw new Error("Duplicate tool name.");
+              seen.add(prepared.nativeName);
+              tools.push(prepared);
+            } catch {
+              warnings.push(
+                `${name}: skipped an invalid, duplicate, or unsupported tool schema.`
+              );
+            }
           }
+          this.lifetime.signal.throwIfAborted();
+          if (generation !== state.catalogGeneration) continue;
+          await state.invalidating;
+          await this.writeCache(
+            identity,
+            tools,
+            () => generation === state.catalogGeneration
+          ).catch(() => {
+            warnings.push(`${name}: catalog cache could not be saved.`);
+          });
+          if (generation !== state.catalogGeneration) continue;
+          state.tools = tools;
+          state.identity = identity;
+          state.catalogDirty = false;
+          state.error = void 0;
+          state.warnings = warnings;
+          return tools;
         }
-        this.lifetime.signal.throwIfAborted();
-        state.tools = tools;
-        state.identity = identity;
-        state.error = void 0;
-        state.warnings = warnings;
-        await this.writeCache(identity, tools).catch(() => {
-          warnings.push(`${name}: catalog cache could not be saved.`);
-        });
-        return tools;
+        throw new ToolContractError(
+          "MCP tool catalog kept changing. Search again."
+        );
       })().catch((error) => {
         state.error = this.failure(name, error);
         throw new DiagnosticError(state.error);
@@ -2812,7 +2992,10 @@ var McpRuntime = class {
       return await client.callTool(
         { name: tool.name, arguments: args },
         {
-          signal: AbortSignal.any([this.lifetime.signal, ...signal ? [signal] : []]),
+          signal: AbortSignal.any([
+            this.lifetime.signal,
+            ...signal ? [signal] : []
+          ]),
           timeout: config.timeoutMs ?? 3e4,
           onprogress: (event) => progress?.(
             event.message ?? `${event.progress}${event.total === void 0 ? "" : `/${event.total}`}`
@@ -2835,18 +3018,38 @@ var McpRuntime = class {
     const state = this.state(name);
     if (state.connecting || state.listing)
       throw failure("busy", { server: name, operation: "reconnect" });
+    await state.client?.autoOpenedSubscription?.close();
     await state.client?.close();
     state.client = void 0;
     await this.catalog(name, void 0, true);
   }
-  status() {
+  serverStatuses() {
     return Object.entries(this.config).map(([name, config]) => {
       const state = this.states.get(name);
-      const status = config.disabled ? "disabled" : state?.connecting || state?.listing ? "connecting" : state?.error ? formatDiagnostic({ ...state.error, server: void 0 }) : state?.client ? "connected" : "disconnected";
-      return `${name}: ${status} \xB7 ${state?.tools?.length ?? "unknown"} catalog tools`;
+      return {
+        name,
+        state: config.disabled ? "disabled" : state?.connecting || state?.listing ? "connecting" : state?.error ? "failed" : state?.client ? "connected" : "disconnected",
+        catalogSize: state?.tools?.length,
+        error: state?.error
+      };
+    });
+  }
+  status(server) {
+    return this.serverStatuses().filter(({ name }) => server === void 0 || name === server).map((row) => {
+      const status = row.state === "failed" && row.error ? formatDiagnostic({ ...row.error, server: void 0 }) : row.state;
+      return `${row.name}: ${status} \xB7 ${row.catalogSize ?? "unknown"} catalog tools`;
     }).join("\n") || "No MCP servers configured.";
   }
-  async close() {
+  close() {
+    return this.closing ??= this.shutdown();
+  }
+  async shutdown() {
+    await Promise.all(
+      [...this.states.values()].map(
+        (state) => state.client?.autoOpenedSubscription?.close().catch(() => {
+        })
+      )
+    );
     this.lifetime.abort(new Error("MCP session ended."));
     await Promise.all(
       [...this.states.values()].map(async (state) => {
@@ -2856,6 +3059,7 @@ var McpRuntime = class {
         });
         await state.listing?.catch(() => {
         });
+        await state.invalidating;
       })
     );
   }
@@ -2871,7 +3075,8 @@ var McpRuntime = class {
     try {
       const path = join2(this.cacheDir, `${identity}.json`);
       const info = await stat(path);
-      if (info.size > 4 * 1024 * 1024 || Date.now() - info.mtimeMs > 864e5) return;
+      if (info.size > 4 * 1024 * 1024 || Date.now() - info.mtimeMs > 864e5)
+        return;
       const data = JSON.parse(await readFile2(path, "utf8"));
       if (!Array.isArray(data) || data.length > 1e4) return;
       return data.filter((tool) => allowed(tool.name, this.definition(name))).map((tool) => prepareTool(name, identity, tool));
@@ -2879,7 +3084,7 @@ var McpRuntime = class {
       return;
     }
   }
-  async writeCache(identity, tools) {
+  async writeCache(identity, tools, isCurrent) {
     const text = JSON.stringify(
       tools.map(({ name, description, inputSchema }) => ({
         name,
@@ -2891,9 +3096,11 @@ var McpRuntime = class {
     await mkdir(this.cacheDir, { recursive: true, mode: 448 });
     const path = join2(this.cacheDir, `${identity}.json`);
     await withFileMutationQueue(path, async () => {
+      if (!isCurrent()) return;
       const temp = `${path}.${randomUUID2()}.tmp`;
       await writeFile(temp, text, { mode: 384 });
-      await rename(temp, path);
+      if (isCurrent()) await rename(temp, path);
+      else await rm(temp, { force: true });
     });
   }
 };
@@ -3036,7 +3243,7 @@ Full MCP result: ${path}`;
 
 // src/render.ts
 import { keyText } from "@earendil-works/pi-coding-agent";
-import { Text, truncateToWidth } from "@earendil-works/pi-tui";
+import { Text, truncateToWidth as truncateToWidth2 } from "@earendil-works/pi-tui";
 init_config();
 var states = {
   queued: { glyph: "\u25CF", color: "dim" },
@@ -3053,10 +3260,10 @@ function renderCall(title, args, theme, expanded) {
       if (width <= 0) return [];
       const text = theme.fg("toolTitle", theme.bold(line(title))) + (preview ? theme.fg("dim", ` ${preview}`) : "");
       if (expanded)
-        return new Text(text, 0, 0).render(width).map((row) => truncateToWidth(row, width));
+        return new Text(text, 0, 0).render(width).map((row) => truncateToWidth2(row, width));
       const key = keyText("app.tools.expand");
       return [
-        truncateToWidth(
+        truncateToWidth2(
           text + (key ? theme.fg("muted", ` (${key} to expand)`) : ""),
           width
         )
@@ -3083,23 +3290,23 @@ function renderResult(result, options, theme, isError) {
       const lines = rows.flatMap((row) => {
         const status = states[row.state] ?? states.failed;
         const value = theme.fg(status.color, status.glyph) + " " + theme.fg("accent", line(row.label));
-        const rendered = options.expanded && (!details?.searchNotes || row.state === "failed") ? new Text(value, 0, 0).render(width).map((x) => truncateToWidth(x, width)) : [truncateToWidth(value, width)];
+        const rendered = options.expanded && (!details?.searchNotes || row.state === "failed") ? new Text(value, 0, 0).render(width).map((x) => truncateToWidth2(x, width)) : [truncateToWidth2(value, width)];
         if (options.expanded && row.description)
-          rendered.push(truncateToWidth(
+          rendered.push(truncateToWidth2(
             theme.fg("dim", `  ${line(row.description)}`),
             width
           ));
         return rendered;
       });
       for (const note of details?.searchNotes ?? [])
-        lines.push(...(options.expanded ? new Text(theme.fg("warning", plain(note)), 0, 0).render(width) : [theme.fg("warning", line(note))]).map((row) => truncateToWidth(row, width)));
+        lines.push(...(options.expanded ? new Text(theme.fg("warning", plain(note)), 0, 0).render(width) : [theme.fg("warning", line(note))]).map((row) => truncateToWidth2(row, width)));
       if (options.expanded && !options.isPartial && text && !details?.searchNotes)
         lines.push(
-          ...new Text(text, 0, 0).render(width).map((x) => truncateToWidth(x, width))
+          ...new Text(text, 0, 0).render(width).map((x) => truncateToWidth2(x, width))
         );
       if (!options.expanded && details?.fullOutputPath)
         lines.push(
-          truncateToWidth(
+          truncateToWidth2(
             theme.fg("dim", `Full result: ${details.fullOutputPath}`),
             width
           )
@@ -3132,6 +3339,7 @@ function mcpClient(pi, options = {}) {
   let runtime;
   let config = {};
   let configError;
+  let sessionGeneration = 0;
   const exposure = new Exposure(pi, registerNative);
   const current = () => {
     if (!runtime)
@@ -3192,28 +3400,54 @@ Text output is limited to 2000 lines or 50 KiB; larger results are saved to a pr
     });
     exposure.restore(tools);
   };
+  async function reloadConfiguration(ctx) {
+    const generation = sessionGeneration;
+    ctx.signal?.throwIfAborted();
+    const nextConfig = await loadConfig(agentDir, ctx.cwd, ctx.isProjectTrusted());
+    ctx.signal?.throwIfAborted();
+    if (generation !== sessionGeneration)
+      throw new CommandUsageError("The Pi session changed during configuration reload.");
+    for (const definition of Object.values(nextConfig)) {
+      if (!definition.disabled) resolveServer(definition, ctx.cwd);
+    }
+    const next = new McpRuntime(
+      nextConfig,
+      ctx.cwd,
+      join4(agentDir, "cache", "pi-mcp-client")
+    );
+    const active = new Set(pi.getActiveTools());
+    const retained = [...exposure.definitions.values()].filter((tool) => {
+      try {
+        return active.has(tool.nativeName) && next.identity(tool.server) === tool.identity && allowed(tool.name, nextConfig[tool.server]);
+      } catch {
+        return false;
+      }
+    });
+    const old = runtime;
+    config = nextConfig;
+    configError = void 0;
+    runtime = next;
+    exposure.restore(retained);
+    await old?.close();
+  }
   pi.on("session_start", async (_event, ctx) => {
+    sessionGeneration++;
     await runtime?.close();
     runtime = void 0;
     config = {};
     configError = void 0;
     try {
       config = await loadConfig(agentDir, ctx.cwd, ctx.isProjectTrusted());
-      runtime = new McpRuntime(
-        config,
-        ctx.cwd,
-        join4(agentDir, "cache", "pi-mcp-client")
-      );
+      runtime = new McpRuntime(config, ctx.cwd, join4(agentDir, "cache", "pi-mcp-client"));
     } catch (error) {
-      configError = new DiagnosticError(
-        diagnose(error, { operation: "configuration" })
-      );
+      configError = new DiagnosticError(diagnose(error, { operation: "configuration" }));
       if (ctx.hasUI) ctx.ui.notify(configError.message, "error");
     }
     restore(ctx);
   });
   pi.on("session_tree", (_event, ctx) => restore(ctx));
   pi.on("session_shutdown", async () => {
+    sessionGeneration++;
     const old = runtime;
     runtime = void 0;
     await old?.close();
@@ -3247,17 +3481,21 @@ Use mcp_search to load relevant tools, then call them directly. Loaded tools rem
           maxLength: 500,
           description: "One focused capability or exact server.tool name, for example linear.list_teams. Do not enumerate every capability of a server."
         }),
-        server: Type.Optional(Type.String({
-          minLength: 1,
-          maxLength: 80,
-          description: "Restrict discovery to this configured MCP server."
-        })),
-        limit: Type.Optional(Type.Integer({
-          minimum: 1,
-          maximum: MAX_SEARCH_LIMIT,
-          default: DEFAULT_SEARCH_LIMIT,
-          description: `Maximum number of tools to load: 1\u2013${MAX_SEARCH_LIMIT} inclusive (default: ${DEFAULT_SEARCH_LIMIT}). This is not a limit on records returned by a native tool. Omit unless more tools are needed.`
-        }))
+        server: Type.Optional(
+          Type.String({
+            minLength: 1,
+            maxLength: 80,
+            description: "Restrict discovery to this configured MCP server."
+          })
+        ),
+        limit: Type.Optional(
+          Type.Integer({
+            minimum: 1,
+            maximum: MAX_SEARCH_LIMIT,
+            default: DEFAULT_SEARCH_LIMIT,
+            description: `Maximum number of tools to load: 1\u2013${MAX_SEARCH_LIMIT} inclusive (default: ${DEFAULT_SEARCH_LIMIT}). This is not a limit on records returned by a native tool. Omit unless more tools are needed.`
+          })
+        )
       },
       { additionalProperties: false }
     ),
@@ -3282,12 +3520,7 @@ Use mcp_search to load relevant tools, then call them directly. Loaded tools rem
         (signal ?? ctx.signal)?.throwIfAborted();
         if (runtime !== activeRuntime)
           throw new Error("MCP session changed during search.");
-        const matches2 = searchTools(
-          discovery.tools,
-          args.query,
-          args.server,
-          args.limit
-        );
+        const matches2 = searchTools(discovery.tools, args.query, args.server, args.limit);
         const { loaded, added, rejected } = exposure.load(matches2);
         const messages2 = loaded.map(
           (tool) => `${added.includes(tool.nativeName) ? "Loaded" : "Already loaded"}: ${tool.nativeName} \u2014 ${line(tool.description).slice(0, 180)}`
@@ -3344,34 +3577,81 @@ Use mcp_search to load relevant tools, then call them directly. Loaded tools rem
     }
   });
   pi.registerCommand("mcp", {
-    description: "Inspect MCP servers; /mcp auth|reconnect|refresh <server>",
+    description: "Manage MCP servers: list, status, reload, inspect|tools|auth|reconnect|refresh <server>",
     getArgumentCompletions(prefix) {
-      const values = [
-        "status",
-        ...["auth", "reconnect", "refresh"].flatMap(
-          (action) => Object.keys(config).map((name) => `${action} ${name}`)
-        )
-      ];
-      return values.filter((value) => value.startsWith(prefix)).map((value) => ({ value, label: value }));
+      const serverActions = ["inspect", "tools", "auth", "reconnect", "refresh"];
+      const input = prefix.trimStart();
+      const match = /^(\S+)\s+(.*)$/s.exec(input);
+      if (!match) {
+        return ["list", "status", "reload", ...serverActions].filter((action2) => action2.startsWith(input)).map((action2) => ({ value: action2, label: action2 }));
+      }
+      const [, action, partialServer] = match;
+      if (!serverActions.includes(action) || /\s/.test(partialServer)) return [];
+      return Object.keys(config).filter(
+        (name) => name.startsWith(partialServer) && (action === "inspect" || !config[name].disabled)
+      ).sort().map((name) => ({ value: `${action} ${name}`, label: name }));
     },
     async handler(args, ctx) {
       await ctx.waitForIdle();
       const [action = "status", server, ...extra] = args.trim().split(/\s+/).filter(Boolean);
       try {
-        if (action === "status" && !server) {
-          const loaded = pi.getActiveTools().filter((name) => exposure.definitions.has(name)).length;
+        if (action === "reload" && !server) {
+          await reloadConfiguration(ctx);
           if (ctx.hasUI)
             ctx.ui.notify(
-              `${current().status()}
-${loaded} native MCP tools loaded.`,
+              "\u2714\uFE0E MCP configuration reloaded. Connections reopen on demand; tools from changed or removed servers are no longer active.",
               "info"
             );
           return;
         }
+        if (action === "inspect" && server && !extra.length && Object.hasOwn(config, server)) {
+          if (ctx.hasUI)
+            ctx.ui.notify(
+              inspectServer(server, config[server], current().status(server)),
+              "info"
+            );
+          return;
+        }
+        if ((action === "status" || action === "list") && !server) {
+          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");
+          return;
+        }
         if (!server || extra.length || !Object.hasOwn(config, server) || config[server].disabled)
           throw new CommandUsageError(
-            "Usage: /mcp auth|reconnect|refresh <enabled-server>"
+            "Usage: /mcp list|status|reload or /mcp inspect|tools|auth|reconnect|refresh <server>. Only inspect accepts a disabled server."
           );
+        if (action === "tools") {
+          if (!ctx.hasUI)
+            throw new CommandUsageError("Tool browsing requires an interactive UI.");
+          const tools = await current().catalog(server, ctx.signal, true);
+          if (!tools.length) {
+            ctx.ui.notify(
+              `${server}: no tools available under the configured filters.`,
+              "info"
+            );
+            return;
+          }
+          const choices = [...tools].sort((a, b) => a.name.localeCompare(b.name));
+          const columns = ctx.mode === "tui" ? process.stdout.columns || 80 : 80;
+          const labels = choices.map((tool2, index) => toolPickerLabel(tool2, index, columns));
+          const selected = await ctx.ui.select(
+            `${server}: ${tools.length} tools (select to inspect; none are activated)`,
+            labels
+          );
+          const tool = selected === void 0 ? void 0 : choices[labels.indexOf(selected)];
+          if (tool)
+            ctx.ui.notify(
+              inspectTool(tool),
+              "info"
+            );
+          return;
+        }
         if (action === "auth") {
           if (!ctx.hasUI)
             throw new CommandUsageError(
@@ -3416,27 +3696,27 @@ ${target}`, "info");
           } else await authenticate(url, open, ctx.signal);
           await current().reconnect(server);
         } else if (action === "reconnect") await current().reconnect(server);
-        else if (action === "refresh")
-          await current().catalog(server, ctx.signal, true);
+        else if (action === "refresh") await current().catalog(server, ctx.signal, true);
         else
           throw new CommandUsageError(
-            "Unknown MCP command. Use /mcp auth|reconnect|refresh <server>."
+            "Unknown MCP command. Use /mcp list|status|reload or /mcp inspect|tools|auth|reconnect|refresh <server>."
           );
         if (ctx.hasUI)
           ctx.ui.notify(
-            `${server}: ${action} complete. Search to load new or changed tools.`,
+            `\u2714\uFE0E ${server}: ${action} complete. Updated tools are available for the assistant to discover.`,
             "info"
           );
       } catch (error) {
         const message = error instanceof CommandUsageError ? error.message : formatDiagnostic(
           diagnose(error, {
             server,
-            operation: action === "auth" ? "auth" : action === "refresh" ? "refresh" : "reconnect",
+            operation: action === "reload" || action === "inspect" ? "configuration" : action === "tools" ? "search" : action === "auth" ? "auth" : action === "refresh" ? "refresh" : "reconnect",
             oauth: config[server]?.oauth,
             signal: ctx.signal
           })
         );
         if (ctx.hasUI) ctx.ui.notify(message, "error");
+        else throw new Error(message);
       }
     }
   });

package/package.json

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