@foldkit/devtools-mcp 0.22.0-canary.b415a3e22be5 → 0.22.0-canary.eb11872b6977

package/README.md

@@ -36,21 +36,7 @@ pnpm add -D @foldkit/devtools-mcp
 yarn add -D @foldkit/devtools-mcp
 ```
 
-Then make two edits to your project.
-
-In `vite.config.ts`, pass `devToolsMcpPort` to the Foldkit plugin so it opens the relay:
-
-```typescript
-import { defineConfig } from 'vite'
-
-import { foldkit } from '@foldkit/vite-plugin'
-
-export default defineConfig({
-  plugins: [foldkit({ devToolsMcpPort: 9988 })],
-})
-```
-
-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:
+Pass your `Message` Schema to `Runtime.makeApplication` to let the agent dispatch Messages. The Runtime rejects a payload that does not match the Schema before it reaches update:
 
 ```typescript
 Runtime.makeApplication({
@@ -108,17 +94,25 @@ High-frequency flows (drag-paint, scroll, keystroke) can fill the history buffer
 Three components cooperate:
 
 - **Browser bridge** (in `foldkit`): runs alongside DevTools, subscribes to the DevTools store, and exchanges typed frames over Vite's HMR WebSocket.
-- **Vite plugin relay** (in `@foldkit/vite-plugin`): opens a separate WebSocket server on `devToolsMcpPort` and forwards traffic between browsers and MCP clients.
+- **Vite plugin relay** (in `@foldkit/vite-plugin`): serves a WebSocket endpoint on the dev server, publishes its address for discovery, and forwards traffic between browsers and MCP clients.
 - **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.
 
 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.
 
 ## Configuration
 
-| Environment variable        | Default     | Description                                                                              |
-| --------------------------- | ----------- | ---------------------------------------------------------------------------------------- |
-| `FOLDKIT_DEVTOOLS_MCP_HOST` | `localhost` | Hostname of the Vite plugin relay.                                                       |
-| `FOLDKIT_DEVTOOLS_MCP_PORT` | `9988`      | Port the Vite plugin relay listens on. Must match `devToolsMcpPort` in your Vite config. |
+The MCP server looks for a running dev server in its project directory. If several relays match, it uses the most recently started one. It discovers the relay again when the dev server restarts.
+
+| Environment variable               | What it changes                                                                                                                                                             |
+| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `FOLDKIT_PROJECT_ROOT`             | Project to search. Defaults to the working directory. A relay for that directory or one inside it can match.                                                                |
+| `FOLDKIT_DEVTOOLS_MCP_PORT`        | Skips discovery and connects to this port. Set it to the `devToolsMcpPort` in your Vite config. Without this setting, the server tries `9988` if discovery finds nothing.   |
+| `FOLDKIT_DEVTOOLS_MCP_HOST`        | Overrides the hostname of a discovered relay or configured port.                                                                                                            |
+| `FOLDKIT_DEVTOOLS_RELAY_DIRECTORY` | Registry location. Defaults to a directory under `XDG_RUNTIME_DIR` when set, or under the OS temporary directory. Set it in both processes if they use different sandboxes. |
+
+A relay discovered through the registry requires the token in its published address. The plugin will not publish that token into a directory owned by another user or readable by other users. A configured `devToolsMcpPort` opens a separate socket on every interface without a token.
+
+On Windows, directory ownership cannot be verified, so automatic discovery is unavailable. Use `devToolsMcpPort` in the Vite config and set `FOLDKIT_DEVTOOLS_MCP_PORT` to the same port.
 
 ## Notes
 

package/dist/install.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../src/install.ts"],"names":[],"mappings":"AAsEA;;;;;GAKG;AACH,eAAO,MAAM,OAAO,QAAO,IAkB1B,CAAA"}
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../src/install.ts"],"names":[],"mappings":"AAoEA;;;;;GAKG;AACH,eAAO,MAAM,OAAO,QAAO,IAkB1B,CAAA"}

package/dist/install.js

@@ -36,15 +36,13 @@ const printNextSteps = (alreadyRegistered) => {
     console.log('');
     console.log('Next steps:');
     console.log('');
-    console.log('  1. Add devToolsMcpPort to your Vite plugin call in vite.config.ts:');
-    console.log('');
-    console.log('       plugins: [foldkit({ devToolsMcpPort: 9988 })]');
-    console.log('');
-    console.log('  2. Pass your Message Schema to Runtime.makeApplication (enables dispatch):');
+    console.log('  1. Pass your Message Schema to Runtime.makeApplication (enables dispatch):');
     console.log('');
     console.log('       devTools: { Message }');
     console.log('');
-    console.log('  3. Restart your dev server, then restart your AI agent (Claude Code, Cursor, etc.).');
+    console.log('  2. Start your dev server, then restart your AI agent (Claude Code, Cursor, etc.).');
+    console.log('');
+    console.log('     The server finds your dev server on its own. See https://foldkit.dev/ai/mcp');
     console.log('');
     console.log('Tools will appear under the foldkit-devtools server, e.g. foldkit_get_model, foldkit_dispatch_message.');
 };

package/dist/relayLocation.d.ts

@@ -0,0 +1,9 @@
+import { Effect, Option } from 'effect';
+export type Settings = Readonly<{
+    maybeConfiguredPort: Option.Option<string>;
+    maybeConfiguredHost: Option.Option<string>;
+    projectRoot: string;
+}>;
+export declare const loadSettings: Effect.Effect<Settings>;
+export declare const resolveRelayUrl: (settings: Settings) => Effect.Effect<string, never, never> | Effect.Effect<string, never, import("./relayRegistry.js").RelayRegistryServices>;
+//# sourceMappingURL=relayLocation.d.ts.map

package/dist/relayLocation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relayLocation.d.ts","sourceRoot":"","sources":["../src/relayLocation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAO/C,MAAM,MAAM,QAAQ,GAAG,QAAQ,CAAC;IAC9B,mBAAmB,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;IAC1C,mBAAmB,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;IAC1C,WAAW,EAAE,MAAM,CAAA;CACpB,CAAC,CAAA;AAEF,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,CAAC,QAAQ,CAe5B,CAAA;AAkBrB,eAAO,MAAM,eAAe,aAAc,QAAQ,2HAmBjD,CAAA"}

package/dist/relayLocation.js

@@ -0,0 +1,33 @@
+import { Config, Effect, Option } from 'effect';
+import { discoverRelay } from './relayRegistry.js';
+const LEGACY_DEFAULT_PORT = 9988;
+const DEFAULT_HOST = 'localhost';
+export const loadSettings = Effect.gen(function* () {
+    const maybeConfiguredPort = yield* Config.option(Config.String('FOLDKIT_DEVTOOLS_MCP_PORT'));
+    const maybeConfiguredHost = yield* Config.option(Config.String('FOLDKIT_DEVTOOLS_MCP_HOST'));
+    const maybeProjectRoot = yield* Config.option(Config.String('FOLDKIT_PROJECT_ROOT'));
+    return {
+        maybeConfiguredPort,
+        maybeConfiguredHost,
+        projectRoot: Option.getOrElse(maybeProjectRoot, () => process.cwd()),
+    };
+}).pipe(Effect.orDie);
+const relayUrl = (host, port) => `ws://${host}:${port}`;
+const withConfiguredHost = (maybeConfiguredHost, url) => Option.match(maybeConfiguredHost, {
+    onNone: () => url,
+    onSome: host => {
+        const parsed = new URL(url);
+        parsed.hostname = host;
+        return parsed.toString();
+    },
+});
+export const resolveRelayUrl = (settings) => {
+    const configuredHost = Option.getOrElse(settings.maybeConfiguredHost, () => DEFAULT_HOST);
+    return Option.match(settings.maybeConfiguredPort, {
+        onSome: port => Effect.succeed(relayUrl(configuredHost, port)),
+        onNone: () => discoverRelay(settings.projectRoot).pipe(Effect.map(maybeRecord => Option.match(maybeRecord, {
+            onSome: record => withConfiguredHost(settings.maybeConfiguredHost, record.url),
+            onNone: () => relayUrl(configuredHost, LEGACY_DEFAULT_PORT),
+        }))),
+    });
+};

package/dist/relayRegistry.d.ts

@@ -0,0 +1,5 @@
+import { Effect, FileSystem, Option, Path } from 'effect';
+import { RelayRecord } from 'foldkit/devtools-protocol';
+export type RelayRegistryServices = FileSystem.FileSystem | Path.Path;
+export declare const discoverRelay: (projectRoot: string) => Effect.Effect<Option.Option<RelayRecord>, never, RelayRegistryServices>;
+//# sourceMappingURL=relayRegistry.d.ts.map

package/dist/relayRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relayRegistry.d.ts","sourceRoot":"","sources":["../src/relayRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,MAAM,EACN,UAAU,EACV,MAAM,EAEN,IAAI,EAIL,MAAM,QAAQ,CAAA;AACf,OAAO,EAGL,WAAW,EACZ,MAAM,2BAA2B,CAAA;AAOlC,MAAM,MAAM,qBAAqB,GAAG,UAAU,CAAC,UAAU,GAAG,IAAI,CAAC,IAAI,CAAA;AA4FrE,eAAO,MAAM,aAAa,gBACX,MAAM,KAClB,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,KAAK,EAAE,qBAAqB,CAoCrE,CAAA"}

package/dist/relayRegistry.js

@@ -0,0 +1,70 @@
+import { Array, Config, Effect, FileSystem, Option, Order, Path, Schema, String, pipe, } from 'effect';
+import { RELAY_REGISTRY_DIRECTORY_NAME, RELAY_REGISTRY_DIRECTORY_VARIABLE, RelayRecord, } from 'foldkit/devtools-protocol';
+import { tmpdir } from 'node:os';
+const RUNTIME_DIRECTORY_VARIABLE = 'XDG_RUNTIME_DIR';
+const RECORD_FILE_EXTENSION = '.json';
+const RETIRING_RECORD_SUFFIX = '.retiring';
+const decodeRelayRecord = Schema.decodeUnknownOption(Schema.fromJsonString(RelayRecord));
+const relayRegistryDirectory = Effect.gen(function* () {
+    const path = yield* Path.Path;
+    const maybeConfigured = yield* Config.option(Config.String(RELAY_REGISTRY_DIRECTORY_VARIABLE));
+    const maybeRuntimeDirectory = yield* Config.option(Config.String(RUNTIME_DIRECTORY_VARIABLE));
+    return Option.getOrElse(maybeConfigured, () => path.join(Option.getOrElse(maybeRuntimeDirectory, tmpdir), RELAY_REGISTRY_DIRECTORY_NAME));
+}).pipe(Effect.orDie);
+const isProcessAlive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error instanceof Error && 'code' in error && error.code === 'EPERM';
+    }
+};
+const readRecordFile = (filePath) => Effect.gen(function* () {
+    const fileSystem = yield* FileSystem.FileSystem;
+    const raw = yield* fileSystem.readFileString(filePath);
+    return decodeRelayRecord(raw);
+}).pipe(Effect.orElseSucceed(() => Option.none()));
+const retireStaleRecord = (filePath, record) => Effect.gen(function* () {
+    const fileSystem = yield* FileSystem.FileSystem;
+    const retiringPath = `${filePath}.${encodeURIComponent(record.id)}${RETIRING_RECORD_SUFFIX}`;
+    const wasRecordMoved = yield* fileSystem
+        .rename(filePath, retiringPath)
+        .pipe(Effect.as(true), Effect.orElseSucceed(() => false));
+    if (!wasRecordMoved) {
+        return;
+    }
+    const maybeRetiringRecord = yield* readRecordFile(retiringPath);
+    const isOriginalRecord = Option.exists(maybeRetiringRecord, retiringRecord => retiringRecord.id === record.id);
+    if (!isOriginalRecord) {
+        yield* fileSystem.link(retiringPath, filePath).pipe(Effect.ignore);
+    }
+    yield* fileSystem.remove(retiringPath, { force: true }).pipe(Effect.ignore);
+});
+const readLiveRecordFile = (filePath) => Effect.gen(function* () {
+    const maybeRecord = yield* readRecordFile(filePath);
+    if (Option.isSome(maybeRecord) && !isProcessAlive(maybeRecord.value.pid)) {
+        yield* retireStaleRecord(filePath, maybeRecord.value);
+        return Option.none();
+    }
+    return maybeRecord;
+});
+const newestFirst = Order.mapInput(Order.flip(Order.Number), record => record.startedAt);
+export const discoverRelay = (projectRoot) => Effect.gen(function* () {
+    const fileSystem = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const directory = yield* relayRegistryDirectory;
+    const isWithinProjectRoot = (candidatePath) => {
+        const relativePath = path.relative(projectRoot, candidatePath);
+        return (relativePath === '' ||
+            (relativePath !== '..' &&
+                !relativePath.startsWith(`..${path.sep}`) &&
+                !path.isAbsolute(relativePath)));
+    };
+    const fileNames = yield* fileSystem
+        .readDirectory(directory)
+        .pipe(Effect.orElseSucceed(() => []));
+    const recordFileNames = Array.filter(fileNames, String.endsWith(RECORD_FILE_EXTENSION));
+    const maybeRecords = yield* Effect.forEach(recordFileNames, recordFileName => readLiveRecordFile(path.join(directory, recordFileName)));
+    return pipe(maybeRecords, Array.getSomes, Array.filter(record => isWithinProjectRoot(record.root)), Array.sort(newestFirst), Array.head);
+});