@mcpc-tech/unplugin-dev-inspector-mcp 0.0.37 → 0.0.38

package/dist/config-updater.cjs

@@ -21,6 +21,7 @@ let _modelcontextprotocol_sdk_inMemory_js = require("@modelcontextprotocol/sdk/i
 let node_process = require("node:process");
 node_process = require_chunk.__toESM(node_process);
 let os = require("os");
+let child_process = require("child_process");
 let fs = require("fs");
 fs = require_chunk.__toESM(fs);
 let http = require("http");
@@ -58015,9 +58016,9 @@ var require_utils$5 = /* @__PURE__ */ require_chunk.__commonJSMin(((exports) =>
 var require_execAsync$1 = /* @__PURE__ */ require_chunk.__commonJSMin(((exports) => {
 	Object.defineProperty(exports, "__esModule", { value: true });
 	exports.execAsync = void 0;
-	const child_process$1 = require("child_process");
+	const child_process$2 = require("child_process");
 	const util$1 = require("util");
-	exports.execAsync = util$1.promisify(child_process$1.exec);
+	exports.execAsync = util$1.promisify(child_process$2.exec);
 }));
 
 //#endregion
@@ -66167,9 +66168,9 @@ var require_utils$1 = /* @__PURE__ */ require_chunk.__commonJSMin(((exports) =>
 var require_execAsync = /* @__PURE__ */ require_chunk.__commonJSMin(((exports) => {
 	Object.defineProperty(exports, "__esModule", { value: true });
 	exports.execAsync = void 0;
-	const child_process = require("child_process");
+	const child_process$1 = require("child_process");
 	const util = require("util");
-	exports.execAsync = util.promisify(child_process.exec);
+	exports.execAsync = util.promisify(child_process$1.exec);
 }));
 
 //#endregion
@@ -86816,6 +86817,7 @@ var ConnectionManager = class {
 		transport.onclose = () => this.removeTransport(sessionId);
 	}
 	removeTransport(sessionId) {
+		console.log(`[dev-inspector] [connection-manager] Removing transport: ${sessionId}`);
 		delete this.transports[sessionId];
 		for (const [_clientId, sessionIds] of this.watchersByClientId) if (sessionIds.has(sessionId)) {
 			sessionIds.delete(sessionId);
@@ -86846,6 +86848,7 @@ var ConnectionManager = class {
 			}
 			sessionsToRemove.push(existingSessionId);
 		}
+		if (sessionsToRemove.length > 0) console.log(`[dev-inspector] [connection-manager] Cleaned up ${sessionsToRemove.length} previous sessions for clientId=${clientId} (new session=${newSessionId})`);
 		for (const sessionId of sessionsToRemove) sessionIds.delete(sessionId);
 	}
 	handleInspectorConnection(sessionId) {
@@ -87056,11 +87059,17 @@ async function handleSseConnection(req, res, serverContext, connectionManager) {
 		const url$1 = new URL(req.url ?? "", `http://${host}:${port}`);
 		const transport = new _modelcontextprotocol_sdk_server_sse_js.SSEServerTransport("/__mcp__/messages", res);
 		const sessionId = transport.sessionId;
-		const clientId = url$1.searchParams.get("clientId") || "agent";
+		const clientId = url$1.searchParams.get("clientId") || `agent-${sessionId}`;
 		const puppetId = url$1.searchParams.get("puppetId") || "inspector";
+		console.log(`[dev-inspector] [sse] New connection request: clientId=${clientId}, puppetId=${puppetId}, sessionId=${sessionId}`);
 		connectionManager.registerTransport(sessionId, transport);
-		if (clientId === "inspector") connectionManager.handleInspectorConnection(sessionId);
-		else connectionManager.handleWatcherConnection(sessionId, clientId, puppetId, transport);
+		if (clientId === "inspector") {
+			console.log(`[dev-inspector] [sse] Handling Inspector connection: ${sessionId}`);
+			connectionManager.handleInspectorConnection(sessionId);
+		} else {
+			console.log(`[dev-inspector] [sse] Handling Watcher connection: ${sessionId} (binding to ${puppetId})`);
+			connectionManager.handleWatcherConnection(sessionId, clientId, puppetId, transport);
+		}
 		await mcpServer.connect(transport);
 	} catch (error) {
 		console.error("Error establishing SSE connection:", error);
@@ -88074,6 +88083,7 @@ var ACPLanguageModel = class {
 		try {
 			await this.ensureConnected();
 			const promptContent = convertAiSdkMessagesToAcp(options, this.isFreshSession);
+			console.log(`###########`, promptContent);
 			this.isFreshSession = false;
 			let accumulatedText = "";
 			const toolCalls = [];
@@ -88283,6 +88293,19 @@ function createACPProvider(config) {
 //#endregion
 //#region src/middleware/acp-middleware.ts
 /**
+* Check if a command exists in the system PATH
+* Skips check for npx since it always exists
+*/
+function checkCommandExists(command) {
+	if (command === "npx" || command === "node") return true;
+	try {
+		(0, child_process.execSync)(`which ${command}`, { stdio: "ignore" });
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
 * Provider manager - stores one provider per agent config
 * Key: agentKey (command:args), Value: ProviderEntry
 */
@@ -88346,12 +88369,33 @@ async function loadMcpToolsV5(transport) {
 	return tools;
 }
 /**
-* Get the Inspector transport from the connection manager
+* Default system instructions for DevInspector - provides AI guidance
+*/
+const DEFAULT_SYSTEM_INSTRUCTIONS = `# DevInspector Context
+
+You are connected to a web app with DevInspector. Available tools:
+
+- **list_inspections**: Check pending element inspections from user
+- **capture_element_context**: Activate visual selector to capture UI elements
+- **update_inspection_status**: Update inspection status with progress/results
+- **execute_page_script**: Run JavaScript in browser context
+- **chrome_devtools**: Access Chrome DevTools for network, console, performance
+
+Workflow: Check \`list_inspections\` first. If there are pending items, help resolve them. Otherwise, assist with the user's request.`;
+/**
+* Get an active transport from the connection manager
 */
 function getActiveTransport() {
 	const connectionManager = getConnectionManager();
 	if (!connectionManager) return null;
-	return connectionManager.getInspectorTransport();
+	return connectionManager.getInspectorTransport() || connectionManager.transports[Object.keys(connectionManager.transports)[0]];
+}
+/**
+* Get specifically the inspector transport for context and tools
+*/
+function getInspectorTransport() {
+	const connectionManager = getConnectionManager();
+	return connectionManager ? connectionManager.getInspectorTransport() : null;
 }
 function setupAcpMiddleware(middlewares, serverContext, acpOptions) {
 	/**
@@ -88398,6 +88442,14 @@ function setupAcpMiddleware(middlewares, serverContext, acpOptions) {
 					console.log(`[dev-inspector] [acp] Reusing existing provider for ${agent.name}`);
 					provider = providerEntry.provider;
 				} else {
+					if (!checkCommandExists(agent.command)) {
+						const hints = [`Agent "${agent.name}" command not found: "${agent.command}"`];
+						if (agent.installCommand) hints.push(`Install with: ${agent.installCommand}`);
+						if (agent.configHint) hints.push(agent.configHint);
+						if (agent.configLink) hints.push(`Documentation: ${agent.configLink}`);
+						console.error(`\n${hints.join("\n")}\n`);
+						return;
+					}
 					console.log(`[dev-inspector] [acp] Creating new global provider for ${agent.name}`);
 					provider = createACPProvider({
 						command: agent.command,
@@ -88424,7 +88476,7 @@ function setupAcpMiddleware(middlewares, serverContext, acpOptions) {
 				}
 				console.log(`[dev-inspector] [acp] Spawning new process/session for ${agent.name}`);
 				const initPromise = (async () => {
-					const transport = getActiveTransport();
+					const transport = getInspectorTransport() || getActiveTransport();
 					let initialTools = {};
 					if (transport) try {
 						const rawTools = await loadMcpToolsV5(transport);
@@ -88456,6 +88508,7 @@ function setupAcpMiddleware(middlewares, serverContext, acpOptions) {
 			res.setHeader("Content-Type", "application/json");
 			res.end(JSON.stringify({ sessionId }));
 		} catch (error) {
+			if (error instanceof Error && error.message.includes("command not found")) throw error;
 			console.error("ACP Init Session Error:", error);
 			if (!res.headersSent) {
 				res.statusCode = 500;
@@ -88550,7 +88603,7 @@ function setupAcpMiddleware(middlewares, serverContext, acpOptions) {
 				});
 				await provider.initSession();
 			}
-			const transport = getActiveTransport();
+			const transport = getInspectorTransport() || getActiveTransport();
 			let mcpTools = {};
 			if (transport) mcpTools = await loadMcpToolsV5(transport);
 			else console.warn("[dev-inspector] [acp] No active MCP transport available, tools will not be loaded");
@@ -88567,10 +88620,21 @@ function setupAcpMiddleware(middlewares, serverContext, acpOptions) {
 				abortController.abort();
 				if (shouldCleanupProvider) provider.cleanup();
 			});
+			const systemPrompt = agent.acpSystemPrompt ?? acpOptions?.acpSystemPrompt ?? DEFAULT_SYSTEM_INSTRUCTIONS;
+			const enhancedMessages = (0, ai.convertToModelMessages)(messages).map((msg, index$1) => {
+				if (index$1 === 0 && msg.role === "user" && Array.isArray(msg.content)) return {
+					...msg,
+					content: [{
+						type: "text",
+						text: `<system_instructions>\n${systemPrompt}\n</system_instructions>\n\n`
+					}, ...msg.content]
+				};
+				return msg;
+			});
 			const response = (0, ai.streamText)({
 				model: provider.languageModel(model, mode),
 				includeRawChunks: true,
-				messages: (0, ai.convertToModelMessages)(messages),
+				messages: enhancedMessages,
 				abortSignal: abortController.signal,
 				tools: acpTools(mcpTools),
 				onError: (error) => {

package/dist/config-updater.js

@@ -17,6 +17,7 @@ import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/
 import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
 import process$1, { cwd } from "node:process";
 import { homedir } from "os";
+import { execSync } from "child_process";
 import fs, { existsSync } from "fs";
 import * as http from "http";
 import * as https from "https";
@@ -86851,6 +86852,7 @@ var ConnectionManager = class {
 		transport.onclose = () => this.removeTransport(sessionId);
 	}
 	removeTransport(sessionId) {
+		console.log(`[dev-inspector] [connection-manager] Removing transport: ${sessionId}`);
 		delete this.transports[sessionId];
 		for (const [_clientId, sessionIds] of this.watchersByClientId) if (sessionIds.has(sessionId)) {
 			sessionIds.delete(sessionId);
@@ -86881,6 +86883,7 @@ var ConnectionManager = class {
 			}
 			sessionsToRemove.push(existingSessionId);
 		}
+		if (sessionsToRemove.length > 0) console.log(`[dev-inspector] [connection-manager] Cleaned up ${sessionsToRemove.length} previous sessions for clientId=${clientId} (new session=${newSessionId})`);
 		for (const sessionId of sessionsToRemove) sessionIds.delete(sessionId);
 	}
 	handleInspectorConnection(sessionId) {
@@ -87091,11 +87094,17 @@ async function handleSseConnection(req, res, serverContext, connectionManager) {
 		const url = new URL(req.url ?? "", `http://${host}:${port}`);
 		const transport = new SSEServerTransport("/__mcp__/messages", res);
 		const sessionId = transport.sessionId;
-		const clientId = url.searchParams.get("clientId") || "agent";
+		const clientId = url.searchParams.get("clientId") || `agent-${sessionId}`;
 		const puppetId = url.searchParams.get("puppetId") || "inspector";
+		console.log(`[dev-inspector] [sse] New connection request: clientId=${clientId}, puppetId=${puppetId}, sessionId=${sessionId}`);
 		connectionManager.registerTransport(sessionId, transport);
-		if (clientId === "inspector") connectionManager.handleInspectorConnection(sessionId);
-		else connectionManager.handleWatcherConnection(sessionId, clientId, puppetId, transport);
+		if (clientId === "inspector") {
+			console.log(`[dev-inspector] [sse] Handling Inspector connection: ${sessionId}`);
+			connectionManager.handleInspectorConnection(sessionId);
+		} else {
+			console.log(`[dev-inspector] [sse] Handling Watcher connection: ${sessionId} (binding to ${puppetId})`);
+			connectionManager.handleWatcherConnection(sessionId, clientId, puppetId, transport);
+		}
 		await mcpServer.connect(transport);
 	} catch (error) {
 		console.error("Error establishing SSE connection:", error);
@@ -88109,6 +88118,7 @@ var ACPLanguageModel = class {
 		try {
 			await this.ensureConnected();
 			const promptContent = convertAiSdkMessagesToAcp(options, this.isFreshSession);
+			console.log(`###########`, promptContent);
 			this.isFreshSession = false;
 			let accumulatedText = "";
 			const toolCalls = [];
@@ -88318,6 +88328,19 @@ function createACPProvider(config) {
 //#endregion
 //#region src/middleware/acp-middleware.ts
 /**
+* Check if a command exists in the system PATH
+* Skips check for npx since it always exists
+*/
+function checkCommandExists(command) {
+	if (command === "npx" || command === "node") return true;
+	try {
+		execSync(`which ${command}`, { stdio: "ignore" });
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
 * Provider manager - stores one provider per agent config
 * Key: agentKey (command:args), Value: ProviderEntry
 */
@@ -88381,12 +88404,33 @@ async function loadMcpToolsV5(transport) {
 	return tools;
 }
 /**
-* Get the Inspector transport from the connection manager
+* Default system instructions for DevInspector - provides AI guidance
+*/
+const DEFAULT_SYSTEM_INSTRUCTIONS = `# DevInspector Context
+
+You are connected to a web app with DevInspector. Available tools:
+
+- **list_inspections**: Check pending element inspections from user
+- **capture_element_context**: Activate visual selector to capture UI elements
+- **update_inspection_status**: Update inspection status with progress/results
+- **execute_page_script**: Run JavaScript in browser context
+- **chrome_devtools**: Access Chrome DevTools for network, console, performance
+
+Workflow: Check \`list_inspections\` first. If there are pending items, help resolve them. Otherwise, assist with the user's request.`;
+/**
+* Get an active transport from the connection manager
 */
 function getActiveTransport() {
 	const connectionManager = getConnectionManager();
 	if (!connectionManager) return null;
-	return connectionManager.getInspectorTransport();
+	return connectionManager.getInspectorTransport() || connectionManager.transports[Object.keys(connectionManager.transports)[0]];
+}
+/**
+* Get specifically the inspector transport for context and tools
+*/
+function getInspectorTransport() {
+	const connectionManager = getConnectionManager();
+	return connectionManager ? connectionManager.getInspectorTransport() : null;
 }
 function setupAcpMiddleware(middlewares, serverContext, acpOptions) {
 	/**
@@ -88433,6 +88477,14 @@ function setupAcpMiddleware(middlewares, serverContext, acpOptions) {
 					console.log(`[dev-inspector] [acp] Reusing existing provider for ${agent.name}`);
 					provider = providerEntry.provider;
 				} else {
+					if (!checkCommandExists(agent.command)) {
+						const hints = [`Agent "${agent.name}" command not found: "${agent.command}"`];
+						if (agent.installCommand) hints.push(`Install with: ${agent.installCommand}`);
+						if (agent.configHint) hints.push(agent.configHint);
+						if (agent.configLink) hints.push(`Documentation: ${agent.configLink}`);
+						console.error(`\n${hints.join("\n")}\n`);
+						return;
+					}
 					console.log(`[dev-inspector] [acp] Creating new global provider for ${agent.name}`);
 					provider = createACPProvider({
 						command: agent.command,
@@ -88459,7 +88511,7 @@ function setupAcpMiddleware(middlewares, serverContext, acpOptions) {
 				}
 				console.log(`[dev-inspector] [acp] Spawning new process/session for ${agent.name}`);
 				const initPromise = (async () => {
-					const transport = getActiveTransport();
+					const transport = getInspectorTransport() || getActiveTransport();
 					let initialTools = {};
 					if (transport) try {
 						const rawTools = await loadMcpToolsV5(transport);
@@ -88491,6 +88543,7 @@ function setupAcpMiddleware(middlewares, serverContext, acpOptions) {
 			res.setHeader("Content-Type", "application/json");
 			res.end(JSON.stringify({ sessionId }));
 		} catch (error) {
+			if (error instanceof Error && error.message.includes("command not found")) throw error;
 			console.error("ACP Init Session Error:", error);
 			if (!res.headersSent) {
 				res.statusCode = 500;
@@ -88585,7 +88638,7 @@ function setupAcpMiddleware(middlewares, serverContext, acpOptions) {
 				});
 				await provider.initSession();
 			}
-			const transport = getActiveTransport();
+			const transport = getInspectorTransport() || getActiveTransport();
 			let mcpTools = {};
 			if (transport) mcpTools = await loadMcpToolsV5(transport);
 			else console.warn("[dev-inspector] [acp] No active MCP transport available, tools will not be loaded");
@@ -88602,10 +88655,21 @@ function setupAcpMiddleware(middlewares, serverContext, acpOptions) {
 				abortController.abort();
 				if (shouldCleanupProvider) provider.cleanup();
 			});
+			const systemPrompt = agent.acpSystemPrompt ?? acpOptions?.acpSystemPrompt ?? DEFAULT_SYSTEM_INSTRUCTIONS;
+			const enhancedMessages = convertToModelMessages(messages).map((msg, index$1) => {
+				if (index$1 === 0 && msg.role === "user" && Array.isArray(msg.content)) return {
+					...msg,
+					content: [{
+						type: "text",
+						text: `<system_instructions>\n${systemPrompt}\n</system_instructions>\n\n`
+					}, ...msg.content]
+				};
+				return msg;
+			});
 			const response = streamText({
 				model: provider.languageModel(model, mode),
 				includeRawChunks: true,
-				messages: convertToModelMessages(messages),
+				messages: enhancedMessages,
 				abortSignal: abortController.signal,
 				tools: acpTools(mcpTools),
 				onError: (error) => {

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import * as unplugin1 from "unplugin";
+import * as unplugin0 from "unplugin";
 
 //#region src/utils/config-updater.d.ts
 type EditorId = "cursor" | "vscode" | "windsurf" | "claude-code" | "antigravity";
@@ -52,6 +52,11 @@ interface AcpOptions {
    * @default undefined (skipped if not specified)
    */
   acpDelay?: number;
+  /**
+   * Custom system instructions to prepend to user messages
+   * @default undefined (uses built-in DevInspector context)
+   */
+  acpSystemPrompt?: string;
 }
 interface Agent extends AcpOptions {
   name: string;
@@ -65,6 +70,18 @@ interface Agent extends AcpOptions {
   meta?: {
     icon?: string;
   };
+  /**
+   * Configuration hint text to help users set up the agent
+   */
+  configHint?: string;
+  /**
+   * Link to configuration documentation or setup guide
+   */
+  configLink?: string;
+  /**
+   * Installation command for the agent (shown in error messages)
+   */
+  installCommand?: string;
 }
 //#endregion
 //#region src/utils/create-plugin.d.ts
@@ -134,10 +151,10 @@ interface DevInspectorOptions extends McpConfigOptions, AcpOptions {
 }
 //#endregion
 //#region src/core.d.ts
-declare const unplugin: unplugin1.UnpluginInstance<DevInspectorOptions | undefined, boolean>;
+declare const unplugin: unplugin0.UnpluginInstance<DevInspectorOptions | undefined, boolean>;
 //#endregion
 //#region src/core-external.d.ts
-declare const unpluginExternal: unplugin1.UnpluginInstance<DevInspectorOptions | undefined, boolean>;
+declare const unpluginExternal: unplugin0.UnpluginInstance<DevInspectorOptions | undefined, boolean>;
 //#endregion
 //#region src/turbopack.d.ts
 interface TurbopackDevInspectorOptions extends DevInspectorOptions {
@@ -162,7 +179,7 @@ interface TurbopackDevInspectorOptions extends DevInspectorOptions {
 declare function turbopackDevInspector(options?: TurbopackDevInspectorOptions): any;
 //#endregion
 //#region src/index.d.ts
-declare const external: unplugin1.UnpluginInstance<DevInspectorOptions | undefined, boolean>;
+declare const external: unplugin0.UnpluginInstance<DevInspectorOptions | undefined, boolean>;
 declare module "virtual:dev-inspector-mcp" {}
 //#endregion
 export { type CustomEditorConfig, type DevInspectorOptions, type EditorId, type McpConfigOptions, type TurbopackDevInspectorOptions, unplugin as default, unplugin, external, turbopackDevInspector, unpluginExternal };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import * as unplugin0 from "unplugin";
+import * as unplugin1 from "unplugin";
 
 //#region src/utils/config-updater.d.ts
 type EditorId = "cursor" | "vscode" | "windsurf" | "claude-code" | "antigravity";
@@ -52,6 +52,11 @@ interface AcpOptions {
    * @default undefined (skipped if not specified)
    */
   acpDelay?: number;
+  /**
+   * Custom system instructions to prepend to user messages
+   * @default undefined (uses built-in DevInspector context)
+   */
+  acpSystemPrompt?: string;
 }
 interface Agent extends AcpOptions {
   name: string;
@@ -65,6 +70,18 @@ interface Agent extends AcpOptions {
   meta?: {
     icon?: string;
   };
+  /**
+   * Configuration hint text to help users set up the agent
+   */
+  configHint?: string;
+  /**
+   * Link to configuration documentation or setup guide
+   */
+  configLink?: string;
+  /**
+   * Installation command for the agent (shown in error messages)
+   */
+  installCommand?: string;
 }
 //#endregion
 //#region src/utils/create-plugin.d.ts
@@ -134,10 +151,10 @@ interface DevInspectorOptions extends McpConfigOptions, AcpOptions {
 }
 //#endregion
 //#region src/core.d.ts
-declare const unplugin: unplugin0.UnpluginInstance<DevInspectorOptions | undefined, boolean>;
+declare const unplugin: unplugin1.UnpluginInstance<DevInspectorOptions | undefined, boolean>;
 //#endregion
 //#region src/core-external.d.ts
-declare const unpluginExternal: unplugin0.UnpluginInstance<DevInspectorOptions | undefined, boolean>;
+declare const unpluginExternal: unplugin1.UnpluginInstance<DevInspectorOptions | undefined, boolean>;
 //#endregion
 //#region src/turbopack.d.ts
 interface TurbopackDevInspectorOptions extends DevInspectorOptions {
@@ -162,7 +179,7 @@ interface TurbopackDevInspectorOptions extends DevInspectorOptions {
 declare function turbopackDevInspector(options?: TurbopackDevInspectorOptions): any;
 //#endregion
 //#region src/index.d.ts
-declare const external: unplugin0.UnpluginInstance<DevInspectorOptions | undefined, boolean>;
+declare const external: unplugin1.UnpluginInstance<DevInspectorOptions | undefined, boolean>;
 declare module "virtual:dev-inspector-mcp" {}
 //#endregion
 export { type CustomEditorConfig, type DevInspectorOptions, type EditorId, type McpConfigOptions, type TurbopackDevInspectorOptions, unplugin as default, unplugin, external, turbopackDevInspector, unpluginExternal };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcpc-tech/unplugin-dev-inspector-mcp",
-  "version": "0.0.37",
+  "version": "0.0.38",
   "description": "Universal dev inspector plugin for React/Vue - inspect component sources and API calls in any bundler",
   "type": "module",
   "license": "MIT",