@pi-unipi/mcp 2.4.1 → 2.6.0

package/README.md

@@ -12,6 +12,7 @@ The add command opens a split-pane overlay: server browser on the left, JSON con
 | `/unipi:mcp-settings` | Interactive settings with enable/disable/edit |
 | `/unipi:mcp-sync` | Force sync server catalog from GitHub |
 | `/unipi:mcp-status` | Text summary of all configured servers |
+| `/unipi:mcp-reload` | Remind you to restart Pi so tool schemas reload as a clean cache epoch |
 
 ### Setup Flow
 
@@ -30,6 +31,18 @@ MCP registers with the info-screen dashboard, showing server count, active serve
 
 MCP tools are registered dynamically based on configured servers. Once a server is added and Pi restarts, its tools become available to the agent.
 
+### Deterministic Definitions and Cache Behavior
+
+At session startup, enabled servers connect and discover tools in parallel. Registration waits for all discoveries to settle, then registers the successful combined tool set in canonical `{serverName}__{toolName}` order. Duplicate final names are rejected explicitly instead of allowing one definition to overwrite another.
+
+MCP input properties are cloned and recursively canonicalized before registration: schema object keys use locale-independent UTF-16 code-unit order, valid schema `required` string arrays are sorted and deduplicated, a missing top-level `required` becomes `[]`, and literal-value arrays keep their source order. Each tool also receives a stable label matching its final Pi name. These stable definitions and registration order prevent equivalent MCP configurations from changing the serialized tool list between runs, improving provider prompt-cache reuse. A server that fails discovery is excluded from the combined set; a registration error fails startup for that prepared set and is not reported as successful.
+
+Pi 0.80 cannot remove dynamically registered tools. Enabling, disabling, deleting, or changing MCP servers is therefore applied on the next Pi restart rather than mutating the tool list mid-session. This prevents stale schemas and makes the restart an explicit cache-epoch boundary.
+
+### Bounded Results
+
+MCP text results are model-visible up to a hard 64 KiB ceiling. A larger result keeps a bounded head/tail preview and, when the raw result is at most 16 MiB, writes the complete text to a private mode-0600 artifact under `~/.unipi/tool-results/`. Existing result directories are tightened to mode 0700. The returned result includes the path and directs the agent to use `read` with offset/limit. Results above the raw safety cap or filesystem write failures still return a bounded preview with an explicit non-retention warning. MCP image bytes are not written by this text bridge; image blocks remain represented by MIME metadata as before.
+
 Example tool calls:
 ```
 github__search_code({ query: "authentication middleware" })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/mcp",
-  "version": "2.4.1",
+  "version": "2.6.0",
   "description": "MCP server management extension for Pi coding agent — browse, add, configure, and use MCP servers",
   "type": "module",
   "main": "src/index.ts",
@@ -26,8 +26,11 @@
     "skills/**/*",
     "README.md"
   ],
+  "scripts": {
+    "test": "npx tsx --test tests/**/*.test.ts"
+  },
   "dependencies": {
-    "@pi-unipi/core": "2.4.1"
+    "@pi-unipi/core": "2.6.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.80.0",

package/src/bridge/registry.ts

@@ -2,19 +2,21 @@
  * @pi-unipi/mcp — Server registry
  *
  * Manages MCP server lifecycle: start, stop, restart, status tracking.
- * Coordinates McpClient instances and tool registration with pi.
+ * Coordinates McpClient instances and deterministic tool registration with pi.
  */
 
 import { UNIPI_EVENTS, MCP_DEFAULTS } from "@pi-unipi/core";
 import type {
   ResolvedServer,
   ServerState,
-  ServerStatus,
-  McpTool,
   McpRegistryEntry,
 } from "../types.js";
 import { McpClient } from "./client.js";
-import { translateMcpTool, type PiExternalTool } from "./translator.js";
+import {
+  compareCodeUnits,
+  translateMcpTool,
+  type PiExternalTool,
+} from "./translator.js";
 
 /** Callback for emitting events */
 export type EventEmitFn = (
@@ -28,6 +30,12 @@ export type RegisterToolFn = (tool: PiExternalTool) => void;
 /** Callback for unregistering a tool with pi */
 export type UnregisterToolFn = (toolName: string) => void;
 
+/** Minimal client surface used by the registry. */
+export type RegistryClient = Pick<
+  McpClient,
+  "connect" | "disconnect" | "listTools" | "callTool" | "pid"
+>;
+
 /** Options for ServerRegistry */
 export interface ServerRegistryOptions {
   /** Function to emit events via pi.events */
@@ -36,156 +44,273 @@ export interface ServerRegistryOptions {
   registerTool: RegisterToolFn;
   /** Function to unregister a tool from pi */
   unregisterTool: UnregisterToolFn;
+  /** Whether the host can actually remove dynamically registered tools. */
+  canUnregisterTools?: boolean;
   /** Per-server startup timeout in ms */
   timeoutMs?: number;
+  /** Client factory, primarily for tests. */
+  createClient?: () => RegistryClient;
 }
 
-/**
- * Server registry — tracks all MCP server connections and their tools.
- */
+interface PreparedServer {
+  entry: McpRegistryEntry;
+  client: RegistryClient;
+  tools: PiExternalTool[];
+}
+
+/** Server registry — tracks all MCP server connections and their tools. */
 export class ServerRegistry {
   private entries = new Map<string, McpRegistryEntry>();
   private readonly emitEvent: EventEmitFn;
   private readonly registerTool: RegisterToolFn;
   private readonly unregisterTool: UnregisterToolFn;
+  private readonly canUnregisterTools: boolean;
   private readonly timeoutMs: number;
+  private readonly createClient: () => RegistryClient;
 
   constructor(options: ServerRegistryOptions) {
     this.emitEvent = options.emitEvent;
     this.registerTool = options.registerTool;
     this.unregisterTool = options.unregisterTool;
+    this.canUnregisterTools = options.canUnregisterTools ?? true;
     this.timeoutMs = options.timeoutMs ?? MCP_DEFAULTS.STARTUP_TIMEOUT_MS;
+    this.createClient = options.createClient ?? (() => new McpClient({ timeoutMs: this.timeoutMs }));
   }
 
   /**
-   * Start an MCP server: spawn process, initialize, discover tools, register.
+   * Start one MCP server. Discovery completes before its tools are registered,
+   * and registration always follows final Pi tool-name order.
    */
   async startServer(resolved: ResolvedServer): Promise<void> {
-    const { name, def } = resolved;
+    await this.startServers([resolved]);
+    const state = this.getServerState(resolved.name);
+    if (state?.status === "error") {
+      throw new Error(state.error ?? `MCP server "${resolved.name}" failed to start`);
+    }
+  }
 
-    // Check max servers limit
-    if (this.entries.size >= MCP_DEFAULTS.MAX_SERVERS) {
+  /**
+   * Start MCP servers behind a discovery barrier.
+   *
+   * Connections and tool discovery run in parallel. Once every server has
+   * either prepared or failed, tools from all successful servers are checked
+   * for duplicate final names, sorted, and only then registered with Pi.
+   * Individual connection failures remain represented by error registry
+   * entries and do not prevent tools from other servers being registered.
+   */
+  async startServers(resolvedServers: ResolvedServer[]): Promise<void> {
+    if (resolvedServers.length === 0) return;
+
+    const names = new Set<string>();
+    for (const { name } of resolvedServers) {
+      if (names.has(name)) {
+        throw new Error(`Duplicate MCP server name in startup batch: "${name}"`);
+      }
+      names.add(name);
+    }
+
+    const replacementCount = [...names].filter((name) => this.entries.has(name)).length;
+    if (this.entries.size - replacementCount + resolvedServers.length > MCP_DEFAULTS.MAX_SERVERS) {
       throw new Error(
         `Maximum number of MCP servers (${MCP_DEFAULTS.MAX_SERVERS}) reached. ` +
           `Stop a server before starting a new one.`,
       );
     }
 
-    // Stop existing server with same name if running
-    if (this.entries.has(name)) {
-      await this.stopServer(name);
-    }
+    // Existing instances must release their names before replacements prepare.
+    await Promise.all(
+      [...names]
+        .filter((name) => this.entries.has(name))
+        .map((name) => this.stopServer(name)),
+    );
 
-    const state: ServerState = {
-      name,
-      status: "starting",
-      toolCount: 0,
-      startedAt: new Date().toISOString(),
-    };
+    const settled = await Promise.allSettled(
+      resolvedServers.map((resolved) => this.prepareServer(resolved)),
+    );
+    const prepared = settled
+      .filter((result): result is PromiseFulfilledResult<PreparedServer> => result.status === "fulfilled")
+      .map((result) => result.value);
 
-    const entry: McpRegistryEntry = {
-      name,
-      resolved,
-      state,
-      client: null,
-      toolNames: [],
-    };
+    if (prepared.length === 0) return;
 
-    this.entries.set(name, entry);
+    const registrations = prepared
+      .flatMap(({ entry, tools }) => tools.map((tool) => ({ entry, tool })))
+      .sort((left, right) => compareCodeUnits(left.tool.name, right.tool.name));
 
     try {
-      // Defensive: ensure server definition has correct types before passing
-      // to the client. Catches rare serialization bugs where env/args become
-      // strings instead of objects/arrays.
-      const safeCommand = typeof def.command === "string" ? def.command : String(def.command);
-      const safeArgs = Array.isArray(def.args) ? def.args : [];
-      let safeEnv: Record<string, string> | undefined;
-      if (def.env !== undefined && def.env !== null) {
-        if (typeof def.env === "object" && !Array.isArray(def.env)) {
-          safeEnv = {};
-          for (const [k, v] of Object.entries(def.env)) {
-            safeEnv[k] = typeof v === "string" ? v : String(v);
+      this.assertUniqueFinalToolNames(registrations.map(({ tool }) => tool.name));
+    } catch (error) {
+      await this.failPreparedServers(prepared, error);
+      throw error;
+    }
+
+    const registeredNames: string[] = [];
+    try {
+      for (const { tool } of registrations) {
+        this.registerTool(tool);
+        registeredNames.push(tool.name);
+      }
+    } catch (error) {
+      if (this.canUnregisterTools) {
+        for (const toolName of registeredNames.reverse()) {
+          try {
+            this.unregisterTool(toolName);
+          } catch {
+            // Preserve the original registration error.
           }
-        } else {
-          // Env config invalid — silently skip env vars.
+        }
+        await this.failPreparedServers(prepared, error);
+      } else {
+        // Pi 0.80 cannot roll back dynamic registration. Keep the successfully
+        // registered subset and its clients alive, and report the partial set
+        // truthfully instead of pretending it was removed.
+        const message = `${error instanceof Error ? error.message : String(error)}; ` +
+          "some MCP tools remain registered until Pi restarts";
+        for (const { entry, client, tools } of prepared) {
+          const toolNames = tools
+            .map((tool) => tool.name)
+            .filter((name) => registeredNames.includes(name))
+            .sort(compareCodeUnits);
+          entry.toolNames = toolNames;
+          entry.state = {
+            ...entry.state,
+            status: "error",
+            pid: client.pid,
+            toolCount: toolNames.length,
+            error: message,
+          };
+          this.emitEvent(UNIPI_EVENTS.MCP_SERVER_ERROR, {
+            name: entry.name,
+            error: message,
+          });
         }
       }
+      throw error;
+    }
 
-      // Create and connect client
-      const client = new McpClient({ timeoutMs: this.timeoutMs });
-      await client.connect(safeCommand, safeArgs, safeEnv);
-
-      entry.client = client;
-
-      // Discover tools
-      const mcpTools = await client.listTools();
-
-      // Translate and register tools
-      const toolNames: string[] = [];
-      for (const mcpTool of mcpTools) {
-        const piTool = translateMcpTool(mcpTool, name, client);
-        this.registerTool(piTool);
-        toolNames.push(piTool.name);
-      }
-
-      // Update state
+    // State and success events are published only after every registration
+    // succeeds. Server event order is deterministic as well.
+    for (const { entry, client, tools } of [...prepared].sort((left, right) =>
+      compareCodeUnits(left.entry.name, right.entry.name))) {
+      const toolNames = tools.map((tool) => tool.name).sort(compareCodeUnits);
+      entry.toolNames = toolNames;
       entry.state = {
-        ...state,
+        ...entry.state,
         status: "running",
         pid: client.pid,
         toolCount: toolNames.length,
       };
-      entry.toolNames = toolNames;
 
-      // Emit events
       this.emitEvent(UNIPI_EVENTS.MCP_SERVER_STARTED, {
-        name,
+        name: entry.name,
         toolCount: toolNames.length,
       });
-
       if (toolNames.length > 0) {
         this.emitEvent(UNIPI_EVENTS.MCP_TOOLS_REGISTERED, {
-          serverName: name,
+          serverName: entry.name,
           toolNames,
         });
       }
-    } catch (err) {
-      const error =
-        err instanceof Error ? err.message : String(err);
+    }
+  }
 
-      entry.state = {
-        ...state,
-        status: "error",
-        error,
-      };
+  private async prepareServer(resolved: ResolvedServer): Promise<PreparedServer> {
+    const { name, def } = resolved;
+    const state: ServerState = {
+      name,
+      status: "starting",
+      toolCount: 0,
+      startedAt: new Date().toISOString(),
+    };
+    const entry: McpRegistryEntry = {
+      name,
+      resolved,
+      state,
+      client: null,
+      toolNames: [],
+    };
+    this.entries.set(name, entry);
+
+    let client: RegistryClient | null = null;
+    try {
+      const safeCommand = typeof def.command === "string" ? def.command : String(def.command);
+      const safeArgs = Array.isArray(def.args) ? def.args : [];
+      let safeEnv: Record<string, string> | undefined;
+      if (def.env !== undefined && def.env !== null && typeof def.env === "object" && !Array.isArray(def.env)) {
+        safeEnv = {};
+        for (const [key, value] of Object.entries(def.env)) {
+          safeEnv[key] = typeof value === "string" ? value : String(value);
+        }
+      }
 
-      // Clean up client if partially connected
-      if (entry.client) {
+      client = this.createClient();
+      const connectedClient = client;
+      await connectedClient.connect(safeCommand, safeArgs, safeEnv);
+      entry.client = connectedClient;
+
+      const mcpTools = await connectedClient.listTools();
+      const tools = mcpTools
+        .map((tool) => translateMcpTool(tool, name, connectedClient))
+        .sort((left, right) => compareCodeUnits(left.name, right.name));
+      return { entry, client: connectedClient, tools };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      entry.state = { ...state, status: "error", error: message };
+      if (client) {
         try {
-          await (entry.client as McpClient).disconnect();
+          await client.disconnect();
         } catch {
-          // Ignore cleanup errors
+          // Ignore cleanup errors.
         }
-        entry.client = null;
       }
+      entry.client = null;
+      this.emitEvent(UNIPI_EVENTS.MCP_SERVER_ERROR, { name, error: message });
+      throw error;
+    }
+  }
 
-      this.emitEvent(UNIPI_EVENTS.MCP_SERVER_ERROR, {
-        name,
-        error,
-      });
-
-      throw err;
+  private assertUniqueFinalToolNames(newNames: string[]): void {
+    const existingNames = this.getActive().flatMap((state) =>
+      this.entries.get(state.name)?.toolNames ?? []);
+    const seen = new Set<string>();
+    const duplicates = new Set<string>();
+    for (const name of [...existingNames, ...newNames]) {
+      if (seen.has(name)) duplicates.add(name);
+      seen.add(name);
+    }
+    if (duplicates.size > 0) {
+      throw new Error(
+        `Duplicate final MCP tool name(s): ${[...duplicates].sort(compareCodeUnits).join(", ")}`,
+      );
     }
   }
 
-  /**
-   * Stop an MCP server: unregister tools, disconnect client.
-   */
+  private async failPreparedServers(prepared: PreparedServer[], error: unknown): Promise<void> {
+    const message = error instanceof Error ? error.message : String(error);
+    await Promise.all(prepared.map(async ({ entry, client }) => {
+      entry.state = { ...entry.state, status: "error", toolCount: 0, error: message };
+      entry.toolNames = [];
+      try {
+        await client.disconnect();
+      } catch {
+        // Ignore cleanup errors.
+      }
+      entry.client = null;
+      this.emitEvent(UNIPI_EVENTS.MCP_SERVER_ERROR, { name: entry.name, error: message });
+    }));
+  }
+
+  /** Stop an MCP server: unregister tools, disconnect client. */
   async stopServer(name: string): Promise<void> {
     const entry = this.entries.get(name);
     if (!entry) return;
 
-    // Unregister tools
+    if (entry.toolNames.length > 0 && !this.canUnregisterTools) {
+      throw new Error(
+        "This Pi version cannot remove MCP tools at runtime; restart Pi to change the MCP tool set.",
+      );
+    }
+
     for (const toolName of entry.toolNames) {
       this.unregisterTool(toolName);
     }
@@ -197,101 +322,83 @@ export class ServerRegistry {
       });
     }
 
-    // Disconnect client
     if (entry.client) {
       try {
-        await (entry.client as McpClient).disconnect();
+        await (entry.client as RegistryClient).disconnect();
       } catch {
-        // Ignore disconnect errors
+        // Ignore disconnect errors.
       }
       entry.client = null;
     }
 
-    // Update state
-    entry.state = {
-      ...entry.state,
-      status: "stopped",
-      toolCount: 0,
-    };
+    entry.state = { ...entry.state, status: "stopped", toolCount: 0 };
     entry.toolNames = [];
-
     this.emitEvent(UNIPI_EVENTS.MCP_SERVER_STOPPED, { name });
   }
 
-  /**
-   * Restart an MCP server: stop then start.
-   */
+  /** Restart an MCP server: stop then start. */
   async restartServer(name: string): Promise<void> {
     const entry = this.entries.get(name);
-    if (!entry) {
-      throw new Error(`Server '${name}' not found in registry`);
-    }
-
+    if (!entry) throw new Error(`Server '${name}' not found in registry`);
     const resolved = entry.resolved;
     await this.stopServer(name);
     await this.startServer(resolved);
   }
 
-  /**
-   * Stop all running servers.
-   */
+  /** Stop all running servers when runtime unregistration is supported. */
   async stopAll(): Promise<void> {
     const names = Array.from(this.entries.keys());
     await Promise.allSettled(names.map((name) => this.stopServer(name)));
   }
 
-  /**
-   * Get all registered server states.
-   */
+  /** Disconnect clients during extension shutdown without claiming tools were removed. */
+  async disconnectAll(): Promise<void> {
+    await Promise.allSettled([...this.entries.values()].map(async (entry) => {
+      if (!entry.client) return;
+      try {
+        await (entry.client as RegistryClient).disconnect();
+      } finally {
+        entry.client = null;
+      }
+    }));
+  }
+
+  /** Get all registered server states. */
   getAll(): ServerState[] {
-    return Array.from(this.entries.values()).map((e) => e.state);
+    return Array.from(this.entries.values()).map((entry) => entry.state);
   }
 
-  /**
-   * Get states of running servers.
-   */
+  /** Get states of running servers. */
   getActive(): ServerState[] {
-    return this.getAll().filter((s) => s.status === "running");
+    return this.getAll().filter((state) => state.status === "running");
   }
 
-  /**
-   * Get states of servers in error state.
-   */
+  /** Get states of servers in error state. */
   getFailed(): ServerState[] {
-    return this.getAll().filter((s) => s.status === "error");
+    return this.getAll().filter((state) => state.status === "error");
   }
 
-  /**
-   * Get total number of tools across all active servers.
-   */
+  /** Get total number of tools across all active servers. */
   getTotalToolCount(): number {
-    return this.getActive().reduce((sum, s) => sum + s.toolCount, 0);
+    return this.getActive().reduce((sum, state) => sum + state.toolCount, 0);
   }
 
-  /**
-   * Get the state of a specific server.
-   */
+  /** Get the state of a specific server. */
   getServerState(name: string): ServerState | null {
     return this.entries.get(name)?.state ?? null;
   }
 
-  /**
-   * Get the full registry entry for a server.
-   */
+  /** Get the full registry entry for a server. */
   getEntry(name: string): McpRegistryEntry | null {
     return this.entries.get(name) ?? null;
   }
 
-  /**
-   * Check if a server exists in the registry.
-   */
+  /** Check if a server exists in the registry. */
   hasServer(name: string): boolean {
     return this.entries.has(name);
   }
 
-  /**
-   * Get the number of registered servers.
-   */
+  /** Get the number of registered servers. */
   get size(): number {
     return this.entries.size;
   }

package/src/bridge/translator.ts

@@ -5,15 +5,19 @@
  * Naming convention: {serverName}__{toolName}
  */
 
-import { MCP_DEFAULTS } from "@pi-unipi/core";
+import { MCP_DEFAULTS, boundModelOutput } from "@pi-unipi/core";
 import type { McpTool, McpToolResult } from "../types.js";
 import type { McpClient } from "./client.js";
 
-/** Pi-compatible tool parameter schema */
+/** Client operation needed by translated tools. */
+export type ToolCallClient = Pick<McpClient, "callTool">;
+
+/** JSON object used as a Pi-compatible tool parameter schema. */
 interface ToolParameters {
+  [key: string]: unknown;
   type: "object";
   properties: Record<string, unknown>;
-  required?: string[];
+  required: unknown;
 }
 
 /** Content block returned by a pi tool */
@@ -31,6 +35,7 @@ interface PiToolResult {
 /** Pi-compatible external tool */
 export interface PiExternalTool {
   name: string;
+  label: string;
   description: string;
   parameters: ToolParameters;
   execute: (
@@ -41,6 +46,66 @@ export interface PiExternalTool {
   ) => Promise<PiToolResult>;
 }
 
+/**
+ * Compare strings by JavaScript/Unicode UTF-16 code units.
+ *
+ * Unlike localeCompare(), this ordering does not depend on the host locale.
+ */
+export function compareCodeUnits(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+const LITERAL_VALUE_KEYWORDS = new Set(["const", "default", "enum", "examples"]);
+
+function canonicalizeValue(
+  value: unknown,
+  key?: string,
+  normalizeSchemaKeywords = true,
+): unknown {
+  if (Array.isArray(value)) {
+    if (
+      normalizeSchemaKeywords &&
+      key === "required" &&
+      value.every((item) => typeof item === "string")
+    ) {
+      return [...new Set(value as string[])].sort(compareCodeUnits);
+    }
+    return value.map((item) => canonicalizeValue(item, undefined, normalizeSchemaKeywords));
+  }
+
+  if (!isObject(value)) return value;
+
+  const canonical: Record<string, unknown> = {};
+  for (const objectKey of Object.keys(value).sort(compareCodeUnits)) {
+    // Values under these JSON Schema keywords are literal application data,
+    // not nested schemas. A property named `required` inside that data must
+    // retain array order (for example under `const`).
+    const childNormalizesSchemaKeywords =
+      normalizeSchemaKeywords && !LITERAL_VALUE_KEYWORDS.has(objectKey);
+    canonical[objectKey] = canonicalizeValue(
+      value[objectKey],
+      objectKey,
+      childNormalizesSchemaKeywords,
+    );
+  }
+  return canonical;
+}
+
+/**
+ * Recursively clone and canonicalize a JSON Schema value.
+ *
+ * Object keys use locale-independent code-unit order. Arrays retain their
+ * original order, except valid `required` arrays (arrays containing only
+ * strings), which are sorted and deduplicated.
+ */
+export function canonicalizeJsonSchema(schema: unknown): unknown {
+  return canonicalizeValue(schema);
+}
+
 /**
  * Translate an MCP tool definition to a pi-compatible external tool.
  *
@@ -52,19 +117,21 @@ export interface PiExternalTool {
 export function translateMcpTool(
   mcpTool: McpTool,
   serverName: string,
-  client: McpClient,
+  client: ToolCallClient,
 ): PiExternalTool {
   const separator = MCP_DEFAULTS.TOOL_NAME_SEPARATOR;
   const toolName = `${serverName}${separator}${mcpTool.name}`;
 
-  // Ensure inputSchema is a valid JSON Schema object
-  const inputSchema = mcpTool.inputSchema ?? {};
-  const parameters: ToolParameters = {
+  // Preserve the existing Pi-facing top-level shape while cloning and
+  // canonicalizing all nested property schemas. Forwarding additional MCP
+  // top-level keywords is a separate provider-compatibility decision.
+  const inputSchema = isObject(mcpTool.inputSchema) ? mcpTool.inputSchema : {};
+  const normalizedSchema: Record<string, unknown> = {
     type: "object",
-    properties:
-      (inputSchema.properties as Record<string, unknown>) ?? {},
-    required: inputSchema.required as string[] | undefined,
+    properties: isObject(inputSchema.properties) ? inputSchema.properties : {},
+    required: Array.isArray(inputSchema.required) ? inputSchema.required : [],
   };
+  const parameters = canonicalizeJsonSchema(normalizedSchema) as ToolParameters;
 
   const description = [
     mcpTool.description || `MCP tool: ${mcpTool.name}`,
@@ -103,21 +170,28 @@ export function translateMcpTool(
         }
       }
 
-      if (result.isError) {
-        const errorText = blocks.map((b) => b.text).join("\n") || "Unknown error";
-        return {
-          content: [{ type: "text", text: `MCP tool error from ${serverName}: ${errorText}` }],
-          details: { error: true, server: serverName, tool: mcpTool.name },
-        };
-      }
-
       if (blocks.length === 0) {
-        blocks.push({ type: "text", text: "(no output)" });
+        blocks.push({ type: "text", text: result.isError ? "Unknown error" : "(no output)" });
       }
 
+      const rawText = blocks.map((block) => block.text).join("\n");
+      const wrapper = result.isError ? `MCP tool error from ${serverName}: ` : "";
+      const output = boundModelOutput(rawText, {
+        maxBytes: Math.max(1024, MCP_DEFAULTS.MAX_MODEL_OUTPUT_BYTES - Buffer.byteLength(wrapper, "utf8")),
+        artifactPrefix: `mcp-${serverName}-${mcpTool.name}`,
+      });
+      const visibleText = `${wrapper}${output.text}`;
+
       return {
-        content: blocks,
-        details: { server: serverName, tool: mcpTool.name },
+        content: [{ type: "text", text: visibleText }],
+        details: {
+          error: result.isError || undefined,
+          server: serverName,
+          tool: mcpTool.name,
+          truncated: output.truncated,
+          originalBytes: output.originalBytes,
+          artifactPath: output.artifactPath,
+        },
       };
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
@@ -137,6 +211,7 @@ export function translateMcpTool(
 
   return {
     name: toolName,
+    label: toolName,
     description,
     parameters,
     execute,

package/src/index.ts

@@ -18,6 +18,7 @@ import type { ResolvedServer } from "./types.js";
 import { loadAndResolve, getGlobalConfigDir } from "./config/manager.js";
 import { syncCatalog, loadCatalog } from "./config/sync.js";
 import { ServerRegistry } from "./bridge/registry.js";
+import { compareCodeUnits } from "./bridge/translator.js";
 import { renderMcpAddOverlay } from "./tui/add-overlay.js";
 import { renderMcpSettingsOverlay } from "./tui/settings-overlay.js";
 
@@ -42,24 +43,32 @@ export default function (pi: ExtensionAPI) {
   // Session start — load configs, start servers
   pi.on("session_start", async (_event, ctx) => {
     // Create registry with pi integration callbacks
+    const toolApi = pi as ExtensionAPI & {
+      registerExternalTool?: (tool: unknown) => void;
+      unregisterTool?: (toolName: string) => void;
+      unregisterExternalTool?: (toolName: string) => void;
+    };
+    const registerTool = typeof toolApi.registerTool === "function"
+      ? (tool: unknown) => toolApi.registerTool(tool as Parameters<typeof toolApi.registerTool>[0])
+      : typeof toolApi.registerExternalTool === "function"
+        ? (tool: unknown) => toolApi.registerExternalTool!(tool)
+        : () => {
+            throw new Error("Pi does not expose a supported MCP tool registration API");
+          };
+    const canUnregisterTools =
+      typeof toolApi.unregisterTool === "function" ||
+      typeof toolApi.unregisterExternalTool === "function";
+    const unregisterTool = typeof toolApi.unregisterTool === "function"
+      ? (toolName: string) => toolApi.unregisterTool!(toolName)
+      : typeof toolApi.unregisterExternalTool === "function"
+        ? (toolName: string) => toolApi.unregisterExternalTool!(toolName)
+        : () => {};
+
     registry = new ServerRegistry({
       emitEvent: (event, payload) => emitEvent(pi, event, payload),
-      registerTool: (tool) => {
-        try {
-          (pi as any).registerTool?.(tool) ??
-            (pi as any).registerExternalTool?.(tool);
-        } catch {
-          // Tool registration may not be available in all contexts
-        }
-      },
-      unregisterTool: (toolName) => {
-        try {
-          (pi as any).unregisterTool?.(toolName) ??
-            (pi as any).unregisterExternalTool?.(toolName);
-        } catch {
-          // Ignore
-        }
-      },
+      registerTool,
+      unregisterTool,
+      canUnregisterTools,
     });
 
     // Load and resolve server configs
@@ -73,21 +82,13 @@ export default function (pi: ExtensionAPI) {
       // Config load failure — servers will be empty, visible via /unipi:mcp-status.
     }
 
-    // Start enabled servers (parallel, non-blocking errors)
-    const startPromises = servers
-      .filter((s) => s.enabled)
-      .map(async (server) => {
-        try {
-          await registry!.startServer(server);
-          // Removed console.log — startup logs cause layout shift in TUI.
-          // Server status visible via /unipi:mcp-status or info screen.
-        } catch (err) {
-          // Removed console.error — errors surfaced via info-screen MCP group.
-          // Server failure tracked in registry state.
-        }
-      });
-
-    await Promise.allSettled(startPromises);
+    // Connect/discover in parallel, then register the successful combined set
+    // after a barrier so tool order is stable across runs.
+    try {
+      await registry.startServers(servers.filter((server) => server.enabled));
+    } catch (_err) {
+      // Errors are tracked in registry state and surfaced by the info screen.
+    }
 
     // Register info-screen group
     const infoRegistry = getInfoRegistry();
@@ -153,16 +154,17 @@ export default function (pi: ExtensionAPI) {
         `unipi:${MCP_COMMANDS.STATUS}`,
         `unipi:${MCP_COMMANDS.RELOAD}`,
       ],
-      tools: activeServers.flatMap((s) =>
-        registry?.getEntry(s.name)?.toolNames ?? [],
-      ),
+      tools: activeServers
+        .flatMap((server) => registry?.getEntry(server.name)?.toolNames ?? [])
+        .sort(compareCodeUnits),
     });
   });
 
-  // Session shutdown — stop all servers
+  // Session shutdown tears down clients. Pi tears down this extension's tool
+  // registry itself, so do not claim per-tool unregistration here.
   pi.on("session_shutdown", async (_event, _ctx) => {
     if (registry) {
-      await registry.stopAll();
+      await registry.disconnectAll();
       registry = null;
     }
   });
@@ -305,38 +307,12 @@ export default function (pi: ExtensionAPI) {
 
   // /unipi:mcp-reload — restart all MCP servers
   pi.registerCommand(`unipi:${MCP_COMMANDS.RELOAD}`, {
-    description: "Reload all MCP servers (restart with current config)",
+    description: "Explain how to reload MCP servers safely",
     handler: async (_args: string, ctx: ExtensionCommandContext) => {
-      const reg = getRegistry();
-      if (!reg) {
-        ctx.ui.notify("MCP extension not initialized", "warning");
-        return;
-      }
-
-      const all = reg.getAll();
-      if (all.length === 0) {
-        ctx.ui.notify("No MCP servers configured. Use /unipi:mcp-add to add one.", "info");
-        return;
-      }
-
-      ctx.ui.notify(`Reloading ${all.length} MCP server(s)...`, "info");
-
-      let restarted = 0;
-      let failed = 0;
-      for (const state of all) {
-        try {
-          await reg.restartServer(state.name);
-          restarted++;
-        } catch (_err) {
-          failed++;
-          // Silently ignore — restart failure tracked in failed count.
-        }
-      }
-
-      const msg = failed > 0
-        ? `Reloaded: ${restarted} ok, ${failed} failed`
-        : `Reloaded ${restarted} MCP server(s) successfully`;
-      ctx.ui.notify(msg, failed > 0 ? "warning" : "info");
+      // Pi 0.80 does not expose dynamic tool removal. Restarting in place can
+      // leave stale schemas in the provider-visible tool list, so require a
+      // process/extension restart to establish a clean cache epoch.
+      ctx.ui.notify("Restart Pi to reload MCP servers and tool schemas safely.", "info");
     },
   });
 }

package/src/tui/settings-overlay.ts

@@ -141,15 +141,9 @@ export function renderMcpSettingsOverlay(params?: {
         };
         saveMetadata(configDir, meta);
 
-        // Try to stop if disabling
-        if (!newEnabled && registry) {
-          try {
-            await registry.stopServer(server.name);
-          } catch {
-            // Ignore stop errors
-          }
-        }
-
+        // Pi 0.80 cannot remove a registered tool definition at runtime.
+        // Persist the setting now; the next Pi restart applies the new set as
+        // one deterministic cache epoch.
         refreshServers();
         refresh();
       } catch (err) {