pi-mcp-adapter 2.22.0 → 2.24.0

package/CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.24.0] - 2026-08-13
+
+### Added
+- Added per-server `searchKeywords` so `mcp({ search })` and `mcpScript` `tools.search` understand user-defined synonyms and aliases for tools. Keywords are keyed by tool name or glob and boost ranked and regex search only. They never appear in tool schemas, describe output, or the metadata cache. Thanks @Serisium for PR #336.
+
+### Fixed
+- Interpolated environment placeholders in stdio server arguments. Thanks @vjik for issue #333.
+- Kept remote `/mcp-auth` authorization links reachable before the callback input opens. Thanks @trevorleibert-mixpanel for PR #331.
+- Cached OAuth credentials in memory and refreshed them after OAuth-backed 401 responses. Thanks @daniel-sampliner for PR #335.
+- Sanitized MCP server-name prefixes for provider-safe tool names while preserving server resolution. Thanks @triple-dex for issue #334.
+- Validated persisted npx resolver cache entries before reuse, including malformed and prototype-sensitive persisted keys.
+
+## [2.23.0] - 2026-08-11
+
+### Added
+- Added interactive callback URL pasting to `/mcp-auth` for OAuth flows running on remote or headless machines. Thanks @trevorleibert-mixpanel for PR #330.
+
+### Fixed
+- Stopped load-time MCP initialization from printing a TUI startup error when Pi action methods are not bound yet. Thanks @21307369 for issue #327.
+- Kept interactive OAuth authorization URLs clickable as a single terminal hyperlink. Thanks @rfccg for PR #329.
+
 ## [2.22.0] - 2026-08-11
 
 ### Added

package/README.md

@@ -227,6 +227,7 @@ In the configuration examples below, `30000` is illustrative only. If `requestTi
 | `toolPrefix` | Override global `settings.toolPrefix` for this server (`"server"`, `"short"`, `"none"`, or `"mcp"`) |
 | `includeTools` | `string[]` of tool names or glob patterns to expose (matches original names like `get_screenshot`, generated resource names like `read_figjam`, and prefixed names like `figma_get_screenshot`) |
 | `excludeTools` | `string[]` of tool names or glob patterns to hide (applied after `includeTools`) |
+| `searchKeywords` | `{ "tool-or-glob": ["keyword", ...] }` — extra keywords that boost `mcp({ search })` ranking for matching tools; never shown to the model |
 | `debug` | Show server stderr (default: false) |
 | `trace` | Enable metadata-only JSONL protocol tracing for this server; payloads, prompts, tool arguments/results, authorization data, and URLs are never persisted |
 | `disabled` | Keep the server visible in config and status, but prevent connections, authentication, tools, and resource calls (only literal `true` disables it) |
@@ -265,7 +266,9 @@ The adapter owns only its client socket and closes that connection when the Pi r
 
 ### Remote/headless OAuth
 
-If Pi is running on a remote server and cannot open a local browser, start OAuth through the proxy tool. Persistent OAuth still requires an available OS credential store; on headless Linux that usually means an unlocked Secret Service/libsecret keyring. The adapter fails closed instead of falling back to plaintext credentials when the secure store is unavailable.
+If Pi is running on a remote server, `/mcp-auth <server>` shows a clickable authorization URL first. Open it in your local browser and approve access, then select **Yes** in Pi to open the callback input. The browser may fail to load the localhost callback page because localhost refers to your workstation; copy the full URL from its address bar and paste it into Pi. The authorization screen closes automatically instead when the browser can reach Pi's callback directly.
+
+The same flow is available through the proxy tool for non-interactive clients. Persistent OAuth still requires an available OS credential store; on headless Linux that usually means an unlocked Secret Service/libsecret keyring. The adapter fails closed instead of falling back to plaintext credentials when the secure store is unavailable.
 
 On Linux, if credential access fails because Pi inherited a revoked session keyring, the adapter uses a best-effort recovery path through `keyctl session - node <packaged helper>` so explicit re-authentication can write fresh credentials without killing a long-lived tmux server. This path requires `keyctl` and `node` on `PATH`; missing, locked, or otherwise unavailable credential stores still fail closed.
 
@@ -648,10 +651,33 @@ Prefer `.mcp.json` for project-local shared MCP config. Use `.pi/mcp.json` only
 
 MCP proxy and direct-tool results render compactly by default: long text shows the first three terminal-wrapped lines plus a `Ctrl+O to expand` hint, while the full result remains available when expanded and is still returned unchanged to the model.
 
-Search includes both MCP tools and Pi tools (from extensions). Pi tools appear first with `[pi tool]` prefix. Space-separated words are ranked by weighted matches across name, server, and description, then returned one page at a time (`limit` defaults to 12). Use `details.nextOffset` for the next page. Regex search is still available with `regex: true`, but regex results are paginated without ranking.
+Search includes both MCP tools and Pi tools (from extensions). Pi tools appear first with `[pi tool]` prefix. Space-separated words are ranked by weighted matches across name, server, description, and any configured `searchKeywords`, then returned one page at a time (`limit` defaults to 12). Use `details.nextOffset` for the next page. Regex search is still available with `regex: true`, but regex results are paginated without ranking.
 
 Tool names are fuzzy-matched on hyphens and underscores — `context7_resolve_library_id` finds `context7_resolve-library-id`. When `describe` or `tool` cannot resolve a name, the result includes top suggestions so the agent can correct a typo or missing prefix in the same turn.
 
+### Search keywords
+
+Search uses literal matching so a tool whose name and description use different vocabulary than the query won't be found. Per-server `searchKeywords` adds extra vocabulary for matching tools:
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "searchKeywords": {
+        "search_code": ["grep"],
+        "*": ["gh"]
+      }
+    }
+  }
+}
+```
+
+With this config, `mcp({ search: "grep" })` finds `github_search_code` even though neither its name nor description contains that word. Similarly, `mcp({ search: "gh" })` finds all tools provided by the github server.
+
+Keys match a tool's original name, prefixed name, or a glob (`*` applies to every tool on the server) and all matching entries combine. Keywords are weighted like description text, with an extra boost when the query exactly matches a configured phrase. They affect ranked and regex search only (including `tools.search` in `mcpScript`): they never appear in tool schemas, `describe` output, direct-tool registration, or the metadata cache, and search with keywords works offline from cached metadata.
+
 When `includeSchemas` is enabled, search and describe render common JSON Schema parameters as compact TypeScript shapes like `{ query: string; limit?: number; }`, with the older schema formatter retained as a fallback for unsupported schemas.
 
 For HTTP servers, failed connects run a one-request shape probe that can turn opaque transport errors into setup hints such as `endpoint returned HTML (200) — this URL does not appear to speak MCP`. Healthy connections are not probed.

