RFC: expose Qwik DevTools to AI agents (MCP)

[Aejkatappaja]

Summary

Add an optional, dev-only machine interface (an MCP server, or a headless JSON/CLI) over the DevTools data and command layer, so AI coding agents can inspect a running Qwik app and drive navigation during a dev loop. It reuses what the DevTools UI already consumes; no new inspection logic.

Motivation

Agent-driven dev loops are increasingly common, and Qwik's resumability and serialization are hard to reason about from source alone. The data an agent would need (component/VNode tree, routes, packages, render performance) is already collected for the DevTools UI. Today it is only reachable by a human clicking the overlay. Exposing it programmatically lets an agent observe real behavior instead of guessing.

Proposal

DevTools already has:

• a client/server RPC data source (readVNodeTree, readComponentDetail, routes, packages, readPerfData, getComponents), and
• since the command palette, a structured command registry where each entry is plain, serializable data (a target plus an activation).

Expose both through a thin machine interface, phased:

• Phase 1, read-only queries: components, VNode tree, routes, packages, performance.
• Phase 2, commands: navigate to a tab, reveal a component, clear performance, mapped from the command registry.
• Phase 3, attach: connect to a running dev server.

Use cases

1. Verification loop: after a change, read the component tree, signal state, and performance to confirm behavior rather than inferring from source.
2. Resumability and serialization debugging: inspect serialized state and what QRLs capture to diagnose serialization errors.
3. Performance: read render events, locate slow components, verify a fix by re-measuring.
4. Route coverage: enumerate routes and check each renders and resumes.
5. Test scaffolding from the live tree and the selected component.

Non-goals

• Not a replacement for the DevTools UI.
• Not shipped in production bundles.
• Opt-in, dev-only.

Open questions

• Transport: MCP stdio vs a local WebSocket/JSON endpoint.
• How to attach: the Vite dev server vs the running page.
• Which subset of the RPC is safe to expose, and isolation/auth for it.
• Should the command registry be the single source of truth for both the palette and the agent surface.

Prior art in-repo

The command palette (QwikDev/qwik#8835) models DevTools commands as serializable data, which is a natural surface to expose.

[Aejkatappaja]

Update: most of what this RFC asked for exists now, just not in the shape I proposed.

@Varixo's #9079 (QwikDev/qwik#9079) shipped @qwik.dev/mcp, a read-only MCP server with a qwikMcp() Vite plugin and a stdio CLI. It covers phase 1 and the "attach" part of phase 3: routes, dev errors, the component and VNode trees, hooks, signal values and parsed serialized state, plus offline docs. It reuses the DevTools instrumentation, so it already is the machine interface over DevTools data this proposal was after. The transport and isolation questions are settled there too (stdio, loopback with a session token, browser origins rejected).

Phase 2 I'm dropping. The palette commands only move the DevTools UI around, an agent has no use for them.

Before building on top of it I fixed a few things in DevTools that an agent-facing surface would have made worse:

• fix(devtools): guard mutating RPCs to local clients qwik#9123: the loopback guard on build analysis never worked (the RPC caller context was lost across birpc's async dispatch), and package install/update had no guard at all, so any device on the network could change your dependencies with vite --host.
• fix(ts-optimizer): keep lowercase JSX tags intrinsic when a prop shares their name qwik#9124: a TS optimizer bug that crashed DevTools SSR on main.
• fix(devtools): fail installs when the pnpm filter matches no project qwik#9125: installs reported success when pnpm's --filter matched nothing.

What's left, which I talked through with @maiieul, is extending @qwik.dev/mcp rather than writing a second server:

• expose what DevTools collects and the MCP doesn't yet: render performance, preloads/QRL loading, build analysis
• element to source with the exact location. QRLDev already carries lo/hi and nothing uses them, so an agent could go from a selector to file:line:col instead of a file name
• resumability diagnostics, the part only Qwik can offer: which QRLs woke up for a given interaction and why, serialized state size per component, prefetch graph per route
• maybe later, qwikDevtools() turning the MCP on so people don't need two plugins

I'll start with the element to source piece. If that direction works for you @Varixo, I'm happy to close this and open smaller discussions per piece when they need one.