@evantahler/mcpx 0.20.1 → 0.21.1

package/.claude/skills/mcpx.md

@@ -162,8 +162,8 @@ mcpx deauth <server>           # remove stored auth
 | `mcpx deauth <server>`                | Remove stored authentication      |
 | `mcpx ping`                           | Check connectivity to all servers |
 | `mcpx ping <server> [server2...]`     | Check specific server(s)          |
-| `mcpx add <name> --command <cmd>`     | Add a stdio MCP server            |
-| `mcpx add <name> --url <url>`         | Add an HTTP MCP server            |
+| `mcpx add <name> --command <cmd>`     | Add a stdio MCP server                              |
+| `mcpx add [name] --url <url>`         | Add an HTTP MCP server (name derived from URL if omitted) |
 | `mcpx remove <name>`                  | Remove an MCP server              |
 | `mcpx skill install --claude`         | Install mcpx skill for Claude     |
 | `mcpx skill install --cursor`         | Install mcpx rule for Cursor      |

package/.cursor/rules/mcpx.mdc

@@ -158,8 +158,8 @@ mcpx deauth <server>           # remove stored auth
 | `mcpx deauth <server>`                | Remove stored authentication      |
 | `mcpx ping`                           | Check connectivity to all servers |
 | `mcpx ping <server> [server2...]`     | Check specific server(s)          |
-| `mcpx add <name> --command <cmd>`     | Add a stdio MCP server            |
-| `mcpx add <name> --url <url>`         | Add an HTTP MCP server            |
+| `mcpx add <name> --command <cmd>`     | Add a stdio MCP server                              |
+| `mcpx add [name] --url <url>`         | Add an HTTP MCP server (name derived from URL if omitted) |
 | `mcpx remove <name>`                  | Remove an MCP server              |
 | `mcpx skill install --claude`         | Install mcpx skill for Claude     |
 | `mcpx skill install --cursor`         | Install mcpx rule for Cursor      |

package/README.md

@@ -92,7 +92,7 @@ mcpx search -n 5 "manage pull requests"
 | `mcpx auth <server> -r`                | Force token refresh                                    |
 | `mcpx deauth <server>`                 | Remove stored authentication for a server              |
 | `mcpx add <name> --command <cmd>`      | Add a stdio MCP server to your config                  |
-| `mcpx add <name> --url <url>`          | Add an HTTP MCP server to your config                  |
+| `mcpx add [name] --url <url>`          | Add an HTTP MCP server (name derived from URL if omitted) |
 | `mcpx remove <name>`                   | Remove an MCP server from your config                  |
 | `mcpx ping`                            | Check connectivity to all configured servers           |
 | `mcpx ping <server> [server2...]`      | Check connectivity to specific server(s)               |
@@ -153,6 +153,11 @@ mcpx add filesystem --command npx --args "-y,@modelcontextprotocol/server-filesy
 # Add an HTTP server with headers
 mcpx add my-api --url https://api.example.com/mcp --header "Authorization:Bearer tok123"
 
+# When --url is used, the name is optional — derived from the URL's last path
+# segment (or hostname if there is none). The example below stores the server
+# under the name "evan-coding".
+mcpx add --url https://api.arcade.dev/mcp/evan-coding
+
 # Add with tool filtering (repeatable, or comma-separated)
 mcpx add github --url https://mcp.github.com --allowed-tools "search_*" --allowed-tools "get_*"
 