package/commands.ts

@@ -25,6 +25,10 @@ import { loadOnboardingState, markSetupCompleted as persistSetupCompleted, markS
 import { openPath, resolveServerUrl, sanitizeTerminalText } from "./utils.ts";
 import { isAbortError } from "./runtime-owner.ts";
 
+function terminalHyperlink(label: string, url: string): string {
+  return `\u001B]8;;${sanitizeTerminalText(url)}\u001B\\${sanitizeTerminalText(label)}\u001B]8;;\u001B\\`;
+}
+
 export async function showStatus(state: McpExtensionState, ctx: ExtensionContext): Promise<void> {
   if (!ctx.hasUI) return;
 
@@ -273,11 +277,26 @@ export async function authenticateServer(
       ...(authStorageOptions.baseDir ? { authStorageOptions } : {}),
       onAuthorizationUrl: (authorizationUrl) => {
         ui.notify(
-          `Open this URL to authenticate ${serverName}:\n\n${authorizationUrl}\n\n` +
-          "After approving, return to Pi; the local callback will complete automatically.",
+          `Open this URL to authenticate ${serverName}:\n\n${terminalHyperlink(authorizationUrl, authorizationUrl)}\n\n` +
+          "After approving, Pi will complete automatically if the browser can reach its localhost callback. " +
+          "On a remote machine, copy the full localhost URL from the browser address bar and paste it into Pi.",
           "info"
         );
       },
+      onAuthorizationInput: async (authorizationUrl, inputSignal) => {
+        const readyToPaste = await ui.confirm(
+          `Authorize ${serverName}`,
+          `Open this link in your browser:\n${terminalHyperlink(authorizationUrl, authorizationUrl)}\n\n` +
+          "After approving access, select Yes to paste the callback URL.",
+          { signal: inputSignal },
+        );
+        if (!readyToPaste || inputSignal.aborted) return undefined;
+        return ui.input(
+          `Complete ${serverName} OAuth`,
+          "Paste the full callback URL",
+          { signal: inputSignal },
+        );
+      },
       ...(signal ? { signal } : {}),
       ...(runtime ? { runtime } : {}),
     });

package/index.ts

@@ -169,13 +169,23 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
     return resolveDirectTools(config, cache, prefix, envDirectToolOverride);
   }
 
