{"id":"afedb9cf-e967-48ae-9c85-52220ee80f49","slug":"dev-inspector-mcp","kind":"mcp","name":"dev-inspector-mcp","summary":"AI-powered visual debugging for your React, Vue, Svelte, SolidJS, Preact & Next.js app via MCP and ACP","owner":"mcpc-tech","repoUrl":"https://github.com/mcpc-tech/dev-inspector-mcp","license":"MIT","licenseTier":"permissive","trust":"community","stars":47,"match":null,"fewStars":false,"format":"mcp","createdAt":null,"addedAt":"2026-10-14T05:42:37.491Z","logoUrl":"https://avatars.githubusercontent.com/u/209499265?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["utilities"],"tags":["dev-inspector-mcp","acp","devtools","react","svelte","vue"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-14T07:19:08.900Z","sample":false,"url":"https://conduits.dev/tools/dev-inspector-mcp","language":"TypeScript","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# dev-inspector-mcp\n\n[![npm version](https://img.shields.io/npm/v/@mcpc-tech/unplugin-dev-inspector-mcp.svg)](https://www.npmjs.com/package/@mcpc-tech/unplugin-dev-inspector-mcp)\n[![npm downloads](https://img.shields.io/npm/dm/@mcpc-tech/unplugin-dev-inspector-mcp.svg)](https://www.npmjs.com/package/@mcpc-tech/unplugin-dev-inspector-mcp)\n\n**The missing runtime context for AI coding agents.**\n\nAI can read your code, but can't see what's happening at runtime. DevInspector provides the missing context: source code location, DOM state, styles, network, console, terminal output, and screenshots.\n\n**Two modes**: Use with your IDE's AI (Cursor, VSCode) via MCP, or run AI agents directly in the browser via ACP (**Claude Code**, **Codex CLI**, **Gemini CLI**, **OpenCode**, [more](https://agentclientprotocol.com/overview/agents)).\n\n> **Using Claude Code or another AI agent?** Install the DevInspector skill so your agent knows how to set up and troubleshoot the inspector:\n>\n> ```bash\n> npx skills add mcpc-tech/dev-inspector-mcp\n> ```\n\n## Table of Contents\n\n- [Demo Video](#demo-video)\n- [Social Media](#social-media)\n- [Key Features](#key-features)\n- [Quick Start](#quick-start)\n  - [Installation](#installation)\n  - [Automated Setup](#automated-setup-recommended)\n  - [Framework Setup](#framework-setup)\n- [Agent Skills](#agent-skills)\n- [Configuration](#configuration)\n  - [Auto-Update MCP Config](#auto-update-mcp-config)\n  - [Agent Installation](#agent-installation)\n  - [Custom Agents](#custom-agents)\n  - [MCP Servers Configuration](#mcp-servers-configuration)\n- [What It Does](#what-it-does)\n- [Two Workflow Modes](#two-workflow-modes)\n- [MCP Tools](#mcp-tools)\n- [Custom Inspector Tools](#custom-inspector-tools)\n- [MCP Prompts](#mcp-prompts)\n- [Architecture](#architecture)\n\n## Demo Video\n\n**Watch the demo:** [https://www.youtube.com/shorts/TCt2oOtPS_k](https://www.youtube.com/shorts/TCt2oOtPS_k)\n\n## Social Media\n\n**Twittter/X Post:** [https://x.com/yaoandyan/status/1995082020431753600](https://x.com/yaoandyan/status/1995082020431753600?s=20)\n\n![Demo: MCP-powered visual debugging in action](https://media.giphy.com/media/sGCk7b783GiGm5vZGl/giphy.gif)\n\n## Key Features\n\n### Visual Context & Region Selection\n\nClick any element to inspect it, or **drag to select a region**. AI gets the full context: source code location, computed styles, component hierarchy, IDs, classes, text content, and **automatically captures screenshots** for pixel-perfect visual understanding.\n\n### Page Overview & Accessibility Tree\n\n`get_page_info` provides AI with a semantic understanding of the page: URL, viewport, and an **accessibility tree** showing landmarks, headings, forms, and links. AI can navigate the page structure without screenshots.\n\n### Universal DevTools Access\n\nAI can access Network and Console logs from **any browser** (via client-side interception) or full Chrome DevTools (via chrome devtools mcp). It sees what you see, regardless of your environment.\n\n### Multi-Agent Workflow\n\nSwitch between agents (Claude Code, Codex, Gemini, Opencode...) and track their debugging progress visually with a **floating status bar**.\n\n## Quick Start\n\n### Installation\n\n```bash\n# npm - basic installation\nnpm i -D @mcpc-tech/unplugin-dev-inspector-mcp\n\n# pnpm - basic installation\npnpm add -D @mcpc-tech/unplugin-dev-inspector-mcp\n\n# yarn - basic installation\nyarn add -D @mcpc-tech/unplugin-dev-inspector-mcp\n```\n\n> **Note:** If you don't need the ACP agents (Inspector Bar mode), add `--no-optional` to skip installing agent packages:\n>\n> ```bash\n> npm i -D @mcpc-tech/unplugin-dev-inspector-mcp --no-optional\n> pnpm add -D @mcpc-tech/unplugin-dev-inspector-mcp --no-optional\n> yarn add -D @mcpc-tech/unplugin-dev-inspector-mcp --no-optional\n> ```\n\n### Automated Setup (Recommended)\n\nRun the setup command to automatically configure your `vite.config.ts`, `webpack.config.js`, or `next.config.ts`:\n\n```bash\nnpx @mcpc-tech/unplugin-dev-inspector-mcp setup\n```\n\n**Options:**\n\n- `--dry-run` - Preview changes without applying them\n- `--config <path>` - Specify config file path (auto-detect by default)\n- `--bundler <type>` - Specify bundler type: vite, webpack, nextjs\n- `--no-backup` - Skip creating backup files\n- `--help` - Show help message\n\n**Examples:**\n\n```bash\n# Preview changes before applying\nnpx @mcpc-tech/unplugin-dev-inspector-mcp setup --dry-run\n\n# Setup specific config file\nnpx @mcpc-tech/unplugin-dev-inspector-mcp setup --config vite.config.ts\n\n# Setup for specific bundler\nnpx @mcpc-tech/unplugin-dev-inspector-mcp setup --bundler vite\n```\n\nThis will:\n\n- Detect your bundler configuration\n- Add the necessary import\n- Add the plugin to your configuration\n- Create a backup of your config file\n\n### Framework Setup\n\nPick your framework below. Each section is self-contained -- just copy the config.\n\n<details>\n<summary><b>Vite</b> (React / Vue / Svelte / Solid / Preact)</summary>\n\n```ts\n// vite.config.ts\nimport DevInspector from '@mcpc-tech/unplugin-dev-inspector-mcp';\nimport react from '@vitejs/plugin-react'; // or vue(), svelte(), solid(), preact()\n\nexport default {\n  plugins: [\n    DevInspector.vite({ enabled: true }),\n    react(),\n  ],\n};\n```\n\n> **Plugin order matters:** Place `DevInspector.vite()` **before** framework plugins. Otherwise source locations may show `unknown:0:0`.\n\n</details>\n\n<details>\n<summary><b>Next.js</b> (Webpack + Turbopack)</summary>\n\n**Step 1 -- next.config.ts:**\n\n```ts\nimport DevInspector, { turbopackDevInspector } from '@mcpc-tech/unplugin-dev-inspector-mcp';\n\nconst nextConfig = {\n  webpack: (config) => {\n    config.plugins.push(DevInspector.webpack({ enabled: true }));\n    return config;\n  },\n  turbopack: {\n    rules: turbopackDevInspector({ enabled: true }),\n  },\n};\n\nexport default nextConfig;\n```\n\n**Step 2 -- app/layout.tsx (required):**\n\n```tsx\nimport { DevInspector } from \"@mcpc-tech/unplugin-dev-inspector-mcp/next\";\n\nexport default function RootLayout({ children }) {\n  return (\n    <html>\n      <body>\n        <DevInspector />\n        {children}\n      </body>\n    </html>\n  );\n}\n```\n\nRun with `next dev` (webpack) or `next dev --turbopack` (turbopack).\n\n</details>\n\n<details>\n<summary><b>React Router v7+</b> (Remix)</summary>\n\n```ts\n// vite.config.ts\nimport { reactRouter } from \"@react-router/dev/vite\";\nimport DevInspector from '@mcpc-tech/unplugin-dev-inspector-mcp';\n\nexport default defineConfig({\n  plugins: [\n    DevInspector.vite({ enabled: true, entry: \"app/root.tsx\" }),\n    reactRouter(),\n  ],\n});\n```\n\n</details>\n\n<details>\n<summary><b>Webpack</b> (standalone)</summary>\n\n```js\n// webpack.config.js\nconst DevInspector = require('@mcpc-tech/unplugin-dev-inspector-mcp');\n\nmodule.exports = {\n  plugins: [\n    DevInspector.webpack({ enabled: true }),\n  ],\n};\n```\n\n</details>\n\n<details>\n<summary><b>Advanced options</b></summary>\n\n#### Non-HTML Projects (Miniapps, Library Bundles)\n\n```ts\nDevInspector.vite({\n  enabled: true,\n  autoInject: false,\n  entry: 'src/main.ts',\n})\n```\n\n#### TypeScript Types\n\nIf you import `virtual:dev-inspector-mcp`, add to your tsconfig:\n\n```jsonc\n{\n  \"compilerOptions\": {\n    \"types\": [\"vite/client\", \"@mcpc-tech/unplugin-dev-inspector-mcp/client\"]\n  }\n}\n```\n\n#### Custom Virtual Module Name\n\n```ts\nDevInspector.vite({\n  enabled: true,\n  autoInject: false,\n  virtualModuleName: 'virtual:my-custom-inspector',\n})\n```\n\n#### Disable Chrome DevTools\n\nSet `disableChrome: true` in plugin options or `DEV_INSPECTOR_DISABLE_CHROME=1` env var.\n\n**Zero Production Impact:** In production builds, `virtual:dev-inspector-mcp` becomes a no-op module.\n\n</details>\n\n### Supported Frameworks\n\nReact, Vue, Svelte, SolidJS, Preact, Next.js (Webpack + Turbopack), React Router v7+. Angular support in progress.\n\n## Agent Skills\n\nDevInspector ships a built-in **Agent Skill** for Claude Code (and compatible AI agents) that teaches the agent how to integrate and troubleshoot the inspector.\n\nInstall it with one command:\n\n```bash\nnpx skills add mcpc-tech/dev-inspector-mcp\n```\n\nThe skill covers setup for all supported bundlers, common gotchas, and troubleshooting -- so the agent can guide you through the entire integration without back-and-forth.\n\n> **What are Agent Skills?** Skills are Markdown-based instruction sets that AI agents load at session start to gain domain-specific knowledge. See the [Claude Code docs](https://code.claude.com/docs/en/skills) for more.\n\n## Configuration\n\n### Auto-Update MCP Config\n\nThe plugin automatically updates MCP configuration files for detected editors when the dev server starts. This saves you from manually configuring MCP endpoints.\n\n**Supported editors:** Cursor, VSCode, Windsurf, Claude Code, Antigravity\n\n```typescript\n// vite.config.ts\nDevInspector.vite({\n  // Auto-detect and update (default: true)\n  updateConfig: true,\n\n  // Or specify editors manually\n  updateConfig: ['cursor', 'vscode'],\n\n  // Or disable\n  updateConfig: false,\n\n  // Server name in MCP config (default: 'dev-inspector')\n  updateConfigServerName: 'my-app-inspector',\n})\n```\n\n**Custom editors:** For non-standard editors, use `customEditors`:\n\n```typescript\nDevInspector.vite({\n  customEditors: [\n    {\n      id: 'my-editor',\n      name: 'My Editor',\n      configPath: '~/.my-editor',        // absolute, ~/relative, or project-relative\n      configFileName: 'mcp.json',\n      serverUrlKey: 'url',               // default: 'url'\n      configFormat: 'mcpServers',        // 'mcpServers' or 'servers' (vscode-style)\n    },\n  ],\n})\n```\n\n### Agent Installation\n\nDevInspector supports multiple AI agents via [ACP](https://agentclientprotocol.com).\n\n**For npm-based agents** (Claude Code, Codex CLI, Cursor Agent, Droid), you can pre-install them as dev dependencies for faster loading.\n\n**For system-level agents**, install globally:\n\n#### Gemini CLI\n\n```bash\nnpm install -g @google/gemini-cli\n```\n\n[Documentation →](https://github.com/google-gemini/gemini-cli)\n\n#### Kimi CLI\n\n```bash\nuv tool install --python 3.13 kimi-cli\n```\n\n[Documentation →](https://github.com/MoonshotAI/kimi-cli)\n\n#### Goose\n\n```bash\npipx install goose-ai\n```\n\n[Documentation →](https://block.github.io/goose/docs/guides/acp-clients)\n\n#### Opencode\n\n```bash\ncurl -fsSL https://opencode.ai/install | bash\n```\n\n[Documentation →](https://github.com/sst/opencode)\n\n#### CodeBuddy Code\n\n```bash\nnpm install -g @tencent-ai/codebuddy-code\n```\n\n[Documentation →](https://copilot.tencent.com/docs/cli/acp)\n\n> **Note:** If you don't pre-install npm-based agents, they will be launched via `npx` on first use (slower startup).\n\n#### Pre-installing npm-based Agents (Recommended)\n\nThe recommended way is to install agents during initial setup (see [Installation](#installation) above).\n\nAlternatively, install them later as dev dependencies:\n\n```bash\n# npm\nnpm i -D @zed-industries/claude-code-acp\n\n# pnpm\npnpm add -D @zed-industries/claude-code-acp\n\n# Or add directly to package.json\n```\n\n```json\n{\n  \"devDependencies\": {\n    \"@zed-industries/claude-code-acp\": \"^0.12.4\",\n    \"@zed-industries/codex-acp\": \"^0.7.1\",\n    \"@blowmage/cursor-agent-acp\": \"^0.1.0\",\n    \"@yaonyan/droid-acp\": \"^0.0.8\"\n  }\n}\n```\n\n> **About optionalDependencies:** Agent packages are installed by default. If you don't need them, use `--no-optional` when installing.\n\n**Why install as `devDependencies`?**\n\n- Ensures faster startup (uses local package via `require.resolve` instead of `npx`)\n- Won't affect production bundle (tree-shaken out unless imported)\n- Standard practice for development tools\n\n### Custom Agents\n\nThis plugin uses the [Agent Client Protocol (ACP)](https://agentclientprotocol.com) to connect with AI agents.\n\n⏱️ **Note:** Initial connection may be slow as agents are launched via `npx` (downloads packages on first run).\n\nDefault agents: [View configuration →](https://github.com/mcpc-tech/dev-inspector-mcp/blob/main/packages/unplugin-dev-inspector/client/constants/agents.ts)\n\nYou can customize available AI agents, filter visible agents, and set a default agent:\n\n```typescript\n// vite.config.ts\nexport default {\n  plugins: [\n    DevInspector.vite({\n      enabled: true,\n\n      // Option 1: Only show specific agents (filters merged agents)\n      visibleAgents: ['Claude Code', 'Gemini CLI', 'Goose'],\n\n      // Option 2: Add custom agents (merges with defaults)\n      agents: [\n        {\n          name: \"Claude Code\", // Matches default - auto-fills icon and env\n          command: \"npx\",\n          args: [\"-y\", \"@zed-industries/claude-code-acp\"],\n        },\n        {\n          name: \"My Custom Agent\",\n          command: \"my-agent-cli\",\n          args: [\"--mode\", \"acp\"],\n          env: [{ key: \"MY_API_KEY\", required: true }],\n          meta: { icon: \"https://example.com/icon.svg\" }\n        }\n      ],\n\n      // Option 3: Combine both - add custom agents and filter visibility\n      agents: [\n        {\n          name: \"My Custom Agent\",\n          command: \"my-agent-cli\",\n          args: [\"--mode\", \"acp\"],\n          env: [{ key: \"MY_API_KEY\", required: true }],\n          meta: { icon: \"https://example.com/icon.svg\" }\n        }\n      ],\n      visibleAgents: ['Claude Code', 'My Custom Agent'], // Only show these\n\n      // Set default agent to show on startup\n      defaultAgent: \"Claude Code\"\n    }),\n  ],\n};\n```\n\n**Key Features:**\n\n- **`agents`**: Merges your custom agents with defaults. Agents with the **same name** as [default agents](https://agentclientprotocol.com/overview/agents) automatically inherit missing properties (icons, env)\n- **`visibleAgents`**: Filters which agents appear in the UI (applies after merging). Great for limiting options to only what your team uses\n- **`defaultAgent`**: Sets which agent is selected on startup\n- If no custom agents provided, defaults are: Claude Code, Codex CLI, Gemini CLI, Kimi CLI, Goose, Opencode, Cursor Agent, Droid, CodeBuddy Code\n\n### MCP Servers Configuration\n\nYou can configure external MCP servers for agents to access additional tools.\n\n```typescript\nDevInspector.vite({\n  mcpServers: [\n    // HTTP/SSE Server\n    {\n      name: 'remote-server',\n      type: 'sse', // or 'http'\n      url: 'https://api.example.com/sse',\n      headers: [{ name: 'Authorization', value: process.env.MCP_TOKEN ?? '' }]\n    },\n    // Local Stdio Server\n    {\n      name: 'local-server',\n      command: 'npx',\n      args: ['-y', '@modelcontextprotocol/server-memory'],\n      env: { MY_VAR: 'value' }\n    }\n  ]\n})\n```\n\n## What It Does\n\n**Click element → Describe issue → AI analyzes → Get fix**\n\n1. Click any UI element to capture context (source, styles, DOM)\n2. Describe what's wrong or ask a question about the element\n3. AI diagnoses using Chrome DevTools integration\n4. Get intelligent solutions through natural conversation\n\n**Examples:**\n\n- \"Why is this button not clickable?\" → AI checks `pointer-events`, z-index, overlays\n- \"This API call is failing\" → AI analyzes network requests, timing, responses\n- \"Where is this component?\" → Jump to source file and line number\n\n## Two Workflow Modes\n\nDevInspector offers two ways to interact with your AI, depending on your preference:\n\n### 1. Editor Mode\n\n**Best for:** Code-heavy tasks, refactoring, and maintaining flow.\n\n- **How it works:** You use your IDE's AI assistant (Cursor, Windsurf, Copilot).\n- **The Flow:** Click an element in the browser -> The context (source, props, styles) is sent to your Editor via MCP -> You ask your Editor to fix it.\n- **Why:** Keeps you in your coding environment.\n\n### 2. Inspector Bar Mode (Recommended)\n\n**Best for:** Quick fixes, visual tweaks, or if you don't use an AI editor.\n\n- **How it works:** You use the floating \"Inspector Bar\" directly in the browser.\n- **The Flow:** Click \"Ask AI\" in the browser -> Select an agent (e.g., Claude Code, Custom Script) -> The agent runs in your terminal but interacts with the browser overlay.\n- **Why:** No context switching. Great for \"what is this?\" questions or network debugging.\n\n## MCP Tools\n\n### `capture_element_context`\n\nCapture single element context. Two modes:\n\n- **Interactive (default)**: User clicks element to select\n- **Automated**: Use `selector` param for programmatic capture\n\nReturns: source location, DOM hierarchy, computed styles, dimensions, user notes, screenshot.\n\n### `capture_area_context`\n\nCapture multiple elements in an area. Two modes:\n\n- **Interactive (default)**: User draws rectangle to select area\n- **Automated**: Use `containerSelector` or `bounds` param\n\nReturns: array of element contexts (max 50).\n\n### `get_page_info`\n\nGet page overview with accessibility tree. Returns URL, title, viewport, document size, and semantic structure (landmarks, headings, forms, links). Start here to understand the page.\n\n### `list_inspections`\n\nList all captured inspections with ID, element details, source location, notes, and status (pending/in-progress/completed/failed).\n\n### `update_inspection_status`\n\nUpdate inspection status. Parameters: `inspectionId` (optional, auto-detects), `status` ('in-progress'|'completed'|'failed'|'deleted'), `message` (required for completed/failed).\n\n### `execute_page_script`\n\nExecute JavaScript in browser context. Access: window, document, DOM APIs, React/Vue instances, localStorage. Must return a value.\n\n### `get_network_requests`\n\nGet network requests from browser. Returns list with reqid, method, URL, status. Use `reqid` param to get full request/response details (headers, body, timing).\n\n### `get_console_messages`\n\nGet console messages from browser. Returns list with msgid, level (log/warn/error), message. Use `msgid` param to get full message details.\n\n### `get_stdio_messages`\n\nGet dev server stdout/stderr. Returns list with stdioid, stream type, content. Use `stdioid` param to get full message.\n\n### `chrome_devtools`\n\nAgentic tool for Chrome DevTools access. Provides network inspection, console logs, performance metrics, element interaction, and more.\n\n## Custom Inspector Tools\n\nYou can register your own custom tools to be used by the AI agent. These tools run directly in the browser context, giving the AI access to your application's state, logic, or any browser APIs.\n\n### `registerInspectorTool`\n\nUse this function to register a tool. It handles the MCP schema definition and implementation in one place.\n\n```typescript\n// main.ts or any entry file\nimport { registerInspectorTool } from 'virtual:dev-inspector-mcp';\n\nregisterInspectorTool({\n  name: \"get_user_state\",\n  description: \"Get current user session and preferences\",\n  inputSchema: {\n    type: \"object\",\n    properties: {\n      includeToken: {\n        type: \"boolean\",\n        description: \"Whether to include the auth token\"\n      }\n    }\n  },\n  implementation: (args) => {\n    // This runs in the browser!\n    const user = window.useUserStore?.getState();\n\n    if (args.includeToken) {\n      return { user, token: localStorage.getItem('token') };\n    }\n    return { user };\n  }\n});\n```\n\nThese custom tools are automatically discovered and made available to the connected AI agent along with the built-in inspector tools.\n\n## MCP Prompts\n\n### `capture_element_context`\n\nCapture single element context. Interactive (user clicks) or automated (selector param).\n\n### `capture_area_context`\n\nCapture multiple elements in area. Interactive (user draws rectangle) or automated (containerSelector/bounds param).\n\n### `list_inspections`\n\nView all element inspections in the queue with their status.\n\n### `launch_chrome_devtools`\n\nLaunch Chrome DevTools and navigate to a specified URL for debugging and inspection.\n\n**Parameter:** `url` (required) - The URL to navigate to (e.g., http://localhost:3000)\n\n### `get_network_requests`\n\nList network requests or get details of a specific one. Always refreshes the list first.\n\n### `get_console_messages`\n\nList console messages or get details of a specific one. Always refreshes the list first.\n\n### `get_stdio_messages`\n\nList stdio (stdout/stderr) messages from the server process. Always refreshes the list first.\n\n## Architecture\n\nFor a deep dive into how the MCP context, CMCP library, and Puppet binding mechanism work together, see the [Architecture Documentation](./docs/architecture/mcp-cmcp-puppet-architecture.md).\n\n**Key concepts:**\n\n- **Hub-and-spoke model**: Vite dev server acts as central hub managing multiple client connections\n- **CMCP bidirectional execution**: Server defines tool schemas, browser client provides implementations\n- **Puppet binding**: Enables Chrome DevTools ↔ Inspector message passthrough\n- **Dynamic rebinding**: Automatic connection recovery after browser refresh\n\n## License\n\n[MIT](./LICENSE)\n"}