vite-plugin-agent

Vite Agents Runtime — a Vite plugin that exposes a structured MCP endpoint so AI coding agents can query, validate, and operate the Vite toolchain.

This is not a framework component-tree inspector (see antfu/vite-plugin-mcp for app-level Vue/Nuxt insight). It targets the toolchain layer: server status, diagnostics, module graph, HMR history, config validation, plugins, and production builds.

Install

bun add -d vite-plugin-agent

Usage

// vite.config.ts
import { defineConfig } from 'vite'
import { agent } from 'vite-plugin-agent'

export default defineConfig({
  plugins: [
    agent({
      mcpPath: '/__mcp', // default
      printUrl: true,
      // Build tools are intentionally disabled by default.
      allowBuild: true,
    }),
  ],
  server: {
    host: '127.0.0.1',
    port: 5173,
    strictPort: true,
  },
})

Create a project-scoped configuration for Claude Code, Codex, or VS Code:

bunx vite-plugin-agent init

The initializer safely manages only the vite-agent entry and preserves unrelated servers and comments. It does not edit global settings, vite.config.*, or AGENTS.md. Use --dry-run to preview, or --client codex --yes in a non-interactive environment.

Start Vite and verify both the local configuration and live MCP handshake:

bun run dev
bunx vite-plugin-agent doctor

The default endpoint is http://127.0.0.1:5173/__mcp. A custom --url must be a loopback HTTP address and must match the Vite host, port, base, and mcpPath. Opening the endpoint in a browser returns the expected 405 Method not allowed response because a normal GET is not an MCP session.

Options

| Option | Default | Description | | ---------------------- | ------------------- | -------------------------------------------------- | | mcpPath | '/__mcp' | HTTP path for Streamable MCP | | printUrl | true | Log MCP endpoint on listen | | hmrHistorySize | 100 | HMR ring buffer size | | diagnosticsSize | 200 | Max retained diagnostics | | moduleGraphNodeLimit | 200 | Hard cap for graph nodes | | buildHistorySize | 20 | Retained process-local build tasks | | buildTaskTtlMs | 300000 | Build task lifetime | | allowBuild | false | Register trigger_build and get_build_result | | experimentalTasks | false | Enable process-local MCP Tasks for capable clients | | tools | six read-only tools | Per-tool enable map; cannot bypass allowBuild |

MCP Tools

| Tool | Side effects | Purpose | | ------------------- | ------------ | ---------------------------------------- | | get_server_status | no | Configured/actual port, mode, Vite state | | get_diagnostics | no | Up to 20 summaries; source is opt-in | | get_module_graph | no | Imports/importers, 50 nodes by default | | get_hmr_history | no | Recent HMR events | | validate_config | no | Resolved config analysis | | list_plugins | no | Loaded plugins + hooks | | trigger_build | yes | Run one-shot or Tasks watch builds | | get_build_result | no | Query retained builds by taskId |

Recommended call order

1. get_server_status
2. get_diagnostics with the compact defaults
3. list_plugins / validate_config
4. After edits → get_hmr_history + get_diagnostics
5. get_module_graph with a narrow filter and small limit
6. trigger_build → get_build_result

An MCP-capable coding agent may select these tools automatically when a request needs live Vite state, but connection does not guarantee a tool call on every turn. You can explicitly ask it to check Vite status, diagnostics, or the module graph. Focused runtime queries can replace broad log or source reads; tool results also consume context, so the plugin does not guarantee lower token usage or a fixed saving ratio.

Security

• Endpoint is intended for local dev agents.
• Host/Origin checks prefer localhost.
• No remote telemetry; project source is not uploaded.
• trigger_build is explicitly documented as a side-effect tool.

Stdio clients

The plugin serves MCP over Streamable HTTP on the Vite dev server. For agents that only support stdio, use the bundled proxy:

# with Vite already running
MCP_URL=http://127.0.0.1:5173/__mcp bunx vite-plugin-agent-mcp-proxy

The proxy uses the official MCP stdio and Streamable HTTP transports. It preserves modern 2026-07-28 negotiation and the legacy initialization fallback; stdout contains only MCP messages.

Experimental MCP Tasks

Tasks require both allowBuild: true and experimentalTasks: true, plus a modern client that declares io.modelcontextprotocol/tasks. The extension supports tasks/get, tasks/update, and tasks/cancel; it intentionally does not expose tasks/list. Clients without Tasks continue to receive synchronous one-shot build results.

Templates

Agent-ready starters live in the monorepo under templates/* (React, Vue, Svelte, Solid, library mode, MPA, …). Each includes AGENTS.md and a direct verification command.

Requirements

• Node.js 22.12.0 or newer
• Vite 8.x

License

MIT