vite-plugin-mcp-client-tools

Pluggable Vite MCP plugin that brings client-side tools to your existing Vite setup.

Give your coding agent eyes and ears for your Vite app during development.

Why This Plugin?

When developing a Vite app with HMR (Hot Module Replacement) using a coding agent, your agent is essentially working blind—it can't see what your app actually looks like in the browser or what's happening in the console. This leads to exchanges like:

• Agent: "Perfect! Now the button looks more modern!"
• You: "Actually, it's completely broken and there are errors in the console..."

This plugin solves that problem by bringing browser visibility directly into your agent's workflow as MCP (Model Context Protocol) tools. It's not a separate service or additional setup—it's just part of your regular Vite development server.

What Makes This Different?

Other solutions for giving coding agents browser visibility typically involve running separate browser instances or automation services (like Playwright or Puppeteer-based MCP servers, or IDE-specific browser control features).

This plugin takes a different approach: it's seamlessly integrated into your existing Vite development workflow. The browser you're already using for HMR becomes the observation point—no additional setup, no separate processes to manage. Just add it to your vite.config.js and the tools are immediately available to your agent.

Features

• Screenshot Tool: Capture the current browser tab with configurable quality
• Console Reader: Access all browser console logs (log, warn, error, info)
• Integrated MCP Server: Works with any MCP-compatible coding agent
• Zero Additional Services: No extra processes or servers to manage

Installation

npm install vite-plugin-mcp-client-tools

Usage

Add the plugin to your vite.config.js:

import { defineConfig } from "vite";
import { viteMcpPlugin } from "vite-plugin-mcp-client-tools";
import { readConsoleTool } from "vite-plugin-mcp-client-tools/tools/read-console";
import { takeScreenshotTool } from "vite-plugin-mcp-client-tools/tools/take-screenshot";

export default defineConfig({
  plugins: [
    viteMcpPlugin({
      tools: [readConsoleTool, takeScreenshotTool],
    }),
  ],
});

Then configure your MCP client (e.g., Claude Code, Cursor) to connect to the Vite dev server's MCP endpoint at http://localhost:5173/mcp (or your configured Vite port).

Available Tools

take-screenshot

Captures a screenshot of the current browser tab.

How It Works:

• On first use, displays a modal asking for screen sharing permission
• Uses the browser's native screen capture API
• Subsequent screenshots are instant—no modal, no delay
• Waits 2 seconds after initial capture to let Chrome's dimension overlay fade

Options:

• JPEG Quality (slider): 0.0 to 1.0 in 0.1 increments (default: 0.2)
  • Lower quality = smaller file sizes
  • Adjust based on your needs (detail vs. bandwidth)
• Save to Disk (checkbox): Optionally save screenshots to tmp/screenshots/ (default: OFF)
  • When enabled, file path is included in the tool response
  • Useful for agents that want to reference saved files

Returns:

• Base64-encoded JPEG image
• Quality value used
• File path (if save-to-disk was enabled)

Example Response:

Screenshot of current browser tab captured (quality: 0.8, saved to: /path/to/screenshot.jpeg)

read-console

Intercepts and returns browser console logs.

Features:

• Captures all log levels: log, warn, error, info
• Preserves log order and timestamps
• Non-visual component (no UI impact)
• Optional tail parameter to limit results (like tail -n)

Parameters:

• tail (optional): Number of most recent entries to return

Returns:

• Array of console entries with:
  • Timestamp (Swedish locale format: YYYY-MM-DD HH:mm:ss)
  • Log level (info/log/warn/error)
  • Message content

Example:

[
  {
    "timestamp": "2025-10-12 16:45:23",
    "level": "info",
    "message": "App started successfully!"
  },
  {
    "timestamp": "2025-10-12 16:45:25",
    "level": "log",
    "message": "Counter incremented to: 1"
  },
  {
    "timestamp": "2025-10-12 16:45:30",
    "level": "warn",
    "message": "Counter reached milestone: 5"
  }
]

Tool Architecture

Beyond the standard MCP tool definition components (name, description, inputSchema, and outputSchema), each tool consists of:

1. Handler: A function that implements the tool's core logic. The handler receives:

   • this.component: The DOM node for the tool's WebComponent (if defined)
   • this.server: A Proxy that lets the tool remote-call its server-side methods (if defined)

2. Component (optional): A factory function for a WebComponent that gets mounted on the document's body. Useful for tools that require user interaction or configurability (e.g., the screenshot tool's quality settings).

3. Server methods (optional): A hash of helper methods that get mounted on the Vite server, namespaced by the tool's name. These are Node.js-side utilities (e.g., file saving for screenshots).

The plugin:

• Exposes an MCP server endpoint at /mcp
• Injects tool components into the page as custom web components
• Uses Vite's HMR WebSocket connection for bi-directional RPC between the browser and server

Creating Custom Tools

See AGENTS.md for detailed information about the architecture and creating your own tools.

Example Project

The example/ directory contains a minimal Vite app demonstrating both tools:

• Counter app with console logging at different levels
• Pre-configured with this plugin and both tools
• Ready to test with your coding agent

See example/README.md for setup instructions.

Advanced Options

Include transformModule as a regular expression that matches a module served by Vite to let the plugin inject its code into that module instead of modifying index.html, for cases where index.html is not served by Vite. In Vite plugin parlance, this makes the plugin use transform on the matching module instead of using transformIndexHtml.

export default defineConfig({
  plugins: [
    viteMcpPlugin({
      transformModule: /src\/main\.js/,
      tools: [readConsoleTool, takeScreenshotTool],
    }),
  ],
});

You also need to include the MCP Bridge virtual module from your page, matching the base URL of the Vite server:

<script type="module" src="/virtual:mcp-bridge"></script>

Development

# Install dependencies
npm install

# Build the plugin
npm run build

# Build the plugin in watch mode
npm run dev

# Run the example (in a separate terminal)
cd example
npm install
npm run dev

Important: Vite plugin code does not support HMR. After making changes to the plugin source:

1. Run npm run build
2. Kill and restart the dev server
3. Reload the browser page

See AGENTS.md for more development tips.

MCP Configuration

Claude Code

Add to your Claude Code MCP configuration:

{
  "mcpServers": {
    "vite-dev": {
      "url": "http://localhost:5173/mcp"
    }
  }
}

Other Agents

Any MCP-compatible coding agent can connect to the /mcp endpoint on your Vite dev server. Check your agent's documentation for MCP server configuration.

Requirements

• Node.js 16+
• Modern browser with Screen Capture API support (Chrome, Edge, etc.)
• Vite 4.0+

License

MIT

Contributing

Contributions welcome! Please feel free to submit issues or pull requests.