@herbertgao/pi-extensions 2026.8.6 → 2026.8.8

package/node_modules/pi-mcp-adapter/package-mcp-loader.ts

@@ -0,0 +1,168 @@
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import stripJsonComments from "strip-json-comments";
+import { getAgentDir, getConfigDirName } from "./agent-dir.ts";
+import type { McpConfig, ServerEntry } from "./types.ts";
+
+interface PackageSetting {
+  source: string;
+}
+
+interface PackageManifest {
+  name?: unknown;
+  pi?: { mcp?: unknown };
+}
+
+export function loadPackageMcpConfigs(cwd = process.cwd()): McpConfig {
+  const mcpServers: Record<string, ServerEntry> = {};
+  const seen = new Set<string>();
+
+  for (const packageRoot of getConfiguredPackageRoots(cwd)) {
+    const manifest = readPackageManifest(packageRoot);
+    if (!manifest || typeof manifest.name !== "string" || !manifest.name) continue;
+    const paths = getManifestMcpPaths(manifest.pi?.mcp, manifest.name);
+    if (!paths) continue;
+
+    const packagePrefix = formatPackageName(manifest.name);
+    const packageServers = new Set<string>();
+    for (const path of paths) {
+      const configPath = resolvePackageConfigPath(packageRoot, path);
+      if (!configPath) {
+        console.warn(`Pi package ${manifest.name} skips MCP config ${path}: file must stay inside the package`);
+        continue;
+      }
+
+      const config = readMcpConfig(configPath, manifest.name);
+      if (!config) continue;
+      for (const [serverName, server] of Object.entries(config.mcpServers)) {
+        const normalizedName = `${packagePrefix}__${formatServerName(serverName)}`;
+        if (packageServers.has(normalizedName) || seen.has(normalizedName)) {
+          console.warn(`Pi package ${manifest.name} skips duplicate normalized MCP server ${normalizedName}`);
+          continue;
+        }
+        packageServers.add(normalizedName);
+        seen.add(normalizedName);
+        mcpServers[normalizedName] = server;
+      }
+    }
+  }
+
+  return { mcpServers };
+}
+
+function getConfiguredPackageRoots(cwd: string): string[] {
+  const roots: string[] = [];
+  for (const [settingsPath, scope] of [
+    [join(cwd, getConfigDirName(), "settings.json"), "project"],
+    [join(getAgentDir(), "settings.json"), "user"],
+  ] as const) {
+    const settings = readOptionalJson(settingsPath, `${scope} Pi settings`);
+    if (settings === undefined) continue;
+    if (typeof settings !== "object" || settings === null || Array.isArray(settings)) {
+      throw new Error(`${scope} Pi settings ${settingsPath} must be a JSON object`);
+    }
+    const packages = (settings as { packages?: unknown }).packages;
+    if (packages === undefined) continue;
+    if (!Array.isArray(packages)) throw new Error(`${scope} Pi settings ${settingsPath} packages must be an array`);
+    for (const entry of packages) {
+      const source = typeof entry === "string"
+        ? entry
+        : entry && typeof entry === "object" && !Array.isArray(entry) && typeof (entry as PackageSetting).source === "string"
+          ? (entry as PackageSetting).source
+          : undefined;
+      if (!source) throw new Error(`${scope} Pi settings ${settingsPath} package entries must be strings or objects with a string source`);
+      const root = resolvePackageRoot(source, scope, cwd);
+      if (root && !roots.includes(root)) roots.push(root);
+    }
+  }
+  return roots;
+}
+
+function resolvePackageRoot(source: string, scope: "user" | "project", cwd: string): string | null {
+  const baseDir = scope === "user" ? getAgentDir() : join(cwd, getConfigDirName());
+  if (source.startsWith("npm:")) {
+    const name = source.slice(4).trim().match(/^(@?[^@]+(?:\/[^@]+)?)/)?.[1];
+    return name ? resolveContainedPath(join(baseDir, "npm", "node_modules"), name) : null;
+  }
+  const gitSource = source.startsWith("git:")
+    ? source.slice(4).trim()
+    : /^(?:(?:https?|ssh):\/\/|git@[^:]+:)/.test(source) ? source : null;
+  if (gitSource) {
+    const value = gitSource
+      .replace(/^ssh:\/\/git@/, "")
+      .replace(/^git@([^:]+):/, "$1/")
+      .replace(/^[a-z]+:\/\//i, "");
+    const path = value.replace(/@[^/]+$/, "").replace(/\.git$/, "");
+    return path && !path.startsWith("/") ? resolveContainedPath(join(baseDir, "git"), path) : null;
+  }
+  return isAbsolute(source) ? resolve(source) : resolve(baseDir, source);
+}
+
+function readPackageManifest(packageRoot: string): PackageManifest | null {
+  const manifest = readOptionalJson(join(packageRoot, "package.json"), `Pi package manifest ${packageRoot}`);
+  return manifest && typeof manifest === "object" && !Array.isArray(manifest) ? manifest as PackageManifest : null;
+}
+
+function getManifestMcpPaths(value: unknown, packageName: string): string[] | null {
+  const paths = typeof value === "string" ? [value] : Array.isArray(value) && value.every((path): path is string => typeof path === "string") ? value : null;
+  if (value !== undefined && !paths) console.warn(`Pi package ${packageName} ignores invalid pi.mcp manifest entry`);
+  return paths;
+}
+
+function readMcpConfig(path: string, packageName: string): McpConfig | null {
+  const config = readRequiredJson(path, `Pi package ${packageName} MCP config`);
+  if (!config || typeof config !== "object" || Array.isArray(config)) {
+    throw new Error(`Pi package ${packageName} MCP config ${path} must be a JSON object`);
+  }
+  const servers = (config as { mcpServers?: unknown }).mcpServers;
+  if (!servers || typeof servers !== "object" || Array.isArray(servers)) {
+    throw new Error(`Pi package ${packageName} MCP config ${path} must contain a JSON object mcpServers field`);
+  }
+  const mcpServers: Record<string, ServerEntry> = {};
+  for (const [name, server] of Object.entries(servers)) {
+    if (!server || typeof server !== "object" || Array.isArray(server)) {
+      throw new Error(`Pi package ${packageName} MCP config ${path} server ${name} must be a JSON object`);
+    }
+    mcpServers[name] = server as ServerEntry;
+  }
+  return { mcpServers };
+}
+
+function readRequiredJson(path: string, description: string): unknown {
+  try {
+    return JSON.parse(stripJsonComments(readFileSync(path, "utf8"), { trailingCommas: true }));
+  } catch (error) {
+    throw new Error(`${description} ${path} contains invalid JSON: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+  }
+}
+
+function readOptionalJson(path: string, description: string): unknown | undefined {
+  if (!existsSync(path)) return undefined;
+  return readRequiredJson(path, description);
+}
+
+function resolveContainedPath(root: string, path: string): string | null {
+  const resolved = resolve(root, path);
+  const rel = relative(root, resolved);
+  return rel === "" || (!rel.startsWith("..") && !rel.startsWith(sep) && !isAbsolute(rel)) ? resolved : null;
+}
+
+function resolvePackageConfigPath(packageRoot: string, path: string): string | null {
+  const lexicalPath = resolveContainedPath(packageRoot, path);
+  if (!lexicalPath || !existsSync(lexicalPath) || !statSync(lexicalPath).isFile()) return null;
+  try {
+    const realPackageRoot = realpathSync(packageRoot);
+    const realConfigPath = realpathSync(lexicalPath);
+    return resolveContainedPath(realPackageRoot, realConfigPath);
+  } catch {
+    return null;
+  }
+}
+
+function formatPackageName(name: string): string {
+  return name.replace(/[^A-Za-z0-9_-]+/g, "_").replace(/^[_-]+|[_-]+$/g, "") || "package";
+}
+
+function formatServerName(name: string): string {
+  return name.replace(/[^A-Za-z0-9_-]+/g, "_").replace(/^[_-]+|[_-]+$/g, "") || "server";
+}

package/node_modules/pi-mcp-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mcp-adapter",
-  "version": "2.26.0",
+  "version": "2.27.0",
   "description": "MCP (Model Context Protocol) adapter extension for Pi coding agent",
   "type": "module",
   "types": "./index.ts",
@@ -88,6 +88,7 @@
     "ui-tool-visibility.ts",
     "ui-app-bridge-helpers.ts",
     "config.ts",
+    "package-mcp-loader.ts",
     "server-manager.ts",
     "request-headers-command.ts",
     "unix-socket-transport.ts",
@@ -115,6 +116,7 @@
     "oauth-handler.ts",
     "oauth.ts",
     "mcp-auth.ts",
+    "mcp-bearer-store.ts",
     "mcp-keyring-helper.cjs",
     "mcp-oauth-provider.ts",
     "mcp-callback-server.ts",

package/node_modules/pi-mcp-adapter/proxy-modes.ts

@@ -13,7 +13,7 @@ import { reconstructPromptMetadata } from "./metadata-cache.ts";
 import { resolveMcpResultContent, transformMcpContent, transformMcpResourceContents } from "./tool-registrar.ts";
 import { guardMcpOutput, guardedMcpDetails, resolveMcpOutputGuardOptions } from "./mcp-output-guard.ts";
 import { maybeStartUiSession, summarizeUiSessionResult, type UiSessionRuntime } from "./ui-session.ts";
-import { formatAuthRequiredMessage, formatMcpStatus, resolveServerUrl, truncateAtWord } from "./utils.ts";
+import { formatAuthRequiredMessage, formatMcpStatus, normalizeToolArguments, 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, resolveSearchKeywords } from "./search-ranking.ts";
@@ -1136,11 +1136,12 @@ export async function executeCall(
     return disabledCallResult(serverName, toolMeta);
   }
 
+  const normalizedArgs = toolMeta.resourceUri ? args ?? {} : normalizeToolArguments(args);
   const approval = await ensureToolCallApproved(
     state,
     serverName,
     toolMeta,
-    args,
+    normalizedArgs,
     ownedSignal,
     origin ?? (toolMeta.resourceUri ? "resource" : "proxy"),
   );
@@ -1217,7 +1218,7 @@ export async function executeCall(
       ? await maybeStartUiSession(state, {
           serverName,
           toolName: toolMeta.originalName,
-          toolArgs: args ?? {},
+          toolArgs: normalizedArgs,
           uiResourceUri: toolMeta.uiResourceUri,
           ...(toolMeta.uiStreamMode !== undefined ? { streamMode: toolMeta.uiStreamMode } : {}),
           ...(signal ? { signal } : {}),
@@ -1235,7 +1236,7 @@ export async function executeCall(
       serverName,
       (conn) => abortable(conn.client.callTool({
         name: toolMeta.originalName,
-        arguments: args ?? {},
+        arguments: normalizedArgs,
         _meta: uiSession?.requestMeta,
       }, requestOptions), ownedSignal),
     );

package/node_modules/pi-mcp-adapter/request-headers-command.ts

@@ -8,64 +8,62 @@ const DEFAULT_TIMEOUT_MS = 10_000;
 const MAX_OUTPUT_BYTES = 64 * 1024;
 const USE_PROCESS_GROUP = process.platform !== "win32";
 const CLEANUP_TOKEN_ENV = "PI_MCP_REQUEST_HEADERS_CLEANUP_TOKEN";
+// Busy hosts can exceed spawnSync's 1 MiB default when `ps axeww` dumps each
+// process environment. Keep discovery below a bounded cap instead of letting
+// `ps` get SIGTERM'd and reporting a false cleanup failure.
+const PS_MAX_BUFFER_BYTES = 8 * 1024 * 1024;
 
 function isNoSuchProcessError(error: unknown): boolean {
   return typeof error === "object" && error !== null && "code" in error && (error as NodeJS.ErrnoException).code === "ESRCH";
 }
 
-function runPosixPs(args: string[]): { status: number | null; stdout: string } {
-  if (process.env.PI_MCP_ADAPTER_TEST_FAIL_PS === "1") return { status: 1, stdout: "" };
-  return spawnSync("ps", args, { encoding: "utf8" });
+function runPosixPs(args: string[]): { status: number | null; signal: NodeJS.Signals | null; stdout: string } {
+  if (process.env.PI_MCP_ADAPTER_TEST_FAIL_PS === "1") return { status: 1, signal: null, stdout: "" };
+  const result = spawnSync("ps", args, { encoding: "utf8", maxBuffer: PS_MAX_BUFFER_BYTES });
+  return { status: result.status, signal: result.signal, stdout: result.stdout };
 }
 
-function collectPosixDescendantPids(rootPid: number): number[] {
-  const result = runPosixPs(["-axo", "pid=,ppid="]);
+function psFailureReason(result: { status: number | null; signal: NodeJS.Signals | null }): string {
+  return result.status === null
+    ? `ps was killed by signal ${result.signal ?? "unknown"}`
+    : `ps exited with code ${result.status}`;
+}
+
+function collectPosixProcessPids(rootPid: number, cleanupToken?: string): number[] {
+  const result = runPosixPs(["axeww", "-o", "pid=,ppid=,command="]);
   if (result.status !== 0) {
-    throw new Error(`HTTP request headers command cleanup failed: ps exited with code ${result.status ?? "unknown"}`);
+    throw new Error(`HTTP request headers command cleanup failed: ${psFailureReason(result)}`);
   }
 
   const childrenByParent = new Map<number, number[]>();
+  const processPids = new Set<number>();
+  const needle = cleanupToken ? `${CLEANUP_TOKEN_ENV}=${cleanupToken}` : undefined;
   for (const line of result.stdout.split("\n")) {
-    const [pidText, ppidText] = line.trim().split(/\s+/, 2);
-    const pid = Number(pidText);
-    const ppid = Number(ppidText);
+    const match = /^\s*(\d+)\s+(\d+)(?:\s+(.*))?$/.exec(line);
+    if (!match) continue;
+    const pid = Number(match[1]);
+    const ppid = Number(match[2]);
     if (!Number.isInteger(pid) || !Number.isInteger(ppid)) continue;
     const children = childrenByParent.get(ppid);
     if (children) children.push(pid);
     else childrenByParent.set(ppid, [pid]);
+    if (needle && pid !== process.pid && match[3]?.includes(needle)) processPids.add(pid);
   }
 
-  const descendants: number[] = [];
   const stack = [...(childrenByParent.get(rootPid) ?? [])];
   while (stack.length > 0) {
     const pid = stack.pop()!;
-    descendants.push(pid);
+    processPids.add(pid);
     stack.push(...(childrenByParent.get(pid) ?? []));
   }
-  return descendants;
+  return [...processPids];
 }
 
-function collectPosixCleanupTokenPids(cleanupToken: string): number[] {
-  const result = runPosixPs(["axeww", "-o", "pid=,command="]);
+function assertPosixProcessDiscoveryAvailable(): void {
+  const result = runPosixPs(["axeww", "-o", "pid=,ppid=,command="]);
   if (result.status !== 0) {
-    throw new Error(`HTTP request headers command cleanup failed: ps exited with code ${result.status ?? "unknown"}`);
+    throw new Error(`HTTP request headers command cleanup failed: ${psFailureReason(result)}`);
   }
-
-  const needle = `${CLEANUP_TOKEN_ENV}=${cleanupToken}`;
-  const pids: number[] = [];
-  for (const line of result.stdout.split("\n")) {
-    const trimmed = line.trim();
-    if (!trimmed.includes(needle)) continue;
-    const [pidText] = trimmed.split(/\s+/, 1);
-    const pid = Number(pidText);
-    if (Number.isInteger(pid) && pid !== process.pid) pids.push(pid);
-  }
-  return pids;
-}
-
-function assertPosixProcessDiscoveryAvailable(): void {
-  collectPosixDescendantPids(process.pid);
-  collectPosixCleanupTokenPids(`${process.pid}-preflight`);
 }
 
 function isTaskkillNoSuchProcess(result: ReturnType<typeof spawnSync>): boolean {
@@ -109,10 +107,7 @@ function killRequestHeadersCommand(child: ChildProcess, trackedPosixDescendantPi
       }
       let stablePasses = 0;
       for (let pass = 0; pass < 16; pass++) {
-        const candidates = [
-          ...collectPosixDescendantPids(child.pid),
-          ...(cleanupToken ? collectPosixCleanupTokenPids(cleanupToken) : []),
-        ];
+        const candidates = collectPosixProcessPids(child.pid, cleanupToken);
         const newPids = candidates.filter(pid => !frozenPids.has(pid));
         if (newPids.length === 0) {
           stablePasses++;
@@ -212,8 +207,7 @@ async function invokeRequestHeadersCommand(
     const trackPosixDescendants = () => {
       if (!USE_PROCESS_GROUP || child.pid === undefined || settled || trackingError) return;
       try {
-        for (const pid of collectPosixDescendantPids(child.pid)) trackedPosixDescendantPids.add(pid);
-        for (const pid of collectPosixCleanupTokenPids(cleanupToken)) trackedPosixDescendantPids.add(pid);
+        for (const pid of collectPosixProcessPids(child.pid, cleanupToken)) trackedPosixDescendantPids.add(pid);
       } catch (error) {
         trackingError = error instanceof Error ? error : new Error(String(error));
       }

package/node_modules/pi-mcp-adapter/search-ranking.ts

@@ -23,6 +23,26 @@ export interface RankedToolMatch {
   score: number;
 }
 
+type SearchField = Exclude<keyof typeof FIELD_WEIGHTS, "keywords">;
+
+interface PreparedToolSearch {
+  tool: ToolMetadata;
+  fields: Array<[SearchField, string, string[]]>;
+  nameTokens: string[];
+  keywordPhrases: string[];
+  keywordTokens: string[];
+}
+
+interface CachedServerSearch {
+  metadata: ToolMetadata[];
+  searchKeywords: ServerEntry["searchKeywords"];
+  toolPrefix: ReturnType<typeof resolveToolPrefix>;
+  withKeywords?: PreparedToolSearch[];
+  withoutKeywords?: PreparedToolSearch[];
+}
+
+const searchCache = new WeakMap<McpExtensionState, Map<string, CachedServerSearch>>();
+
 /**
  * Resolve the configured searchKeywords entries that apply to a tool.
  * Keys match by original name, prefixed name, or glob — the same candidate
@@ -64,25 +84,37 @@ export function tokenize(value: string): string[] {
   return normalizeSearchText(value).split(/[^a-z0-9]+/).filter(Boolean);
 }
 
-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;
-
+function prepareToolSearch(tool: ToolMetadata, server: string, keywords?: string[]): PreparedToolSearch {
   const fields = {
     name: normalizeSearchText(tool.name),
     originalName: normalizeSearchText(tool.originalName),
     server: normalizeSearchText(server),
     description: normalizeSearchText(tool.description),
   };
+  const preparedFields = (Object.entries(fields) as Array<[SearchField, string]>)
+    .map(([field, value]): [SearchField, string, string[]] => [field, value, tokenize(value)]);
+  const keywordPhrases = keywords?.map(keyword => normalizeSearchText(keyword).trim()).filter(Boolean) ?? [];
+  return {
+    tool,
+    fields: preparedFields,
+    nameTokens: preparedFields[0]![2],
+    keywordPhrases,
+    keywordTokens: keywordPhrases.flatMap(tokenize),
+  };
+}
+
+function scorePreparedToolMatch(
+  prepared: PreparedToolSearch,
+  normalizedQuery: string,
+  queryTokens: string[],
+): number | null {
   let score = 0;
   let phraseMatched = false;
   let wholeFieldExact = false;
   const matchedTokens = new Set<string>();
 
-  for (const [field, value] of Object.entries(fields) as Array<[keyof typeof FIELD_WEIGHTS, string]>) {
+  for (const [field, value, fieldTokens] of prepared.fields) {
     const weight = FIELD_WEIGHTS[field];
-    const fieldTokens = tokenize(value);
     if (value === normalizedQuery) {
       score += weight * 14;
       phraseMatched = true;
@@ -112,11 +144,10 @@ 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) {
+  if (prepared.keywordPhrases.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) {
+    for (const phrase of prepared.keywordPhrases) {
       if (phrase === normalizedQuery) {
         phraseScore = Math.max(phraseScore, weight * 14);
         phraseMatched = true;
@@ -131,15 +162,14 @@ export function scoreToolMatch(tool: ToolMetadata, server: string, query: string
     }
     score += phraseScore;
 
-    const keywordTokens = phrases.flatMap(tokenize);
     for (const token of queryTokens) {
-      if (keywordTokens.includes(token)) {
+      if (prepared.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)))) {
+      } else if (prepared.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))) {
+      } else if (prepared.keywordPhrases.some(phrase => phrase.includes(token))) {
         score += weight;
         matchedTokens.add(token);
       }
@@ -151,11 +181,52 @@ export function scoreToolMatch(tool: ToolMetadata, server: string, query: string
 
   score += coverage === 1 ? 25 : Math.round(coverage * 10);
   const firstQueryToken = queryTokens[0];
-  if (firstQueryToken !== undefined && tokenize(fields.name).includes(firstQueryToken)) score += 8;
+  if (firstQueryToken !== undefined && prepared.nameTokens.includes(firstQueryToken)) score += 8;
   if (wholeFieldExact) score += 20;
   return score;
 }
 
+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;
+  return scorePreparedToolMatch(prepareToolSearch(tool, server, keywords), normalizedQuery, queryTokens);
+}
+
+function getPreparedTools(
+  state: McpExtensionState,
+  serverName: string,
+  metadata: ToolMetadata[],
+  definition: ServerEntry | undefined,
+  globalPrefix: ToolPrefix,
+  includeKeywords: boolean,
+): PreparedToolSearch[] {
+  let stateCache = searchCache.get(state);
+  if (!stateCache) {
+    stateCache = new Map();
+    searchCache.set(state, stateCache);
+  }
+  const toolPrefix = resolveToolPrefix(definition, globalPrefix);
+  let cached = stateCache.get(serverName);
+  if (cached?.metadata !== metadata || cached.searchKeywords !== definition?.searchKeywords || cached.toolPrefix !== toolPrefix) {
+    cached = { metadata, searchKeywords: definition?.searchKeywords, toolPrefix };
+    stateCache.set(serverName, cached);
+  }
+  const cacheKey = includeKeywords ? "withKeywords" : "withoutKeywords";
+  let prepared = cached[cacheKey];
+  if (!prepared) {
+    prepared = metadata.map(tool => prepareToolSearch(
+      tool,
+      serverName,
+      includeKeywords && definition?.searchKeywords !== undefined
+        ? resolveSearchKeywords(definition, tool.originalName, serverName, globalPrefix)
+        : undefined,
+    ));
+    cached[cacheKey] = prepared;
+  }
+  return prepared;
+}
+
 export function rankToolMatches(
   state: McpExtensionState,
   query: string,
@@ -163,18 +234,17 @@ export function rankToolMatches(
   includeKeywords = true,
 ): RankedToolMatch[] {
   const matches: RankedToolMatch[] = [];
+  const normalizedQuery = normalizeSearchText(query).trim();
+  const queryTokens = tokenize(query);
+  if (queryTokens.length === 0) return matches;
   const globalPrefix = state.config.settings?.toolPrefix ?? "server";
   for (const [serverName, metadata] of state.toolMetadata.entries()) {
     if (server && serverName !== server) continue;
     const definition = state.config.mcpServers[serverName];
     if (isServerDisabled(definition)) continue;
-    const hasKeywords = includeKeywords && definition?.searchKeywords !== undefined;
-    for (const tool of metadata) {
-      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 });
+    for (const prepared of getPreparedTools(state, serverName, metadata, definition, globalPrefix, includeKeywords)) {
+      const score = scorePreparedToolMatch(prepared, normalizedQuery, queryTokens);
+      if (score !== null) matches.push({ server: serverName, tool: prepared.tool, score });
     }
   }
   return matches.sort((a, b) => b.score - a.score || a.tool.name.localeCompare(b.tool.name));