@foldkit/devtools-mcp 0.1.0

package/README.md

@@ -0,0 +1,104 @@
+# @foldkit/devtools-mcp
+
+A Model Context Protocol server that exposes a running [Foldkit](https://foldkit.dev) app to AI agents (Claude Code, Codex, Cursor, Windsurf, anything that speaks MCP).
+
+With it attached, agents can:
+
+- Read the current Model
+- List and inspect the Message history
+- Replay to any past state and resume
+- Dispatch Messages into the runtime, validated against your `Message` Schema
+
+## Quick Start
+
+Projects scaffolded with [`create-foldkit-app`](https://foldkit.dev/getting-started) ship with the MCP server pre-wired. Open the project in your AI agent and the tools appear under the `foldkit-devtools` prefix.
+
+For existing projects, run the init command in your project root:
+
+```bash
+npx @foldkit/devtools-mcp init
+```
+
+This writes a `.mcp.json` (or merges into an existing one) so any MCP-aware agent picks up the server.
+
+For faster startup, install the MCP server as a devDependency. Otherwise `npx` fetches it on each AI agent restart:
+
+```bash
+npm install -D @foldkit/devtools-mcp
+# or
+pnpm add -D @foldkit/devtools-mcp
+# or
+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 { foldkit } from '@foldkit/vite-plugin'
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  plugins: [foldkit({ devToolsMcpPort: 9988 })],
+})
+```
+
+In your `Runtime.makeProgram` call, pass your `Message` Schema. This is what the agent sees when it asks "what Messages can I dispatch?", and it gates dispatch by validating every payload before it reaches your update function:
+
+```typescript
+Runtime.makeProgram({
+  devTools: {
+    // Rest of your DevTools config
+    Message,
+  },
+})
+```
+
+Restart your dev server, then restart your AI agent. The MCP server will appear with the eight `foldkit_*` tools attached.
+
+## Tools
+
+Each tool accepts an optional `runtime_id`. When omitted, the most recently connected runtime is used.
+
+| Tool                         | Description                                                                                                                                                          |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `foldkit_list_runtimes`      | Returns metadata for every connected browser tab, including each runtime's Message Schema as JSON Schema. Agents call this first to discover what they can dispatch. |
+| `foldkit_get_model`          | Snapshots the current Model.                                                                                                                                         |
+| `foldkit_list_messages`      | Lists recent Message history entries with pagination. Each entry carries the Message body, command names triggered, timestamp, and a path-level diff.                |
+| `foldkit_get_message`        | Reads one entry at a given index, including the Model before and after the Message was applied.                                                                      |
+| `foldkit_list_keyframes`     | Returns the indices Foldkit can replay back to. Index `-1` is the initial Model.                                                                                     |
+| `foldkit_replay_to_keyframe` | Time-travels the runtime to a previous state. The runtime is paused at that snapshot until `foldkit_resume` is called.                                               |
+| `foldkit_resume`             | Resumes normal execution after a replay.                                                                                                                             |
+| `foldkit_dispatch_message`   | Enqueues a Message into the runtime as if your application produced it. The bridge validates the payload against your Schema before it reaches the update loop.      |
+
+## Architecture
+
+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.
+- **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. |
+
+## Notes
+
+- 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.
+- Without `Message` in your `DevToolsConfig`, dispatch is rejected. The other (read-only) tools still work.
+- The relay only runs at dev time. Production builds never include the relay or the bridge, regardless of any `show` setting.
+
+## Documentation
+
+See [foldkit.dev/ai/mcp](https://foldkit.dev/ai/mcp) for the full guide.
+
+## License
+
+MIT

package/dist/install.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Initialize the Foldkit DevTools MCP server in the current working directory.
+ * Writes (or merges into) `.mcp.json` so any AI agent that respects the file
+ * picks up the server. Idempotent: re-running overwrites only the
+ * `foldkit-devtools` entry, leaving any other configured servers alone.
+ */
+export declare const runInit: () => void;
+//# sourceMappingURL=install.d.ts.map

package/dist/install.d.ts.map

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

package/dist/install.js

@@ -0,0 +1,72 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+const MCP_SERVER_NAME = 'foldkit-devtools';
+const DEFAULT_MCP_FILE_NAME = '.mcp.json';
+const SERVER_ENTRY = {
+    command: 'npx',
+    args: ['-y', '@foldkit/devtools-mcp'],
+};
+const loadExistingConfig = (mcpPath) => {
+    if (!existsSync(mcpPath)) {
+        return {};
+    }
+    try {
+        const raw = readFileSync(mcpPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== 'object' || parsed === null) {
+            throw new Error('config root is not an object');
+        }
+        return parsed;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`[foldkit-devtools-mcp] failed to parse existing ${mcpPath}: ${message}`);
+        console.error('[foldkit-devtools-mcp] aborting init to avoid clobbering your config. Fix the JSON and re-run.');
+        process.exit(1);
+    }
+};
+const printNextSteps = (alreadyRegistered) => {
+    console.log('');
+    if (alreadyRegistered) {
+        console.log('Updated existing foldkit-devtools entry.');
+    }
+    else {
+        console.log('Added foldkit-devtools to .mcp.json.');
+    }
+    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.makeProgram (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('');
+    console.log('Tools will appear under the foldkit-devtools server, e.g. foldkit_get_model, foldkit_dispatch_message.');
+};
+/**
+ * Initialize the Foldkit DevTools MCP server in the current working directory.
+ * Writes (or merges into) `.mcp.json` so any AI agent that respects the file
+ * picks up the server. Idempotent: re-running overwrites only the
+ * `foldkit-devtools` entry, leaving any other configured servers alone.
+ */
+export const runInit = () => {
+    const cwd = process.cwd();
+    const mcpPath = join(cwd, DEFAULT_MCP_FILE_NAME);
+    const existing = loadExistingConfig(mcpPath);
+    const existingServers = (existing.mcpServers ?? {});
+    const alreadyRegistered = MCP_SERVER_NAME in existingServers;
+    const next = {
+        ...existing,
+        mcpServers: {
+            ...existingServers,
+            [MCP_SERVER_NAME]: SERVER_ENTRY,
+        },
+    };
+    writeFileSync(mcpPath, `${JSON.stringify(next, null, 2)}\n`, 'utf-8');
+    printNextSteps(alreadyRegistered);
+};

package/dist/server.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":""}

package/dist/server.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { Effect, HashMap, Option, Runtime } from 'effect';
+import { runInit } from './install.js';
+import { buildTools } from './tools.js';
+import { connectWebSocketClient } from './webSocketClient.js';
+const DEFAULT_PORT = 9988;
+const DEFAULT_HOST = 'localhost';
+const port = Number(process.env['FOLDKIT_DEVTOOLS_MCP_PORT'] ?? DEFAULT_PORT);
+const host = process.env['FOLDKIT_DEVTOOLS_MCP_HOST'] ?? DEFAULT_HOST;
+const main = Effect.gen(function* () {
+    const wsClient = yield* connectWebSocketClient(`ws://${host}:${port}`);
+    const tools = buildTools(wsClient);
+    const toolsByName = HashMap.fromIterable(tools.map(tool => [tool.name, tool]));
+    const runtime = yield* Effect.runtime();
+    const server = new Server({ name: '@foldkit/devtools-mcp', version: '0.1.0' }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, () => Promise.resolve({
+        tools: tools.map(({ name, description, inputSchema }) => ({
+            name,
+            description,
+            inputSchema,
+        })),
+    }));
+    server.setRequestHandler(CallToolRequestSchema, request => Option.match(HashMap.get(toolsByName, request.params.name), {
+        onNone: () => Promise.resolve({
+            content: [
+                {
+                    type: 'text',
+                    text: `Error: unknown tool ${request.params.name}`,
+                },
+            ],
+            isError: true,
+        }),
+        onSome: tool => Runtime.runPromise(runtime)(tool.handle(request.params.arguments ?? {})),
+    }));
+    const transport = new StdioServerTransport();
+    yield* Effect.tryPromise({
+        try: () => server.connect(transport),
+        catch: error => error,
+    });
+    yield* Effect.sync(() => console.error('[foldkit-devtools-mcp] MCP server ready on stdio'));
+});
+const subcommand = process.argv[2];
+if (subcommand === 'init') {
+    runInit();
+}
+else {
+    Effect.runPromise(main).catch(error => {
+        console.error('[foldkit-devtools-mcp] fatal error', error);
+        process.exit(1);
+    });
+}

package/dist/tools.d.ts

@@ -0,0 +1,24 @@
+import { Effect } from 'effect';
+import type { WebSocketClient } from './webSocketClient.js';
+type ToolResult = Readonly<{
+    content: ReadonlyArray<Readonly<{
+        type: 'text';
+        text: string;
+    }>>;
+    isError?: boolean;
+}>;
+/** A tool registration the MCP server hands to its low-level `Server.setRequestHandler` for `tools/list` and `tools/call`. */
+export type ToolDefinition = Readonly<{
+    name: string;
+    description: string;
+    inputSchema: object;
+    handle: (rawInput: unknown) => Effect.Effect<ToolResult>;
+}>;
+/**
+ * Build the read-only Foldkit DevTools tool definitions. Each tool decodes its
+ * input via Effect Schema, dispatches a typed `Request` through the WebSocket
+ * relay, and formats the typed `Response` as MCP tool content.
+ */
+export declare const buildTools: (wsClient: WebSocketClient) => ReadonlyArray<ToolDefinition>;
+export {};
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,MAAM,EAA0C,MAAM,QAAQ,CAAA;AAc9E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAyF3D,KAAK,UAAU,GAAG,QAAQ,CAAC;IACzB,OAAO,EAAE,aAAa,CAAC,QAAQ,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAA;IAChE,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB,CAAC,CAAA;AAEF,8HAA8H;AAC9H,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC;IACpC,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE,MAAM,CAAA;IACnB,MAAM,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAA;CACzD,CAAC,CAAA;AA4GF;;;;GAIG;AACH,eAAO,MAAM,UAAU,GACrB,UAAU,eAAe,KACxB,aAAa,CAAC,cAAc,CA0F9B,CAAA"}

package/dist/tools.js

@@ -0,0 +1,162 @@
+import { Array, Effect, JSONSchema, Match, Option, Schema as S } from 'effect';
+import { RequestDispatchMessage, RequestGetMessage, RequestGetModel, RequestListKeyframes, RequestListMessages, RequestListRuntimes, RequestReplayToKeyframe, RequestResume, } from 'foldkit/devtools-protocol';
+const RUNTIME_ID_DESCRIPTION = 'Optional connection id of a specific Foldkit runtime. Defaults to the most recently connected runtime.';
+const DEFAULT_LIST_MESSAGES_LIMIT = 50;
+const RuntimeIdField = S.optional(S.String.annotations({ description: RUNTIME_ID_DESCRIPTION }));
+const ListLimit = S.Number.pipe(S.int(), S.between(1, 500), S.annotations({
+    description: `Maximum number of entries to return. Defaults to ${DEFAULT_LIST_MESSAGES_LIMIT}; max 500.`,
+}));
+const SinceIndex = S.Number.pipe(S.int(), S.annotations({
+    description: 'Absolute history index to start from. Use the maybeNextIndex returned by a prior call to paginate.',
+}));
+const MessageIndex = S.Number.pipe(S.int(), S.annotations({
+    description: 'Absolute history index of the entry to read.',
+}));
+const KeyframeIndex = S.Number.pipe(S.int(), S.annotations({
+    description: 'Index to replay to. Use -1 to jump to the initial Model (before any messages). Use a non-negative index to jump to the Model state right after that history index. Call foldkit_list_keyframes for the canonical replay points.',
+}));
+const GetModelInput = S.Struct({
+    runtime_id: RuntimeIdField,
+});
+const ListMessagesInput = S.Struct({
+    runtime_id: RuntimeIdField,
+    limit: S.optional(ListLimit),
+    since_index: S.optional(SinceIndex),
+});
+const GetMessageInput = S.Struct({
+    runtime_id: RuntimeIdField,
+    index: MessageIndex,
+});
+const ListKeyframesInput = S.Struct({
+    runtime_id: RuntimeIdField,
+});
+const ReplayToKeyframeInput = S.Struct({
+    runtime_id: RuntimeIdField,
+    keyframe_index: KeyframeIndex,
+});
+const ResumeInput = S.Struct({
+    runtime_id: RuntimeIdField,
+});
+const DispatchMessageInput = S.Struct({
+    runtime_id: RuntimeIdField,
+    message: S.Unknown.annotations({
+        description: "A Foldkit Message object to dispatch into the runtime. Must match the runtime's Message Schema (call foldkit_list_runtimes and inspect each runtime's maybeMessageSchema field for the exact shape). At minimum it has a `_tag` field naming the variant.",
+    }),
+});
+/**
+ * JSON Schema for tools that take no input. Inlined as a literal because
+ * `JSONSchema.make(S.Struct({}))` produces a shape MCP's AJV validator
+ * rejects (no top-level `type: "object"` for an empty struct).
+ */
+const NO_INPUT_SCHEMA = {
+    type: 'object',
+    properties: {},
+    additionalProperties: false,
+};
+const formatResult = (value) => ({
+    content: [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+});
+const formatError = (reason) => ({
+    content: [{ type: 'text', text: `Error: ${reason}` }],
+    isError: true,
+});
+/**
+ * Decode a tool's raw input against its Effect Schema. Failure surfaces as an
+ * `Error` for the outer handler's `catchAll` to convert into a `ToolResult`.
+ */
+const decodeInput = (schema, rawInput) => S.decodeUnknown(schema)(rawInput).pipe(Effect.mapError(error => new Error(`Invalid input: ${error.message}`)));
+/**
+ * Resolve a runtime id, defaulting to the most recently connected runtime when
+ * the caller did not specify one. Failures (no runtimes connected, relay
+ * error) surface as `Error` for the outer handler's `catchAll` to convert.
+ */
+const resolveRuntimeId = (wsClient, explicit) => {
+    if (explicit !== undefined) {
+        return Effect.succeed(explicit);
+    }
+    return Effect.gen(function* () {
+        const response = yield* wsClient.sendRequest(RequestListRuntimes(), Option.none());
+        return yield* Match.value(response).pipe(Match.tag('ResponseRuntimes', ({ runtimes }) => Array.last(runtimes).pipe(Option.match({
+            onNone: () => Effect.fail(new Error('No connected Foldkit runtimes. Open a Foldkit dev page and try again.')),
+            onSome: runtime => Effect.succeed(runtime.connectionId),
+        }))), Match.tag('ResponseError', ({ reason }) => Effect.fail(new Error(reason))), Match.orElse(({ _tag }) => Effect.fail(new Error(`Unexpected response from RequestListRuntimes: ${_tag}`))));
+    });
+};
+const responseToToolResult = (response) => response._tag === 'ResponseError'
+    ? formatError(response.reason)
+    : formatResult(response);
+const callRuntimeRequest = (wsClient, explicitRuntimeId, buildRequest) => Effect.gen(function* () {
+    const runtimeId = yield* resolveRuntimeId(wsClient, explicitRuntimeId);
+    const response = yield* wsClient.sendRequest(buildRequest(), Option.some(runtimeId));
+    return responseToToolResult(response);
+}).pipe(Effect.catchAll(error => Effect.succeed(formatError(error.message))));
+/**
+ * Build a tool handler that decodes its input, resolves the target runtime,
+ * issues a typed `Request`, and formats the response. Used for every tool
+ * except `foldkit_list_runtimes`, which does not target a specific runtime.
+ */
+const runRuntimeTool = (inputSchema, buildRequest, wsClient) => (rawInput) => Effect.gen(function* () {
+    const input = yield* decodeInput(inputSchema, rawInput);
+    return yield* callRuntimeRequest(wsClient, input.runtime_id, () => buildRequest(input));
+}).pipe(Effect.catchAll(error => Effect.succeed(formatError(error.message))));
+/**
+ * Build the read-only Foldkit DevTools tool definitions. Each tool decodes its
+ * input via Effect Schema, dispatches a typed `Request` through the WebSocket
+ * relay, and formats the typed `Response` as MCP tool content.
+ */
+export const buildTools = (wsClient) => [
+    {
+        name: 'foldkit_get_model',
+        description: 'Snapshot the current Model from a connected Foldkit runtime.',
+        inputSchema: JSONSchema.make(GetModelInput),
+        handle: runRuntimeTool(GetModelInput, () => RequestGetModel(), wsClient),
+    },
+    {
+        name: 'foldkit_list_messages',
+        description: 'List recent Message history entries from a Foldkit runtime, with optional pagination via since_index.',
+        inputSchema: JSONSchema.make(ListMessagesInput),
+        handle: runRuntimeTool(ListMessagesInput, ({ limit, since_index }) => RequestListMessages({
+            limit: limit ?? DEFAULT_LIST_MESSAGES_LIMIT,
+            maybeSinceIndex: Option.fromNullable(since_index),
+        }), wsClient),
+    },
+    {
+        name: 'foldkit_get_message',
+        description: 'Read a single Message history entry by absolute index, including before/after Model snapshots.',
+        inputSchema: JSONSchema.make(GetMessageInput),
+        handle: runRuntimeTool(GetMessageInput, ({ index }) => RequestGetMessage({ index }), wsClient),
+    },
+    {
+        name: 'foldkit_list_keyframes',
+        description: 'List the available keyframes (replayable Model snapshots) from a Foldkit runtime.',
+        inputSchema: JSONSchema.make(ListKeyframesInput),
+        handle: runRuntimeTool(ListKeyframesInput, () => RequestListKeyframes(), wsClient),
+    },
+    {
+        name: 'foldkit_replay_to_keyframe',
+        description: 'Time-travel a Foldkit runtime back to a previous Model snapshot. Pass `keyframe_index: -1` for the initial Model, or a non-negative index for the state right after that history entry. The runtime is paused at the snapshot until foldkit_resume is called.',
+        inputSchema: JSONSchema.make(ReplayToKeyframeInput),
+        handle: runRuntimeTool(ReplayToKeyframeInput, ({ keyframe_index }) => RequestReplayToKeyframe({ keyframeIndex: keyframe_index }), wsClient),
+    },
+    {
+        name: 'foldkit_resume',
+        description: 'Resume normal execution of a Foldkit runtime that was paused by foldkit_replay_to_keyframe.',
+        inputSchema: JSONSchema.make(ResumeInput),
+        handle: runRuntimeTool(ResumeInput, () => RequestResume(), wsClient),
+    },
+    {
+        name: 'foldkit_dispatch_message',
+        description: "Dispatch a Message into a Foldkit runtime's message queue, as if the application itself produced it. Requires the runtime to have configured DevToolsConfig.Message; without it, dispatch is rejected. Use foldkit_list_runtimes to discover the runtime's maybeMessageSchema and construct a Message object.",
+        inputSchema: JSONSchema.make(DispatchMessageInput),
+        handle: runRuntimeTool(DispatchMessageInput, ({ message }) => RequestDispatchMessage({ message }), wsClient),
+    },
+    {
+        name: 'foldkit_list_runtimes',
+        description: 'List Foldkit runtimes (browser tabs) currently connected to the dev server.',
+        inputSchema: NO_INPUT_SCHEMA,
+        handle: () => Effect.gen(function* () {
+            const response = yield* wsClient.sendRequest(RequestListRuntimes(), Option.none());
+            return responseToToolResult(response);
+        }).pipe(Effect.catchAll(error => Effect.succeed(formatError(error.message)))),
+    },
+];

package/dist/webSocketClient.d.ts

@@ -0,0 +1,28 @@
+import { type Cause, Effect, Option } from 'effect';
+import { type Request, type Response } from 'foldkit/devtools-protocol';
+/**
+ * A connected WebSocket client to the Foldkit Vite plugin's DevTools relay.
+ *
+ * Sends typed `Request`s and resolves with the matching `Response`. The
+ * `sendRequest` Effect fails with `TimeoutException` when no response arrives
+ * within the request timeout window, or with `Error` when the socket is not
+ * open or the send throws. Either way, no pending entry leaks.
+ *
+ * The client transparently reconnects with exponential backoff when the
+ * underlying socket closes (e.g. when the user restarts the Vite dev server).
+ * Pending response correlators live in a client-owned Ref, not on the socket,
+ * so they survive reconnects: in-flight requests time out and future requests
+ * succeed once the new socket is open.
+ */
+export type WebSocketClient = Readonly<{
+    sendRequest: (request: typeof Request.Type, maybeRuntimeId: Option.Option<string>) => Effect.Effect<typeof Response.Type, Cause.TimeoutException | Error>;
+    close: Effect.Effect<void>;
+}>;
+/**
+ * Open a WebSocket connection to the Foldkit Vite plugin's DevTools relay.
+ * The Effect succeeds once the initial connection is open and ready for
+ * traffic. It fails with the underlying `Error` if the *first* connection
+ * cannot be opened. Subsequent disconnects reconnect transparently.
+ */
+export declare const connectWebSocketClient: (url: string) => Effect.Effect<WebSocketClient, Error>;
+//# sourceMappingURL=webSocketClient.d.ts.map

package/dist/webSocketClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webSocketClient.d.ts","sourceRoot":"","sources":["../src/webSocketClient.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,KAAK,EAGV,MAAM,EAIN,MAAM,EAMP,MAAM,QAAQ,CAAA;AACf,OAAO,EACL,KAAK,OAAO,EAEZ,KAAK,QAAQ,EAEd,MAAM,2BAA2B,CAAA;AAYlC;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC;IACrC,WAAW,EAAE,CACX,OAAO,EAAE,OAAO,OAAO,CAAC,IAAI,EAC5B,cAAc,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,KAClC,MAAM,CAAC,MAAM,CAAC,OAAO,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,gBAAgB,GAAG,KAAK,CAAC,CAAA;IACxE,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;CAC3B,CAAC,CAAA;AAwDF;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,GACjC,KAAK,MAAM,KACV,MAAM,CAAC,MAAM,CAAC,eAAe,EAAE,KAAK,CAuHnC,CAAA"}

package/dist/webSocketClient.js

@@ -0,0 +1,134 @@
+import { Deferred, Duration, Effect, Either, Fiber, HashMap, Option, Ref, Runtime, Schema as S, Schedule, pipe, } from 'effect';
+import { ResponseFrame, } from 'foldkit/devtools-protocol';
+import { WebSocket } from 'ws';
+const REQUEST_TIMEOUT = Duration.seconds(10);
+const INITIAL_RECONNECT_DELAY = Duration.millis(500);
+const MAX_RECONNECT_DELAY = Duration.seconds(30);
+const generateRequestId = () => `req-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+/** Exponential backoff capped at MAX_RECONNECT_DELAY, retried indefinitely. */
+const reconnectSchedule = Schedule.exponential(INITIAL_RECONNECT_DELAY).pipe(Schedule.modifyDelay(delay => Duration.lessThanOrEqualTo(delay, MAX_RECONNECT_DELAY)
+    ? delay
+    : MAX_RECONNECT_DELAY));
+const attemptOpen = (url) => Effect.async(resume => {
+    const socket = new WebSocket(url);
+    let settled = false;
+    socket.once('open', () => {
+        if (settled)
+            return;
+        settled = true;
+        resume(Effect.succeed(socket));
+    });
+    socket.once('error', error => {
+        if (settled)
+            return;
+        settled = true;
+        resume(Effect.fail(error));
+    });
+    return Effect.sync(() => {
+        if (!settled) {
+            socket.removeAllListeners();
+            socket.close();
+        }
+    });
+});
+const waitForClose = (socket) => Effect.async(resume => {
+    const isAlreadyClosing = socket.readyState === WebSocket.CLOSED ||
+        socket.readyState === WebSocket.CLOSING;
+    if (isAlreadyClosing) {
+        resume(Effect.void);
+        return undefined;
+    }
+    else {
+        const handler = () => {
+            resume(Effect.void);
+        };
+        socket.once('close', handler);
+        return Effect.sync(() => {
+            socket.off('close', handler);
+        });
+    }
+});
+/**
+ * Open a WebSocket connection to the Foldkit Vite plugin's DevTools relay.
+ * The Effect succeeds once the initial connection is open and ready for
+ * traffic. It fails with the underlying `Error` if the *first* connection
+ * cannot be opened. Subsequent disconnects reconnect transparently.
+ */
+export const connectWebSocketClient = (url) => Effect.gen(function* () {
+    const initialSocket = yield* attemptOpen(url);
+    yield* Effect.sync(() => console.error(`[foldkit-devtools-mcp] connected to ${url}`));
+    const pendingResponsesRef = yield* Ref.make(HashMap.empty());
+    const currentSocketRef = yield* Ref.make(initialSocket);
+    const isManuallyClosedRef = yield* Ref.make(false);
+    const runtime = yield* Effect.runtime();
+    const attachMessageHandler = (socket) => {
+        socket.on('message', raw => {
+            Runtime.runFork(runtime)(handleIncomingMessage(raw, pendingResponsesRef));
+        });
+        socket.on('error', error => {
+            console.error(`[foldkit-devtools-mcp] socket error: ${error.message}`);
+        });
+    };
+    attachMessageHandler(initialSocket);
+    const reconnectLoop = Effect.gen(function* () {
+        const socket = yield* Ref.get(currentSocketRef);
+        yield* waitForClose(socket);
+        const isManual = yield* Ref.get(isManuallyClosedRef);
+        if (isManual) {
+            return;
+        }
+        yield* Effect.sync(() => console.error('[foldkit-devtools-mcp] connection lost, reconnecting with backoff'));
+        const newSocket = yield* pipe(attemptOpen(url), Effect.tapError(error => Effect.sync(() => console.error(`[foldkit-devtools-mcp] reconnect attempt failed: ${error.message}`))), Effect.retry(reconnectSchedule), Effect.orDie);
+        yield* Effect.sync(() => console.error(`[foldkit-devtools-mcp] reconnected to ${url}`));
+        attachMessageHandler(newSocket);
+        yield* Ref.set(currentSocketRef, newSocket);
+        yield* reconnectLoop;
+    });
+    const reconnectFiber = yield* Effect.forkDaemon(reconnectLoop);
+    const sendRequest = (request, maybeRuntimeId) => Effect.gen(function* () {
+        const id = generateRequestId();
+        const deferred = yield* Deferred.make();
+        yield* Ref.update(pendingResponsesRef, HashMap.set(id, deferred));
+        const socket = yield* Ref.get(currentSocketRef);
+        if (socket.readyState !== WebSocket.OPEN) {
+            yield* Ref.update(pendingResponsesRef, HashMap.remove(id));
+            return yield* Effect.fail(new Error('Socket not open. The dev server may have just restarted; the MCP client is reconnecting. Retry the tool call in a moment.'));
+        }
+        const frame = {
+            id,
+            maybeConnectionId: maybeRuntimeId,
+            request,
+        };
+        yield* Effect.try({
+            try: () => socket.send(JSON.stringify(frame)),
+            catch: error => error instanceof Error
+                ? error
+                : new Error(`Failed to send request: ${String(error)}`),
+        }).pipe(Effect.tapError(() => Ref.update(pendingResponsesRef, HashMap.remove(id))));
+        return yield* Deferred.await(deferred).pipe(Effect.timeout(REQUEST_TIMEOUT), Effect.onError(() => Ref.update(pendingResponsesRef, HashMap.remove(id))));
+    });
+    const close = Effect.gen(function* () {
+        yield* Ref.set(isManuallyClosedRef, true);
+        const socket = yield* Ref.get(currentSocketRef);
+        yield* Effect.sync(() => socket.close());
+        yield* Fiber.interrupt(reconnectFiber);
+    });
+    return { sendRequest, close };
+});
+const handleIncomingMessage = (raw, pendingResponsesRef) => {
+    const decoded = S.decodeUnknownEither(S.parseJson(ResponseFrame))(raw.toString());
+    return Either.match(decoded, {
+        onLeft: error => Effect.sync(() => console.error('[foldkit-devtools-mcp] failed to decode frame', error)),
+        onRight: responseFrame => Effect.gen(function* () {
+            const map = yield* Ref.get(pendingResponsesRef);
+            const maybeDeferred = HashMap.get(map, responseFrame.id);
+            yield* Option.match(maybeDeferred, {
+                onNone: () => Effect.void,
+                onSome: deferred => Effect.gen(function* () {
+                    yield* Ref.update(pendingResponsesRef, HashMap.remove(responseFrame.id));
+                    yield* Deferred.succeed(deferred, responseFrame.response);
+                }),
+            });
+        }),
+    });
+};

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@foldkit/devtools-mcp",
+  "version": "0.1.0",
+  "description": "MCP server exposing Foldkit DevTools to AI agents (Claude Code, Cursor, etc.)",
+  "type": "module",
+  "main": "./dist/server.js",
+  "module": "./dist/server.js",
+  "types": "./dist/server.d.ts",
+  "bin": {
+    "foldkit-devtools-mcp": "./dist/server.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    }
+  },
+  "scripts": {
+    "clean": "rimraf dist *.tsbuildinfo",
+    "build": "pnpm run clean && tsc -b",
+    "watch": "tsc -b --watch",
+    "typecheck": "tsc -b --noEmit"
+  },
+  "peerDependencies": {
+    "effect": "^3.18.2",
+    "foldkit": "workspace:^0.76.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.5.13",
+    "effect": "^3.19.19",
+    "foldkit": "workspace:*",
+    "rimraf": "^6.0.0",
+    "typescript": "^6.0.2"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "foldkit",
+    "mcp",
+    "model-context-protocol",
+    "devtools",
+    "ai"
+  ],
+  "author": "Devin Jameson",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/foldkit/foldkit.git",
+    "directory": "packages/devtools-mcp"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}