pi-mcp-adapter 2.2.0 → 2.2.2

package/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.2.2] - 2026-04-03
+
+### Fixed
+- Session lifecycle teardown now handles repeated `session_start` transitions safely and prevents stale async init results from replacing newer state.
+- Shutdown now still runs `gracefulShutdown()` even if metadata cache flushing throws, avoiding leaked MCP processes.
+- Proxy/direct tool init error paths now preserve and surface underlying error messages instead of returning generic failures.
+- Invalid `mcp` tool `args` now fail by throwing with parse/type context instead of returning non-failing tool payloads.
+- Added focused lifecycle regressions tests for stale init cleanup and init-error visibility.
+
+## [2.2.1] - 2026-03-23
+
+### Fixed
+- Added `promptSnippet` to MCP proxy tool and direct MCP tools so they appear in the system prompt's Available tools section (required since pi 0.59.0)
+
 ## [2.2.0] - 2026-03-16
 
 ### Added

package/direct-tools.ts

@@ -181,10 +181,11 @@ export function createDirectToolExecutor(
     if (!state && initPromise) {
       try {
         state = await initPromise;
-      } catch {
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
         return {
-          content: [{ type: "text" as const, text: "MCP initialization failed" }],
-          details: { error: "init_failed" },
+          content: [{ type: "text" as const, text: `MCP initialization failed: ${message}` }],
+          details: { error: "init_failed", message },
         };
       }
     }

package/index.ts

@@ -1,4 +1,4 @@
-import type { ExtensionAPI, ExtensionContext, ToolInfo } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI, ToolInfo } from "@mariozechner/pi-coding-agent";
 import type { McpExtensionState } from "./state.js";
 import { Type } from "@sinclair/typebox";
 import { showStatus, showTools, reconnectServers, authenticateServer, openMcpPanel } from "./commands.js";
@@ -7,11 +7,42 @@ import { buildProxyDescription, createDirectToolExecutor, resolveDirectTools } f
 import { flushMetadataCache, initializeMcp, updateStatusBar } from "./init.js";
 import { loadMetadataCache } from "./metadata-cache.js";
 import { executeCall, executeConnect, executeDescribe, executeList, executeSearch, executeStatus, executeUiMessages } from "./proxy-modes.js";
-import { getConfigPathFromArgv } from "./utils.js";
+import { getConfigPathFromArgv, truncateAtWord } from "./utils.js";
 
 export default function mcpAdapter(pi: ExtensionAPI) {
   let state: McpExtensionState | null = null;
   let initPromise: Promise<McpExtensionState> | null = null;
+  let lifecycleGeneration = 0;
+
+  async function shutdownState(currentState: McpExtensionState | null, reason: string): Promise<void> {
+    if (!currentState) return;
+
+    if (currentState.uiServer) {
+      currentState.uiServer.close(reason);
+      currentState.uiServer = null;
+    }
+
+    let flushError: unknown;
+    try {
+      flushMetadataCache(currentState);
+    } catch (error) {
+      flushError = error;
+    }
+
+    try {
+      await currentState.lifecycle.gracefulShutdown();
+    } catch (error) {
+      if (flushError) {
+        console.error("MCP: graceful shutdown failed after metadata flush error", error);
+      } else {
+        throw error;
+      }
+    }
+
+    if (flushError) {
+      throw flushError;
+    }
+  }
 
   const earlyConfigPath = getConfigPathFromArgv();
   const earlyConfig = loadMcpConfig(earlyConfigPath);
@@ -33,6 +64,7 @@ export default function mcpAdapter(pi: ExtensionAPI) {
       name: spec.prefixedName,
       label: `MCP: ${spec.originalName}`,
       description: spec.description || "(no description)",
+      promptSnippet: truncateAtWord(spec.description, 100) || `MCP tool from ${spec.serverName}`,
       parameters: Type.Unsafe<Record<string, unknown>>(spec.inputSchema || { type: "object", properties: {} }),
       execute: createDirectToolExecutor(() => state, () => initPromise, spec),
     });
