vite-vue-mcp-inspect 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,205 @@
+import { Plugin, ViteDevServer } from "vite";
+import { Hookable } from "hookable";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+//#region ../../node_modules/.pnpm/birpc@4.0.0/node_modules/birpc/dist/index.d.mts
+//#endregion
+//#region src/utils.d.ts
+type ArgumentsType<T> = T extends ((...args: infer A) => any) ? A : never;
+type ReturnType<T> = T extends ((...args: any) => infer R) ? R : never;
+//#endregion
+//#region src/main.d.ts
+type PromisifyFn<T> = ReturnType<T> extends Promise<any> ? T : (...args: ArgumentsType<T>) => Promise<Awaited<ReturnType<T>>>;
+type BirpcFn<T> = PromisifyFn<T> & {
+  /**
+   * Send event without asking for response
+   */
+  asEvent: (...args: ArgumentsType<T>) => Promise<void>;
+};
+type ProxifiedRemoteFunctions<RemoteFunctions extends object = Record<string, unknown>> = { [K in keyof RemoteFunctions]: BirpcFn<RemoteFunctions[K]> };
+//#endregion
+//#region src/group.d.ts
+interface BirpcGroupReturnBuiltin<RemoteFunctions> {
+  /**
+   * Call the remote function and wait for the result.
+   * An alternative to directly calling the function
+   */
+  $call: <K$1 extends keyof RemoteFunctions>(method: K$1, ...args: ArgumentsType<RemoteFunctions[K$1]>) => Promise<Awaited<ReturnType<RemoteFunctions[K$1]>>[]>;
+  /**
+   * Same as `$call`, but returns `undefined` if the function is not defined on the remote side.
+   */
+  $callOptional: <K$1 extends keyof RemoteFunctions>(method: K$1, ...args: ArgumentsType<RemoteFunctions[K$1]>) => Promise<Awaited<ReturnType<RemoteFunctions[K$1]> | undefined>>;
+  /**
+   * Send event without asking for response
+   */
+  $callEvent: <K$1 extends keyof RemoteFunctions>(method: K$1, ...args: ArgumentsType<RemoteFunctions[K$1]>) => Promise<void>;
+  /**
+   * Call the remote function with the raw options.
+   */
+  $callRaw: (options: {
+    method: string;
+    args: unknown[];
+    event?: boolean;
+    optional?: boolean;
+  }) => Promise<Awaited<ReturnType<any>>[]>;
+}
+type BirpcGroupReturn<RemoteFunctions extends object = Record<string, unknown>, Proxify extends boolean = true> = Proxify extends true ? ProxifiedRemoteFunctions<RemoteFunctions> & BirpcGroupReturnBuiltin<RemoteFunctions> : BirpcGroupReturnBuiltin<RemoteFunctions>;
+//#endregion
+//#region src/types.d.ts
+type Awaitable<T> = T | Promise<T>;
+interface IdeMcpConfig {
+  /**
+   * Enable/disable config writing for this IDE.
+   * @default true (only when the IDE directory exists)
+   */
+  enabled?: boolean;
+  /**
+   * The MCP server name key in the IDE config.
+   * @default 'vue-mcp'
+   */
+  serverName?: string;
+}
+interface ClaudeDesktopConfig {
+  enabled: boolean;
+  /**
+   * Full path to claude_desktop_config.json.
+   * Defaults to the platform-specific location.
+   */
+  configPath?: string;
+  /** @default 'vue-mcp' */
+  serverName?: string;
+}
+interface VueMcpOptions {
+  /**
+   * The hostname to listen on.
+   * @default 'localhost'
+   */
+  host?: string;
+  /**
+   * Print the MCP server URLs in the console.
+   * @default true
+   */
+  printUrl?: boolean;
+  /**
+   * Custom MCP server factory. When provided, built-in tools are skipped.
+   */
+  mcpServer?: (viteServer: ViteDevServer, ctx: VueMcpContext) => Awaitable<McpServer>;
+  /**
+   * Hook called after the MCP server is created. You can add tools or
+   * return a replacement McpServer instance.
+   */
+  mcpServerSetup?: (server: McpServer, viteServer: ViteDevServer) => Awaitable<void | McpServer>;
+  /**
+   * Override the MCP server name/version info.
+   */
+  mcpServerInfo?: {
+    name: string;
+    version: string;
+  };
+  /**
+   * The path prefix for MCP routes.
+   * @default '/__mcp'
+   */
+  mcpPath?: string;
+  /**
+   * Timeout in milliseconds before browser-dependent tools return an error.
+   * @default 10000
+   */
+  browserTimeout?: number;
+  /**
+   * Update `.cursor/mcp.json` with the MCP URL if `.cursor/` exists.
+   * @default true
+   */
+  updateCursorMcpJson?: boolean | IdeMcpConfig;
+  /**
+   * Update `.windsurf/mcp.json` with the MCP URL if `.windsurf/` exists.
+   * @default true
+   */
+  updateWindsurfMcpJson?: boolean | IdeMcpConfig;
+  /**
+   * Update `.vscode/mcp.json` with the MCP URL if `.vscode/` exists.
+   * @default true
+   */
+  updateVscodeMcpJson?: boolean | IdeMcpConfig;
+  /**
+   * Update the Claude Desktop config file with the MCP URL.
+   * Opt-in because the config file location is global (not project-local).
+   * @default false
+   */
+  updateClaudeDesktopConfig?: boolean | ClaudeDesktopConfig;
+  /**
+   * Append an import to the module ending with `appendTo` instead of
+   * injecting a <script> tag. Useful for non-HTML entry points.
+   *
+   * @default undefined (injects via <script> in HTML)
+   */
+  appendTo?: string | RegExp;
+}
+interface ServerRpcFunctions {
+  getInspectorTree(query: {
+    event: string;
+  }): void;
+  getDetailedComponentTree(query: {
+    event: string;
+  }): void;
+  getInspectorState(query: {
+    event: string;
+    componentName: string;
+  }): void;
+  editComponentState(query: {
+    componentName: string;
+    path: string[];
+    value: string;
+    valueType: string;
+    event: string;
+  }): void;
+  highlightComponent(query: {
+    componentName: string;
+    event: string;
+  }): void;
+  scrollToComponent(query: {
+    componentName: string;
+    event: string;
+  }): void;
+  getRouterInfo(query: {
+    event: string;
+  }): void;
+  getPiniaTree(query: {
+    event: string;
+  }): void;
+  getPiniaState(query: {
+    event: string;
+    storeName: string;
+  }): void;
+  editPiniaState(query: {
+    storeName: string;
+    path: string[];
+    value: string;
+    valueType: string;
+    event: string;
+  }): void;
+  navigateToRoute(query: {
+    path: string;
+    event: string;
+  }): void;
+  getAppInfo(query: {
+    event: string;
+  }): void;
+  reloadApp(query: {
+    event: string;
+  }): void;
+  getComponentByFile(query: {
+    filePath: string;
+    event: string;
+  }): void;
+}
+interface VueMcpContext {
+  hooks: Hookable<Record<string, any>>;
+  /** Populated in configureServer. Null before plugin initialises. */
+  rpcServer: BirpcGroupReturn<ServerRpcFunctions> | null;
+}
+//#endregion
+//#region src/index.d.ts
+declare function VueMcp(options?: VueMcpOptions): Plugin;
+//#endregion
+export { type ClaudeDesktopConfig, type IdeMcpConfig, type VueMcpContext, type VueMcpOptions, VueMcp as default };