+  function getActiveToolsIfReady(): string[] | undefined {
+    try {
+      return pi.getActiveTools?.();
+    } catch (error) {
+      if (error instanceof Error
+        && error.message.includes("Action methods cannot be called during extension loading")) return undefined;
+      throw error;
+    }
+  }
+
   function deactivateTools(toolNames: string[]): string[] {
     if (toolNames.length === 0) return [];
     const unregisterTool = (pi as ExtensionAPI & { unregisterTool?: (name: string) => boolean }).unregisterTool;
     const unregistered = toolNames.filter((toolName) => unregisterTool?.(toolName) === true);
     const fallbackNames = toolNames.filter((toolName) => !unregistered.includes(toolName));
     const remove = new Set(toolNames);
-    const activeTools = pi.getActiveTools?.();
+    const activeTools = getActiveToolsIfReady();
     if (!activeTools || activeTools.length === 0) {
       for (const toolName of fallbackNames) fallbackDeactivatedTools.add(toolName);
       return unregistered;
@@ -207,7 +217,7 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
         registerDirectTool(spec);
         registeredDirectTools.set(spec.prefixedName, fingerprint);
         if (fallbackDeactivatedTools.delete(spec.prefixedName)) {
-          const activeTools = pi.getActiveTools?.();
+          const activeTools = getActiveToolsIfReady();
           if (activeTools && !activeTools.includes(spec.prefixedName)) {
             pi.setActiveTools([...activeTools, spec.prefixedName]);
           }
@@ -849,7 +859,7 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
         registerProxyTool(description);
         return;
       }
-      const activeTools = pi.getActiveTools?.();
+      const activeTools = getActiveToolsIfReady();
       if (activeTools && !activeTools.includes("mcp")) {
         pi.setActiveTools([...activeTools, "mcp"]);
       }

package/mcp-auth-flow.ts

@@ -49,6 +49,10 @@ export interface McpOAuthRuntime {
 
 export interface AuthenticateOptions {
   onAuthorizationUrl?: (authorizationUrl: string) => void | Promise<void>
+  onAuthorizationInput?: (
+    authorizationUrl: string,
+    signal: AbortSignal,
+  ) => Promise<string | undefined>
   authStorageOptions?: AuthStorageOptions
   signal?: AbortSignal
   runtime?: McpOAuthRuntime
@@ -568,6 +572,53 @@ export function parseAuthorizationCodeInput(input: string, expectedState?: strin
   return parseAuthorizationRedirectInput(input, expectedState).code
 }
 
+type AuthorizationResponse = {
+  input: AuthorizationCodeInput
+  source: "callback" | "manual"
+}
+
+/**
+ * Wait for either the localhost callback or a manually pasted redirect URL.
+ * The manual input prompt is dismissed as soon as either path finishes.
+ */
+export async function waitForAuthorizationResponse(
+  callbackPromise: Promise<AuthorizationCodeInput>,
+  authorizationUrl: string,
+  expectedState: string,
+  onAuthorizationInput?: AuthenticateOptions["onAuthorizationInput"],
+  signal?: AbortSignal,
+): Promise<AuthorizationResponse> {
+  if (!onAuthorizationInput) {
+    return {
+      input: await abortable(callbackPromise, signal),
+      source: "callback",
+    }
+  }
+
+  const inputController = new AbortController()
+  try {
+    const response = await abortable(Promise.race([
+      callbackPromise.then((input) => ({ input, source: "callback" as const })),
+      onAuthorizationInput(authorizationUrl, inputController.signal).then((input) => ({
+        input,
+        source: "manual" as const,
+      })),
+    ]), signal)
+
+    if (response.source === "callback") return response
+    if (!response.input?.trim()) throw new Error("OAuth authentication cancelled")
+    if (!getSearchParamsFromInput(response.input.trim())) {
+      throw new Error("Paste the full OAuth callback URL, including its code and state parameters")
+    }
+    return {
+      input: parseAuthorizationRedirectInput(response.input, expectedState),
+      source: "manual",
+    }
+  } finally {
+    inputController.abort()
+  }
+}
+
 /**
  * Complete OAuth authentication from manual user input.
  */
@@ -728,12 +779,22 @@ export async function authenticate(
         console.warn(`MCP Auth: Failed to open browser for ${serverName}; waiting for manual callback`, { error })
       }
 
-      const callbackResult = await abortable(callbackPromise, signal)
+      const authorizationResponse = await waitForAuthorizationResponse(
+        callbackPromise,
+        authorizationUrl,
+        oauthState,
+        options.onAuthorizationInput,
+        signal,
+      )
+      if (authorizationResponse.source === "manual") {
+        cancelPendingCallback(oauthState)
+      }
 
-      // The callback server accepted only the flow-local reserved state.
+      // The callback server accepted only the flow-local reserved state. Manual
+      // input is checked against the same state before token exchange.
       throwIfAborted(signal)
 
-      return await completeAuth(serverName, callbackResult, {
+      return await completeAuth(serverName, authorizationResponse.input, {
         ...options,
         ...(signal ? { signal } : {}),
         runtime,

package/mcp-auth.ts

@@ -37,6 +37,7 @@ const KEYRING_RECOVERY_KEYCTL_ENV = 'PI_MCP_ADAPTER_KEYRING_RECOVERY_KEYCTL';
 const KEYRING_RECOVERY_NODE_ENV = 'PI_MCP_ADAPTER_KEYRING_RECOVERY_NODE';
 const KEYRING_RECOVERY_HELPER_ENV = 'PI_MCP_ADAPTER_KEYRING_RECOVERY_HELPER';
 const TEST_LINUX_KEYRING_RECOVERY_ENV = 'PI_MCP_ADAPTER_TEST_LINUX_KEYRING_RECOVERY';
+const AUTH_CACHE_DISABLED_ENV = 'PI_MCP_ADAPTER_DISABLE_AUTH_CACHE';
 const KEYRING_RECOVERY_TIMEOUT_MS = 10_000;
 const AUTH_CHUNK_MANIFEST_KEY = '__piMcpAdapterOAuthChunked';
 
@@ -148,8 +149,20 @@ interface AuthEntryChunkManifest {
 let KeyringEntryClass: KeyringEntryConstructor | undefined;
 const memoryAuthEntries = new Map<string, string>();
 
+let testAuthSecretStoreReadCount = 0;
+const authEntryCache = new Map<string, AuthEntry | undefined>();
+
+function isAuthEntryCacheEnabled(): boolean {
+  return process.env[AUTH_CACHE_DISABLED_ENV] !== '1';
+}
+
+function cloneAuthEntry(entry: AuthEntry | undefined): AuthEntry | undefined {
+  return entry === undefined ? undefined : structuredClone(entry);
+}
+
 const memoryAuthSecretStore: AuthSecretStore = {
   read(account) {
+    testAuthSecretStoreReadCount++;
     return memoryAuthEntries.get(account);
   },
   write(account, payload) {
@@ -175,6 +188,7 @@ const keyringAuthSecretStore: AuthSecretStore = {
 /** Mimics the Windows Credential Manager per-value ceiling for tests. */
 const sizeLimitedAuthSecretStore: AuthSecretStore = {
   read(account) {
+    testAuthSecretStoreReadCount++;
     return memoryAuthEntries.get(account);
   },
   write(account, payload) {
@@ -190,6 +204,7 @@ const sizeLimitedAuthSecretStore: AuthSecretStore = {
 
 const unavailableAuthSecretStore: AuthSecretStore = {
   read() {
+    testAuthSecretStoreReadCount++;
     throw new Error('simulated secure credential store unavailable');
   },
   write() {
@@ -206,6 +221,7 @@ function createKeyRevokedTestError(): Error {
 
 const keyRevokedAuthSecretStore: AuthSecretStore = {
   read() {
+    testAuthSecretStoreReadCount++;
     throw createKeyRevokedTestError();
   },
   write() {
@@ -218,6 +234,16 @@ const keyRevokedAuthSecretStore: AuthSecretStore = {
 
 export function resetTestAuthSecretStore(): void {
   memoryAuthEntries.clear();
+  authEntryCache.clear();
+  testAuthSecretStoreReadCount = 0;
+}
+
+export function resetAuthEntryCache(): void {
+  authEntryCache.clear();
+}
+
+export function getTestAuthSecretStoreReadCount(): number {
+  return testAuthSecretStoreReadCount;
 }
 
 export function getTestAuthSecretStoreEntries(): [string, string][] {
@@ -649,6 +675,19 @@ function writeSecureAuthEntryToStore(store: AuthSecretStore, serverName: string,
       error,
     );
   }
+
+  publishAuthEntryToCache(serverName, payload);
+}
+
+function publishAuthEntryToCache(serverName: string, payload: string): void {
+  if (!isAuthEntryCacheEnabled()) return;
+  // Cache the same normalized shape a fresh persistent-store read returns.
+  const normalized = toAuthEntry(JSON.parse(payload) as unknown);
+  if (!normalized) {
+    authEntryCache.delete(serverName);
+    return;
+  }
+  authEntryCache.set(serverName, cloneAuthEntry(normalized));
 }
 
 function writeSecureAuthEntry(serverName: string, entry: AuthEntry): void {
@@ -704,12 +743,23 @@ function readAuthEntry(
   options?: AuthStorageOptions,
   behavior: { migrateLegacy?: boolean } = {},
 ): AuthEntry | undefined {
+  // Status-only reads deliberately bypass the cache because they do not
+  // migrate legacy entries.
+  const cacheable = behavior.migrateLegacy !== false && isAuthEntryCacheEnabled();
+  if (cacheable && authEntryCache.has(serverName)) {
+    return cloneAuthEntry(authEntryCache.get(serverName));
+  }
+
+  let entry: AuthEntry | undefined;
   try {
-    return readAuthEntryFromStore(getAuthSecretStore(), serverName, options, behavior);
+    entry = readAuthEntryFromStore(getAuthSecretStore(), serverName, options, behavior);
   } catch (error) {
     if (!shouldAttemptLinuxKeyringRecovery(error)) throw error;
-    return readAuthEntryFromStore(linuxKeyringRecoveryAuthSecretStore, serverName, options, behavior);
+    entry = readAuthEntryFromStore(linuxKeyringRecoveryAuthSecretStore, serverName, options, behavior);
   }
+
+  if (cacheable) authEntryCache.set(serverName, cloneAuthEntry(entry));
+  return entry;
 }
 
 /**
@@ -794,9 +844,17 @@ export function removeAuthEntry(serverName: string, options?: AuthStorageOptions
     if (!shouldAttemptLinuxKeyringRecovery(error)) throw error;
     removeAuthEntryFromStore(linuxKeyringRecoveryAuthSecretStore, serverName);
   }
+  authEntryCache.delete(serverName);
   removeLegacyAuthEntry(serverName, options);
 }
 
+/**
+ * Forget a cached entry so the next ordinary read reloads secure storage.
+ */
+export function invalidateAuthEntryCache(serverName: string): void {
+  authEntryCache.delete(serverName);
+}
+
 /**
  * Update tokens for a server.
  */

package/npx-resolver.ts

@@ -1,11 +1,11 @@
 // npx-resolver.ts - Resolve npx/npm exec binaries to avoid npm parent processes
-import { existsSync, readFileSync, realpathSync, readdirSync, statSync, writeFileSync, renameSync, mkdirSync, openSync, readSync, closeSync } from "node:fs";
+import { existsSync, readFileSync, realpathSync, readdirSync, statSync, writeFileSync, renameSync, mkdirSync, openSync, readSync, closeSync, unlinkSync } from "node:fs";
 import { join, dirname, extname, resolve, sep } from "node:path";
 import { getAgentPath } from "./agent-dir.ts";
 import { throwIfAborted } from "./abort.ts";
 import crossSpawn from "cross-spawn";
 
-const CACHE_VERSION = 1;
+const CACHE_VERSION = 2;
 const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
 const EXACT_PACKAGE_VERSION_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z][0-9A-Za-z.-]*)?(?:\+[0-9A-Za-z][0-9A-Za-z.-]*)?$/;
 
@@ -53,7 +53,7 @@ export async function resolveNpxBinary(
   if (!parsed) return null;
 
   const packageSpec = parsePackageSpec(parsed.packageSpec);
-  const cacheKey = JSON.stringify([command, ...args]);
+  const cacheKey = JSON.stringify([command, parsed.packageSpec, parsed.binName ?? ""]);
   const cache = loadCache();
   const cached = cache?.entries?.[cacheKey];
 
@@ -434,41 +434,96 @@ function getNpxCachePath(): string {
   return getAgentPath("mcp-npx-cache.json");
 }
 
-function loadCache(): NpxCache | null {
-  const cachePath = getNpxCachePath();
+function readNpxCachePayload(cachePath: string): unknown | null {
   if (!existsSync(cachePath)) return null;
   try {
-    const raw = JSON.parse(readFileSync(cachePath, "utf-8"));
-    if (!raw || typeof raw !== "object") return null;
-    if (raw.version !== CACHE_VERSION) return null;
-    if (!raw.entries || typeof raw.entries !== "object") return null;
-    return raw as NpxCache;
+    return JSON.parse(readFileSync(cachePath, "utf-8")) as unknown;
   } catch {
     return null;
   }
 }
 
-function saveCacheEntry(key: string, entry: NpxCacheEntry): void {
-  const cachePath = getNpxCachePath();
-  const dir = dirname(cachePath);
-  mkdirSync(dir, { recursive: true });
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : null;
+}
+
+function createCacheEntries(): Record<string, NpxCacheEntry> {
+  return Object.create(null) as Record<string, NpxCacheEntry>;
+}
+
+function toNpxCacheEntry(value: unknown): NpxCacheEntry | null {
+  const raw = asRecord(value);
+  if (!raw) return null;
+  if (typeof raw.resolvedBin !== "string") return null;
+  if (typeof raw.resolvedAt !== "number" || !Number.isFinite(raw.resolvedAt)) return null;
+  if (typeof raw.isJs !== "boolean") return null;
+  if (raw.packageVersion !== undefined && typeof raw.packageVersion !== "string") return null;
+  return {
+    resolvedBin: raw.resolvedBin,
+    resolvedAt: raw.resolvedAt,
+    ...(raw.packageVersion !== undefined ? { packageVersion: raw.packageVersion } : {}),
+    isJs: raw.isJs,
+  };
+}
+
+function toNpxCache(value: unknown): NpxCache | null {
+  const raw = asRecord(value);
+  if (!raw || raw.version !== CACHE_VERSION) return null;
+  const rawEntries = asRecord(raw.entries);
+  if (!rawEntries) return null;
+
+  const entries = createCacheEntries();
+  for (const [key, rawEntry] of Object.entries(rawEntries)) {
+    const entry = toNpxCacheEntry(rawEntry);
+    if (entry) entries[key] = entry;
+  }
+  return { version: CACHE_VERSION, entries };
+}
 
-  let merged: NpxCache = { version: CACHE_VERSION, entries: {} };
+function clearLegacyCache(): boolean {
+  const cachePath = getNpxCachePath();
+  const raw = asRecord(readNpxCachePayload(cachePath));
+  if (raw?.version !== 1) return false;
   try {
-    if (existsSync(cachePath)) {
-      const existing = JSON.parse(readFileSync(cachePath, "utf-8")) as NpxCache;
-      if (existing && existing.version === CACHE_VERSION && existing.entries) {
-        merged.entries = { ...existing.entries };
-      }
-    }
+    unlinkSync(cachePath);
   } catch {
-    // Ignore parse errors
+    try {
+      writeFileSync(cachePath, "", "utf-8");
+    } catch {
+      // Cache cleanup is best effort; resolution must still proceed.
+    }
   }
+  return true;
+}
 
-  merged.entries[key] = entry;
-  const tmpPath = `${cachePath}.${process.pid}.tmp`;
-  writeFileSync(tmpPath, JSON.stringify(merged, null, 2), "utf-8");
-  renameSync(tmpPath, cachePath);
+clearLegacyCache();
+
+function loadCache(): NpxCache | null {
+  if (clearLegacyCache()) return null;
+
+  return toNpxCache(readNpxCachePayload(getNpxCachePath()));
+}
+
+function saveCacheEntry(key: string, entry: NpxCacheEntry): void {
+  try {
+    const cachePath = getNpxCachePath();
+    const dir = dirname(cachePath);
+    mkdirSync(dir, { recursive: true });
+
+    const existing = toNpxCache(readNpxCachePayload(cachePath));
+    const entries = createCacheEntries();
+    if (existing) Object.assign(entries, existing.entries);
+    const merged: NpxCache = { version: CACHE_VERSION, entries };
+
+    merged.entries[key] = entry;
+    const tmpPath = `${cachePath}.${process.pid}.tmp`;
+    writeFileSync(tmpPath, JSON.stringify(merged, null, 2), "utf-8");
+    renameSync(tmpPath, cachePath);
+  } catch {
+    // Cache writes are best effort; resolution must still proceed.
+  }
 }
 
 function safeRealpath(path: string): string {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mcp-adapter",
-  "version": "2.22.0",
+  "version": "2.24.0",
   "description": "MCP (Model Context Protocol) adapter extension for Pi coding agent",
   "type": "module",
   "types": "./index.ts",
@@ -34,8 +34,8 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
-    "test:oauth": "PI_MCP_ADAPTER_TEST_AUTH_STORE=memory node --import tsx --test --test-concurrency=1 oauth-public-api.test.ts mcp-auth.test.ts mcp-auth-flow.test.ts mcp-callback-server.test.ts mcp-oauth-provider.test.ts",
-    "test:oauth-provider": "PI_MCP_ADAPTER_TEST_AUTH_STORE=memory node --import tsx --test mcp-oauth-provider.test.ts",
+    "test:oauth": "PI_MCP_ADAPTER_TEST_AUTH_STORE=memory PI_MCP_ADAPTER_DISABLE_AUTH_CACHE=1 node --import tsx --test --test-concurrency=1 oauth-public-api.test.ts mcp-auth.test.ts mcp-auth-flow.test.ts mcp-callback-server.test.ts mcp-oauth-provider.test.ts",
+    "test:oauth-provider": "PI_MCP_ADAPTER_TEST_AUTH_STORE=memory PI_MCP_ADAPTER_DISABLE_AUTH_CACHE=1 node --import tsx --test mcp-oauth-provider.test.ts",
     "test:conformance": "bash conformance/run.sh"
   },
   "repository": {

package/proxy-modes.ts

@@ -16,7 +16,7 @@ import { maybeStartUiSession, summarizeUiSessionResult, type UiSessionRuntime }
 import { formatAuthRequiredMessage, formatMcpStatus, resolveServerUrl, truncateAtWord } from "./utils.ts";
 import { authenticate, completeAuthFromInput, startAuth, supportsOAuth } from "./mcp-auth-flow.ts";
 import { SessionRecoveryAuthRequiredError, withSessionRecovery } from "./session-recovery.ts";
-import { paginate, rankSuggestions, rankToolMatches } from "./search-ranking.ts";
+import { paginate, rankSuggestions, rankToolMatches, resolveSearchKeywords } from "./search-ranking.ts";
 import { ensureToolCallApproved, isToolCallApprovalRequired } from "./tool-approval.ts";
 
 type ProxyToolResult = AgentToolResult<Record<string, unknown>>;
@@ -503,11 +503,15 @@ export function executeSearch(
     }
 
     matches = [];
+    const globalPrefix = state.config.settings?.toolPrefix ?? "server";
     for (const [serverName, metadata] of state.toolMetadata.entries()) {
-      if (isServerDisabled(state.config.mcpServers[serverName])) continue;
+      const definition = state.config.mcpServers[serverName];
+      if (isServerDisabled(definition)) continue;
       if (server && serverName !== server) continue;
       for (const tool of metadata) {
-        if (pattern.test(tool.name) || pattern.test(tool.description)) matches.push({ server: serverName, tool, score: 0 });
+        const matched = pattern.test(tool.name) || pattern.test(tool.description)
+          || resolveSearchKeywords(definition, tool.originalName, serverName, globalPrefix).some(keyword => pattern.test(keyword));
+        if (matched) matches.push({ server: serverName, tool, score: 0 });
       }
     }
   } else if (query.trim().length === 0) {

package/search-ranking.ts

@@ -1,6 +1,6 @@
 import type { McpExtensionState } from "./state.ts";
-import type { ToolMetadata } from "./types.ts";
-import { getServerPrefix, isServerDisabled } from "./types.ts";
+import type { ServerEntry, ToolMetadata, ToolPrefix } from "./types.ts";
+import { getServerPrefix, getToolNameCandidates, isServerDisabled, matchesToolPattern, resolveToolPrefix } from "./types.ts";
 
 /**
  * Shortest field token allowed to stem-match a longer query token.
@@ -14,6 +14,7 @@ const FIELD_WEIGHTS = {
   originalName: 10,
   server: 8,
   description: 5,
+  keywords: 5,
 } as const;
 
 export interface RankedToolMatch {
@@ -22,6 +23,36 @@ export interface RankedToolMatch {
   score: number;
 }
 
+/**
+ * Resolve the configured searchKeywords entries that apply to a tool.
+ * Keys match by original name, prefixed name, or glob — the same candidate
+ * set includeTools/excludeTools use — and all matching entries are unioned.
+ */
+export function resolveSearchKeywords(
+  definition: ServerEntry | undefined,
+  toolOriginalName: string,
+  serverName: string,
+  globalPrefix: ToolPrefix,
+): string[] {
+  const map = definition?.searchKeywords;
+  if (!map || typeof map !== "object" || Array.isArray(map)) return [];
+  const candidates = getToolNameCandidates(toolOriginalName, serverName, resolveToolPrefix(definition, globalPrefix));
+  const keywords: string[] = [];
+  const seen = new Set<string>();
+  for (const [pattern, values] of Object.entries(map)) {
+    if (!Array.isArray(values)) continue;
+    if (!matchesToolPattern(candidates, [pattern])) continue;
+    for (const value of values) {
+      if (typeof value !== "string") continue;
+      const trimmed = value.trim();
+      if (!trimmed || seen.has(trimmed)) continue;
+      seen.add(trimmed);
+      keywords.push(trimmed);
+    }
+  }
+  return keywords;
+}
+
 export function normalizeSearchText(value: string): string {
   return value
     .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
@@ -33,7 +64,7 @@ export function tokenize(value: string): string[] {
   return normalizeSearchText(value).split(/[^a-z0-9]+/).filter(Boolean);
 }
 
-export function scoreToolMatch(tool: ToolMetadata, server: string, query: string): number | null {
+export function scoreToolMatch(tool: ToolMetadata, server: string, query: string, keywords?: string[]): number | null {
   const normalizedQuery = normalizeSearchText(query).trim();
   const queryTokens = tokenize(query);
   if (queryTokens.length === 0) return null;
@@ -78,6 +109,43 @@ export function scoreToolMatch(tool: ToolMetadata, server: string, query: string
     }
   }
 
+  // Configured keywords are discrete phrases, so the phrase-level bonus is
+  // computed per phrase (best match wins) rather than on a joined string,
+  // which would phrase-match queries spanning two unrelated keywords.
+  if (keywords !== undefined && keywords.length > 0) {
+    const weight = FIELD_WEIGHTS.keywords;
+    const phrases = keywords.map(keyword => normalizeSearchText(keyword).trim()).filter(Boolean);
+    let phraseScore = 0;
+    for (const phrase of phrases) {
+      if (phrase === normalizedQuery) {
+        phraseScore = Math.max(phraseScore, weight * 14);
+        phraseMatched = true;
+        wholeFieldExact = true;
+      } else if (phrase.startsWith(normalizedQuery)) {
+        phraseScore = Math.max(phraseScore, weight * 9);
+        phraseMatched = true;
+      } else if (phrase.includes(normalizedQuery)) {
+        phraseScore = Math.max(phraseScore, weight * 6);
+        phraseMatched = true;
+      }
+    }
+    score += phraseScore;
+
+    const keywordTokens = phrases.flatMap(tokenize);
+    for (const token of queryTokens) {
+      if (keywordTokens.includes(token)) {
+        score += weight * 4;
+        matchedTokens.add(token);
+      } else if (keywordTokens.some(keywordToken => keywordToken.startsWith(token) || (keywordToken.length >= MIN_STEM_LENGTH && token.startsWith(keywordToken)))) {
+        score += weight * 2;
+        matchedTokens.add(token);
+      } else if (phrases.some(phrase => phrase.includes(token))) {
+        score += weight;
+        matchedTokens.add(token);
+      }
+    }
+  }
+
   const coverage = matchedTokens.size / queryTokens.length;
   if (!phraseMatched && (queryTokens.length <= 2 ? coverage !== 1 : coverage < 0.6)) return null;
 
@@ -88,13 +156,24 @@ export function scoreToolMatch(tool: ToolMetadata, server: string, query: string
   return score;
 }
 
-export function rankToolMatches(state: McpExtensionState, query: string, server?: string): RankedToolMatch[] {
+export function rankToolMatches(
+  state: McpExtensionState,
+  query: string,
+  server?: string,
+  includeKeywords = true,
+): RankedToolMatch[] {
   const matches: RankedToolMatch[] = [];
+  const globalPrefix = state.config.settings?.toolPrefix ?? "server";
   for (const [serverName, metadata] of state.toolMetadata.entries()) {
     if (server && serverName !== server) continue;
-    if (isServerDisabled(state.config.mcpServers[serverName])) continue;
+    const definition = state.config.mcpServers[serverName];
+    if (isServerDisabled(definition)) continue;
+    const hasKeywords = includeKeywords && definition?.searchKeywords !== undefined;
     for (const tool of metadata) {
-      const score = scoreToolMatch(tool, serverName, query);
+      const keywords = hasKeywords
+        ? resolveSearchKeywords(definition, tool.originalName, serverName, globalPrefix)
+        : undefined;
+      const score = scoreToolMatch(tool, serverName, query, keywords);
       if (score !== null) matches.push({ server: serverName, tool, score });
     }
   }
@@ -123,5 +202,5 @@ export function rankSuggestions(state: McpExtensionState, name: string, limit: n
     .sort((a, b) => b.length - a.length)
     .map(candidate => name.slice(candidate.length + 1));
   const query = stripped[0] ?? name;
-  return rankToolMatches(state, query).slice(0, limit).map(match => match.tool.name);
+  return rankToolMatches(state, query, undefined, false).slice(0, limit).map(match => match.tool.name);
 }

package/server-manager.ts

@@ -31,7 +31,7 @@ import { createJsonSchemaValidator } from "./json-schema-validator.ts";
 import { logger } from "./logger.ts";
 import { McpOAuthProvider } from "./mcp-oauth-provider.ts";
 import { extractOAuthConfig, supportsOAuth, type McpOAuthRuntime } from "./mcp-auth-flow.ts";
-import type { AuthStorageOptions } from "./mcp-auth.ts";
+import { invalidateAuthEntryCache, type AuthStorageOptions } from "./mcp-auth.ts";
 import { registerSamplingHandler, type ServerSamplingConfig } from "./sampling-handler.ts";
 import {
   handleUrlElicitation,
@@ -39,6 +39,7 @@ import {
   type ServerElicitationConfig,
 } from "./elicitation-handler.ts";
 import {
+  interpolateEnvVars,
   resolveBearerToken,
   resolveCommandSecret,
   resolveCommandSecretsRecord,
@@ -129,8 +130,11 @@ export interface ServerConnection {
   lastUsedAt: number;
   inFlight: number;
   status: "connected" | "closed" | "needs-auth";
+  /** True once this needs-auth episode discarded the cached credential. */
+  credentialsInvalidated?: boolean;
 }
 
+
 type UiStreamListener = (serverName: string, notification: ServerStreamResultPatchNotification["params"]) => void;
 type MetadataListChangedListener = (serverName: string, reason: string) => void;
 
@@ -238,10 +242,12 @@ export class McpServerManager {
       return existing;
     }
 
+    const credentialsInvalidated = existing?.status === "needs-auth"
+      && existing.credentialsInvalidated === true;
     const generation = this.closeGenerations.get(name) ?? 0;
     const attemptController = new AbortController();
     const attemptSignal = combineAbortSignals(ownedSignal, attemptController.signal);
-    const connectionAttempt = this.createConnection(name, definition, attemptSignal, ownedSignal);
+    const connectionAttempt = this.createConnection(name, definition, attemptSignal, ownedSignal, credentialsInvalidated);
     const promise = definition.url
       ? connectionAttempt.catch(async error => { throw await this.enrichHttpConnectionError(definition, error); })
       : connectionAttempt;
@@ -324,6 +330,7 @@ export class McpServerManager {
     definition: ServerDefinition,
     signal?: AbortSignal,
     requestSignal?: AbortSignal,
+    credentialsInvalidated = false,
   ): Promise<ServerConnection> {
     throwIfAborted(signal);
 
@@ -338,6 +345,7 @@ export class McpServerManager {
     let client: Client;
     let transport: Transport;
     let clientConnected = false;
+    let invalidated = credentialsInvalidated;
     let transportAlreadyTraced = false;
     let stderrTail: Buffer<ArrayBufferLike> = Buffer.alloc(0);
     const configuredTransports = [definition.command, definition.url, definition.socket]
@@ -351,7 +359,7 @@ export class McpServerManager {
     if (definition.command) {
       client = this.createClient(name, definition);
       let command = definition.command;
-      let args = definition.args ?? [];
+      let args = (definition.args ?? []).map(interpolateEnvVars);
 
       if (command === "npx" || command === "npm") {
         const resolved = await resolveNpxBinary(command, args, signal);
@@ -387,9 +395,11 @@ export class McpServerManager {
         requestOptions,
         signal,
         traceObserver,
+        invalidated,
       );
       client = httpConnection.client;
       transport = httpConnection.transport;
+      invalidated = httpConnection.credentialsInvalidated;
       if (httpConnection.status === "needs-auth") {
         return {
           client,
@@ -401,6 +411,7 @@ export class McpServerManager {
           lastUsedAt: Date.now(),
           inFlight: 0,
           status: "needs-auth",
+          credentialsInvalidated: invalidated,
         };
       }
       clientConnected = true;
@@ -477,6 +488,10 @@ export class McpServerManager {
       // A cleanup failure remains a setup failure rather than being hidden
       // behind needs-auth.
       if (isUnauthorizedHttpError(error) && supportsOAuth(definition) && cleanupFailures.length === 0) {
+        if (!invalidated) {
+          invalidateAuthEntryCache(name);
+          invalidated = true;
+        }
         return {
           client,
           transport,
@@ -487,6 +502,7 @@ export class McpServerManager {
           lastUsedAt: Date.now(),
           inFlight: 0,
           status: "needs-auth",
+          credentialsInvalidated: invalidated,
         };
       }
 
@@ -694,7 +710,8 @@ export class McpServerManager {
     requestOptions: RequestOptions | undefined,
     signal?: AbortSignal,
     traceObserver?: McpTraceObserver,
-  ): Promise<{ client: Client; transport: Transport; status: "connected" | "needs-auth" }> {
+    credentialsInvalidated = false,
+  ): Promise<{ client: Client; transport: Transport; status: "connected" | "needs-auth"; credentialsInvalidated: boolean }> {
     throwIfAborted(signal);
     const serverUrl = resolveServerUrl(definition)!;
     const url = new URL(serverUrl);
@@ -791,9 +808,10 @@ export class McpServerManager {
     // OAuth challenge; use SSE only for definitive endpoint incompatibility.
     // Agent Plugins set httpTransport, and their declared transport is used without fallback.
     let kind: "streamable-http" | "sse" = definition.httpTransport ?? "streamable-http";
+    let invalidated = credentialsInvalidated;
     for (;;) {
       const result = await attempt(kind);
-      if (result.status === "connected") return result;
+      if (result.status === "connected") return { ...result, credentialsInvalidated: invalidated };
       if (result.error instanceof AggregateError
         && result.error.message === "MCP connection abort cleanup failed") {
         throw result.error;
@@ -806,7 +824,16 @@ export class McpServerManager {
       }
       if (isUnauthorizedHttpError(result.error)) {
         if (supportsOAuth(definition)) {
-          return { client: result.client, transport: result.transport, status: "needs-auth" };
+          if (!invalidated) {
+            invalidateAuthEntryCache(serverName);
+            invalidated = true;
+          }
+          return {
+            client: result.client,
+            transport: result.transport,
+            status: "needs-auth",
+            credentialsInvalidated: invalidated,
+          };
         }
         throw result.error;
       }
@@ -850,6 +877,7 @@ export class McpServerManager {
       return { prompts, failed: false };
     } catch (error) {
       if (requestOptions?.signal?.aborted) throwIfAborted(requestOptions.signal);
+      if (isUnauthorizedHttpError(error)) throw error;
       const message = error instanceof Error ? error.message : String(error);
       logger.debug(`MCP: prompts/list failed: ${message}`);
       return { prompts: [], failed: true };
@@ -871,10 +899,11 @@ export class McpServerManager {
       } while (cursor);
 
       return allResources;
-    } catch {
+    } catch (error) {
       if (requestOptions?.signal?.aborted) {
         throwIfAborted(requestOptions.signal);
       }
+      if (isUnauthorizedHttpError(error)) throw error;
       // The server advertises resources but the listing failed
       return [];
     }

package/session-recovery.ts

@@ -20,10 +20,12 @@
 //     many things other than "your session is gone"
 //   - treat generic -32000/ConnectionClosed errors as session expiry
 //   - treat AbortError/cancellation as a session failure
-import { ProtocolError, SdkHttpError } from "@modelcontextprotocol/client";
+import { ProtocolError, SdkHttpError, UnauthorizedError } from "@modelcontextprotocol/client";
 import { logger } from "./logger.ts";
 import { throwIfAborted } from "./abort.ts";
 import { isServerDisabled, type McpConfig } from "./types.ts";
+import { supportsOAuth } from "./mcp-auth-flow.ts";
+import { invalidateAuthEntryCache } from "./mcp-auth.ts";
 import type { McpServerManager, ServerConnection } from "./server-manager.ts";
 
 /**
@@ -106,6 +108,11 @@ export async function withSessionRecovery<T>(
   try {
     return await fn(connection);
   } catch (err) {
+    const definition = deps.config.mcpServers[serverName];
+    if (definition && supportsOAuth(definition)
+      && (err instanceof UnauthorizedError || (err instanceof SdkHttpError && err.status === 401))) {
+      invalidateAuthEntryCache(serverName);
+    }
     if (!isTerminatedSession(err, hadSessionId)) {
       throw err;
     }
@@ -114,7 +121,6 @@ export async function withSessionRecovery<T>(
     // connection's definition, in case config changed since connect. If the
     // server was removed from config in the meantime there is nothing to
     // reconnect to, so surface the original error.
-    const definition = deps.config.mcpServers[serverName];
     if (!definition) {
       throw err;
     }

package/types.ts

@@ -395,6 +395,13 @@ export interface ServerEntry {
   // Include/exclude specific MCP tools/resources by original or prefixed name
   includeTools?: string[];
   excludeTools?: string[];
+  /**
+   * Extra search keywords per tool, keyed by original name, prefixed name, or
+   * glob (same matching rules as includeTools/excludeTools). Keywords boost
+   * mcp({ search }) ranking only — they never appear in tool schemas,
+   * describe output, or the metadata cache.
+   */
+  searchKeywords?: Record<string, string[]>;
   // Require interactive approval before calling matching MCP tools/resources.
   approveTools?: boolean | string[];
   // Debug
@@ -635,18 +642,24 @@ export interface McpPanelResult {
 /**
  * Get server prefix based on tool prefix mode.
  */
+function sanitizeServerPrefix(serverName: string): string {
+  return Array.from(serverName, char =>
+    /^[A-Za-z0-9]$/.test(char) ? char : `_${char.codePointAt(0)!.toString(16)}_`,
+  ).join("");
+}
+
 export function getServerPrefix(
   serverName: string,
   mode: ToolPrefix
 ): string {
   if (mode === "none") return "";
   if (mode === "short") {
-    let short = serverName.replace(/-?mcp$/i, "").replace(/-/g, "_");
+    let short = sanitizeServerPrefix(serverName.replace(/-?mcp$/i, ""));
     if (!short) short = "mcp";
     return short;
   }
-  if (mode === "mcp") return `mcp__${serverName.replace(/-/g, "_")}`;
-  return serverName.replace(/-/g, "_");
+  if (mode === "mcp") return `mcp__${sanitizeServerPrefix(serverName)}`;
+  return sanitizeServerPrefix(serverName);
 }
 
 /**
@@ -700,11 +713,9 @@ export function resolveServerFromToolName(
   if (candidates.length === 0) return undefined;
   candidates.sort((a, b) => b.prefix.length - a.prefix.length);
   const best = candidates[0];
-  // Fail safe: two distinct server names can normalize to the same prefix
-  // (e.g. my-server and my_server both -> my_server under "server" mode).
-  // When that happens the owning server is ambiguous; return undefined so a
-  // downstream permission gate falls back to its existing wildcard path rather
-  // than enforcing a rule against the wrong server.
+  // Fail safe: short mode can intentionally map names such as foo and foo-mcp
+  // to the same prefix. Return undefined so a downstream permission gate uses
+  // its existing wildcard path rather than enforcing a rule against the wrong server.
   if (candidates.some((c) => c.prefix === best!.prefix && c.name !== best!.name)) {
     return undefined;
   }
@@ -722,7 +733,7 @@ export function formatPromptCommandName(
   serverName: string,
   prefix: ToolPrefix,
 ): string {
-  const serverPart = getServerPrefix(serverName, prefix) || serverName.replace(/-/g, "_") || "server";
+  const serverPart = getServerPrefix(serverName, prefix) || sanitizeServerPrefix(serverName) || "server";
   return `mcp__${serverPart}__${sanitizePromptName(promptName)}`;
 }