@@ -46,35 +78,59 @@ export default function mcpAdapter(pi: ExtensionAPI) {
   });
 
   pi.on("session_start", async (_event, ctx) => {
-    initPromise = initializeMcp(pi, ctx);
+    const generation = ++lifecycleGeneration;
+    const previousState = state;
+    state = null;
+    initPromise = null;
+
+    try {
+      await shutdownState(previousState, "session_restart");
+    } catch (error) {
+      console.error("MCP: failed to shut down previous session state", error);
+    }
+
+    if (generation !== lifecycleGeneration) {
+      return;
+    }
+
+    const promise = initializeMcp(pi, ctx);
+    initPromise = promise;
 
-    initPromise.then(s => {
-      state = s;
+    promise.then(async (nextState) => {
+      if (generation !== lifecycleGeneration || initPromise !== promise) {
+        try {
+          await shutdownState(nextState, "stale_session_start");
+        } catch (error) {
+          console.error("MCP: failed to clean stale session state", error);
+        }
+        return;
+      }
+
+      state = nextState;
+      updateStatusBar(nextState);
       initPromise = null;
-      updateStatusBar(s);
     }).catch(err => {
+      if (generation !== lifecycleGeneration) {
+        return;
+      }
+      if (initPromise !== promise && initPromise !== null) {
+        return;
+      }
       console.error("MCP initialization failed:", err);
       initPromise = null;
     });
   });
 
   pi.on("session_shutdown", async () => {
-    if (initPromise) {
-      try {
-        state = await initPromise;
-      } catch {
-        // Initialization failed, nothing to clean up
-      }
-    }
+    ++lifecycleGeneration;
+    const currentState = state;
+    state = null;
+    initPromise = null;
 
-    if (state) {
-      if (state.uiServer) {
-        state.uiServer.close("session_shutdown");
-        state.uiServer = null;
-      }
-      flushMetadataCache(state);
-      await state.lifecycle.gracefulShutdown();
-      state = null;
+    try {
+      await shutdownState(currentState, "session_shutdown");
+    } catch (error) {
+      console.error("MCP: session shutdown cleanup failed", error);
     }
   });
 
@@ -84,8 +140,9 @@ export default function mcpAdapter(pi: ExtensionAPI) {
       if (!state && initPromise) {
         try {
           state = await initPromise;
-        } catch {
-          if (ctx.hasUI) ctx.ui.notify("MCP initialization failed", "error");
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          if (ctx.hasUI) ctx.ui.notify(`MCP initialization failed: ${message}`, "error");
           return;
         }
       }
@@ -130,8 +187,9 @@ export default function mcpAdapter(pi: ExtensionAPI) {
       if (!state && initPromise) {
         try {
           state = await initPromise;
-        } catch {
-          if (ctx.hasUI) ctx.ui.notify("MCP initialization failed", "error");
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          if (ctx.hasUI) ctx.ui.notify(`MCP initialization failed: ${message}`, "error");
           return;
         }
       }
@@ -148,6 +206,7 @@ export default function mcpAdapter(pi: ExtensionAPI) {
     name: "mcp",
     label: "MCP",
     description: buildProxyDescription(earlyConfig, earlyCache, directSpecs),
+    promptSnippet: "MCP gateway - connect to MCP servers and call their tools",
     parameters: Type.Object({
       tool: Type.Optional(Type.String({ description: "Tool name to call (e.g., 'xcodebuild_list_sims')" })),
       args: Type.Optional(Type.String({ description: "Arguments as JSON string (e.g., '{\"key\": \"value\"}')" })),
@@ -176,28 +235,24 @@ export default function mcpAdapter(pi: ExtensionAPI) {
           parsedArgs = JSON.parse(params.args);
           if (typeof parsedArgs !== "object" || parsedArgs === null || Array.isArray(parsedArgs)) {
             const gotType = Array.isArray(parsedArgs) ? "array" : parsedArgs === null ? "null" : typeof parsedArgs;
-            return {
-              content: [{ type: "text" as const, text: `Invalid args: expected a JSON object, got ${gotType}` }],
-              isError: true,
-              details: { error: "invalid_args_type" },
-            };
+            throw new Error(`Invalid args: expected a JSON object, got ${gotType}`);
           }
-        } catch (e) {
-          return {
-            content: [{ type: "text" as const, text: `Invalid args JSON: ${e instanceof Error ? e.message : e}` }],
-            isError: true,
-            details: { error: "invalid_args" },
-          };
+        } catch (error) {
+          if (error instanceof SyntaxError) {
+            throw new Error(`Invalid args JSON: ${error.message}`, { cause: error });
+          }
+          throw error;
         }
       }
 
       if (!state && initPromise) {
         try {
           state = await initPromise;
-        } catch {
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
           return {
-            content: [{ type: "text" as const, text: "MCP initialization failed" }],
-            details: { error: "init_failed" },
+            content: [{ type: "text" as const, text: `MCP initialization failed: ${message}` }],
+            details: { error: "init_failed", message },
           };
         }
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mcp-adapter",
-  "version": "2.2.0",
+  "version": "2.2.2",
   "description": "MCP (Model Context Protocol) adapter extension for Pi coding agent",
   "type": "module",
   "license": "MIT",