package/dist/index.mjs

@@ -0,0 +1,691 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import ansis from "ansis";
+import { createRPCServer } from "vite-dev-rpc";
+import { searchForWorkspaceRoot, transformWithOxc } from "vite";
+import { createHooks } from "hookable";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { randomUUID } from "node:crypto";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import fs from "node:fs/promises";
+import { homedir } from "node:os";
+//#region src/context.ts
+function createVueMcpContext() {
+	return {
+		hooks: createHooks(),
+		rpcServer: null
+	};
+}
+//#endregion
+//#region src/rpc.ts
+/**
+* Creates the RPC handler object passed to `createRPCServer`.
+*
+* Two parts:
+* - Outgoing stubs (server → browser): no-op functions; the RPC framework
+*   serialises the call and sends it to the browser over WebSocket.
+* - Incoming callbacks (browser → server): fire the matching hookable event
+*   so the pending MCP tool promise resolves.
+*/
+function createServerRpc(ctx) {
+	return {
+		getInspectorTree: () => {},
+		getDetailedComponentTree: () => {},
+		getInspectorState: () => {},
+		editComponentState: () => {},
+		highlightComponent: () => {},
+		scrollToComponent: () => {},
+		getRouterInfo: () => {},
+		getPiniaTree: () => {},
+		getPiniaState: () => {},
+		editPiniaState: () => {},
+		navigateToRoute: () => {},
+		getAppInfo: () => {},
+		reloadApp: () => {},
+		getComponentByFile: () => {},
+		onInspectorTreeUpdated(event, data) {
+			ctx.hooks.callHook(event, data);
+		},
+		onDetailedComponentTreeUpdated(event, data) {
+			ctx.hooks.callHook(event, data);
+		},
+		onInspectorStateUpdated(event, data) {
+			ctx.hooks.callHook(event, data);
+		},
+		onEditComponentStateDone(event, result) {
+			ctx.hooks.callHook(event, result);
+		},
+		onHighlightComponentDone(event, result) {
+			ctx.hooks.callHook(event, result);
+		},
+		onScrollToComponentDone(event, result) {
+			ctx.hooks.callHook(event, result);
+		},
+		onRouterInfoUpdated(event, data) {
+			ctx.hooks.callHook(event, data);
+		},
+		onPiniaTreeUpdated(event, data) {
+			ctx.hooks.callHook(event, data);
+		},
+		onPiniaInfoUpdated(event, data) {
+			ctx.hooks.callHook(event, data);
+		},
+		onPiniaStateEditDone(event, result) {
+			ctx.hooks.callHook(event, result);
+		},
+		onNavigateToRouteDone(event, result) {
+			ctx.hooks.callHook(event, result);
+		},
+		onAppInfoUpdated(event, data) {
+			ctx.hooks.callHook(event, data);
+		},
+		onReloadAppDone(event) {
+			ctx.hooks.callHook(event, null);
+		},
+		onComponentByFileUpdated(event, data) {
+			ctx.hooks.callHook(event, data);
+		}
+	};
+}
+//#endregion
+//#region src/utils/timeout.ts
+/**
+* Wraps a one-shot hookable event in a timeout.
+*
+* 1. Registers a `hookOnce` listener for `eventName`.
+* 2. Calls `trigger()` to fire the RPC call that will eventually resolve the hook.
+* 3. Races the hook against a timeout.
+* 4. If the timeout fires first the promise rejects with a user-friendly error.
+*    The dangling hook listener cleans itself up when it eventually fires
+*    (hookOnce auto-removes after first invocation) — the `settled` flag
+*    ensures the resolution is ignored.
+*/
+function withBrowserTimeout(hooks, eventName, trigger, timeoutMs, toolName) {
+	return new Promise((resolve, reject) => {
+		let settled = false;
+		const timer = setTimeout(() => {
+			if (!settled) {
+				settled = true;
+				reject(/* @__PURE__ */ new Error(`Tool "${toolName}" timed out after ${timeoutMs}ms.\nMake sure the Vue app is open in a browser tab and @vue/devtools is loaded.`));
+			}
+		}, timeoutMs);
+		hooks.hookOnce(eventName, (data) => {
+			if (!settled) {
+				settled = true;
+				clearTimeout(timer);
+				resolve(data);
+			}
+		});
+		try {
+			trigger();
+		} catch (err) {
+			if (!settled) {
+				settled = true;
+				clearTimeout(timer);
+				reject(err);
+			}
+		}
+	});
+}
+//#endregion
+//#region src/server.ts
+function ok(data) {
+	return { content: [{
+		type: "text",
+		text: JSON.stringify(data)
+	}] };
+}
+function err(message) {
+	return {
+		content: [{
+			type: "text",
+			text: message
+		}],
+		isError: true
+	};
+}
+function errorMessage(e) {
+	return e instanceof Error ? e.message : String(e);
+}
+function isErrorResult(r) {
+	return r !== null && r !== void 0 && typeof r === "object" && "error" in r;
+}
+function createMcpServer(options, ctx, browserTimeout) {
+	const server = new McpServer({
+		name: "vue-mcp",
+		version: "1.0.0",
+		...options.mcpServerInfo
+	});
+	let eventId = 0;
+	/** Wrap a browser-dependent tool: generates event ID, fires RPC, races timeout. */
+	function withTool(toolName, trigger) {
+		const event = String(++eventId);
+		return withBrowserTimeout(ctx.hooks, event, () => trigger(event), browserTimeout, toolName);
+	}
+	server.registerTool("get-component-tree", { description: "Get the Vue component tree in a hierarchical JSON structure." }, async () => {
+		try {
+			return ok(await withTool("get-component-tree", (e) => ctx.rpcServer.getInspectorTree({ event: e })));
+		} catch (e) {
+			return err(errorMessage(e));
+		}
+	});
+	server.registerTool("get-component-tree-detailed", { description: "Get all Vue components with their names, source file paths, and current state. More comprehensive than get-component-tree but slower." }, async () => {
+		try {
+			return ok(await withTool("get-component-tree-detailed", (e) => ctx.rpcServer.getDetailedComponentTree({ event: e })));
+		} catch (e) {
+			return err(errorMessage(e));
+		}
+	});
+	server.registerTool("get-component-state", {
+		description: "Get the props, data, computed properties and other state of a specific Vue component.",
+		inputSchema: { componentName: z.string().describe("The name of the Vue component, e.g. \"Counter\" or \"App\"") }
+	}, async ({ componentName }) => {
+		try {
+			const result = await withTool("get-component-state", (e) => ctx.rpcServer.getInspectorState({
+				event: e,
+				componentName
+			}));
+			if (isErrorResult(result)) return err(result.error);
+			return ok(result);
+		} catch (e) {
+			return err(errorMessage(e));
+		}
+	});
+	server.registerTool("edit-component-state", {
+		description: "Edit the state (props/data/computed) of a specific Vue component.",
+		inputSchema: {
+			componentName: z.string().describe("The name of the Vue component"),
+			path: z.array(z.string()).describe("Property path, e.g. [\"count\"] or [\"user\", \"name\"]"),
+			value: z.string().describe("New value as a JSON-serialisable string"),
+			valueType: z.enum([
+				"string",
+				"number",
+				"boolean",
+				"object",
+				"array"
+			]).describe("The data type of the new value")
+		}
+	}, async ({ componentName, path, value, valueType }) => {
+		try {
+			const result = await withTool("edit-component-state", (e) => ctx.rpcServer.editComponentState({
+				componentName,
+				path,
+				value,
+				valueType,
+				event: e
+			}));
+			if (!result.success) return err(result.error ?? "Unknown error");
+			return ok({
+				success: true,
+				componentName,
+				path,
+				value
+			});
+		} catch (e) {
+			return err(errorMessage(e));
+		}
+	});
+	server.registerTool("highlight-component", {
+		description: "Visually highlight a Vue component in the browser for 5 seconds.",
+		inputSchema: { componentName: z.string().describe("The name of the Vue component to highlight") }
+	}, async ({ componentName }) => {
+		try {
+			const result = await withTool("highlight-component", (e) => ctx.rpcServer.highlightComponent({
+				componentName,
+				event: e
+			}));
+			if (!result.success) return err(result.error ?? "Unknown error");
+			return ok({
+				success: true,
+				componentName
+			});
+		} catch (e) {
+			return err(errorMessage(e));
+		}
+	});
+	server.registerTool("scroll-to-component", {
+		description: "Scroll the browser viewport to a Vue component and highlight it.",
+		inputSchema: { componentName: z.string().describe("The name of the Vue component to scroll to") }
+	}, async ({ componentName }) => {
+		try {
+			const result = await withTool("scroll-to-component", (e) => ctx.rpcServer.scrollToComponent({
+				componentName,
+				event: e
+			}));
+			if (!result.success) return err(result.error ?? "Unknown error");
+			return ok({
+				success: true,
+				componentName
+			});
+		} catch (e) {
+			return err(errorMessage(e));
+		}
+	});
+	server.registerTool("get-router-info", { description: "Get Vue Router information: current route, all defined routes, navigation history." }, async () => {
+		try {
+			return ok(await withTool("get-router-info", (e) => ctx.rpcServer.getRouterInfo({ event: e })));
+		} catch (e) {
+			return err(errorMessage(e));
+		}
+	});
+	server.registerTool("navigate-to-route", {
+		description: "Programmatically navigate to a Vue Router route in the browser.",
+		inputSchema: { path: z.string().describe("Route path to navigate to, e.g. \"/about\" or \"/users/42\"") }
+	}, async ({ path }) => {
+		try {
+			const result = await withTool("navigate-to-route", (e) => ctx.rpcServer.navigateToRoute({
+				path,
+				event: e
+			}));
+			if (!result.success) return err(result.error ?? "Unknown error");
+			return ok({
+				success: true,
+				navigatedTo: path
+			});
+		} catch (e) {
+			return err(errorMessage(e));
+		}
+	});
+	server.registerTool("get-pinia-tree", { description: "Get the list of all Pinia stores registered in the application." }, async () => {
+		try {
+			return ok(await withTool("get-pinia-tree", (e) => ctx.rpcServer.getPiniaTree({ event: e })));
+		} catch (e) {
+			return err(errorMessage(e));
+		}
+	});
+	server.registerTool("get-pinia-state", {
+		description: "Get the current state of a specific Pinia store.",
+		inputSchema: { storeName: z.string().describe("The Pinia store ID, e.g. \"counter\" or \"user\"") }
+	}, async ({ storeName }) => {
+		try {
+			const result = await withTool("get-pinia-state", (e) => ctx.rpcServer.getPiniaState({
+				event: e,
+				storeName
+			}));
+			if (isErrorResult(result)) return err(result.error);
+			return ok(result);
+		} catch (e) {
+			return err(errorMessage(e));
+		}
+	});
+	server.registerTool("edit-pinia-state", {
+		description: "Edit a property in a Pinia store.",
+		inputSchema: {
+			storeName: z.string().describe("The Pinia store ID, e.g. \"counter\""),
+			path: z.array(z.string()).describe("Property path, e.g. [\"count\"] or [\"user\", \"name\"]"),
+			value: z.string().describe("New value as a JSON-serialisable string"),
+			valueType: z.enum([
+				"string",
+				"number",
+				"boolean",
+				"object",
+				"array"
+			]).describe("The data type of the new value")
+		}
+	}, async ({ storeName, path, value, valueType }) => {
+		try {
+			const result = await withTool("edit-pinia-state", (e) => ctx.rpcServer.editPiniaState({
+				storeName,
+				path,
+				value,
+				valueType,
+				event: e
+			}));
+			if (!result.success) return err(result.error ?? "Unknown error");
+			return ok({
+				success: true,
+				storeName,
+				path,
+				value
+			});
+		} catch (e) {
+			return err(errorMessage(e));
+		}
+	});
+	server.registerTool("get-app-info", { description: "Get general information about the Vue application: version, registered plugins, router state, devtools status." }, async () => {
+		try {
+			return ok(await withTool("get-app-info", (e) => ctx.rpcServer.getAppInfo({ event: e })));
+		} catch (e) {
+			return err(errorMessage(e));
+		}
+	});
+	server.registerTool("reload-app", { description: "Trigger a full page reload of the Vue application in the browser." }, async () => {
+		try {
+			const event = String(++eventId);
+			const reloadTimeout = Math.min(browserTimeout, 3e3);
+			await withBrowserTimeout(ctx.hooks, event, () => ctx.rpcServer.reloadApp({ event }), reloadTimeout, "reload-app");
+			return ok({
+				success: true,
+				message: "App reload triggered"
+			});
+		} catch (e) {
+			const msg = errorMessage(e);
+			if (msg.includes("timed out")) return ok({
+				success: true,
+				message: "App reload triggered (page reloaded before ack)"
+			});
+			return err(msg);
+		}
+	});
+	server.registerTool("get-component-by-file", {
+		description: "Find a Vue component by its source file path and return its name and current state.",
+		inputSchema: { filePath: z.string().describe("Partial or full path to the component source file, e.g. \"Counter.vue\" or \"components/Counter.vue\"") }
+	}, async ({ filePath }) => {
+		try {
+			const result = await withTool("get-component-by-file", (e) => ctx.rpcServer.getComponentByFile({
+				filePath,
+				event: e
+			}));
+			if (isErrorResult(result)) return err(result.error);
+			return ok(result);
+		} catch (e) {
+			return err(errorMessage(e));
+		}
+	});
+	return server;
+}
+//#endregion
+//#region src/transport.ts
+/** 1 MB — generous for JSON-RPC MCP messages. */
+const MAX_BODY_SIZE = 1024 * 1024;
+/** Parse the raw body of an IncomingMessage as JSON. */
+async function readJsonBody(req) {
+	return new Promise((resolve, reject) => {
+		const chunks = [];
+		let size = 0;
+		req.on("data", (chunk) => {
+			size += chunk.length;
+			if (size > MAX_BODY_SIZE) {
+				req.destroy();
+				reject(/* @__PURE__ */ new Error("Request body too large"));
+				return;
+			}
+			chunks.push(chunk);
+		});
+		req.on("end", () => {
+			try {
+				const data = Buffer.concat(chunks, size).toString("utf8");
+				resolve(data ? JSON.parse(data) : void 0);
+			} catch (err) {
+				reject(err);
+			}
+		});
+		req.on("error", reject);
+	});
+}
+function sendJsonError(res, status, message) {
+	res.statusCode = status;
+	res.setHeader("Content-Type", "application/json");
+	res.end(JSON.stringify({ error: message }));
+}
+/**
+* Register Streamable HTTP transport on the Vite dev server at `{base}/mcp`.
+*
+* Returns a cleanup function to call when the server closes.
+*/
+async function setupTransports(base, createServer, vite) {
+	const sessions = /* @__PURE__ */ new Map();
+	vite.middlewares.use(`${base}/mcp`, async (req, res) => {
+		const sRes = res;
+		try {
+			const sessionId = req.headers["mcp-session-id"];
+			if (req.method === "POST") {
+				let body;
+				try {
+					body = await readJsonBody(req);
+				} catch (e) {
+					const message = e instanceof Error ? e.message : "Invalid JSON body";
+					sendJsonError(sRes, message === "Request body too large" ? 413 : 400, message);
+					return;
+				}
+				if (!sessionId) {
+					const server = await createServer();
+					const transport = new StreamableHTTPServerTransport({
+						sessionIdGenerator: () => randomUUID(),
+						onsessioninitialized: (id) => {
+							sessions.set(id, {
+								server,
+								transport
+							});
+						}
+					});
+					let closing = false;
+					transport.onclose = () => {
+						if (transport.sessionId) sessions.delete(transport.sessionId);
+						if (!closing) {
+							closing = true;
+							server.close().catch(() => {});
+						}
+					};
+					await server.connect(transport);
+					await transport.handleRequest(req, sRes, body);
+					return;
+				}
+				const entry = sessions.get(sessionId);
+				if (!entry) {
+					sendJsonError(sRes, 404, `Session "${sessionId}" not found`);
+					return;
+				}
+				await entry.transport.handleRequest(req, sRes, body);
+				return;
+			}
+			if (req.method === "GET" || req.method === "DELETE") {
+				if (!sessionId) {
+					sendJsonError(sRes, 400, "Missing mcp-session-id header");
+					return;
+				}
+				const entry = sessions.get(sessionId);
+				if (!entry) {
+					sendJsonError(sRes, 404, `Session "${sessionId}" not found`);
+					return;
+				}
+				await entry.transport.handleRequest(req, sRes);
+				return;
+			}
+			sendJsonError(sRes, 405, "Method Not Allowed");
+		} catch (err) {
+			console.error("[vue-mcp] Streamable HTTP error:", err);
+			if (!sRes.headersSent) sendJsonError(sRes, 500, "Internal server error");
+		}
+	});
+	return async () => {
+		await Promise.allSettled([...sessions.values()].flatMap((e) => [e.transport.close(), e.server.close()]));
+		sessions.clear();
+	};
+}
+//#endregion
+//#region src/ide-config.ts
+async function writeJsonConfig(filePath, update) {
+	let json = {};
+	if (existsSync(filePath)) try {
+		const raw = await fs.readFile(filePath, "utf-8");
+		json = JSON.parse(raw || "{}");
+	} catch {}
+	update(json);
+	await fs.writeFile(filePath, `${JSON.stringify(json, null, 2)}\n`);
+}
+async function updateIdeConfigs(opts) {
+	const { root, mcpUrl, cursor, windsurf, vscode, claudeDesktop } = opts;
+	if (cursor) {
+		const cursorDir = path.join(root, ".cursor");
+		if (existsSync(cursorDir)) {
+			const configPath = path.join(cursorDir, "mcp.json");
+			try {
+				await writeJsonConfig(configPath, (json) => {
+					json.mcpServers ??= {};
+					json.mcpServers[cursor.serverName] = { url: mcpUrl };
+				});
+			} catch (err) {
+				console.warn(`[vue-mcp] Failed to update .cursor/mcp.json: ${err}`);
+			}
+		}
+	}
+	if (windsurf) {
+		const windsurfDir = path.join(root, ".windsurf");
+		if (existsSync(windsurfDir)) {
+			const configPath = path.join(windsurfDir, "mcp.json");
+			try {
+				await writeJsonConfig(configPath, (json) => {
+					json.mcpServers ??= {};
+					json.mcpServers[windsurf.serverName] = { serverUrl: mcpUrl };
+				});
+			} catch (err) {
+				console.warn(`[vue-mcp] Failed to update .windsurf/mcp.json: ${err}`);
+			}
+		}
+	}
+	if (vscode) {
+		const vscodeDir = path.join(root, ".vscode");
+		if (existsSync(vscodeDir)) {
+			const configPath = path.join(vscodeDir, "mcp.json");
+			try {
+				await writeJsonConfig(configPath, (json) => {
+					json.servers ??= {};
+					json.servers[vscode.serverName] = {
+						type: "http",
+						url: mcpUrl
+					};
+				});
+			} catch (err) {
+				console.warn(`[vue-mcp] Failed to update .vscode/mcp.json: ${err}`);
+			}
+		}
+	}
+	if (claudeDesktop) {
+		const configPath = claudeDesktop.configPath || getClaudeDesktopConfigPath();
+		if (configPath) try {
+			await writeJsonConfig(configPath, (json) => {
+				json.mcpServers ??= {};
+				json.mcpServers[claudeDesktop.serverName] = {
+					type: "streamablehttp",
+					url: mcpUrl
+				};
+			});
+		} catch (err) {
+			console.warn(`[vue-mcp] Failed to update Claude Desktop config: ${err}`);
+		}
+	}
+}
+function getClaudeDesktopConfigPath() {
+	const platform = process.platform;
+	if (platform === "darwin") return path.join(homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
+	if (platform === "win32") {
+		const appData = process.env.APPDATA;
+		if (appData) return path.join(appData, "Claude", "claude_desktop_config.json");
+	}
+	return null;
+}
+//#endregion
+//#region src/index.ts
+const _dirname = fileURLToPath(new URL(".", import.meta.url));
+const VIRTUAL_MODULE_ID = "virtual:vue-mcp-overlay";
+const RESOLVED_VIRTUAL_ID = `\0${VIRTUAL_MODULE_ID}`;
+function resolveIdeMcpConfig(opt, defaultEnabled) {
+	if (opt === false) return false;
+	if (opt === true || opt === void 0) return defaultEnabled ? { serverName: "vue-mcp" } : false;
+	if (opt.enabled === false) return false;
+	return { serverName: opt.serverName ?? "vue-mcp" };
+}
+function resolveClaudeDesktopConfig(opt) {
+	if (!opt) return false;
+	if (opt === true) return {
+		serverName: "vue-mcp",
+		configPath: ""
+	};
+	if (opt.enabled === false) return false;
+	return {
+		serverName: opt.serverName ?? "vue-mcp",
+		configPath: opt.configPath ?? ""
+	};
+}
+function VueMcp(options = {}) {
+	const { host: _host, printUrl = true, mcpPath = "/__mcp", browserTimeout = 1e4, appendTo } = options;
+	const ctx = createVueMcpContext();
+	let config;
+	let overlaySource = null;
+	return {
+		name: "vite-vue-mcp-inspect",
+		apply: "serve",
+		configResolved(resolvedConfig) {
+			config = resolvedConfig;
+		},
+		resolveId(id, importer) {
+			if (id === VIRTUAL_MODULE_ID) return RESOLVED_VIRTUAL_ID;
+			if (importer === RESOLVED_VIRTUAL_ID) return this.resolve(id, path.resolve(_dirname, "_overlay_importer.js"), { skipSelf: true });
+		},
+		async load(id) {
+			if (id === RESOLVED_VIRTUAL_ID) {
+				if (!overlaySource) {
+					const overlayPath = path.resolve(_dirname, "../src/client/overlay.ts");
+					const altPath = path.resolve(_dirname, "client/overlay.ts");
+					overlaySource = readFileSync(existsSync(overlayPath) ? overlayPath : altPath, "utf-8");
+				}
+				return (await transformWithOxc(overlaySource, "overlay.ts")).code;
+			}
+		},
+		transformIndexHtml() {
+			if (appendTo) return [];
+			return [{
+				tag: "script",
+				attrs: {
+					type: "module",
+					src: "/@id/__x00__virtual:vue-mcp-overlay"
+				},
+				injectTo: "head-prepend"
+			}];
+		},
+		transform(code, id) {
+			if (!appendTo) return;
+			if ((appendTo instanceof RegExp ? appendTo : new RegExp(`${appendTo.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}$`)).test(id)) return {
+				code: `${code}\nimport "${VIRTUAL_MODULE_ID}"`,
+				map: null
+			};
+		},
+		async configureServer(vite) {
+			const rpcHandlers = createServerRpc(ctx);
+			ctx.rpcServer = createRPCServer("vite-vue-mcp-inspect", vite.ws, rpcHandlers, { timeout: -1 });
+			const createServer = async () => {
+				let mcpServer = options.mcpServer ? await options.mcpServer(vite, ctx) : createMcpServer(options, ctx, browserTimeout);
+				if (options.mcpServerSetup) {
+					const replacement = await options.mcpServerSetup(mcpServer, vite);
+					if (replacement) mcpServer = replacement;
+				}
+				return mcpServer;
+			};
+			const cleanup = await setupTransports(mcpPath, createServer, vite);
+			vite.httpServer?.on("close", () => {
+				cleanup().catch(() => {});
+			});
+			const resolvedHost = _host ?? "localhost";
+			const address = vite.httpServer?.address();
+			const port = typeof address === "object" && address ? address.port : 5173;
+			const mcpUrl = `http://${resolvedHost}:${port}${mcpPath}/mcp`;
+			const ideOpts = {
+				root: searchForWorkspaceRoot(config.root),
+				mcpUrl,
+				cursor: resolveIdeMcpConfig(options.updateCursorMcpJson, true),
+				windsurf: resolveIdeMcpConfig(options.updateWindsurfMcpJson, true),
+				vscode: resolveIdeMcpConfig(options.updateVscodeMcpJson, true),
+				claudeDesktop: resolveClaudeDesktopConfig(options.updateClaudeDesktopConfig)
+			};
+			if (vite.httpServer) vite.httpServer.once("listening", () => {
+				const actualAddress = vite.httpServer?.address();
+				const actualMcpUrl = `http://${resolvedHost}:${typeof actualAddress === "object" && actualAddress ? actualAddress.port : port}${mcpPath}/mcp`;
+				if (printUrl) setTimeout(() => {
+					console.log(`  ${ansis.green("➜")}  ${ansis.bold("MCP")}: ${ansis.cyan(actualMcpUrl)}`);
+				}, 0);
+				ideOpts.mcpUrl = actualMcpUrl;
+				updateIdeConfigs(ideOpts).catch((err) => {
+					console.warn(`[vue-mcp] IDE config update failed: ${err}`);
+				});
+			});
+			else updateIdeConfigs(ideOpts).catch((err) => {
+				console.warn(`[vue-mcp] IDE config update failed: ${err}`);
+			});
+		}
+	};
+}
+//#endregion
+export { VueMcp as default };

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "vite-vue-mcp-inspect",
+  "version": "1.0.0",
+  "license": "MIT",
+  "description": "Vite plugin that turns a running Vue app into an MCP server",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "vue",
+    "vite",
+    "vite-plugin",
+    "devtools",
+    "ai"
+  ],
+  "author": "Robonen Andrew <robonenandrew@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/robonen/vue-mcp.git",
+    "directory": "packages/vite-vue-mcp-inspect"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src/client"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "peerDependencies": {
+    "vite": "^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@vue/devtools-kit": "^8.1.1",
+    "ansis": "^4.2.0",
+    "hookable": "^6.1.0",
+    "vite-dev-rpc": "^1.1.0",
+    "vite-hot-client": "^2.1.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "birpc": "^4.0.0",
+    "playwright": "^1.52.0",
+    "tsdown": "^0.21.7",
+    "vite": "^8.0.3",
+    "vitest": "^3.2.1"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:unit": "vitest run --project unit",
+    "test:browser": "vitest run --project browser",
+    "typecheck": "tsc --noEmit",
+    "build": "tsdown",
+    "dev": "tsdown --watch"
+  }
+}

