@foldkit/vite-plugin 0.2.3 → 0.3.0

package/README.md

@@ -44,6 +44,18 @@ The plugin uses Vite's WebSocket connection to communicate between the dev serve
 
 Model is preserved across hot reloads but cleared on manual browser refreshes, giving you control over when to reset your app.
 
+## DevTools MCP relay
+
+Pass `devToolsMcpPort` to enable the relay that exposes your running Foldkit app to AI agents via the [`@foldkit/devtools-mcp`](https://www.npmjs.com/package/@foldkit/devtools-mcp) MCP server:
+
+```typescript
+plugins: [foldkit({ devToolsMcpPort: 9988 })]
+```
+
+When set, the plugin opens a separate WebSocket server on the given port. The MCP server connects to it and forwards typed `Request` and `Response` frames between AI agents and your runtime. Without `devToolsMcpPort` (the default), the relay is not started and the plugin behaves exactly as before.
+
+See the [DevTools MCP documentation](https://foldkit.dev/ai/mcp) for setup, the available tools, and how dispatch validation works.
+
 ## License
 
 MIT

package/dist/index.d.ts

@@ -1,3 +1,13 @@
 import type { Plugin } from 'vite';
-export declare const foldkit: () => Plugin;
+/** Options for the `foldkit` Vite plugin. */
+export type FoldkitPluginOptions = Readonly<{
+    /**
+     * Port for the WebSocket server that exposes the DevTools relay to an
+     * external MCP server. When `undefined` (the default), no MCP relay is
+     * started. When set, the plugin listens on this port for connections from
+     * the Foldkit DevTools MCP server.
+     */
+    devToolsMcpPort?: number;
+}>;
+export declare const foldkit: (options?: FoldkitPluginOptions) => Plugin;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAiB,MAAM,MAAM,CAAA;AAKjD,eAAO,MAAM,OAAO,QAAO,MAO1B,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,MAAM,EAAkC,MAAM,MAAM,CAAA;AAGlE,6CAA6C;AAC7C,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAC1C;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB,CAAC,CAAA;AAqBF,eAAO,MAAM,OAAO,GAAI,UAAS,oBAAyB,KAAG,MAO5D,CAAA"}

package/dist/index.js

@@ -1,14 +1,24 @@
+import { Array, Effect, Either, HashMap, HashSet, Match, Option, Ref, Schema as S, pipe, } from 'effect';
+import { EventFrame, RequestFrame, ResponseFrame, ResponseRuntimes, } from 'foldkit/devtools-protocol';
+import { WebSocketServer } from 'ws';
 let preservedModel = undefined;
 let isHmrReload = false;
-export const foldkit = () => {
+const connectedRuntimesRef = Ref.unsafeMake(HashMap.empty());
+const mcpClientsRef = Ref.unsafeMake(HashSet.empty());
+const clientConnectionsRef = Ref.unsafeMake(HashMap.empty());
+const trackedClientsRef = Ref.unsafeMake(HashSet.empty());
+let viteServer = null;
+let mcpWebSocketServer = null;
+export const foldkit = (options = {}) => {
     return {
         name: 'foldkit-hmr',
         apply: 'serve',
-        configureServer,
+        configureServer: server => configureServer(server, options),
         handleHotUpdate,
     };
 };
-const configureServer = (server) => {
+const configureServer = (server, options) => {
+    viteServer = server;
     server.ws.on('foldkit:preserve-model', model => {
         preservedModel = model;
     });
@@ -19,6 +29,140 @@ const configureServer = (server) => {
         }
         isHmrReload = false;
     });
+    server.ws.on('foldkit:devTools:event', (data, client) => {
+        ensureClientTracked(client);
+        handleBrowserEventFrame(data, client);
+    });
+    server.ws.on('foldkit:devTools:response', (data) => {
+        handleBrowserResponseFrame(data);
+    });
+    if (options.devToolsMcpPort !== undefined) {
+        startMcpWebSocketServer(options.devToolsMcpPort);
+        server.httpServer?.on('close', stopMcpWebSocketServer);
+    }
+};
+const startMcpWebSocketServer = (port) => {
+    const wss = new WebSocketServer({ port });
+    mcpWebSocketServer = wss;
+    wss.on('error', error => {
+        console.error(`[foldkit:devTools] MCP relay failed to start on port ${port}; continuing without the relay`, error);
+        mcpWebSocketServer = null;
+    });
+    wss.on('connection', client => {
+        Effect.runSync(Ref.update(mcpClientsRef, HashSet.add(client)));
+        const total = HashSet.size(Effect.runSync(Ref.get(mcpClientsRef)));
+        console.log(`[foldkit:devTools] MCP client connected (${total} total)`);
+        client.on('message', raw => {
+            handleMcpMessage(client, raw.toString());
+        });
+        client.on('close', () => {
+            Effect.runSync(Ref.update(mcpClientsRef, HashSet.remove(client)));
+            const remaining = HashSet.size(Effect.runSync(Ref.get(mcpClientsRef)));
+            console.log(`[foldkit:devTools] MCP client disconnected (${remaining} remaining)`);
+        });
+        client.on('error', error => {
+            console.error('[foldkit:devTools] MCP client error', error);
+        });
+    });
+    console.log(`[foldkit:devTools] MCP relay listening on ws://localhost:${port}`);
+};
+const stopMcpWebSocketServer = () => {
+    const clients = Effect.runSync(Ref.get(mcpClientsRef));
+    HashSet.forEach(clients, client => {
+        client.close();
+    });
+    Effect.runSync(Ref.set(mcpClientsRef, HashSet.empty()));
+    mcpWebSocketServer?.close();
+    mcpWebSocketServer = null;
+    console.log('[foldkit:devTools] MCP relay stopped');
+};
+const handleBrowserEventFrame = (data, client) => {
+    const decoded = S.decodeUnknownEither(EventFrame)(data);
+    Either.match(decoded, {
+        onLeft: error => {
+            console.warn('[foldkit:devTools] failed to decode browser event frame', error);
+        },
+        onRight: frame => Match.value(frame.event).pipe(Match.tagsExhaustive({
+            EventConnected: event => handleConnectedEvent(event, client),
+            EventDisconnected: handleDisconnectedEvent,
+        })),
+    });
+};
+const ensureClientTracked = (client) => {
+    const tracked = Effect.runSync(Ref.get(trackedClientsRef));
+    if (HashSet.has(tracked, client)) {
+        return;
+    }
+    Effect.runSync(Ref.update(trackedClientsRef, HashSet.add(client)));
+    client.socket.on('close', () => handleClientClose(client));
+};
+const handleClientClose = (client) => {
+    pipe(Effect.runSync(Ref.get(clientConnectionsRef)), HashMap.get(client), Option.match({
+        onNone: () => { },
+        onSome: connectionIds => HashSet.forEach(connectionIds, connectionId => {
+            Effect.runSync(Ref.update(connectedRuntimesRef, HashMap.remove(connectionId)));
+            console.log(`[foldkit:devTools] runtime pruned (socket close): ${connectionId}`);
+        }),
+    }));
+    Effect.runSync(Ref.update(clientConnectionsRef, HashMap.remove(client)));
+    Effect.runSync(Ref.update(trackedClientsRef, HashSet.remove(client)));
+};
+const handleBrowserResponseFrame = (data) => {
+    const decoded = S.decodeUnknownEither(ResponseFrame)(data);
+    Either.match(decoded, {
+        onLeft: error => {
+            console.warn('[foldkit:devTools] failed to decode browser response frame', error);
+        },
+        onRight: forwardResponseToMcpClients,
+    });
+};
+const handleConnectedEvent = (event, client) => {
+    Effect.runSync(Ref.update(connectedRuntimesRef, HashMap.set(event.runtime.connectionId, event.runtime)));
+    Effect.runSync(Ref.update(clientConnectionsRef, currentMap => {
+        const existing = pipe(HashMap.get(currentMap, client), Option.getOrElse(() => HashSet.empty()));
+        return HashMap.set(currentMap, client, HashSet.add(existing, event.runtime.connectionId));
+    }));
+    console.log(`[foldkit:devTools] runtime connected: ${event.runtime.connectionId} (${event.runtime.title})`);
+};
+const handleDisconnectedEvent = (event) => {
+    Effect.runSync(Ref.update(connectedRuntimesRef, HashMap.remove(event.connectionId)));
+    console.log(`[foldkit:devTools] runtime disconnected: ${event.connectionId}`);
+};
+const broadcastToMcpClients = (payload) => {
+    const clients = Effect.runSync(Ref.get(mcpClientsRef));
+    HashSet.forEach(clients, client => {
+        if (client.readyState === client.OPEN) {
+            client.send(payload);
+        }
+    });
+};
+const forwardResponseToMcpClients = (responseFrame) => {
+    broadcastToMcpClients(JSON.stringify(responseFrame));
+};
+const handleMcpMessage = (client, raw) => {
+    const decoded = S.decodeUnknownEither(S.parseJson(RequestFrame))(raw);
+    Either.match(decoded, {
+        onLeft: error => {
+            console.warn('[foldkit:devTools] failed to decode MCP request frame', error);
+        },
+        onRight: frame => Match.value(frame.request).pipe(Match.tag('RequestListRuntimes', () => replyListRuntimes(client, frame.id)), Match.orElse(() => forwardRequestToBrowsers(frame))),
+    });
+};
+const replyListRuntimes = (client, requestId) => {
+    const runtimes = pipe(Effect.runSync(Ref.get(connectedRuntimesRef)), HashMap.values, Array.fromIterable);
+    const responseFrame = {
+        id: requestId,
+        response: ResponseRuntimes({ runtimes }),
+    };
+    if (client.readyState === client.OPEN) {
+        client.send(JSON.stringify(responseFrame));
+    }
+};
+const forwardRequestToBrowsers = (frame) => {
+    if (viteServer === null) {
+        return;
+    }
+    viteServer.ws.send('foldkit:devTools:request', frame);
 };
 const handleHotUpdate = ({ server, modules, }) => {
     if (modules.length === 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldkit/vite-plugin",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Vite plugin for Foldkit hot module reloading with state preservation",
   "type": "module",
   "main": "./dist/index.js",
@@ -16,11 +16,19 @@
     "dist"
   ],
   "peerDependencies": {
+    "effect": "^3.18.2",
+    "foldkit": "^0.76.0",
     "vite": "^7.0.0"
   },
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
   "devDependencies": {
-    "typescript": "^5.9.3",
-    "vite": "^7.3.1"
+    "@types/ws": "^8.5.13",
+    "effect": "^3.19.19",
+    "typescript": "^6.0.2",
+    "vite": "^7.3.1",
+    "foldkit": "0.76.0"
   },
   "keywords": [
     "vite",