@vue/devtools-agent 0.0.0-stage → 9.0.0-rc.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2023 webfansplz
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,181 @@
1
- # Temporary Holding Version
1
+ # @vue/devtools-agent
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Let AI agents inspect a running Vue application through MCP: find components, read state, edit individual fields, inspect Pinia stores, and check routes.
4
+
5
+ The Vite integration connects agents to the same runtime used by Vue DevTools. Open your app in a browser; the Vue DevTools panel can stay closed. Inspection tools are read-only. Hosts with a Kit command connection also expose explicit actions for editing component and Inspector fields.
6
+
7
+ ## Get started
8
+
9
+ ### 1. Enable Vue DevTools in your app
10
+
11
+ Use `vite-plugin-vue-devtools` alongside `@vitejs/devtools` and Vite 8.3 or later. Add the following to your existing Vite configuration:
12
+
13
+ ```ts
14
+ import { defineConfig } from 'vite'
15
+ import vueDevTools from 'vite-plugin-vue-devtools'
16
+
17
+ export default defineConfig({
18
+ devtools: { apply: 'serve' },
19
+ plugins: [vueDevTools()],
20
+ })
21
+ ```
22
+
23
+ Start the dev server, open the app in your browser, and allow the Vite DevTools connection when prompted. Vue's agent tools register automatically when the host exposes MCP. Setting `devtools.mcp` to `false` disables MCP access.
24
+
25
+ ### 2. Connect your agent
26
+
27
+ Add this entry to your agent client's MCP configuration. Use its global configuration to make the connector available across projects; the configuration file location depends on the client.
28
+
29
+ ```json
30
+ {
31
+ "mcpServers": {
32
+ "vue-devtools": {
33
+ "command": "npx",
34
+ "args": ["-y", "@vue/devtools-agent", "connect"]
35
+ }
36
+ }
37
+ }
38
+ ```
39
+
40
+ The CLI uses Devframe's connector to discover running projects automatically. You do not need to configure a fixed port for each project.
41
+
42
+ ### 3. Inspect the running app
43
+
44
+ An agent follows this sequence:
45
+
46
+ 1. Call `devframe_connect_list-instances` and select the project by its `rootDir`.
47
+ 2. Find the page's Vue tools in that instance's tool list. Call `list-apps` to check the page URL and get an app ID.
48
+ 3. Call `component-tree` to get component IDs, then `component-state` to inspect a component. Use `expand-value` when you need more detail about an object or array.
49
+
50
+ Invoke page tools through `devframe_connect_call-tool`, using the port and exact tool name returned by discovery. Tools that take an options object expose it as `arg0`. For example:
51
+
52
+ ```json
53
+ {
54
+ "port": 5173,
55
+ "tool": "<component-state tool name from discovery>",
56
+ "args": {
57
+ "arg0": {
58
+ "appId": "<app ID from list-apps>",
59
+ "componentId": "<component ID from component-tree>"
60
+ }
61
+ }
62
+ }
63
+ ```
64
+
65
+ Each browser document has its own `vue-devtools:agent:<document-id>` namespace. If several pages are open, use `list-apps` to identify the one you want. After a reload, discover its tools again before making further calls.
66
+
67
+ ## Available tools
68
+
69
+ | Task | Tools |
70
+ | --------------------------------------- | ----------------------------------------------------------------------------- |
71
+ | Identify the app and check the runtime | `list-apps`, `list-plugins`, `runtime-health` |
72
+ | Explore components | `component-tree`, `component-children`, `cancel-component-children` |
73
+ | Inspect component state and render code | `component-state`, `component-value`, `expand-value`, `component-render-code` |
74
+ | Read Pinia stores and other plugin data | `list-inspectors`, `inspector-tree`, `inspector-state`, `inspector-value` |
75
+ | Inspect routing without navigating | `router-state`, `router-matches` |
76
+ | Edit an existing field | `edit-component-state`, `edit-inspector-state` |
77
+
78
+ App-specific tools require an explicit `appId`. Every tool declares an output schema. Successful calls return `{ page, capturedAt, result }`; rejected calls use the MCP tool error channel. Field reads return `found: false` for a missing target or path. A present null or undefined value instead has `found: true` and a tagged codec value. The page URL follows browser navigation; use `router-state` for Vue Router's current route and registered routes.
79
+
80
+ The component tree loads incrementally. Without a filter, `component-tree` returns the initially expanded nodes. With a filter, it searches the whole app by component name or source file and returns up to 100 matches. Use `component-children` to read more nodes, pass its cursor to continue, and cancel unfinished reads with `cancel-component-children`.
81
+
82
+ ## Read all state with pagination
83
+
84
+ `component-state` and `inspector-state` return the first page of fields, grouped by section. To read everything, follow `pagination.next` until it is `null`:
85
+
86
+ ```json
87
+ {
88
+ "snapshotId": "state-page:1",
89
+ "pagination": {
90
+ "total": 126,
91
+ "current": 1,
92
+ "next": 2
93
+ },
94
+ "sections": []
95
+ }
96
+ ```
97
+
98
+ This example shows the pagination metadata; actual responses include the page's entries in `sections`. `total` counts fields across all sections, not pages. `current` and `next` are page numbers starting at 1.
99
+
100
+ For the next call, keep the original query parameters, pass back `snapshotId`, and set `page` to the returned `next`. For example, the next `component-state` call uses:
101
+
102
+ ```json
103
+ {
104
+ "appId": "<app ID>",
105
+ "componentId": "<component ID>",
106
+ "page": 2,
107
+ "snapshotId": "state-page:1"
108
+ }
109
+ ```
110
+
111
+ Pages can contain different numbers of entries. Always follow `next` to determine whether more data is available. A section's `partial` flag means this page contains only part of that section; it does not mean the remaining fields are inaccessible.
112
+
113
+ The same pagination parameters work with `expand-value`. For `component-value` and `inspector-value`, omit them for a compact preview, or pass `page: 1` to start paging through the selected value. Collections return a page of preview entries. Strings return text segments: `total` counts UTF-16 code units, and concatenating the segments reconstructs the full string.
114
+
115
+ A batch keeps the original field order, but it is not an atomic snapshot of the application. Object properties can change as they are read. For `inspector-state`, the plugin hook runs when the batch starts. Component reactivity graphs, when available, appear on the first state page. Read pages in order; retrying the most recent page returns the same result. To start over, omit `snapshotId` and request page 1. Batches are retained temporarily; an expired ID returns instructions to restart.
116
+
117
+ ### Value handles
118
+
119
+ A **value handle** is a temporary reference to an object or array. Pass it to `expand-value`, optionally with a property path, to read details omitted from a preview. A missing path produces an error; an existing `undefined` value is returned with its codec tag.
120
+
121
+ Handles can expire when the same component or Inspector node is read again, including by the DevTools panel, or when the runtime releases retained values. Keeping the connection open does not keep handles valid. To recover, start a fresh state query and use its new handles, or read a known field path directly. After a page reload, rediscover the page tools as well.
122
+
123
+ ## Read or edit a specific field
124
+
125
+ For a known component field, call `component-value` with its `appId`, `componentId`, `sectionId`, and `path`. Built-in sections include `props`, `data`, and `setup`. Array indexes are strings. This reads the live value without requiring a previous handle:
126
+
127
+ ```json
128
+ {
129
+ "appId": "app:0",
130
+ "componentId": "app:0:12",
131
+ "sectionId": "setup",
132
+ "path": ["user", "name"]
133
+ }
134
+ ```
135
+
136
+ For plugin state such as Pinia, discover the Inspector and node first, then use `inspector-value` with `inspectorId`, `nodeId`, `sectionId`, and `path`. The path starts with the Inspector entry key. Kit still invokes the plugin's state hook, but encodes only the requested value. Both field tools return compact previews for objects and arrays.
137
+
138
+ To change a field:
139
+
140
+ 1. Read it with `component-value` or `inspector-value`. Check `found` and `editable`.
141
+ 2. Call `edit-component-state` or `edit-inspector-state` with the same target and a JSON `value`.
142
+ 3. Inspect the returned `result.state`, which contains the value read after the command. `status: 1` acknowledges the command; a plugin may normalize the value or leave it unchanged.
143
+
144
+ Editing uses the same Kit commands and plugin hooks as the panel. These tools change existing fields; they do not delete or rename fields, navigate, or invoke arbitrary plugin actions. Props may be overwritten by a parent render. Component field tools target built-in state sections; custom plugin state is accessed through its Inspector.
145
+
146
+ | Situation | Next step |
147
+ | -------------------------------- | --------------------------------------------------------------------- |
148
+ | `found: false` | Check the target IDs and field path; rediscover tools after a reload |
149
+ | Read-only field | Choose a field marked `editable: true` |
150
+ | Expired handle | Read the original state again, or use a field path directly |
151
+ | Response exceeds the byte budget | Read a narrower field path if a single entry is too large |
152
+ | Edit transport or readback error | Read the current state before retrying; the edit may already have run |
153
+
154
+ ## Connection and access
155
+
156
+ Vite DevTools manages the MCP endpoint, discovery, and authentication. The connector sends a bearer token only when `DEVFRAME_MCP_AUTH_TOKEN` is set. Vite DevTools accepts local callers by default; set that variable if your host configuration requires a token.
157
+
158
+ If automatic discovery cannot find your project, probe its port explicitly:
159
+
160
+ ```sh
161
+ npx @vue/devtools-agent connect --port 5173 --base /__devtools/
162
+ ```
163
+
164
+ To probe several ports, repeat `--port` or pass a comma-separated list, such as `--port 5173,5174`. The base path points the probe to Vite DevTools' connection metadata. See [Devframe MCP](https://devfra.me/adapters/mcp) for endpoint and authentication configuration.
165
+
166
+ Discovery alone does not open a Vue runtime connection. The Vite adapter connects on the first query and keeps that connection until the page's tool registration is disposed. Keeping it open does not guarantee that individual value handles remain valid.
167
+
168
+ Connected agents can read application state, including private data stored in it. Reads use the same getters and plugin hooks as the Vue DevTools UI, so inspecting a value may execute application code. The Vite integration runs during development.
169
+
170
+ ## Integrate another host
171
+
172
+ The tool definitions are independent of Vite. To expose them in another host, supply a Kit connection and a unique ID for each browser document.
173
+
174
+ | Export | Entry point | Purpose |
175
+ | ------------------------------------------------ | ------------------------------ | ----------------------------------------------------------------------------------- |
176
+ | `createVueDevtoolsAgentTools(connection, page)` | `@vue/devtools-agent` | Create tool definitions for a page |
177
+ | `createVueDevtoolsAgentSession(connect)` | `@vue/devtools-agent` | Open a connection lazily and manage its lifetime |
178
+ | `registerVueDevtoolsAgentPage(connection, page)` | `@vue/devtools-agent/devframe` | Register page tools with Devframe |
179
+ | `registerVueDevtoolsAgentHost(ctx)` | `@vue/devtools-agent/node` | Register a help tool so the host's MCP endpoint is available before a page connects |
180
+
181
+ The connection supplies Kit's typed `query` method; `command` enables editing actions and cursor cleanup. Hosts that supply only `query` do not register editing actions. Disposing a page registration removes its tools. The host remains responsible for disposing the connection.
package/dist/cli.d.mts ADDED
@@ -0,0 +1 @@
1
+ export {}
package/dist/cli.mjs ADDED
@@ -0,0 +1,37 @@
1
+ #!/usr/bin/env node
2
+ import process from "node:process";
3
+ import { cac } from "cac";
4
+ //#region src/cli.ts
5
+ async function main() {
6
+ const cli = cac("vue-devtools-agent");
7
+ cli.command("connect", "Discover running Devframe projects and expose their tools over stdio MCP").option("--port <port>", "Probe an additional port (repeatable or comma-separated)").option("--base <path>", "Base path for explicit port probes", { default: "/" }).option("--instances-dir <dir>", "Override the Devframe instance registry directory").option("--timeout <ms>", "Probe timeout per instance in milliseconds", { default: "1000" }).action(async (options) => {
8
+ const ports = [options.port ?? []].flat().flatMap((value) => String(value).split(",")).filter((value) => value.trim() !== "").map(Number);
9
+ if (ports.some((port) => !Number.isInteger(port) || port < 1 || port > 65535)) throw new Error("--port must be an integer between 1 and 65535");
10
+ const timeoutMs = Number(options.timeout);
11
+ if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) throw new Error("--timeout must be a positive number of milliseconds");
12
+ const { startConnectServer } = await import("@devframes/agentic/connect");
13
+ await startConnectServer({
14
+ ports,
15
+ base: options.base,
16
+ instancesDir: options.instancesDir,
17
+ timeoutMs,
18
+ authToken: process.env.DEVFRAME_MCP_AUTH_TOKEN
19
+ });
20
+ process.stdin.resume();
21
+ });
22
+ cli.help();
23
+ cli.parse(process.argv, { run: false });
24
+ if (!cli.matchedCommand) {
25
+ if (!cli.options.help) cli.outputHelp();
26
+ return;
27
+ }
28
+ await cli.runMatchedCommand();
29
+ }
30
+ main().catch((error) => {
31
+ console.error(error instanceof Error ? error.message : String(error));
32
+ process.exitCode = 1;
33
+ });
34
+ //#endregion
35
+ export {};
36
+
37
+ //# sourceMappingURL=cli.mjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cli.mjs","names":[],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\nimport process from 'node:process'\nimport { cac } from 'cac'\n\nasync function main() {\n const cli = cac('vue-devtools-agent')\n cli\n .command('connect', 'Discover running Devframe projects and expose their tools over stdio MCP')\n .option('--port <port>', 'Probe an additional port (repeatable or comma-separated)')\n .option('--base <path>', 'Base path for explicit port probes', { default: '/' })\n .option('--instances-dir <dir>', 'Override the Devframe instance registry directory')\n .option('--timeout <ms>', 'Probe timeout per instance in milliseconds', { default: '1000' })\n .action(async (options) => {\n const ports = [options.port ?? []]\n .flat()\n .flatMap((value: string | number) => String(value).split(','))\n .filter((value) => value.trim() !== '')\n .map(Number)\n if (ports.some((port) => !Number.isInteger(port) || port < 1 || port > 65535)) {\n throw new Error('--port must be an integer between 1 and 65535')\n }\n const timeoutMs = Number(options.timeout)\n if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {\n throw new Error('--timeout must be a positive number of milliseconds')\n }\n const { startConnectServer } = await import('@devframes/agentic/connect')\n await startConnectServer({\n ports,\n base: options.base,\n instancesDir: options.instancesDir,\n timeoutMs,\n authToken: process.env.DEVFRAME_MCP_AUTH_TOKEN,\n })\n process.stdin.resume()\n })\n cli.help()\n cli.parse(process.argv, { run: false })\n if (!cli.matchedCommand) {\n if (!cli.options.help) cli.outputHelp()\n return\n }\n await cli.runMatchedCommand()\n}\n\nvoid main().catch((error: unknown) => {\n console.error(error instanceof Error ? error.message : String(error))\n process.exitCode = 1\n})\n"],"mappings":";;;;AAIA,eAAe,OAAO;CACpB,MAAM,MAAM,IAAI,oBAAoB;CACpC,IACG,QAAQ,WAAW,0EAA0E,CAAC,CAC9F,OAAO,iBAAiB,0DAA0D,CAAC,CACnF,OAAO,iBAAiB,sCAAsC,EAAE,SAAS,IAAI,CAAC,CAAC,CAC/E,OAAO,yBAAyB,mDAAmD,CAAC,CACpF,OAAO,kBAAkB,8CAA8C,EAAE,SAAS,OAAO,CAAC,CAAC,CAC3F,OAAO,OAAO,YAAY;EACzB,MAAM,QAAQ,CAAC,QAAQ,QAAQ,CAAC,CAAC,CAAC,CAC/B,KAAK,CAAC,CACN,SAAS,UAA2B,OAAO,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAC7D,QAAQ,UAAU,MAAM,KAAK,MAAM,EAAE,CAAC,CACtC,IAAI,MAAM;EACb,IAAI,MAAM,MAAM,SAAS,CAAC,OAAO,UAAU,IAAI,KAAK,OAAO,KAAK,OAAO,KAAK,GAC1E,MAAM,IAAI,MAAM,+CAA+C;EAEjE,MAAM,YAAY,OAAO,QAAQ,OAAO;EACxC,IAAI,CAAC,OAAO,SAAS,SAAS,KAAK,aAAa,GAC9C,MAAM,IAAI,MAAM,qDAAqD;EAEvE,MAAM,EAAE,uBAAuB,MAAM,OAAO;EAC5C,MAAM,mBAAmB;GACvB;GACA,MAAM,QAAQ;GACd,cAAc,QAAQ;GACtB;GACA,WAAW,QAAQ,IAAI;EACzB,CAAC;EACD,QAAQ,MAAM,OAAO;CACvB,CAAC;CACH,IAAI,KAAK;CACT,IAAI,MAAM,QAAQ,MAAM,EAAE,KAAK,MAAM,CAAC;CACtC,IAAI,CAAC,IAAI,gBAAgB;EACvB,IAAI,CAAC,IAAI,QAAQ,MAAM,IAAI,WAAW;EACtC;CACF;CACA,MAAM,IAAI,kBAAkB;AAC9B;AAEK,KAAK,CAAC,CAAC,OAAO,UAAmB;CACpC,QAAQ,MAAM,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,CAAC;CACpE,QAAQ,WAAW;AACrB,CAAC"}
@@ -0,0 +1,7 @@
1
+ import { i as VueDevtoolsAgentPage, n as createVueDevtoolsAgentSession, r as VueDevtoolsAgentConnection, t as VueDevtoolsAgentSession } from "./session-1Buaf6lK.mjs";
2
+ //#region src/mcp/page.d.ts
3
+ /** Register inspection and optional editing tools in Devframe's browser registry, using a unique document namespace. */
4
+ export declare function registerVueDevtoolsAgentPage(connection: VueDevtoolsAgentConnection, page: VueDevtoolsAgentPage): () => void;
5
+ //#endregion
6
+ export { type VueDevtoolsAgentSession, createVueDevtoolsAgentSession };
7
+ //# sourceMappingURL=devframe.d.mts.map
@@ -0,0 +1,15 @@
1
+ import { n as createVueDevtoolsAgentTools, t as createVueDevtoolsAgentSession } from "./session-D7L9Vjbr.mjs";
2
+ import { createPageScriptChannel } from "devframe/in-page-channel";
3
+ //#region src/mcp/page.ts
4
+ /** Register inspection and optional editing tools in Devframe's browser registry, using a unique document namespace. */
5
+ function registerVueDevtoolsAgentPage(connection, page) {
6
+ const channel = createPageScriptChannel({
7
+ name: `vue-devtools:agent:${page.id}`,
8
+ functions: createVueDevtoolsAgentTools(connection, page)
9
+ });
10
+ return () => channel.close();
11
+ }
12
+ //#endregion
13
+ export { createVueDevtoolsAgentSession, registerVueDevtoolsAgentPage };
14
+
15
+ //# sourceMappingURL=devframe.mjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"devframe.mjs","names":[],"sources":["../src/mcp/page.ts"],"sourcesContent":["import { createPageScriptChannel } from 'devframe/in-page-channel'\nimport { createVueDevtoolsAgentTools } from './tools'\nimport type { VueDevtoolsAgentConnection, VueDevtoolsAgentPage } from '../types'\n\n/** Register inspection and optional editing tools in Devframe's browser registry, using a unique document namespace. */\nexport function registerVueDevtoolsAgentPage(\n connection: VueDevtoolsAgentConnection,\n page: VueDevtoolsAgentPage,\n): () => void {\n const channel = createPageScriptChannel({\n name: `vue-devtools:agent:${page.id}`,\n functions: createVueDevtoolsAgentTools(connection, page),\n })\n return () => channel.close()\n}\n"],"mappings":";;;;AAKA,SAAgB,6BACd,YACA,MACY;CACZ,MAAM,UAAU,wBAAwB;EACtC,MAAM,sBAAsB,KAAK;EACjC,WAAW,4BAA4B,YAAY,IAAI;CACzD,CAAC;CACD,aAAa,QAAQ,MAAM;AAC7B"}