@@ -274,7 +279,7 @@ Contains every discovered tool with metadata for semantic search. Built and upda
 {
   "version": 1,
   "indexed_at": "2026-03-03T10:00:00Z",
-  "embedding_model": "Xenova/all-MiniLM-L6-v2",
+  "embedding_model": "Xenova/bge-small-en-v1.5",
   "tools": [
     {
       "server": "linear",
@@ -295,7 +300,7 @@ Each tool gets:
 - **keywords** — terms extracted by splitting the tool name on `_`, `-`, and camelCase boundaries
 - **embedding** — 384-dim vector for cosine similarity search
 
-Scenarios and keywords are extracted heuristically from tool names and descriptions. Embeddings are generated in-process using `Xenova/all-MiniLM-L6-v2` (~23MB ONNX model, downloaded on first run). No API keys needed.
+Scenarios and keywords are extracted heuristically from tool names and descriptions. Embeddings are generated in-process using `Xenova/bge-small-en-v1.5` (~33MB ONNX model, downloaded on first run). No API keys needed.
 
 ## Config Resolution Order
 
@@ -820,7 +825,7 @@ bun lint
 | MCP Client  | `@modelcontextprotocol/sdk`                           |
 | CLI Parsing | `commander`                                           |
 | Validation  | `ajv` (JSON Schema)                                   |
-| Embeddings  | `@huggingface/transformers` (Xenova/all-MiniLM-L6-v2) |
+| Embeddings  | `@huggingface/transformers` (Xenova/bge-small-en-v1.5) |
 
 ## Inspiration
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@evantahler/mcpx",
-	"version": "0.20.1",
+	"version": "0.21.1",
 	"description": "A command-line interface for MCP servers. curl for MCP.",
 	"type": "module",
 	"exports": {
@@ -25,6 +25,7 @@
 		"test:e2e": "bun test test/integration/remote-server.test.ts",
 		"lint": "biome ci . && tsc --noEmit",
 		"format": "biome check --write .",
+		"prebuild": "bash scripts/apply-transformers-patch.sh",
 		"build": "bun build --compile --minify --sourcemap ./src/cli.ts --outfile dist/mcpx"
 	},
 	"publishConfig": {
@@ -51,6 +52,7 @@
 		"ansis": "^4.2.0",
 		"commander": "^14.0.3",
 		"nanospinner": "^1.2.2",
+		"onnxruntime-web": "1.26.0-dev.20260416-b7804b056c",
 		"picomatch": "^4.0.4",
 		"@types/picomatch": "^4.0.3"
 	},

package/src/client/elicitation.ts

@@ -283,16 +283,35 @@ async function promptMultiSelect(
 // URL mode
 // ---------------------------------------------------------------------------
 
-async function handleUrlElicitation(
+export async function handleUrlElicitation(
 	params: ElicitRequestURLParams,
 	options: ElicitationOptions,
 ): Promise<ElicitResult> {
 	if (options.json) {
 		return handleUrlJson(params);
 	}
+	if (options.noInteractive) {
+		printUrlElicitation(params);
+		return { action: "decline" };
+	}
 	return handleUrlInteractive(params);
 }
 
+function printUrlElicitation(params: ElicitRequestURLParams): void {
+	const domain = (() => {
+		try {
+			return new URL(params.url).hostname;
+		} catch {
+			return "unknown";
+		}
+	})();
+
+	logger.writeRaw(`\n${ansis.bold("Server requests URL interaction:")}\n`);
+	logger.writeRaw(`  ${params.message}\n`);
+	logger.writeRaw(`  ${ansis.yellow("Domain:")} ${domain}\n`);
+	logger.writeRaw(`  ${ansis.yellow("URL:")} ${params.url}\n`);
+}
+
 async function handleUrlJson(params: ElicitRequestURLParams): Promise<ElicitResult> {
 	const request = {
 		type: "elicitation",
@@ -313,32 +332,70 @@ async function handleUrlJson(params: ElicitRequestURLParams): Promise<ElicitResu
 }
 
 async function handleUrlInteractive(params: ElicitRequestURLParams): Promise<ElicitResult> {
-	const rl = createInterface({ input: process.stdin, output: process.stderr });
-	const question = (prompt: string): Promise<string> => new Promise((resolve) => rl.question(prompt, resolve));
-
-	try {
-		const domain = (() => {
-			try {
-				return new URL(params.url).hostname;
-			} catch {
-				return "unknown";
-			}
-		})();
+	printUrlElicitation(params);
 
-		logger.writeRaw(`\n${ansis.bold("Server requests URL interaction:")}\n`);
-		logger.writeRaw(`  ${params.message}\n`);
-		logger.writeRaw(`  ${ansis.yellow("Domain:")} ${domain}\n`);
-		logger.writeRaw(`  ${ansis.yellow("URL:")} ${params.url}\n`);
+	const yes = await promptYesNo(`  Open in browser? [y/n]: `);
+	if (yes) {
+		await openBrowser(params.url);
+		return { action: "accept" };
+	}
+	return { action: "decline" };
+}
 
-		const answer = await question(`  Open in browser? [y/n]: `);
-		if (["y", "yes"].includes(answer.toLowerCase())) {
-			await openBrowser(params.url);
-			return { action: "accept" };
-		}
-		return { action: "decline" };
-	} finally {
-		rl.close();
+/**
+ * Prompt for a yes/no answer.
+ * On a TTY, accepts a single keypress (y/Y/n/N/Enter/Esc) without requiring Enter.
+ * Off a TTY, falls back to line-buffered input so piped tests still work.
+ */
+function promptYesNo(prompt: string): Promise<boolean> {
+	logger.writeRaw(prompt);
+	const stdin = process.stdin;
+
+	if (!stdin.isTTY) {
+		return new Promise((resolve) => {
+			const rl = createInterface({ input: stdin });
+			rl.once("line", (line) => {
+				rl.close();
+				const ch = line.trim().toLowerCase();
+				resolve(ch === "y" || ch === "yes");
+			});
+			rl.once("close", () => resolve(false));
+		});
 	}
+
+	return new Promise((resolve) => {
+		stdin.setRawMode(true);
+		stdin.resume();
+
+		const cleanup = () => {
+			stdin.removeListener("data", onData);
+			stdin.setRawMode(false);
+			stdin.pause();
+		};
+
+		const onData = (data: Buffer) => {
+			const key = data.toString();
+			// Ctrl+C
+			if (key === "\u0003") {
+				cleanup();
+				logger.writeRaw("\n");
+				process.exit(130);
+			}
+			const ch = key.toLowerCase();
+			if (ch === "y") {
+				cleanup();
+				logger.writeRaw("y\n");
+				resolve(true);
+			} else if (ch === "n" || key === "\u001b") {
+				cleanup();
+				logger.writeRaw("n\n");
+				resolve(false);
+			}
+			// Ignore other keys
+		};
+
+		stdin.on("data", onData);
+	});
 }
 
 // ---------------------------------------------------------------------------

package/src/client/manager.ts

@@ -13,6 +13,7 @@ import {
 	CallToolResultSchema,
 	ElicitRequestSchema,
 	LoggingMessageNotificationSchema,
+	UrlElicitationRequiredError,
 } from "@modelcontextprotocol/sdk/types.js";
 import picomatch from "picomatch";
 import pkg from "../../package.json";
@@ -305,6 +306,8 @@ export class ServerManager {
 				return await fn();
 			} catch (err) {
 				lastError = err instanceof Error ? err : new Error(String(err));
+				// Don't retry auth challenges — the user needs to authorize first
+				if (err instanceof UrlElicitationRequiredError) throw lastError;
 				if (attempt < this.maxRetries && serverName) {
 					// Clear cached client so next attempt reconnects fresh
 					try {

package/src/commands/add.ts

@@ -2,12 +2,13 @@ import type { Command } from "commander";
 import { resolveResourceUrl, tryOAuthIfSupported } from "../client/oauth.ts";
 import { loadRawAuth, loadRawServers, saveServers } from "../config/loader.ts";
 import type { ServerConfig } from "../config/schemas.ts";
+import { logger } from "../output/logger.ts";
 import { runIndex } from "./index.ts";
 
 export function registerAddCommand(program: Command) {
 	program
-		.command("add <name> [passthroughArgs...]")
-		.description("add an MCP server to your config")
+		.command("add [name] [passthroughArgs...]")
+		.description("add an MCP server to your config (name derived from URL when omitted with --url)")
 		.option("--command <cmd>", "command to run (stdio server)")
 		.option("--args <arg>", "argument for the command (repeatable, comma-separated, or pass after --)", collect, [])
 		.option("--env <KEY=VAL>", "environment variable (repeatable or comma-separated)", collect, [])
@@ -22,7 +23,7 @@ export function registerAddCommand(program: Command) {
 		.option("--no-index", "skip rebuilding the search index after adding")
 		.action(
 			async (
-				name: string,
+				name: string | undefined,
 				passthroughArgs: string[],
 				options: {
 					command?: string;
@@ -55,6 +56,23 @@ export function registerAddCommand(program: Command) {
 					process.exit(1);
 				}
 
+				if (!name) {
+					if (hasUrl) {
+						const derived = deriveNameFromUrl(options.url!);
+						if (!derived) {
+							console.error(`Could not derive a server name from URL "${options.url}". Pass an explicit name.`);
+							process.exit(1);
+						}
+						name = derived;
+						logger.warn(
+							`Using derived server name "${name}". Pass an explicit name to override: mcpx add <name> --url ${options.url}`,
+						);
+					} else {
+						console.error("A server name is required when using --command. Usage: mcpx add <name> --command <cmd>");
+						process.exit(1);
+					}
+				}
+
 				const configFlag = program.opts().config;
 				const { configDir, servers } = await loadRawServers(configFlag);
 
@@ -133,6 +151,48 @@ function collect(value: string, previous: string[]): string[] {
 	return previous.concat([value]);
 }
 
+function sanitizeName(s: string): string {
+	return s
+		.toLowerCase()
+		.replace(/[^a-z0-9_-]+/g, "-")
+		.replace(/^-+|-+$/g, "");
+}
+
+// Generic path segments that don't make good server names on their own
+// (e.g. https://mcp.linear.app/mcp should derive "linear", not "mcp").
+const GENERIC_SEGMENTS = new Set(["mcp", "api", "sse", "v1", "v2", "v3", "rpc"]);
+
+// Derive a server name from a URL. Strategy:
+//   1. Walk path segments from last to first; return the first non-generic one.
+//   2. Otherwise fall back to the second-to-last hostname label
+//      (e.g. "mcp.linear.app" → "linear", "api.arcade.dev" → "arcade").
+//   3. Otherwise fall back to the full hostname.
+export function deriveNameFromUrl(rawUrl: string): string | null {
+	let parsed: URL;
+	try {
+		parsed = new URL(rawUrl);
+	} catch {
+		return null;
+	}
+
+	const segments = parsed.pathname.split("/").filter((s) => s.length > 0);
+	for (let i = segments.length - 1; i >= 0; i--) {
+		const candidate = sanitizeName(segments[i]!);
+		if (candidate.length > 1 && !GENERIC_SEGMENTS.has(candidate)) {
+			return candidate;
+		}
+	}
+
+	const hostnameParts = parsed.hostname.split(".").filter((s) => s.length > 0);
+	if (hostnameParts.length >= 2) {
+		const secondToLast = sanitizeName(hostnameParts[hostnameParts.length - 2]!);
+		if (secondToLast.length > 0) return secondToLast;
+	}
+
+	const fullHost = sanitizeName(parsed.hostname);
+	return fullHost.length > 0 ? fullHost : null;
+}
+
 // Flatten a list of repeated CLI values, splitting each on commas and trimming.
 // Supports both `--flag a --flag b` and `--flag "a,b"` forms.
 function splitCommaList(values: string[]): string[] {

package/src/commands/exec.ts

@@ -1,4 +1,6 @@
+import { UrlElicitationRequiredError } from "@modelcontextprotocol/sdk/types.js";
 import type { Command } from "commander";
+import { handleUrlElicitation } from "../client/elicitation.ts";
 import type { ServerManager } from "../client/manager.ts";
 import { DEFAULTS } from "../constants.ts";
 import { getContext } from "../context.ts";
@@ -108,7 +110,7 @@ export function registerExecCommand(program: Command) {
 				trailing: string[],
 				options: { file?: string; wait: boolean; ttl: string },
 			) => {
-				const { manager, formatOptions } = await getContext(program);
+				const { manager, formatOptions, noInteractive } = await getContext(program);
 
 				let resolved: ResolvedArgs;
 				try {
@@ -252,11 +254,22 @@ export function registerExecCommand(program: Command) {
 					} else {
 						// Standard synchronous tool call
 						const spinner = logger.startSpinner(`Executing ${server}/${tool}...`, formatOptions);
-						const result = await manager.callTool(server, tool, args);
-						spinner.stop();
+						let result: unknown;
+						try {
+							result = await manager.callTool(server, tool, args);
+						} finally {
+							spinner.stop();
+						}
 						console.log(formatCallResult(result, formatOptions));
 					}
 				} catch (err) {
+					if (err instanceof UrlElicitationRequiredError) {
+						const elicitOptions = { noInteractive, json: !!formatOptions.json };
+						for (const elicitation of err.elicitations) {
+							await handleUrlElicitation(elicitation, elicitOptions);
+						}
+						process.exit(1);
+					}
 					console.error(formatError(String(err), formatOptions));
 					process.exit(1);
 				} finally {

package/src/commands/search.ts

@@ -1,10 +1,10 @@
 import type { Command } from "commander";
-import { DEFAULTS } from "../constants.ts";
+import { DEFAULTS, EMBEDDING_MODEL } from "../constants.ts";
 import { getContext } from "../context.ts";
 import { formatError, formatSearchResults } from "../output/formatter.ts";
 import { logger } from "../output/logger.ts";
 import { search } from "../search/index.ts";
-import { getStaleServers } from "../search/staleness.ts";
+import { getStaleServers, isEmbeddingModelStale } from "../search/staleness.ts";
 
 export function registerSearchCommand(program: Command) {
 	program
@@ -17,6 +17,13 @@ export function registerSearchCommand(program: Command) {
 			const query = terms.join(" ");
 			const { config, formatOptions } = await getContext(program);
 
+			if (isEmbeddingModelStale(config.searchIndex)) {
+				logger.warn(
+					`Index was built with embedding model "${config.searchIndex.embedding_model}", but mcpx now uses "${EMBEDDING_MODEL.REPO}". Run: mcpx index`,
+				);
+				config.searchIndex.tools = [];
+			}
+
 			if (config.searchIndex.tools.length === 0) {
 				console.error(formatError("No search index found. Run: mcpx index", formatOptions));
 				process.exit(1);

package/src/constants.ts

@@ -26,3 +26,9 @@ export const DEFAULTS = {
 	UPDATE_CHECK_INTERVAL_MS: 24 * 60 * 60 * 1000,
 	UPDATE_CHECK_TIMEOUT_MS: 5_000,
 } as const;
+
+/** Hugging Face repo + revision used for the bundled embedding model. */
+export const EMBEDDING_MODEL = {
+	REPO: "Xenova/bge-small-en-v1.5",
+	REVISION: "main",
+} as const;

package/src/context.ts

@@ -10,6 +10,7 @@ export interface AppContext {
 	config: Config;
 	manager: ServerManager;
 	formatOptions: FormatOptions;
+	noInteractive: boolean;
 }
 
 /** Build the app context from the root commander program options */
@@ -67,5 +68,5 @@ export async function getContext(program: Command): Promise<AppContext> {
 
 	logger.configure(formatOptions);
 
-	return { config, manager, formatOptions };
+	return { config, manager, formatOptions, noInteractive };
 }

package/src/output/formatter.ts

@@ -363,16 +363,25 @@ function formatCallResultAsMarkdown(result: unknown): string {
 			mimeType?: string;
 			uri?: string;
 		}>;
+		structuredContent?: unknown;
+		_meta?: unknown;
 		isError?: boolean;
 	};
 
-	if (!r.content || !Array.isArray(r.content) || r.content.length === 0) {
+	const hasContent = Array.isArray(r.content) && r.content.length > 0;
+	const hasStructured = r.structuredContent !== undefined && r.structuredContent !== null;
+	const hasMeta =
+		r._meta !== undefined &&
+		r._meta !== null &&
+		!(typeof r._meta === "object" && Object.keys(r._meta as object).length === 0);
+
+	if (!hasContent && !hasStructured && !hasMeta) {
 		return renderMarkdownToAnsi(jsonToMarkdown(result));
 	}
 
 	const parts: string[] = [];
 
-	for (const block of r.content) {
+	for (const block of r.content ?? []) {
 		switch (block.type) {
 			case "text":
 				if (block.text !== undefined) {
@@ -390,15 +399,31 @@ function formatCallResultAsMarkdown(result: unknown): string {
 					`[image: ${block.mimeType ?? "unknown type"}, ${block.data ? Math.ceil((block.data.length * 3) / 4) : 0} bytes]`,
 				);
 				break;
+			case "audio":
+				parts.push(
+					`[audio: ${block.mimeType ?? "unknown type"}, ${block.data ? Math.ceil((block.data.length * 3) / 4) : 0} bytes]`,
+				);
+				break;
 			case "resource":
 				parts.push(`[resource: ${block.uri ?? "unknown"}]`);
 				break;
+			case "resource_link":
+				parts.push(`[resource_link: ${block.uri ?? "unknown"}]`);
+				break;
 			default:
-				parts.push(`[${block.type}]`);
+				parts.push(`[${block.type}]\n\n\`\`\`json\n${JSON.stringify(block, null, 2)}\n\`\`\``);
 				break;
 		}
 	}
 
+	if (hasStructured) {
+		parts.push(`**Structured Content:**\n\n${jsonToMarkdown(r.structuredContent)}`);
+	}
+
+	if (hasMeta) {
+		parts.push(`**Meta:**\n\n${jsonToMarkdown(r._meta)}`);
+	}
+
 	let output = parts.join("\n\n");
 	if (r.isError) {
 		output = `**error:** ${output}`;

package/src/search/indexer.ts

@@ -1,5 +1,6 @@
 import type { ServerManager, ToolWithServer } from "../client/manager.ts";
 import type { IndexedTool, SearchIndex } from "../config/schemas.ts";
+import { EMBEDDING_MODEL } from "../constants.ts";
 import { logger } from "../output/logger.ts";
 import { generateEmbedding } from "./semantic.ts";
 
@@ -86,7 +87,7 @@ export async function buildSearchIndex(
 	return {
 		version: 1,
 		indexed_at: new Date().toISOString(),
-		embedding_model: "Xenova/all-MiniLM-L6-v2",
+		embedding_model: EMBEDDING_MODEL.REPO,
 		tools: indexed,
 	};
 }

package/src/search/onnx-wasm-paths.ts

@@ -0,0 +1,20 @@
+// Embed the onnxruntime-web WASM runtime files into the compiled binary
+// (`bun build --compile`) so they survive in a single-binary distribution
+// where the user has no node_modules.
+//
+// This file is loaded **dynamically** by semantic.ts. The relative paths
+// only resolve in the local repo / compiled binary; for npm/bun-installed
+// mcpx the parent directory layout is different (deps are hoisted), the
+// dynamic import throws, and we fall back to letting transformers.js
+// load WASM via its default mechanism — which works fine because in
+// that environment node_modules exists and onnxruntime-web is reachable
+// through normal module resolution.
+
+import wasmMjsPath from "../../node_modules/onnxruntime-web/dist/ort-wasm-simd-threaded.asyncify.mjs" with {
+	type: "file",
+};
+import wasmBinPath from "../../node_modules/onnxruntime-web/dist/ort-wasm-simd-threaded.asyncify.wasm" with {
+	type: "file",
+};
+
+export { wasmBinPath, wasmMjsPath };

package/src/search/semantic.ts

@@ -1,5 +1,8 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
 import type { IndexedTool } from "../config/schemas.ts";
-import { DEFAULTS } from "../constants.ts";
+import { DEFAULTS, EMBEDDING_MODEL } from "../constants.ts";
+import { logger } from "../output/logger.ts";
 import type { BaseMatch } from "./types.ts";
 
 export type SemanticMatch = BaseMatch;
@@ -11,9 +14,51 @@ let pipelineInstance: ((text: string) => Promise<Float32Array>) | null = null;
 async function getEmbedder(): Promise<(text: string) => Promise<Float32Array>> {
 	if (pipelineInstance) return pipelineInstance;
 
-	const { pipeline } = await import("@huggingface/transformers");
-	const extractor = await pipeline("feature-extraction", "Xenova/all-MiniLM-L6-v2", {
-		dtype: "fp32",
+	const transformers = await import("@huggingface/transformers");
+
+	// transformers.js is patched (see patches/@huggingface%2Ftransformers@4.2.0.patch,
+	// applied by `bun run scripts/apply-transformers-patch.sh` during prebuild) to
+	// force the WASM backend instead of onnxruntime-node — the native bindings can't
+	// be bundled into the Bun --compile single binary.
+	const ortWasm = transformers.env.backends.onnx?.wasm;
+	if (ortWasm) {
+		ortWasm.numThreads = 1;
+		ortWasm.proxy = false;
+
+		// For the compiled binary, embed the onnxruntime-web .wasm/.mjs files via
+		// Bun's `with { type: "file" }` and point the loader at them. The dynamic
+		// import is wrapped in a try because the asset paths only resolve in the
+		// local repo / compiled binary; for npm/bun-installed mcpx the deps are
+		// hoisted to a different layout, the import throws, and transformers.js
+		// loads WASM via its default mechanism (which works because node_modules
+		// is reachable in that environment).
+		try {
+			const { wasmMjsPath, wasmBinPath } = await import("./onnx-wasm-paths.ts");
+			const toFileUrl = (p: string) => (p.startsWith("file://") ? p : `file://${p}`);
+			ortWasm.wasmPaths = {
+				mjs: toFileUrl(wasmMjsPath),
+				wasm: toFileUrl(wasmBinPath),
+			};
+		} catch (err) {
+			logger.debug(`Bundled onnxruntime-web assets not found, using default loader: ${err}`);
+		}
+	}
+
+	// Inside a `bun build --compile` binary, `import.meta.url` resolves under the
+	// read-only `/$bunfs` virtual filesystem, so transformers' default cacheDir
+	// becomes unwritable. Redirect cache to the user's home so model downloads
+	// (and any future cached files) land somewhere we can write to.
+	const userCacheDir = join(homedir(), ".cache", "mcpx", "transformers");
+	transformers.env.cacheDir = userCacheDir;
+	transformers.env.localModelPath = join(userCacheDir, "models");
+
+	// WASM device defaults to q8 quantization, which gives near-identical
+	// embedding quality at ~25% the model size (≈22 MB vs ≈86 MB for fp32).
+	// Both CI and `bun run build` apply the transformers patch first, so
+	// wasm is the only supported device in this codepath.
+	const extractor = await transformers.pipeline("feature-extraction", EMBEDDING_MODEL.REPO, {
+		device: "wasm",
+		dtype: "q8",
 	});
 
 	pipelineInstance = async (text: string): Promise<Float32Array> => {

package/src/search/staleness.ts

@@ -1,4 +1,5 @@
 import type { SearchIndex, ServersFile } from "../config/schemas.ts";
+import { EMBEDDING_MODEL } from "../constants.ts";
 
 /** Return server names that appear in the index but not in the current config */
 export function getStaleServers(index: SearchIndex, servers: ServersFile): string[] {
@@ -6,3 +7,8 @@ export function getStaleServers(index: SearchIndex, servers: ServersFile): strin
 	const indexed = new Set(index.tools.map((t) => t.server));
 	return [...indexed].filter((s) => !configured.has(s));
 }
+
+/** Return true if the index was built with a different embedding model than the one we'd use now. */
+export function isEmbeddingModelStale(index: SearchIndex): boolean {
+	return index.tools.length > 0 && index.embedding_model !== EMBEDDING_MODEL.REPO;
+}

package/src/types/file-imports.d.ts

@@ -0,0 +1,14 @@
+// Type declarations for Bun's `import ... with { type: "file" }` asset embedding.
+// TS doesn't natively know how to resolve `.wasm` or `.mjs` modules, so we
+// declare them as default-exporting strings (Bun returns the embedded file's
+// runtime path).
+
+declare module "*.wasm" {
+	const path: string;
+	export default path;
+}
+
+declare module "*.mjs" {
+	const path: string;
+	export default path;
+}