@foldkit/devtools-mcp 0.16.0 → 0.16.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/README.md +16 -16
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -6,13 +6,13 @@ With it attached, agents can:
|
|
|
6
6
|
|
|
7
7
|
- Read the current Model, or any historical Model by history index
|
|
8
8
|
- Narrow reads with dot-string paths and summarized payloads to fit token budgets
|
|
9
|
-
- List and inspect the Message history, with Command and Mount lifecycle, diffs, and
|
|
9
|
+
- List and inspect the Message history, with Command and Mount lifecycle, diffs, and Submodel chains
|
|
10
10
|
- Query history server-side: filter entries by changed Model paths, count Messages by tag, tail the latest entries, and diff the Models at two indices
|
|
11
11
|
- Read the recorded init Model, the Commands returned from `init`, and the Mounts that fired during the first render
|
|
12
|
-
- Inspect
|
|
12
|
+
- Inspect Runtime state: current index, retained history bounds, pause status
|
|
13
13
|
- Replay to any past state and resume
|
|
14
|
-
- Discover the
|
|
15
|
-
- Dispatch Messages into the
|
|
14
|
+
- Discover the Runtime's `Message` Schema as JSON Schema so agents can construct valid payloads without reading the application source
|
|
15
|
+
- Dispatch Messages into the Runtime, singly or as an ordered batch, decoded against your `Message` Schema
|
|
16
16
|
|
|
17
17
|
## Quick Start
|
|
18
18
|
|
|
@@ -50,7 +50,7 @@ export default defineConfig({
|
|
|
50
50
|
})
|
|
51
51
|
```
|
|
52
52
|
|
|
53
|
-
In your `Runtime.makeApplication` call, pass your `Message` Schema. The
|
|
53
|
+
In your `Runtime.makeApplication` call, pass your `Message` Schema. The Runtime decodes every dispatched payload against it, returning a clean error if the shape does not match before it reaches your update function:
|
|
54
54
|
|
|
55
55
|
```typescript
|
|
56
56
|
Runtime.makeApplication({
|
|
@@ -63,29 +63,29 @@ Runtime.makeApplication({
|
|
|
63
63
|
|
|
64
64
|
Restart your dev server, then restart your AI agent. The MCP server will appear with the `foldkit_*` tools attached.
|
|
65
65
|
|
|
66
|
-
The browser bridge runs inside your app, so the MCP server only sees a
|
|
66
|
+
The browser bridge runs inside your app, so the MCP server only sees a Runtime while the app is open in a browser tab. Close the tab and the Runtime disappears from `foldkit_list_runtimes`.
|
|
67
67
|
|
|
68
68
|
## Tools
|
|
69
69
|
|
|
70
|
-
Each tool accepts an optional `runtime_id`. When omitted, the most recently connected
|
|
70
|
+
Each tool accepts an optional `runtime_id`. When omitted, the most recently connected Runtime is used.
|
|
71
71
|
|
|
72
72
|
| Tool | Description |
|
|
73
73
|
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
74
|
-
| `foldkit_list_runtimes` | Returns metadata for every connected browser tab. Agents call this first to discover which
|
|
74
|
+
| `foldkit_list_runtimes` | Returns metadata for every connected browser tab. Agents call this first to discover which Runtime to target. |
|
|
75
75
|
| `foldkit_get_model` | Snapshots the current Model. Accepts an optional `path` to narrow to a subtree and `expand` to control summarization. |
|
|
76
|
-
| `foldkit_get_model_at` | Snapshots a historical Model after a given history entry. Pass `index: N - 1` to read the Model just before
|
|
76
|
+
| `foldkit_get_model_at` | Snapshots a historical Model after a given history entry. Pass `index: N - 1` to read the Model just before Message `N`. Same `path`/`expand` semantics as `foldkit_get_model`. Indices outside the readable range (older entries are evicted past the rolling buffer) are rejected with the valid bounds. For the initial Model (and the init Commands and Mounts), use `foldkit_get_init`. |
|
|
77
77
|
| `foldkit_get_init` | Reads the recorded initial Model, the Commands returned from the application's `init` function, and the Mounts that fired during the first render. Each Command and Mount carries its declared args. Equivalent to selecting the synthetic "init" row in the DevTools panel. |
|
|
78
|
-
| `foldkit_get_runtime_state` | Snapshots the
|
|
78
|
+
| `foldkit_get_runtime_state` | Snapshots the Runtime's DevTools state: history bounds, current paused/live status, and whether init is recorded. Useful for understanding what `foldkit_list_messages` and `foldkit_get_message` will see and detecting whether the Runtime is paused. |
|
|
79
79
|
| `foldkit_list_messages` | Lists Message history entries. Each entry carries the Message body, Commands triggered (with args), Mounts that started or ended during the resulting render (with args), timestamp, an `isModelChanged` flag, the diff path lists (`changedPaths` / `affectedPaths`), and any extracted Submodel chain. Filter server-side with `changed_paths_match`, read the latest entries with `from_end`, and paginate forward with `since_index`. |
|
|
80
80
|
| `foldkit_count_messages_by_tag` | Counts retained history entries by Message tag, without payloads, sorted by count descending. A cheap reconnaissance call before paging through history: it surfaces the high-frequency Messages worth filtering out, and with `changed_paths_match` it answers which Message tags touch a Model subtree. |
|
|
81
81
|
| `foldkit_diff_models` | Diffs the Models at two history indices server-side, returning path-level changes `{ path, before, after }` with summarized values. Each side is `{ _tag: 'Present', value }`, or `{ _tag: 'Absent' }` when the path does not exist on that side. Pass `changed_paths_match` to narrow the diff to a subtree. |
|
|
82
82
|
| `foldkit_get_message` | Reads one entry at a given index. The response carries the SerializedEntry only; to inspect the Model around the entry, call `foldkit_get_model_at` with `index - 1` (before) and `index` (after). Use `foldkit_get_init` for the synthetic init entry. |
|
|
83
83
|
| `foldkit_list_keyframes` | Returns the indices Foldkit can replay back to. Index `-1` is the initial Model. |
|
|
84
|
-
| `foldkit_replay_to_keyframe` | Time-travels the
|
|
84
|
+
| `foldkit_replay_to_keyframe` | Time-travels the Runtime to a previous state. The Runtime is paused at that snapshot until `foldkit_resume` is called. |
|
|
85
85
|
| `foldkit_resume` | Resumes normal execution after a replay. |
|
|
86
|
-
| `foldkit_get_message_schema` | Describes the
|
|
87
|
-
| `foldkit_dispatch_message` | Dispatches a Message into the
|
|
88
|
-
| `foldkit_dispatch_messages` | Dispatches an ordered batch of 1 to 100 Messages in one call, first to last. The
|
|
86
|
+
| `foldkit_get_message_schema` | Describes the Runtime's Message Schema so agents can construct valid Messages without reading the application source. With no arguments, returns a small variant index (top-level tag names plus payload fields). With `variant_tag` set to a dot-separated path of variant tags (e.g. `"GotChildMessage.Opened"`), narrows the JSON Schema along the chain and collapses deeper unions to summary placeholders. Returns `maybeResult: None` when the Runtime hasn't configured `DevToolsConfig.Message`. |
|
|
87
|
+
| `foldkit_dispatch_message` | Dispatches a Message into the Runtime as if your application produced it. The Runtime decodes the payload against your Schema and returns a clean error if it does not match. |
|
|
88
|
+
| `foldkit_dispatch_messages` | Dispatches an ordered batch of 1 to 100 Messages in one call, first to last. The Runtime validates every payload before dispatching any of them, so one invalid entry rejects the whole batch with its zero-based position and nothing is dispatched. The response reports the predicted history index for each Message. |
|
|
89
89
|
|
|
90
90
|
### Reading the Model efficiently
|
|
91
91
|
|
|
@@ -111,7 +111,7 @@ Three components cooperate:
|
|
|
111
111
|
- **Vite plugin relay** (in `@foldkit/vite-plugin`): opens a separate WebSocket server on `devToolsMcpPort` and forwards traffic between browsers and MCP clients.
|
|
112
112
|
- **MCP server** (this package): runs as a Node child process under your AI agent, connects to the plugin's relay over WebSocket, and exposes the typed tools over MCP's stdio transport.
|
|
113
113
|
|
|
114
|
-
Multiple browser tabs can be connected at once and each is addressable by its connection id. Tabs that close (gracefully or not) are pruned from the live
|
|
114
|
+
Multiple browser tabs can be connected at once and each is addressable by its connection id. Tabs that close (gracefully or not) are pruned from the live Runtime list automatically.
|
|
115
115
|
|
|
116
116
|
## Configuration
|
|
117
117
|
|
|
@@ -122,7 +122,7 @@ Multiple browser tabs can be connected at once and each is addressable by its co
|
|
|
122
122
|
|
|
123
123
|
## Notes
|
|
124
124
|
|
|
125
|
-
- The MCP bridge shares its lifecycle with Foldkit DevTools. If you set `devTools: false` in your program config, the bridge does not start and the
|
|
125
|
+
- The MCP bridge shares its lifecycle with Foldkit DevTools. If you set `devTools: false` in your program config, the bridge does not start and the Runtime is invisible to MCP. The default enables the bridge in dev.
|
|
126
126
|
- Without `Message` in your `DevToolsConfig`, dispatch is rejected. The other (read-only) tools still work.
|
|
127
127
|
- The relay only runs at dev time. Production builds never include the relay or the bridge, regardless of any `show` setting.
|
|
128
128
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@foldkit/devtools-mcp",
|
|
3
|
-
"version": "0.16.
|
|
3
|
+
"version": "0.16.1",
|
|
4
4
|
"description": "MCP server exposing Foldkit DevTools to AI agents (Claude Code, Cursor, etc.)",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/server.js",
|
|
@@ -30,7 +30,7 @@
|
|
|
30
30
|
"esbuild": "^0.28.1",
|
|
31
31
|
"rimraf": "^6.1.3",
|
|
32
32
|
"typescript": "^6.0.3",
|
|
33
|
-
"foldkit": "0.
|
|
33
|
+
"foldkit": "0.148.2"
|
|
34
34
|
},
|
|
35
35
|
"files": [
|
|
36
36
|
"dist"
|