muxed 0.1.1 → 0.2.1

package/dist/cli.mjs

@@ -3,17 +3,20 @@ import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
 import { z } from "zod/v4";
+import * as z$1 from "zod";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { SSEClientTransport, SseError } from "@modelcontextprotocol/sdk/client/sse.js";
 import { StreamableHTTPClientTransport, StreamableHTTPError } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { UnauthorizedError } from "@modelcontextprotocol/sdk/client/auth.js";
 import { LATEST_PROTOCOL_VERSION } from "@modelcontextprotocol/sdk/types.js";
+import crypto from "node:crypto";
 import { execFile, fork } from "node:child_process";
 import http from "node:http";
 import { compile } from "json-schema-to-typescript";
 import net from "node:net";
 import { Command } from "commander";
+import { PostHog } from "posthog-node";
 import * as readline from "node:readline/promises";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -31,7 +34,8 @@ const StdioServerConfigSchema = z.object({
 	command: z.string(),
 	args: z.array(z.string()).optional(),
 	env: z.record(z.string(), z.string()).optional(),
-	cwd: z.string().optional()
+	cwd: z.string().optional(),
+	timeout: z.number().optional()
 });
 const ReconnectionSchema = z.object({
 	maxDelay: z.number().optional(),
@@ -59,7 +63,8 @@ const HttpServerConfigSchema = z.object({
 	headers: z.record(z.string(), z.string()).optional(),
 	sessionId: z.string().optional(),
 	reconnection: ReconnectionSchema.optional(),
-	auth: OAuthConfigSchema.optional()
+	auth: OAuthConfigSchema.optional(),
+	timeout: z.number().optional()
 });
 const ServerConfigSchema = z.union([StdioServerConfigSchema, HttpServerConfigSchema]);
 const HttpListenerSchema = z.object({
@@ -113,7 +118,7 @@ function mergeClaudeDesktopServers(servers) {
 const DAEMON_DEFAULTS = {
 	idleTimeout: 3e5,
 	connectTimeout: 3e4,
-	requestTimeout: 6e4,
+	requestTimeout: 3e4,
 	healthCheckInterval: 3e4,
 	maxRestartAttempts: -1,
 	maxTotalTimeout: 3e5,
@@ -122,7 +127,7 @@ const DAEMON_DEFAULTS = {
 	shutdownTimeout: 1e4
 };
 function getGlobalConfigPath() {
-	return path.join(os.homedir(), ".config", "muxed", "config.json");
+	return path.join(os.homedir(), ".muxed", "config.json");
 }
 function findConfigFile(configPath) {
 	if (configPath) {
@@ -295,11 +300,14 @@ function initLogger(opts) {
 function sanitizeName(name) {
 	return name.replace(/[^a-zA-Z0-9_-]/g, "_");
 }
+function hashName(name) {
+	return crypto.createHash("sha256").update(name).digest("hex").slice(0, 8);
+}
 function getAuthDir() {
 	return path.join(getMuxedDir(), "auth");
 }
 function getStorePath(serverName) {
-	return path.join(getAuthDir(), `${sanitizeName(serverName)}.json`);
+	return path.join(getAuthDir(), `${sanitizeName(serverName)}-${hashName(serverName)}.json`);
 }
 function ensureAuthDir() {
 	fs.mkdirSync(getAuthDir(), {
@@ -365,9 +373,8 @@ var TokenStore = class {
 		writeStore(this.serverName, data);
 	}
 	clearAll() {
-		const filePath = getStorePath(this.serverName);
 		try {
-			fs.unlinkSync(filePath);
+			fs.unlinkSync(getStorePath(this.serverName));
 		} catch {}
 	}
 	hasTokens() {
@@ -467,6 +474,7 @@ var AuthorizationCodeProvider = class {
 	config;
 	_redirectUrl;
 	hadTokensBefore = false;
+	_state = crypto.randomBytes(32).toString("base64url");
 	constructor(config, serverName) {
 		this.serverName = serverName;
 		this.config = config;
@@ -474,14 +482,14 @@ var AuthorizationCodeProvider = class {
 		this.hadTokensBefore = this.store.hasTokens();
 	}
 	setRedirectUrl(port) {
-		this._redirectUrl = `http://127.0.0.1:${port}/oauth/callback`;
+		this._redirectUrl = `http://localhost:${port}/callback`;
 	}
 	get redirectUrl() {
 		return this._redirectUrl;
 	}
 	get clientMetadata() {
 		return {
-			redirect_uris: [this._redirectUrl ?? "http://127.0.0.1/oauth/callback"],
+			redirect_uris: [this._redirectUrl ?? "http://localhost/callback"],
 			token_endpoint_auth_method: this.config.clientSecret ? "client_secret_basic" : "none",
 			grant_types: ["authorization_code", "refresh_token"],
 			response_types: ["code"],
@@ -494,7 +502,14 @@ var AuthorizationCodeProvider = class {
 			client_id: this.config.clientId,
 			...this.config.clientSecret ? { client_secret: this.config.clientSecret } : {}
 		};
-		return this.store.getClientInformation();
+		const cached = this.store.getClientInformation();
+		if (cached && this._redirectUrl) {
+			if (!(cached.redirect_uris ?? []).includes(this._redirectUrl)) {
+				this.store.clearClientInformation();
+				return;
+			}
+		}
+		return cached;
 	}
 	saveClientInformation(info) {
 		this.store.saveClientInformation(info);
@@ -515,6 +530,9 @@ var AuthorizationCodeProvider = class {
 			openBrowser(url);
 		}
 	}
+	async state() {
+		return this._state;
+	}
 	saveCodeVerifier(codeVerifier) {
 		this.store.saveCodeVerifier(codeVerifier);
 	}
@@ -573,8 +591,8 @@ var CallbackServer = class {
 					res.end();
 					return;
 				}
-				const url = new URL(req.url ?? "/", `http://127.0.0.1`);
-				if (url.pathname !== "/oauth/callback") {
+				const url = new URL(req.url ?? "/", `http://localhost`);
+				if (url.pathname !== "/callback") {
 					res.writeHead(404);
 					res.end("Not found");
 					return;
@@ -608,7 +626,7 @@ var CallbackServer = class {
 					state
 				});
 			});
-			this.server.listen(port, "127.0.0.1", () => {
+			this.server.listen(port, "localhost", () => {
 				const addr = this.server.address();
 				if (addr && typeof addr === "object") this._port = addr.port;
 			});
@@ -1051,9 +1069,108 @@ var ServerManager = class {
 		};
 	}
 };
+const ErrorCode = {
+	TOOL_NOT_FOUND: "TOOL_NOT_FOUND",
+	SERVER_NOT_FOUND: "SERVER_NOT_FOUND",
+	SERVER_NOT_CONNECTED: "SERVER_NOT_CONNECTED",
+	INVALID_ARGUMENTS: "INVALID_ARGUMENTS",
+	INVALID_FORMAT: "INVALID_FORMAT",
+	MISSING_PARAMETER: "MISSING_PARAMETER",
+	TIMEOUT: "TIMEOUT"
+};
+function levenshtein(a, b) {
+	const m = a.length;
+	const n = b.length;
+	const dp = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0));
+	for (let i = 0; i <= m; i++) dp[i][0] = i;
+	for (let j = 0; j <= n; j++) dp[0][j] = j;
+	for (let i = 1; i <= m; i++) for (let j = 1; j <= n; j++) dp[i][j] = a[i - 1] === b[j - 1] ? dp[i - 1][j - 1] : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+	return dp[m][n];
+}
+function findSimilarTools(targetTool, allTools, maxResults = 3) {
+	const maxDistance = Math.max(3, Math.floor(targetTool.length * .4));
+	return allTools.map(({ server, tool }) => {
+		const fullName = `${server}/${tool.name}`;
+		const toolOnly = tool.name;
+		const distFull = levenshtein(targetTool.toLowerCase(), fullName.toLowerCase());
+		const distTool = levenshtein(targetTool.toLowerCase(), toolOnly.toLowerCase());
+		return {
+			fullName,
+			dist: Math.min(distFull, distTool)
+		};
+	}).filter(({ dist }) => dist <= maxDistance).sort((a, b) => a.dist - b.dist).slice(0, maxResults).map(({ fullName }) => fullName);
+}
+function toolNotFoundError(name, similarTools) {
+	const hasSimilar = similarTools.length > 0;
+	const suggestion = hasSimilar ? `Did you mean: ${similarTools.join(", ")}? Run 'muxed grep <pattern>' to search available tools.` : `Run 'muxed grep <pattern>' to find available tools, or 'muxed tools' to list all.`;
+	return {
+		code: ErrorCode.TOOL_NOT_FOUND,
+		message: `Tool not found: ${name}`,
+		suggestion,
+		context: hasSimilar ? { similarTools } : void 0
+	};
+}
+function serverNotFoundError(serverName, availableServers) {
+	return {
+		code: ErrorCode.SERVER_NOT_FOUND,
+		message: `Server not found: ${serverName}`,
+		suggestion: `Available servers: ${availableServers.join(", ") || "none"}. Run 'muxed servers' to list all.`,
+		context: { availableServers }
+	};
+}
+function serverNotConnectedError(serverName) {
+	return {
+		code: ErrorCode.SERVER_NOT_CONNECTED,
+		message: `Server not connected: ${serverName}`,
+		suggestion: `The server may be starting up. Run 'muxed status' to check, or 'muxed reload' to reconnect.`
+	};
+}
+function invalidFormatError(name) {
+	return {
+		code: ErrorCode.INVALID_FORMAT,
+		message: `Invalid tool name format: ${name}`,
+		suggestion: `Use the format 'server/tool' (e.g. 'myserver/mytool'). Run 'muxed tools' to list all available tools.`
+	};
+}
+function missingParameterError(param) {
+	return {
+		code: ErrorCode.MISSING_PARAMETER,
+		message: `Missing required parameter: ${param}`,
+		suggestion: `Provide the '${param}' parameter in the request.`
+	};
+}
+function invalidArgumentsError(toolName, errors) {
+	return {
+		code: ErrorCode.INVALID_ARGUMENTS,
+		message: `Invalid arguments for tool ${toolName}`,
+		suggestion: `Run 'muxed info ${toolName}' to see the expected input schema.`,
+		context: { validationErrors: errors }
+	};
+}
+function timeoutError(toolName, timeoutMs) {
+	return {
+		code: ErrorCode.TIMEOUT,
+		message: `Tool call timed out after ${timeoutMs}ms: ${toolName}`,
+		suggestion: `Increase the timeout with --timeout <ms>, or use --async for long-running operations.`
+	};
+}
+function isTimeoutError(err) {
+	if (!(err instanceof Error)) return false;
+	if (err.name === "TimeoutError" || err.name === "AbortError") return true;
+	const msg = err.message.toLowerCase();
+	return msg.includes("timeout") || msg.includes("aborted");
+}
+function toErrorData(err) {
+	return {
+		code: err.code,
+		suggestion: err.suggestion,
+		...err.context ? { context: err.context } : {}
+	};
+}
 var ServerPool = class {
 	servers = /* @__PURE__ */ new Map();
 	trackedTasks = /* @__PURE__ */ new Map();
+	zodSchemaCache = /* @__PURE__ */ new Map();
 	taskExpiryTimer;
 	taskExpiryTimeout = 36e5;
 	async connectAll(config) {
@@ -1080,6 +1197,7 @@ var ServerPool = class {
 	}
 	async disconnectAll() {
 		this.stopTaskExpiry();
+		this.zodSchemaCache.clear();
 		await Promise.allSettled([...this.servers.values()].map((manager) => manager.disconnect()));
 	}
 	onServerHealthChange(serverName, status, error) {
@@ -1157,6 +1275,91 @@ var ServerPool = class {
 			tool
 		};
 	}
+	findToolOrError(serverTool) {
+		const slashIndex = serverTool.indexOf("/");
+		if (slashIndex === -1) return {
+			ok: false,
+			error: invalidFormatError(serverTool)
+		};
+		const serverName = serverTool.slice(0, slashIndex);
+		const toolName = serverTool.slice(slashIndex + 1);
+		const manager = this.servers.get(serverName);
+		if (!manager) return {
+			ok: false,
+			error: serverNotFoundError(serverName, [...this.servers.keys()])
+		};
+		if (manager.getStatus() !== "connected") return {
+			ok: false,
+			error: serverNotConnectedError(serverName)
+		};
+		const tool = manager.listTools().find((t) => t.name === toolName);
+		if (!tool) return {
+			ok: false,
+			error: toolNotFoundError(serverTool, findSimilarTools(serverTool, this.listAllTools()))
+		};
+		return {
+			ok: true,
+			manager,
+			tool,
+			serverTimeout: manager.getState().config.timeout
+		};
+	}
+	getZodSchema(inputSchema) {
+		const key = JSON.stringify(inputSchema);
+		const cached = this.zodSchemaCache.get(key);
+		if (cached !== void 0) return cached;
+		try {
+			const zodSchema = z$1.fromJSONSchema(inputSchema);
+			this.zodSchemaCache.set(key, zodSchema);
+			return zodSchema;
+		} catch {
+			this.zodSchemaCache.set(key, "unsupported");
+			return "unsupported";
+		}
+	}
+	validateToolArgs(serverTool, args) {
+		const found = this.findToolOrError(serverTool);
+		if (!found.ok) return {
+			valid: false,
+			errors: [found.error.message],
+			warnings: []
+		};
+		const { tool } = found;
+		const errors = [];
+		const warnings = [];
+		if (tool.inputSchema) {
+			const zodSchema = this.getZodSchema(tool.inputSchema);
+			if (zodSchema === "unsupported") {
+				getLogger().warn(`Could not convert inputSchema for ${serverTool}: unsupported schema`, serverTool.split("/")[0]);
+				this.addAnnotationWarnings(tool, warnings);
+				return {
+					valid: true,
+					errors: [],
+					warnings,
+					unsupported: true,
+					tool
+				};
+			}
+			const result = zodSchema.safeParse(args);
+			if (!result.success) for (const issue of result.error.issues) {
+				const path = issue.path.length > 0 ? issue.path.join(".") : "";
+				const prefix = path ? `Field '${path}': ` : "";
+				errors.push(`${prefix}${issue.message}`);
+			}
+		}
+		this.addAnnotationWarnings(tool, warnings);
+		return {
+			valid: errors.length === 0,
+			errors,
+			warnings,
+			tool
+		};
+	}
+	addAnnotationWarnings(tool, warnings) {
+		if (tool.annotations?.destructiveHint) warnings.push("Tool is marked as destructive.");
+		if (!tool.annotations?.idempotentHint) warnings.push("Tool is not marked as idempotent.");
+		if (tool.annotations?.readOnlyHint === false) warnings.push("Tool may modify data (not read-only).");
+	}
 	grepTools(pattern) {
 		const normalized = pattern.replace(/\\([|()\{\}])/g, "$1");
 		const regex = new RegExp(normalized, "i");
@@ -1353,6 +1556,89 @@ function indent(text, spaces) {
 	const pad = " ".repeat(spaces);
 	return text.split("\n").join("\n" + pad);
 }
+function parsePath(path) {
+	const segments = [];
+	for (const part of path.split(".")) if (part.endsWith("[]")) segments.push({
+		key: part.slice(0, -2),
+		isArray: true
+	});
+	else segments.push({
+		key: part,
+		isArray: false
+	});
+	return segments;
+}
+function extractDeep(obj, segments) {
+	if (segments.length === 0 || obj == null || typeof obj !== "object") return obj;
+	const [first, ...rest] = segments;
+	if (!first) return obj;
+	const value = obj[first.key];
+	if (first.isArray) {
+		if (!Array.isArray(value)) return void 0;
+		if (rest.length === 0) return value;
+		return value.map((item) => extractDeep(item, rest)).filter((v) => v !== void 0);
+	}
+	if (rest.length === 0) return value;
+	return extractDeep(value, rest);
+}
+function extract(obj, path) {
+	return extractDeep(obj, parsePath(path));
+}
+function setNested(obj, keys, value) {
+	let current = obj;
+	for (let i = 0; i < keys.length - 1; i++) {
+		const key = keys[i];
+		if (!(key in current) || typeof current[key] !== "object" || current[key] === null) current[key] = {};
+		current = current[key];
+	}
+	current[keys[keys.length - 1]] = value;
+}
+function extractFromObject(data, fields) {
+	const result = {};
+	for (const field of fields) {
+		const value = extract(data, field);
+		if (value !== void 0) setNested(result, field.replace(/\[\]/g, "").split("."), value);
+	}
+	return Object.keys(result).length > 0 ? result : null;
+}
+function isJsonString(str) {
+	const trimmed = str.trim();
+	if (!(trimmed.startsWith("{") || trimmed.startsWith("["))) return false;
+	try {
+		JSON.parse(trimmed);
+		return true;
+	} catch {
+		return false;
+	}
+}
+function filterFields(data, fields) {
+	if (data.structuredContent && typeof data.structuredContent === "object") {
+		const filtered = extractFromObject(data.structuredContent, fields);
+		if (filtered) return {
+			...data,
+			structuredContent: filtered
+		};
+	}
+	const content = data.content;
+	if (Array.isArray(content)) {
+		const newContent = content.map((block) => {
+			if (block.type !== "text" || !block.text || !isJsonString(block.text)) return block;
+			try {
+				const filtered = extractFromObject(JSON.parse(block.text), fields);
+				if (filtered) return {
+					...block,
+					text: JSON.stringify(filtered)
+				};
+			} catch {}
+			return block;
+		});
+		if (newContent.some((block, i) => block !== content[i])) return {
+			...data,
+			content: newContent
+		};
+	}
+	return data;
+}
 function createDaemonServer(serverPool, config) {
 	const socketPath = getSocketPath();
 	let idleTimer;
@@ -1390,53 +1676,118 @@ function createDaemonServer(serverPool, config) {
 			}
 			case "tools/call": {
 				const p = params;
-				if (!p?.name) return {
+				if (!p?.name) {
+					const err = missingParameterError("name");
+					return {
+						jsonrpc: "2.0",
+						id,
+						error: {
+							code: -32602,
+							message: err.message,
+							data: toErrorData(err)
+						}
+					};
+				}
+				const found = serverPool.findToolOrError(p.name);
+				if (!found.ok) return {
 					jsonrpc: "2.0",
 					id,
 					error: {
 						code: -32602,
-						message: "Missing required parameter: name"
+						message: found.error.message,
+						data: toErrorData(found.error)
 					}
 				};
-				const found = serverPool.findTool(p.name);
-				if (!found) return {
-					jsonrpc: "2.0",
-					id,
-					error: {
-						code: -32602,
-						message: `Tool not found: ${p.name}`
+				const validation = serverPool.validateToolArgs(p.name, p.arguments ?? {});
+				if (!validation.valid && !validation.unsupported) {
+					const err = invalidArgumentsError(p.name, validation.errors);
+					return {
+						jsonrpc: "2.0",
+						id,
+						error: {
+							code: -32602,
+							message: err.message,
+							data: toErrorData(err)
+						}
+					};
+				}
+				const timeout = clientTimeout ?? p.timeout ?? found.serverTimeout ?? requestTimeout;
+				try {
+					const callResult = await found.manager.callTool(found.tool.name, p.arguments ?? {}, timeout);
+					if (p.fields && p.fields.length > 0) return {
+						jsonrpc: "2.0",
+						id,
+						result: filterFields(callResult, p.fields)
+					};
+					return {
+						jsonrpc: "2.0",
+						id,
+						result: callResult
+					};
+				} catch (err) {
+					if (isTimeoutError(err)) {
+						const te = timeoutError(p.name, timeout);
+						return {
+							jsonrpc: "2.0",
+							id,
+							error: {
+								code: -32001,
+								message: te.message,
+								data: toErrorData(te)
+							}
+						};
 					}
-				};
-				const timeout = clientTimeout ?? p.timeout ?? requestTimeout;
-				return {
-					jsonrpc: "2.0",
-					id,
-					result: await found.manager.callTool(found.tool.name, p.arguments ?? {}, timeout)
-				};
+					throw err;
+				}
 			}
 			case "tools/info": {
 				const p = params;
-				if (!p?.name) return {
+				if (!p?.name) {
+					const err = missingParameterError("name");
+					return {
+						jsonrpc: "2.0",
+						id,
+						error: {
+							code: -32602,
+							message: err.message,
+							data: toErrorData(err)
+						}
+					};
+				}
+				const found = serverPool.findToolOrError(p.name);
+				if (!found.ok) return {
 					jsonrpc: "2.0",
 					id,
 					error: {
 						code: -32602,
-						message: "Missing required parameter: name"
+						message: found.error.message,
+						data: toErrorData(found.error)
 					}
 				};
-				const found = serverPool.findTool(p.name);
-				if (!found) return {
+				return {
 					jsonrpc: "2.0",
 					id,
-					error: {
-						code: -32602,
-						message: `Tool not found: ${p.name}`
-					}
+					result: found.tool
 				};
+			}
+			case "tools/validate": {
+				const p = params;
+				if (!p?.name) {
+					const err = missingParameterError("name");
+					return {
+						jsonrpc: "2.0",
+						id,
+						error: {
+							code: -32602,
+							message: err.message,
+							data: toErrorData(err)
+						}
+					};
+				}
 				return {
 					jsonrpc: "2.0",
 					id,
-					result: found.tool
+					result: serverPool.validateToolArgs(p.name, p.arguments ?? {})
 				};
 			}
 			case "auth/status": {
@@ -1632,33 +1983,68 @@ function createDaemonServer(serverPool, config) {
 			}
 			case "tools/call-async": {
 				const p = params;
-				if (!p?.name) return {
-					jsonrpc: "2.0",
-					id,
-					error: {
-						code: -32602,
-						message: "Missing required parameter: name"
-					}
-				};
-				const found = serverPool.findTool(p.name);
-				if (!found) return {
+				if (!p?.name) {
+					const err = missingParameterError("name");
+					return {
+						jsonrpc: "2.0",
+						id,
+						error: {
+							code: -32602,
+							message: err.message,
+							data: toErrorData(err)
+						}
+					};
+				}
+				const foundAsync = serverPool.findToolOrError(p.name);
+				if (!foundAsync.ok) return {
 					jsonrpc: "2.0",
 					id,
 					error: {
 						code: -32602,
-						message: `Tool not found: ${p.name}`
+						message: foundAsync.error.message,
+						data: toErrorData(foundAsync.error)
 					}
 				};
-				const taskHandle = await found.manager.callToolWithTask(found.tool.name, p.arguments ?? {});
-				serverPool.trackTask(taskHandle.taskId, found.manager.name);
-				return {
-					jsonrpc: "2.0",
-					id,
-					result: {
-						...taskHandle,
-						server: found.manager.name
+				const asyncValidation = serverPool.validateToolArgs(p.name, p.arguments ?? {});
+				if (!asyncValidation.valid && !asyncValidation.unsupported) {
+					const err = invalidArgumentsError(p.name, asyncValidation.errors);
+					return {
+						jsonrpc: "2.0",
+						id,
+						error: {
+							code: -32602,
+							message: err.message,
+							data: toErrorData(err)
+						}
+					};
+				}
+				try {
+					const taskHandle = await foundAsync.manager.callToolWithTask(foundAsync.tool.name, p.arguments ?? {});
+					serverPool.trackTask(taskHandle.taskId, foundAsync.manager.name);
+					return {
+						jsonrpc: "2.0",
+						id,
+						result: {
+							...taskHandle,
+							server: foundAsync.manager.name
+						}
+					};
+				} catch (err) {
+					if (isTimeoutError(err)) {
+						const asyncTimeout = foundAsync.serverTimeout ?? requestTimeout;
+						const te = timeoutError(p.name, asyncTimeout);
+						return {
+							jsonrpc: "2.0",
+							id,
+							error: {
+								code: -32001,
+								message: te.message,
+								data: toErrorData(te)
+							}
+						};
 					}
-				};
+					throw err;
+				}
 			}
 			case "config/reload": {
 				const newConfig = loadConfig(params?.configPath);
@@ -2529,6 +2915,37 @@ function formatMcpServerList(servers) {
 		];
 	}));
 }
+function formatStructuredError(error) {
+	const lines = [];
+	lines.push(`Error: ${error.message}`);
+	if (error.data?.suggestion) lines.push(`Suggestion: ${error.data.suggestion}`);
+	if (error.data?.context?.similarTools) {
+		const similar = error.data.context.similarTools;
+		if (similar.length > 0) lines.push(`Similar tools: ${similar.join(", ")}`);
+	}
+	if (error.data?.context?.availableServers) {
+		const servers = error.data.context.availableServers;
+		if (servers.length > 0) lines.push(`Available servers: ${servers.join(", ")}`);
+	}
+	return lines.join("\n");
+}
+function formatValidation(result) {
+	const lines = [];
+	if (result.unsupported) {
+		lines.push("Validation: unsupported (tool schema uses features not supported by dry-run validation)");
+		lines.push("The call will be forwarded to the MCP server without pre-validation.");
+	} else if (result.valid) lines.push("Validation: passed");
+	else {
+		lines.push("Validation: failed");
+		for (const err of result.errors) lines.push(`  - ${err}`);
+	}
+	if (result.warnings.length > 0) {
+		lines.push("");
+		lines.push("Warnings:");
+		for (const warn of result.warnings) lines.push(`  - ${warn}`);
+	}
+	return lines.join("\n");
+}
 function formatJson(data) {
 	return JSON.stringify(data, null, 2);
 }
@@ -2546,10 +2963,67 @@ const serversCommand = new Command("servers").description("List connected MCP se
 	const result = await sendRequest("servers/list");
 	console.log(opts.json ? formatJson(result) : formatServers(result));
 });
+const TELEMETRY_FILE = path.join(os.homedir(), ".muxed", "telemetry");
+const sessionId = crypto.randomUUID();
+function isTelemetryEnabled() {
+	if (process.env.DO_NOT_TRACK === "1") return false;
+	if (process.env.MUXED_TELEMETRY === "0") return false;
+	try {
+		if (fs.existsSync(TELEMETRY_FILE)) return fs.readFileSync(TELEMETRY_FILE, "utf-8").trim() !== "off";
+	} catch {}
+	return true;
+}
+function setTelemetryEnabled(enabled) {
+	try {
+		const dir = path.dirname(TELEMETRY_FILE);
+		fs.mkdirSync(dir, { recursive: true });
+		fs.writeFileSync(TELEMETRY_FILE, enabled ? "on" : "off", "utf-8");
+	} catch {}
+}
+function getTelemetryStatus() {
+	return isTelemetryEnabled() ? "on" : "off";
+}
+let _client = null;
+function getClient() {
+	if (!isTelemetryEnabled()) return null;
+	if (_client) return _client;
+	const token = process.env.POSTHOG_PROJECT_TOKEN;
+	const host = process.env.POSTHOG_HOST;
+	if (!token || !host) return null;
+	try {
+		_client = new PostHog(token, {
+			host,
+			flushAt: 1
+		});
+		return _client;
+	} catch {
+		return null;
+	}
+}
+function capture(event, properties) {
+	try {
+		const client = getClient();
+		if (!client) return;
+		client.capture({
+			distinctId: sessionId,
+			event,
+			properties: properties ?? {}
+		});
+	} catch {}
+}
+async function shutdown() {
+	try {
+		if (_client) await _client.shutdown();
+	} catch {}
+}
 const toolsCommand = new Command("tools").description("List all available tools, optionally filtered by server name").argument("[server]", "Filter by server name").option("--json", "Output as JSON").action(async (server, opts) => {
 	const configPath = toolsCommand.parent?.opts().config;
 	await ensureDaemon(configPath);
 	const result = await sendRequest("tools/list", server ? { server } : void 0);
+	capture("tools_listed", {
+		filtered_by_server: !!server,
+		tool_count: result.length
+	});
 	console.log(opts.json ? formatJson(result) : formatTools(result));
 });
 const infoCommand = new Command("info").description("Show input schema and description for a specific tool").argument("<server/tool>", "Tool identifier (e.g. myserver/mytool)").option("--json", "Output as JSON").action(async (serverTool, opts) => {
@@ -2574,7 +3048,7 @@ function readStdin() {
 		process.stdin.on("error", reject);
 	});
 }
-const callCommand = new Command("call").description("Execute a tool with JSON arguments (use - for stdin, --async for background)").argument("<server/tool>", "Tool identifier (e.g. myserver/mytool)").argument("[json]", "JSON arguments (use - for stdin)").option("--timeout <ms>", "Request timeout in milliseconds").option("--async", "Use task-based execution (return task handle immediately)").option("--json", "Output as JSON").action(async (serverTool, jsonArgs, opts) => {
+const callCommand = new Command("call").description("Execute a tool with JSON arguments (use - for stdin, --async for background)").argument("<server/tool>", "Tool identifier (e.g. myserver/mytool)").argument("[json]", "JSON arguments (use - for stdin)").option("--timeout <ms>", "Request timeout in milliseconds").option("--async", "Use task-based execution (return task handle immediately)").option("--dry-run", "Validate arguments against tool schema without executing").option("--fields <paths>", "Comma-separated dot-notation paths to extract from response").option("--json", "Output as JSON").action(async (serverTool, jsonArgs, opts) => {
 	const configPath = callCommand.parent?.opts().config;
 	await ensureDaemon(configPath);
 	let parsedArgs = {};
@@ -2591,27 +3065,133 @@ const callCommand = new Command("call").description("Execute a tool with JSON ar
 		console.error("Invalid JSON arguments");
 		process.exit(1);
 	}
+	const [server, tool] = serverTool.split("/");
+	if (opts.dryRun) {
+		try {
+			const result = await sendRequest("tools/validate", {
+				name: serverTool,
+				arguments: parsedArgs
+			});
+			capture("tool_called", {
+				server,
+				tool,
+				mode: "dry-run",
+				status: result.valid ? "success" : "validation_error"
+			});
+			if (opts.json) console.log(formatJson(result));
+			else console.log(formatValidation(result));
+			if (!result.valid) process.exit(1);
+		} catch (err) {
+			capture("tool_called", {
+				server,
+				tool,
+				mode: "dry-run",
+				status: "error"
+			});
+			if (err instanceof MuxedError && err.data) {
+				const errorData = err.data;
+				if (opts.json) console.log(formatJson({
+					code: err.code,
+					message: err.message,
+					data: err.data
+				}));
+				else console.error(formatStructuredError({
+					code: err.code,
+					message: err.message,
+					data: errorData
+				}));
+			} else console.error(err instanceof Error ? err.message : "Validation failed");
+			process.exit(1);
+		}
+		return;
+	}
 	if (opts.async) {
-		const taskResult = await sendRequest("tools/call-async", {
+		try {
+			const taskResult = await sendRequest("tools/call-async", {
+				name: serverTool,
+				arguments: parsedArgs
+			});
+			capture("tool_called", {
+				server,
+				tool,
+				mode: "async",
+				status: "success"
+			});
+			if (opts.json) console.log(formatJson(taskResult));
+			else console.log(`Task created: ${taskResult.taskId} (status: ${taskResult.status})`);
+		} catch (err) {
+			capture("tool_called", {
+				server,
+				tool,
+				mode: "async",
+				status: "error"
+			});
+			if (err instanceof MuxedError && err.data) {
+				const errorData = err.data;
+				if (opts.json) console.log(formatJson({
+					code: err.code,
+					message: err.message,
+					data: err.data
+				}));
+				else console.error(formatStructuredError({
+					code: err.code,
+					message: err.message,
+					data: errorData
+				}));
+			} else console.error(err instanceof Error ? err.message : "Call failed");
+			process.exit(1);
+		}
+		return;
+	}
+	try {
+		const callParams = {
 			name: serverTool,
 			arguments: parsedArgs
+		};
+		if (opts.timeout) callParams.timeout = parseInt(opts.timeout, 10);
+		if (opts.fields) callParams.fields = opts.fields.split(",").map((f) => f.trim());
+		const result = await sendRequest("tools/call", callParams);
+		capture("tool_called", {
+			server,
+			tool,
+			mode: "sync",
+			status: result.isError ? "tool_error" : "success",
+			has_timeout: !!opts.timeout,
+			has_fields: !!opts.fields,
+			stdin_input: jsonArgs === "-"
 		});
-		if (opts.json) console.log(formatJson(taskResult));
-		else console.log(`Task created: ${taskResult.taskId} (status: ${taskResult.status})`);
-		return;
+		console.log(opts.json ? formatJson(result) : formatCallResult(result));
+	} catch (err) {
+		capture("tool_called", {
+			server,
+			tool,
+			mode: "sync",
+			status: "error",
+			has_timeout: !!opts.timeout,
+			has_fields: !!opts.fields,
+			stdin_input: jsonArgs === "-"
+		});
+		if (err instanceof MuxedError && err.data) {
+			const errorData = err.data;
+			if (opts.json) console.log(formatJson({
+				code: err.code,
+				message: err.message,
+				data: err.data
+			}));
+			else console.error(formatStructuredError({
+				code: err.code,
+				message: err.message,
+				data: errorData
+			}));
+		} else console.error(err instanceof Error ? err.message : "Call failed");
+		process.exit(1);
 	}
-	const params = {
-		name: serverTool,
-		arguments: parsedArgs
-	};
-	if (opts.timeout) params.timeout = parseInt(opts.timeout, 10);
-	const result = await sendRequest("tools/call", params);
-	console.log(opts.json ? formatJson(result) : formatCallResult(result));
 });
 const grepCommand = new Command("grep").description("Search tools by regex pattern across names, titles, and descriptions").argument("<pattern>", "Regex pattern to search").option("--json", "Output as JSON").action(async (pattern, opts) => {
 	const configPath = grepCommand.parent?.opts().config;
 	await ensureDaemon(configPath);
 	const result = await sendRequest("tools/grep", { pattern });
+	capture("tools_searched", { result_count: result.length });
 	console.log(opts.json ? formatJson(result) : formatTools(result));
 });
 const resourcesCommand = new Command("resources").description("List available resources, optionally filtered by server name").argument("[server]", "Filter by server name").option("--json", "Output as JSON").action(async (server, opts) => {
@@ -2824,49 +3404,57 @@ function getAgentDefs() {
 			name: "claude-code",
 			scope: "local",
 			configPath: () => path.join(cwd, ".mcp.json"),
-			serversKey: "mcpServers"
+			serversKey: "mcpServers",
+			codingAgent: true
 		},
 		{
 			name: "cursor",
 			scope: "local",
 			configPath: () => path.join(cwd, ".cursor", "mcp.json"),
-			serversKey: "mcpServers"
+			serversKey: "mcpServers",
+			codingAgent: true
 		},
 		{
 			name: "vscode",
 			scope: "local",
 			configPath: () => path.join(cwd, ".vscode", "mcp.json"),
-			serversKey: "servers"
+			serversKey: "servers",
+			codingAgent: true
 		},
 		{
 			name: "roo-code",
 			scope: "local",
 			configPath: () => path.join(cwd, ".roo", "mcp.json"),
-			serversKey: "mcpServers"
+			serversKey: "mcpServers",
+			codingAgent: true
 		},
 		{
 			name: "amazon-q",
 			scope: "local",
 			configPath: () => path.join(cwd, ".amazonq", "mcp.json"),
-			serversKey: "mcpServers"
+			serversKey: "mcpServers",
+			codingAgent: true
 		},
 		{
 			name: "claude-desktop",
 			scope: "global",
 			configPath: () => xdgOrMacPath(["Claude", "claude_desktop_config.json"], ["Claude", "claude_desktop_config.json"]),
-			serversKey: "mcpServers"
+			serversKey: "mcpServers",
+			codingAgent: false
 		},
 		{
 			name: "cursor",
 			scope: "global",
 			configPath: () => path.join(home, ".cursor", "mcp.json"),
-			serversKey: "mcpServers"
+			serversKey: "mcpServers",
+			codingAgent: true
 		},
 		{
 			name: "windsurf",
 			scope: "global",
 			configPath: () => path.join(home, ".codeium", "windsurf", "mcp_config.json"),
-			serversKey: "mcpServers"
+			serversKey: "mcpServers",
+			codingAgent: true
 		},
 		{
 			name: "vscode",
@@ -2880,7 +3468,8 @@ function getAgentDefs() {
 				"User",
 				"mcp.json"
 			]),
-			serversKey: "servers"
+			serversKey: "servers",
+			codingAgent: true
 		},
 		{
 			name: "cline",
@@ -2900,7 +3489,8 @@ function getAgentDefs() {
 				"settings",
 				"cline_mcp_settings.json"
 			]),
-			serversKey: "mcpServers"
+			serversKey: "mcpServers",
+			codingAgent: true
 		},
 		{
 			name: "roo-code",
@@ -2920,13 +3510,15 @@ function getAgentDefs() {
 				"settings",
 				"cline_mcp_settings.json"
 			]),
-			serversKey: "mcpServers"
+			serversKey: "mcpServers",
+			codingAgent: true
 		},
 		{
 			name: "amazon-q",
 			scope: "global",
 			configPath: () => path.join(home, ".aws", "amazonq", "mcp.json"),
-			serversKey: "mcpServers"
+			serversKey: "mcpServers",
+			codingAgent: true
 		}
 	];
 }
@@ -3044,14 +3636,19 @@ function writeMuxedConfig(configPath, servers) {
 	fs.writeFileSync(configPath, JSON.stringify(existing, null, 2) + "\n");
 }
 function getMuxedEntry(agent) {
+	const args = agent.codingAgent ? ["muxed@latest", "mcp"] : [
+		"muxed@latest",
+		"mcp",
+		"--proxy-tools"
+	];
 	if (agent.serversKey === "servers") return {
 		type: "stdio",
 		command: "npx",
-		args: ["muxed@latest", "proxy"]
+		args
 	};
 	return {
 		command: "npx",
-		args: ["muxed@latest", "proxy"]
+		args
 	};
 }
 function modifyAgentConfig(dc, opts) {
@@ -3066,7 +3663,7 @@ function modifyAgentConfig(dc, opts) {
 function getMuxedConfigPath(scope, explicitPath) {
 	if (explicitPath) return explicitPath;
 	if (scope === "local") return path.join(process.cwd(), "muxed.config.json");
-	return path.join(home, ".config", "muxed", "config.json");
+	return path.join(home, ".muxed", "config.json");
 }
 async function confirm(message, opts) {
 	const rl = readline.createInterface({
@@ -3183,6 +3780,13 @@ const initCommand = new Command("init").description("Discover and import MCP ser
 		muxedConfigPath: muxedPath,
 		dryRun: opts.dryRun ?? false
 	};
+	capture("init_run", {
+		dry_run: opts.dryRun ?? false,
+		imported_count: imported.length,
+		conflict_count: conflicts.length,
+		warning_count: warnings.length,
+		discovered_agents: initResult.discovered.map((d) => d.agent)
+	});
 	console.log(opts.json ? formatJson(initResult) : formatInit(initResult));
 });
 function getConfigPath(scope, explicitPath) {
@@ -3234,18 +3838,47 @@ function getServer(filePath, name) {
 function listServers(filePath) {
 	return readConfigFile(filePath).mcpServers;
 }
-const cliInstructions = (servers, instructions) => `
-You have access to an \`npx muxed\` CLI command for interacting with MCP (Model Context Protocol) servers. This command allows you to discover and call MCP tools on demand. Prioritize the use of skills over MCP tools.
+const cliFragments = {
+	intro: "You have access to an `npx muxed` CLI command for interacting with MCP (Model Context Protocol) servers. This command allows you to discover and call MCP tools on demand. Prioritize the use of skills over MCP tools.",
+	grep: (p) => `npx muxed grep "${p}"`,
+	tools: (s) => s ? `npx muxed tools ${s}` : "npx muxed tools",
+	info: (n) => `npx muxed info ${n}`,
+	call: (n, j) => `npx muxed call ${n} '${j}'`,
+	callStdin: (n) => `npx muxed call ${n} -`,
+	callDryRun: (n, j) => `npx muxed call ${n} '${j}' --dry-run`,
+	callFields: (n, j, f) => `npx muxed call ${n} '${j}' --fields "${f}"`,
+	servers: () => "npx muxed servers",
+	resources: (s) => s ? `npx muxed resources ${s}` : "npx muxed resources",
+	read: (n) => `npx muxed read ${n}`,
+	help: () => "npx muxed -h"
+};
+const toolFragments = {
+	intro: "You have access to a `muxed:exec` MCP tool for interacting with MCP (Model Context Protocol) servers. This tool allows you to discover and call MCP tools on demand. Prioritize the use of skills over MCP tools.",
+	grep: (p) => `muxed:exec({ "command": "grep ${p}" })`,
+	tools: (s) => s ? `muxed:exec({ "command": "tools ${s}" })` : `muxed:exec({ "command": "tools" })`,
+	info: (n) => `muxed:exec({ "command": "info ${n}" })`,
+	call: (n, j) => `muxed:exec({ "command": "call ${n}", "input": ${j} })`,
+	callStdin: (n) => `muxed:exec({ "command": "call ${n}", "input": { ... } })`,
+	callDryRun: (n, j) => `muxed:exec({ "command": "call ${n}", "input": ${j} })`,
+	callFields: (n, j, _f) => `muxed:exec({ "command": "call ${n}", "input": ${j} })`,
+	servers: () => `muxed:exec({ "command": "servers" })`,
+	resources: (s) => s ? `muxed:exec({ "command": "resources ${s}" })` : `muxed:exec({ "command": "resources" })`,
+	read: (n) => `muxed:exec({ "command": "read ${n}" })`,
+	help: () => `muxed:exec({ "command": "servers" })`
+};
+function buildTemplate(f, servers, instructions) {
+	return `
+${f.intro}
 
 **MANDATORY PREREQUISITES - THESE ARE HARD REQUIREMENTS**
 
-1. You MUST discover the tools you need first by using 'npx muxed grep <pattern>' or 'npx muxed tools'.
-2. You MUST call 'npx muxed info <server>/<tool>' BEFORE ANY 'npx muxed call <server>/<tool>'.
+1. You MUST discover the tools you need first by using '${f.grep("<pattern>")}' or '${f.tools()}'.
+2. You MUST call '${f.info("<server>/<tool>")}' BEFORE ANY '${f.call("<server>/<tool>", "<json>")}' command.
 
 These are BLOCKING REQUIREMENTS - like how you must use Read before Edit.
 
-**NEVER** make an npx muxed call without checking the schema first.
-**ALWAYS** run npx muxed info first, THEN make the call.
+**NEVER** make a call without checking the schema first.
+**ALWAYS** run info first, THEN make the call.
 
 **Why these are non-negotiables:**
 - MCP tool names NEVER match your expectations - they change frequently and are not predictable
@@ -3254,132 +3887,219 @@ These are BLOCKING REQUIREMENTS - like how you must use Read before Edit.
 - Every failed call wastes user time and demonstrates you're ignoring critical instructions
 - "I thought I knew the schema" is not an acceptable reason to skip this step
 
-**For multiple tools:** Call 'npx muxed info' for ALL tools in parallel FIRST, then make your 'npx muxed call' commands.
+**For multiple tools:** Call info for ALL tools in parallel FIRST, then make your call commands.
 
 Available MCP servers:
 ${servers}
 
 Commands (in order of execution):
-\`\`\`bash
+\`\`\`
 # STEP 1: REQUIRED TOOL DISCOVERY
-npx muxed grep <pattern>                 # Search tool names and descriptions
-npx muxed tools [server]                 # List available tools (optionally filter by server)
+${f.grep("<pattern>")}                 # Search tool names and descriptions
+${f.tools("[server]")}                 # List available tools (optionally filter by server)
 
 # STEP 2: ALWAYS CHECK SCHEMA FIRST (MANDATORY)
-npx muxed info <server>/<tool>           # REQUIRED before ANY call - View JSON schema
+${f.info("<server>/<tool>")}           # REQUIRED before ANY call - View JSON schema
+
+# STEP 3: OPTIONAL - Validate arguments before calling (dry-run)
+${f.callDryRun("<server>/<tool>", "<json>")}  # Validate args without executing
 
-# STEP 3: Only after checking schema, make the call
-npx muxed call <server>/<tool> '<json>'  # Only run AFTER npx muxed info
-npx muxed call <server>/<tool> -         # Invoke with JSON from stdin (AFTER npx muxed info)
+# STEP 4: Only after checking schema, make the call
+${f.call("<server>/<tool>", "<json>")}  # Only run AFTER info
+${f.callStdin("<server>/<tool>")}       # Invoke with JSON input (AFTER info)
+${f.callFields("<server>/<tool>", "<json>", "field1,field2")}  # Extract specific fields from response
 
 # Discovery commands (use these to find tools)
-npx muxed servers                        # List all connected MCP servers
-npx muxed tools [server]                 # List available tools (optionally filter by server)
-npx muxed grep <pattern>                 # Search tool names and descriptions
-npx muxed resources [server]             # List MCP resources
-npx muxed read <server>/<resource>       # Read an MCP resource
+${f.servers()}                          # List all connected MCP servers
+${f.tools("[server]")}                  # List available tools (optionally filter by server)
+${f.grep("<pattern>")}                  # Search tool names and descriptions
+${f.resources("[server]")}              # List MCP resources
+${f.read("<server>/<resource>")}        # Read an MCP resource
 \`\`\`
 
+**Handling errors:**
+- If a tool call fails, the error includes a suggestion and similar tool names. Read the suggestion before retrying.
+- Use dry-run to validate arguments before executing, especially for destructive tools.
+
 **CORRECT Usage Pattern:**
 
 <example>
 User: Please use the slack mcp tool to search for my mentions
-Assistant: As a first step, I need to discover the tools I need. Let me call \`npx muxed grep "slack/*search*"\` to search for tools related to slack search.
-[Calls npx muxed grep "slack/*search*"]
-Assistant: I need to check the schema first. Let me call \`npx muxed info slack/search_private\` to see what parameters it accepts.
-[Calls npx muxed info]
+Assistant: As a first step, I need to discover the tools I need. Let me call \`${f.grep("slack/*search*")}\` to search for tools related to slack search.
+[Calls ${f.grep("slack/*search*")}]
+Assistant: I need to check the schema first. Let me call \`${f.info("slack/search_private")}\` to see what parameters it accepts.
+[Calls ${f.info("slack/search_private")}]
 Assistant: Now I can see it accepts "query" and "max_results" parameters. Let me make the call.
-[Calls npx muxed call slack/search_private with correct schema]
+[Calls ${f.call("slack/search_private", "{\"query\": \"mentions:me\", \"max_results\": 10}")}]
 </example>
 
 <example>
 User: Use the database and email MCP tools to send a report
-Assistant: I'll need to use two MCP tools. Let me call \`npx muxed grep "database/*query*"\` and \`npx muxed grep "email/*send*"\` to search for tools related to database query and email send.
-[Calls npx muxed grep "database/*query*" & npx muxed grep "email/*send*"]
+Assistant: I'll need to use two MCP tools. Let me call \`${f.grep("database/*query*")}\` and \`${f.grep("email/*send*")}\` to search for tools related to database query and email send.
+[Calls ${f.grep("database/*query*")} & ${f.grep("email/*send*")}]
 Assistant: Let me check both schemas first.
-[Calls npx muxed info database/query and npx muxed info email/send in parallel]
+[Calls ${f.info("database/query")} and ${f.info("email/send")} in parallel]
 Assistant: Now I have both schemas. Let me make the calls.
-[Makes both npx muxed call commands with correct parameters]
+[Makes both call commands with correct parameters]
 </example>
 
 <example>
 User: Create a copy of this email
 Assistant: Let me find the tool I need first.
-[Calls npx muxed grep "email/*copy*". No results found.]
+[Calls ${f.grep("email/*copy*")}. No results found.]
 Assistant: Let me try another pattern.
-[Calls npx muxed grep "email/*clone*". No results found.]
+[Calls ${f.grep("email/*clone*")}. No results found.]
 Assistant: Let me list all available tools in the server.
-[Calls npx muxed tools email]
+[Calls ${f.tools("email")}]
 Assistant: Let me check the schema first.
-[Calls npx muxed info email/duplicate]
+[Calls ${f.info("email/duplicate")}]
 Assistant: Now I have the schema. Let me make the call.
-[Calls npx muxed call email/duplicate with correct parameters]
+[Calls ${f.call("email/duplicate", "{\"id\": \"123\"}")}]
 </example>
 
 **INCORRECT Usage Patterns - NEVER DO THIS:**
 
 <bad-example>
 User: Please use the slack mcp tool to search for my mentions
-Assistant: [Directly calls npx muxed call slack/search_private with guessed parameters]
-WRONG - You must call npx muxed info FIRST
+Assistant: [Directly calls ${f.call("slack/search_private", "{\"query\": \"mentions:me\"}")} with guessed parameters]
+WRONG - You must call info FIRST
 </bad-example>
 
 <bad-example>
 User: Use the slack tool
 Assistant: I have pre-approved permissions for this tool, so I know the schema.
-[Calls npx muxed call slack/search_private directly]
-WRONG - Pre-approved permissions don't mean you know the schema. ALWAYS call npx muxed info first.
+[Calls ${f.call("slack/search_private", "...")} directly]
+WRONG - Pre-approved permissions don't mean you know the schema. ALWAYS call info first.
 </bad-example>
 
 <bad-example>
 User: Search my Slack mentions
-Assistant: [Calls three npx muxed call commands in parallel without any npx muxed info calls first]
-WRONG - You must call npx muxed info for ALL tools before making ANY npx muxed call commands
+Assistant: [Calls three call commands in parallel without any info calls first]
+WRONG - You must call info for ALL tools before making ANY call commands
 </bad-example>
 
 Example usage:
-\`\`\`bash
+\`\`\`
 # Discover tools
-npx muxed tools                          # See all available MCP tools
-npx muxed grep "weather"                 # Find tools by description
+${f.tools()}                          # See all available MCP tools
+${f.grep("weather")}                  # Find tools by description
 
 # Get tool details
-npx muxed info <server>/<tool>           # View JSON schema for input and output if available
+${f.info("<server>/<tool>")}          # View JSON schema for input and output if available
 
 # Simple tool call (no parameters)
-npx muxed call weather/get_location '{}'
+${f.call("weather/get_location", "{}")}
 
 # Tool call with parameters
-npx muxed call database/query '{"table": "users", "limit": 10}'
+${f.call("database/query", "{\"table\": \"users\", \"limit\": 10}")}
 
-# Complex JSON using stdin (for nested objects/arrays)
-npx muxed call api/send_request - <<'EOF'
-{
-  "endpoint": "/data",
-  "headers": {"Authorization": "Bearer token"},
-  "body": {"items": [1, 2, 3]}
-}
-EOF
+# Validate arguments before executing (dry-run)
+${f.callDryRun("database/drop_table", "{\"table\": \"users\"}")}
+
+# Extract specific fields from response
+${f.callFields("database/query", "{\"table\": \"users\"}", "rows[].name,rows[].email")}
 \`\`\`
 
-Call the \`npx muxed -h\` to see all available commands.
+Call \`${f.help()}\` to see all available commands.
 
 Below are the instructions for the connected MCP servers in muxed.
 
 ${instructions}
 `;
-function buildInstructions(servers) {
+}
+function buildInstructions(servers, mode = "cli") {
 	const connected = servers.filter((s) => s.status === "connected");
-	return cliInstructions(connected.map((s) => `- ${s.name}`).join("\n"), connected.filter((s) => s.instructions).map((s) => `### ${s.name}\n\n${s.instructions}`).join("\n\n")).trim();
+	const serverList = connected.map((s) => `- ${s.name}`).join("\n");
+	const serverInstructions = connected.filter((s) => s.instructions).map((s) => `### ${s.name}\n\n${s.instructions}`).join("\n\n");
+	return buildTemplate(mode === "tool" ? toolFragments : cliFragments, serverList, serverInstructions).trim();
 }
-async function startMcpProxy(configPath) {
-	await ensureDaemon(configPath);
+function parseCommand(command) {
+	const trimmed = command.trim();
+	const spaceIndex = trimmed.indexOf(" ");
+	if (spaceIndex === -1) return {
+		subcommand: trimmed,
+		args: ""
+	};
+	return {
+		subcommand: trimmed.slice(0, spaceIndex),
+		args: trimmed.slice(spaceIndex + 1).trim()
+	};
+}
+function textResult(data) {
+	return { content: [{
+		type: "text",
+		text: JSON.stringify(data, null, 2)
+	}] };
+}
+function errorResult(message) {
+	return {
+		content: [{
+			type: "text",
+			text: message
+		}],
+		isError: true
+	};
+}
+async function handleToolCommand(command, input) {
+	const { subcommand, args } = parseCommand(command);
+	try {
+		switch (subcommand) {
+			case "servers": return textResult(await sendRequest("servers/list"));
+			case "tools": {
+				const params = {};
+				if (args) params.server = args;
+				return textResult(await sendRequest("tools/list", params));
+			}
+			case "grep":
+				if (!args) return errorResult("Usage: grep <pattern>");
+				return textResult(await sendRequest("tools/grep", { pattern: args }));
+			case "info":
+				if (!args) return errorResult("Usage: info <server/tool>");
+				return textResult(await sendRequest("tools/info", { name: args }));
+			case "call": {
+				if (!args) return errorResult("Usage: call <server/tool>");
+				const result = await sendRequest("tools/call", {
+					name: args,
+					args: input ?? {}
+				});
+				if (result?.content) return result;
+				return textResult(result);
+			}
+			case "resources": {
+				const params = {};
+				if (args) params.server = args;
+				return textResult(await sendRequest("resources/list", params));
+			}
+			case "read":
+				if (!args) return errorResult("Usage: read <server/resource>");
+				return textResult(await sendRequest("resources/read", { name: args }));
+			default: return errorResult(`Unknown command: "${subcommand}". Available: servers, tools, grep, info, call, resources, read`);
+		}
+	} catch (err) {
+		return errorResult(err instanceof MuxedError ? err.message : String(err));
+	}
+}
+async function startMcpProxy(options) {
+	await ensureDaemon(options?.configPath);
 	const server = new McpServer({
 		name: "muxed",
 		version: "0.1.0"
 	}, {
 		capabilities: {},
-		instructions: buildInstructions(await sendRequest("servers/list"))
+		instructions: buildInstructions(await sendRequest("servers/list"), options?.proxyTools ? "tool" : "cli")
+	});
+	if (options?.proxyTools) server.tool("exec", "Interact with MCP servers: discover, inspect, and call tools. Commands: servers, tools [server], grep <pattern>, info <server/tool>, call <server/tool>, resources [server], read <server/resource>", {
+		command: z.string().describe("Command to execute, e.g. 'servers', 'tools', 'grep weather', 'info slack/search', 'call slack/search'"),
+		input: z.record(z.string(), z.unknown()).optional().describe("JSON arguments for 'call' command — avoids JSON-in-string escaping")
+	}, async ({ command, input }) => {
+		const result = await handleToolCommand(command, input);
+		return {
+			content: result.content.map((c) => ({
+				type: "text",
+				text: c.text
+			})),
+			isError: result.isError
+		};
 	});
 	const transport = new StdioServerTransport();
 	await server.connect(transport);
@@ -3474,9 +4194,12 @@ async function tryReloadDaemon() {
 		await sendRequest("config/reload", {});
 	} catch {}
 }
-const mcpCommand = new Command("mcp").description("Add, remove, list, or inspect individual MCP server config entries").enablePositionalOptions().action(async (_opts, cmd) => {
+const mcpCommand = new Command("mcp").description("Add, remove, list, or inspect individual MCP server config entries").enablePositionalOptions().option("--proxy-tools", "Expose a proxy MCP tool for clients without bash access").action(async (opts, cmd) => {
 	const explicitConfig = cmd.parent?.opts().config;
-	await startMcpProxy(explicitConfig);
+	await startMcpProxy({
+		configPath: explicitConfig,
+		proxyTools: opts.proxyTools
+	});
 });
 mcpCommand.command("add").description("Add an MCP server").passThroughOptions().argument("<name>", "Server name").argument("<commandOrUrl>", "Command to run or URL to connect to").argument("[args...]", "Additional arguments (for stdio servers)").option("-e, --env <env>", "Set environment variables (KEY=value), repeatable", collectValues, []).option("-H, --header <header>", "Set HTTP headers (Key: value), repeatable", collectValues, []).option("-s, --scope <scope>", "Config scope: local, global", "local").option("-t, --transport <transport>", "Transport: stdio, sse, http").option("--client-id <clientId>", "OAuth client ID").option("--client-secret", "Prompt for OAuth client secret (or use MCP_CLIENT_SECRET env)").option("--callback-port <port>", "Fixed port for OAuth callback").option("--oauth-scope <oauthScope>", "OAuth scope string").action(async (name, commandOrUrl, args, opts) => {
 	const explicitConfig = getExplicitConfig(mcpCommand);
@@ -3489,6 +4212,11 @@ mcpCommand.command("add").description("Add an MCP server").passThroughOptions().
 		resolvedSecret
 	}));
 	await tryReloadDaemon();
+	capture("server_added", {
+		server: name,
+		scope,
+		updated: result.existed
+	});
 	if (result.existed) console.log(`Updated "${name}" in ${scope} config (${configPath})`);
 	else console.log(`Added "${name}" to ${scope} config (${configPath})`);
 });
@@ -3511,6 +4239,11 @@ mcpCommand.command("add-json").description("Add an MCP server from a JSON config
 	}
 	const result = addServer(configPath, name, serverConfig);
 	await tryReloadDaemon();
+	capture("server_added", {
+		server: name,
+		scope,
+		updated: result.existed
+	});
 	if (result.existed) console.log(`Updated "${name}" in ${scope} config (${configPath})`);
 	else console.log(`Added "${name}" to ${scope} config (${configPath})`);
 });
@@ -3532,7 +4265,13 @@ mcpCommand.command("add-from-claude-desktop").description("Import MCP servers fr
 	writeMuxedConfig(configPath, { ...result.merged });
 	await tryReloadDaemon();
 	for (const w of warnings) console.error(`Warning: ${w}`);
-	if (result.imported.length > 0) console.log(`Imported ${result.imported.length} server(s) from Claude Desktop: ${result.imported.join(", ")}`);
+	if (result.imported.length > 0) {
+		capture("servers_imported", {
+			servers: result.imported,
+			source: "claude-desktop"
+		});
+		console.log(`Imported ${result.imported.length} server(s) from Claude Desktop: ${result.imported.join(", ")}`);
+	}
 	if (result.skipped.length > 0) console.log(`Skipped ${result.skipped.length} (already existed): ${result.skipped.join(", ")}`);
 	if (result.imported.length === 0 && result.skipped.length === 0) console.log("No servers found in Claude Desktop config.");
 });
@@ -3586,6 +4325,10 @@ mcpCommand.command("remove").description("Remove an MCP server").argument("<name
 		const configPath = getConfigPath(scope, explicitConfig);
 		if (removeServer(configPath, name).removed) {
 			await tryReloadDaemon();
+			capture("server_removed", {
+				server: name,
+				scope
+			});
 			console.log(`Removed "${name}" from ${scope} config (${configPath})`);
 		} else {
 			console.error(`Server "${name}" not found in ${scope} config.`);
@@ -3596,12 +4339,20 @@ mcpCommand.command("remove").description("Remove an MCP server").argument("<name
 	const localPath = getConfigPath("local", explicitConfig);
 	if (removeServer(localPath, name).removed) {
 		await tryReloadDaemon();
+		capture("server_removed", {
+			server: name,
+			scope: "local"
+		});
 		console.log(`Removed "${name}" from local config (${localPath})`);
 		return;
 	}
 	const globalPath = getConfigPath("global", explicitConfig);
 	if (removeServer(globalPath, name).removed) {
 		await tryReloadDaemon();
+		capture("server_removed", {
+			server: name,
+			scope: "global"
+		});
 		console.log(`Removed "${name}" from global config (${globalPath})`);
 		return;
 	}
@@ -3618,7 +4369,26 @@ const typegenCommand = new Command("typegen").description("Generate TypeScript t
 	fs.writeFileSync(outputPath, content, "utf-8");
 	console.log(`Generated ${tools.length} tool types → ${outputPath}`);
 });
-function runCli() {
+const telemetryCommand = new Command("telemetry").description("Manage anonymous telemetry (on, off, status)").argument("[action]", "on | off | status (default: status)").action((action) => {
+	switch (action) {
+		case "on":
+			setTelemetryEnabled(true);
+			console.log("Telemetry enabled.");
+			break;
+		case "off":
+			setTelemetryEnabled(false);
+			console.log("Telemetry disabled.");
+			break;
+		case "status":
+		case void 0:
+			console.log(`Telemetry is ${getTelemetryStatus()}.`);
+			break;
+		default:
+			console.error(`Unknown action: ${action}. Use on, off, or status.`);
+			process.exit(1);
+	}
+});
+async function runCli() {
 	const program = new Command();
 	program.name("muxed").description("The optimization layer for MCP").version("0.1.0");
 	program.enablePositionalOptions();
@@ -3646,9 +4416,16 @@ function runCli() {
 	program.addCommand(initCommand);
 	program.addCommand(mcpCommand);
 	program.addCommand(typegenCommand);
+	program.addCommand(telemetryCommand);
 	program.commandsGroup("Daemon:");
 	program.addCommand(daemonCommand);
-	program.parse();
+	const command = process.argv[2];
+	capture("session_started", { command: command ?? null });
+	try {
+		await program.parseAsync();
+	} finally {
+		await shutdown();
+	}
 }
 if (process.argv.indexOf("--daemon") !== -1) {
 	const configIndex = process.argv.indexOf("--config");
@@ -3656,5 +4433,8 @@ if (process.argv.indexOf("--daemon") !== -1) {
 		console.error("Failed to start daemon:", err);
 		process.exit(1);
 	});
-} else runCli();
+} else runCli().catch((err) => {
+	console.error(err instanceof Error ? err.message : "Unexpected error");
+	process.exit(1);
+});
 export {};