package/src/client/overlay.ts

@@ -0,0 +1,419 @@
+import {
+  activeAppRecord,
+  devtools,
+  devtoolsRouterInfo,
+  devtoolsState,
+  getInspector,
+  stringify,
+  toggleHighPerfMode,
+} from '@vue/devtools-kit'
+import { createRPCClient } from 'vite-dev-rpc'
+import { createHotContext } from 'vite-hot-client'
+
+const base = (import.meta as any).env?.BASE_URL ?? '/'
+const hot = createHotContext('', base)
+
+const COMPONENTS_INSPECTOR_ID = 'components'
+const PINIA_INSPECTOR_ID = 'pinia'
+
+devtools.init()
+
+// ── Helpers ──────────────────────────────────────────────────────────────
+
+function flattenChildren(node: any): any[] {
+  const result: any[] = []
+  function traverse(n: any): void {
+    if (!n) return
+    result.push(n)
+    if (Array.isArray(n.children)) n.children.forEach(traverse)
+  }
+  traverse(node)
+  return result
+}
+
+function findNode(tree: any, name: string): { node: any; error?: never } | { node?: never; error: string } {
+  const all = flattenChildren(tree)
+  const node = all.find((n: any) => n.name === name)
+  if (!node) {
+    const available = [...new Set(all.map((n: any) => n.name))].slice(0, 20).join(', ')
+    return { error: `Component "${name}" not found.\nAvailable: ${available}` }
+  }
+  return { node }
+}
+
+let highlightTimer: ReturnType<typeof setTimeout> | null = null
+
+/** Fetch the component tree, find a node by name, and call the callback with it. */
+async function withComponentNode<S, E>(
+  name: string,
+  onSuccess: (node: any) => Promise<S> | S,
+  onError: (error: string) => E,
+): Promise<S | E> {
+  const tree = await devtools.api.getInspectorTree({
+    inspectorId: COMPONENTS_INSPECTOR_ID,
+    filter: '',
+  })
+  const { node, error } = findNode(tree[0], name)
+  if (error) return onError(error)
+  return onSuccess(node)
+}
+
+/** Highlight a component node for 5 seconds, clearing any previous highlight timer. */
+function setHighlight(nodeId: string): void {
+  if (highlightTimer) clearTimeout(highlightTimer)
+  ;(devtools as any).ctx.hooks.callHook('componentHighlight', { uid: nodeId })
+  highlightTimer = setTimeout(() => {
+    ;(devtools as any).ctx.hooks.callHook('componentUnhighlight')
+  }, 5000)
+}
+
+/** Run async tasks in batches of `concurrency` to avoid freezing the browser. */
+async function mapConcurrent<T, R>(
+  items: T[],
+  concurrency: number,
+  fn: (item: T) => Promise<R>,
+): Promise<R[]> {
+  const results: R[] = []
+  for (let i = 0; i < items.length; i += concurrency) {
+    const batch = items.slice(i, i + concurrency)
+    results.push(...await Promise.all(batch.map(fn)))
+  }
+  return results
+}
+
+// ── RPC client ───────────────────────────────────────────────────────────
+
+const rpc = createRPCClient<any, any>(
+  'vite-vue-mcp-inspect',
+  hot,
+  {
+    // ── Component tree ──────────────────────────────────────────────────
+    async getInspectorTree(query: { event: string }) {
+      try {
+        const tree = await devtools.api.getInspectorTree({
+          inspectorId: COMPONENTS_INSPECTOR_ID,
+          filter: '',
+        })
+        rpc.onInspectorTreeUpdated(query.event, tree[0])
+      }
+      catch (err) {
+        rpc.onInspectorTreeUpdated(query.event, { error: String(err) })
+      }
+    },
+
+    async getDetailedComponentTree(query: { event: string }) {
+      try {
+        const tree = await devtools.api.getInspectorTree({
+          inspectorId: COMPONENTS_INSPECTOR_ID,
+          filter: '',
+        })
+        const all = flattenChildren(tree[0])
+        const detailed = await mapConcurrent(all, 10, async (node: any) => {
+          try {
+            const state = await devtools.api.getInspectorState({
+              inspectorId: COMPONENTS_INSPECTOR_ID,
+              nodeId: node.id,
+            })
+            return { name: node.name, id: node.id, file: node.file, state: stringify(state) }
+          }
+          catch {
+            return { name: node.name, id: node.id, file: node.file }
+          }
+        })
+        rpc.onDetailedComponentTreeUpdated(query.event, detailed)
+      }
+      catch (err) {
+        rpc.onDetailedComponentTreeUpdated(query.event, { error: String(err) })
+      }
+    },
+
+    // ── Component state ─────────────────────────────────────────────────
+    async getInspectorState(query: { event: string; componentName: string }) {
+      try {
+        const result = await withComponentNode(
+          query.componentName,
+          async (node) => {
+            const state = await devtools.api.getInspectorState({
+              inspectorId: COMPONENTS_INSPECTOR_ID,
+              nodeId: node.id,
+            })
+            return stringify(state)
+          },
+          (error) => ({ error }),
+        )
+        rpc.onInspectorStateUpdated(query.event, result)
+      }
+      catch (err) {
+        rpc.onInspectorStateUpdated(query.event, { error: String(err) })
+      }
+    },
+
+    // ── Edit component state ────────────────────────────────────────────
+    async editComponentState(query: {
+      componentName: string
+      path: string[]
+      value: string
+      valueType: string
+      event: string
+    }) {
+      try {
+        const result = await withComponentNode(
+          query.componentName,
+          async (node) => {
+            await (devtools as any).ctx.api.editInspectorState({
+              inspectorId: COMPONENTS_INSPECTOR_ID,
+              nodeId: node.id,
+              path: query.path,
+              state: {
+                new: null,
+                remove: false,
+                type: query.valueType,
+                value: query.value,
+              },
+              type: undefined,
+            })
+            return { success: true as const }
+          },
+          (error) => ({ success: false as const, error }),
+        )
+        rpc.onEditComponentStateDone(query.event, result)
+      }
+      catch (err) {
+        rpc.onEditComponentStateDone(query.event, { success: false, error: String(err) })
+      }
+    },
+
+    // ── Highlight component ─────────────────────────────────────────────
+    async highlightComponent(query: { componentName: string; event: string }) {
+      try {
+        const result = await withComponentNode(
+          query.componentName,
+          (node) => {
+            setHighlight(node.id)
+            return { success: true as const }
+          },
+          (error) => ({ success: false as const, error }),
+        )
+        rpc.onHighlightComponentDone(query.event, result)
+      }
+      catch (err) {
+        rpc.onHighlightComponentDone(query.event, { success: false, error: String(err) })
+      }
+    },
+
+    // ── Scroll to component ─────────────────────────────────────────────
+    async scrollToComponent(query: { componentName: string; event: string }) {
+      try {
+        const result = await withComponentNode(
+          query.componentName,
+          async (node) => {
+            setHighlight(node.id)
+            // Wait for the overlay to paint
+            await new Promise(r => setTimeout(r, 50))
+            // Scroll to the highlight overlay if it exists in the DOM
+            const overlay = document.querySelector<HTMLElement>('.__vue-devtools-component-inspector__')
+              ?? document.querySelector<HTMLElement>('[data-vue-devtools-component-inspector]')
+            if (overlay) {
+              overlay.scrollIntoView({ behavior: 'smooth', block: 'center' })
+            }
+            return { success: true as const }
+          },
+          (error) => ({ success: false as const, error }),
+        )
+        rpc.onScrollToComponentDone(query.event, result)
+      }
+      catch (err) {
+        rpc.onScrollToComponentDone(query.event, { success: false, error: String(err) })
+      }
+    },
+
+    // ── Router info ─────────────────────────────────────────────────────
+    async getRouterInfo(query: { event: string }) {
+      try {
+        rpc.onRouterInfoUpdated(query.event, JSON.parse(JSON.stringify(devtoolsRouterInfo)))
+      }
+      catch (err) {
+        rpc.onRouterInfoUpdated(query.event, { error: String(err) })
+      }
+    },
+
+    // ── Navigate to route ────────────────────────────────────────────────
+    async navigateToRoute(query: { path: string; event: string }) {
+      try {
+        // Access the Vue Router instance via the app's globalProperties
+        const router = activeAppRecord.value?.app?.config?.globalProperties?.$router
+        if (!router) {
+          rpc.onNavigateToRouteDone(query.event, {
+            success: false,
+            error: 'Vue Router not detected. Make sure vue-router is installed and configured.',
+          })
+          return
+        }
+        await router.push(query.path)
+        rpc.onNavigateToRouteDone(query.event, { success: true })
+      }
+      catch (err) {
+        rpc.onNavigateToRouteDone(query.event, { success: false, error: String(err) })
+      }
+    },
+
+    // ── Pinia tree ──────────────────────────────────────────────────────
+    async getPiniaTree(query: { event: string }) {
+      const wasHighPerf = devtoolsState.highPerfModeEnabled
+      if (wasHighPerf) toggleHighPerfMode(false)
+      try {
+        const tree = await devtools.api.getInspectorTree({
+          inspectorId: PINIA_INSPECTOR_ID,
+          filter: '',
+        })
+        rpc.onPiniaTreeUpdated(query.event, tree)
+      }
+      catch (err) {
+        rpc.onPiniaTreeUpdated(query.event, { error: String(err) })
+      }
+      finally {
+        if (wasHighPerf) toggleHighPerfMode(true)
+      }
+    },
+
+    // ── Pinia state ─────────────────────────────────────────────────────
+    async getPiniaState(query: { event: string; storeName: string }) {
+      const wasHighPerf = devtoolsState.highPerfModeEnabled
+      if (wasHighPerf) toggleHighPerfMode(false)
+      try {
+        const inspector = getInspector(PINIA_INSPECTOR_ID)
+        const prevNodeId = inspector?.selectedNodeId
+        try {
+          if (inspector) inspector.selectedNodeId = query.storeName
+          const state = await (devtools as any).ctx.api.getInspectorState({
+            inspectorId: PINIA_INSPECTOR_ID,
+            nodeId: query.storeName,
+          })
+          rpc.onPiniaInfoUpdated(query.event, stringify(state))
+        }
+        finally {
+          if (inspector && prevNodeId !== undefined) inspector.selectedNodeId = prevNodeId
+        }
+      }
+      catch (err) {
+        rpc.onPiniaInfoUpdated(query.event, { error: String(err) })
+      }
+      finally {
+        if (wasHighPerf) toggleHighPerfMode(true)
+      }
+    },
+
+    // ── Edit Pinia state ────────────────────────────────────────────────
+    async editPiniaState(query: {
+      storeName: string
+      path: string[]
+      value: string
+      valueType: string
+      event: string
+    }) {
+      const wasHighPerf = devtoolsState.highPerfModeEnabled
+      if (wasHighPerf) toggleHighPerfMode(false)
+      try {
+        const inspector = getInspector(PINIA_INSPECTOR_ID)
+        if (!inspector) {
+          rpc.onPiniaStateEditDone(query.event, { success: false, error: 'Pinia inspector not found' })
+          return
+        }
+        const prevNodeId = inspector.selectedNodeId
+        try {
+          inspector.selectedNodeId = query.storeName
+          await (devtools as any).ctx.api.editInspectorState({
+            inspectorId: PINIA_INSPECTOR_ID,
+            nodeId: query.storeName,
+            path: query.path,
+            state: {
+              new: null,
+              remove: false,
+              type: query.valueType,
+              value: query.value,
+            },
+            type: undefined,
+          })
+          rpc.onPiniaStateEditDone(query.event, { success: true })
+        }
+        finally {
+          if (prevNodeId !== undefined) inspector.selectedNodeId = prevNodeId
+        }
+      }
+      catch (err) {
+        rpc.onPiniaStateEditDone(query.event, { success: false, error: String(err) })
+      }
+      finally {
+        if (wasHighPerf) toggleHighPerfMode(true)
+      }
+    },
+
+    // ── App info ────────────────────────────────────────────────────────
+    async getAppInfo(query: { event: string }) {
+      try {
+        const appRecord = activeAppRecord.value
+        const vueApp = appRecord?.app
+        const info = {
+          vueVersion: vueApp?.version ?? 'unknown',
+          plugins: Object.keys(vueApp?.config?.globalProperties ?? {}).filter((k: string) => !k.startsWith('__')),
+          devtoolsState: {
+            connected: devtoolsState.connected,
+            vitePluginDetected: devtoolsState.vitePluginDetected,
+            highPerfModeEnabled: devtoolsState.highPerfModeEnabled,
+          },
+          router: devtoolsRouterInfo
+            ? {
+                currentRoute: devtoolsRouterInfo.currentRoute,
+                routesCount: devtoolsRouterInfo.routes?.length ?? 0,
+              }
+            : null,
+        }
+        rpc.onAppInfoUpdated(query.event, info)
+      }
+      catch (err) {
+        rpc.onAppInfoUpdated(query.event, { error: String(err) })
+      }
+    },
+
+    // ── Reload app ──────────────────────────────────────────────────────
+    async reloadApp(query: { event: string }) {
+      // Fire the ack BEFORE reloading so the server receives it
+      rpc.onReloadAppDone(query.event)
+      await new Promise(r => setTimeout(r, 50))
+      location.reload()
+    },
+
+    // ── Get component by file ───────────────────────────────────────────
+    async getComponentByFile(query: { filePath: string; event: string }) {
+      try {
+        const tree = await devtools.api.getInspectorTree({
+          inspectorId: COMPONENTS_INSPECTOR_ID,
+          filter: '',
+        })
+        const all = flattenChildren(tree[0])
+        const match = all.find((n: any) => n.file?.endsWith(query.filePath))
+        if (!match) {
+          rpc.onComponentByFileUpdated(query.event, {
+            found: false,
+            error: `No component found with file path ending in "${query.filePath}"`,
+          })
+          return
+        }
+        const state = await devtools.api.getInspectorState({
+          inspectorId: COMPONENTS_INSPECTOR_ID,
+          nodeId: match.id,
+        })
+        rpc.onComponentByFileUpdated(query.event, {
+          found: true,
+          name: match.name,
+          file: match.file,
+          state: stringify(state),
+        })
+      }
+      catch (err) {
+        rpc.onComponentByFileUpdated(query.event, { found: false, error: String(err) })
+      }
+    },
+  },
+  { timeout: -1 },
+)