The best way to control Claude Code, Codex and more from any computer or phone
feat(mcp): preview_open goes straight to a dev-server port (#28027)
Co-authored-by: maria-rcks <254055478+maria-rcks@users.noreply.github.com>
maria committed
Nov 1, 2026 at 06:52 UTC
6328c8472255e9b93bd362af63ae0d3c17e2d540
7 files changed
+147
-9
apps/server/src/mcp/toolkits/preview/handlers.test.ts
+92
-2
@@ -1,17 +1,107 @@
1
import { describe, expect, it } from "@effect/vitest";
2
import * as NodeServices from "@effect/platform-node/NodeServices";
3
-import { ThreadId } from "@t3tools/contracts";
3
+import {
4
+ EnvironmentId,
5
+ PreviewTabId,
6
+ ProviderInstanceId,
7
+ ThreadId,
8
+ type PreviewAutomationRequest,
9
+} from "@t3tools/contracts";
10
+import * as Deferred from "effect/Deferred";
11
import * as Effect from "effect/Effect";
12
import * as FileSystem from "effect/FileSystem";
13
import * as Layer from "effect/Layer";
14
import * as Path from "effect/Path";
15
+import * as Stream from "effect/Stream";
16
17
import {
18
createPendingAttachmentId,
19
parseThreadSegmentFromAttachmentId,
20
} from "../../../attachmentStore.ts";
21
import * as ServerConfig from "../../../config.ts";
14
-import { claimPreviewRecording } from "./handlers.ts";
22
+import * as McpInvocationContext from "../../McpInvocationContext.ts";
23
+import * as McpToolAccess from "../../McpToolAccess.ts";
24
+import { liveThreadsLayer } from "../../McpToolAccess.testkit.ts";
25
+import * as PreviewAutomationBroker from "../../PreviewAutomationBroker.ts";
26
+import { claimPreviewRecording, layerStandard } from "./handlers.ts";
27
+import { PreviewStandardToolkit } from "./tools.ts";
28
+
29
+it.effect("preview_open navigates the opened tab to a dev server in one tool call", () =>
30
+ Effect.scoped(
31
+ Effect.gen(function* () {
32
+ const scope = yield* McpInvocationContext.McpInvocationContext;
33
+ const broker = yield* PreviewAutomationBroker.PreviewAutomationBroker;
34
+ const connected = yield* Deferred.make<void>();
35
+ const tabId = PreviewTabId.make("opened-tab");
36
+ const target = {
37
+ kind: "environment-port" as const,
38
+ port: 3000,
39
+ path: "/settings?tab=account",
40
+ };
41
+ const requests: PreviewAutomationRequest[] = [];
42
+ const status = {
43
+ available: true,
44
+ visible: false,
45
+ tabId,
46
+ url: "http://localhost:3000/settings?tab=account",
47
+ title: "Settings",
48
+ loading: false,
49
+ };
50
+ const events = yield* broker.connect({
51
+ clientId: "client-1",
52
+ environmentId: scope.environmentId,
53
+ });
54
+ yield* Stream.runForEach(events, (event) => {
55
+ if (event.type === "connected") return Deferred.succeed(connected, undefined);
56
+ requests.push(event.request);
57
+ return broker.respond({
58
+ clientId: "client-1",
59
+ connectionId: event.connectionId,
60
+ requestId: event.request.requestId,
61
+ ok: true,
62
+ result: event.request.operation === "open" ? { ...status, url: "about:blank" } : status,
63
+ });
64
+ }).pipe(Effect.forkScoped);
65
+ yield* Deferred.await(connected);
66
+ const toolkit = yield* PreviewStandardToolkit.pipe(
67
+ Effect.provide(McpToolAccess.HandlersLayer.layer(layerStandard)),
68
+ );
69
+ const results = yield* toolkit
70
+ .handle("preview_open", {
71
+ url: "http://localhost:3000",
72
+ target,
73
+ open: false,
74
+ reuseExistingTab: false,
75
+ })
76
+ .pipe(Stream.unwrap, Stream.runCollect);
77
+ expect(results.at(-1)?.result).toEqual(status);
78
+ expect(requests.map(({ operation, input }) => ({ operation, input }))).toEqual([
79
+ { operation: "open", input: { open: false, show: false, reuseExistingTab: false } },
80
+ { operation: "navigate", input: { target } },
81
+ ]);
82
+ expect(requests[1]?.tabId).toBe(tabId);
83
+ expect(requests[1]?.tabIdExplicit).toBe(true);
84
+ }).pipe(
85
+ Effect.provideService(McpInvocationContext.McpInvocationContext, {
86
+ environmentId: EnvironmentId.make("environment-1"),
87
+ requestNamespace: "provider-session-1",
88
+ thread: {
89
+ threadId: ThreadId.make("thread-1"),
90
+ providerSessionId: "provider-session-1",
91
+ providerInstanceId: ProviderInstanceId.make("codex"),
92
+ },
93
+ client: undefined,
94
+ capabilities: new Set(["preview"] as const),
95
+ issuedAt: 1,
96
+ }),
97
+ Effect.provide(
98
+ Layer.mergeAll(PreviewAutomationBroker.layer, liveThreadsLayer).pipe(
99
+ Layer.provide(NodeServices.layer),
100
+ ),
101
+ ),
102
+ ),
103
+ ),
104
+);
105
106
describe("claimPreviewRecording", () => {
107
it.effect("overlapping and repeated claims return the same retained recording", () =>
apps/server/src/mcp/toolkits/preview/handlers.ts
+15
-2
@@ -195,8 +195,21 @@ const handlers = {
195
preview_status: McpToolAccess.readsAsCaller((input) =>
196
invokeTargeted<PreviewAutomationStatus>("status", input ?? {}),
197
),
198
- preview_open: McpToolAccess.actsAsCaller((input) =>
199
- invokeTargeted<PreviewAutomationStatus>("open", normalizePreviewOpenInput(input)),
198
+ // Models often pass a dev server as both `url` and `target`; the target knows the environment.
199
+ preview_open: McpToolAccess.actsAsCaller(({ target, url, ...input }) =>
200
+ Effect.gen(function* () {
201
+ const opened = yield* invokeTargeted<PreviewAutomationStatus>(
202
+ "open",
203
+ normalizePreviewOpenInput(
204
+ target === undefined && url !== undefined ? { ...input, url } : input,
205
+ ),
206
+ );
207
+ if (target === undefined || opened.tabId === null) return opened;
208
+ return yield* invokeTargeted<PreviewAutomationStatus>("navigate", {
209
+ target,
210
+ tabId: opened.tabId,
211
+ });
212
+ }),
213
),
214
preview_navigate: McpToolAccess.actsAsCaller((input) =>
215
invokeTargeted<PreviewAutomationStatus>("navigate", input, input.timeoutMs),
apps/server/src/mcp/toolkits/preview/tools.test.ts
+15
@@ -1,4 +1,5 @@
1
import { expect, it } from "@effect/vitest";
2
+import * as Schema from "effect/Schema";
3
import { Tool } from "effect/ai";
4
5
import { PreviewToolkit } from "./tools.ts";
@@ -36,3 +37,17 @@ it("exports provider-compatible object schemas", () => {
37
).toBeDefined();
38
}
39
});
40
+
41
+it("preview_open accepts a target while preserving open input constraints", () => {
42
+ const decode = Schema.decodeUnknownSync(PreviewToolkit.tools.preview_open.parametersSchema);
43
+ const target = { kind: "environment-port", port: 3000 };
44
+ expect(decode({ target })).toEqual({ target });
45
+ expect(decode({})).toEqual({});
46
+ expect(decode({ url: "https://example.com" })).toEqual({ url: "https://example.com" });
47
+ expect(decode({ url: "http://localhost:3000", target })).toEqual({
48
+ url: "http://localhost:3000",
49
+ target,
50
+ });
51
+ expect(() => decode({ target: { ...target, port: 0 } })).toThrow();
52
+ expect(() => decode({ target, tabId: "tab-1", reuseExistingTab: false })).toThrow();
53
+});
apps/server/src/mcp/toolkits/preview/tools.ts
+9
-2
@@ -1,4 +1,5 @@
1
import {
2
+ BrowserNavigationTarget,
3
OrchestratorMcpFailure,
4
ToolActivityIcon,
5
PreviewAutomationActInput,
@@ -62,11 +63,17 @@ const PreviewStatusTool = Tool.make("preview_status", {
63
.annotate(Tool.Destructive, false)
64
.annotate(Tool.Idempotent, true);
65
66
+// `url` already covers websites, so open only adds the dev-server target.
67
+const EnvironmentPortTarget = BrowserNavigationTarget.members[1];
68
+
69
const PreviewOpenTool = browserTool(
70
Tool.make("preview_open", {
71
description:
68
- "Open a preview tab in this thread and show it. `open=false` keeps it in the background. Reuses your current tab unless `tabId` or `reuseExistingTab=false` says otherwise. Parallel subagents in one session must each use `reuseExistingTab=false`, then their own returned `tabId`.",
69
- parameters: PreviewAutomationOpenInput,
72
+ "Open a preview tab in this thread and show it. For a dev server, pass `target` instead of `url`. `open=false` keeps it in the background. Reuses your current tab unless `tabId` or `reuseExistingTab=false` says otherwise. Parallel subagents in one session must each use `reuseExistingTab=false`, then their own returned `tabId`.",
73
+ parameters: PreviewAutomationOpenInput.mapFields(
74
+ (fields) => ({ ...fields, target: Schema.optional(EnvironmentPortTarget) }),
75
+ { unsafePreserveChecks: true },
76
+ ),
77
success: PreviewAutomationStatus,
78
failure: PreviewToolFailure,
79
dependencies,
apps/server/src/provider/agentContextBudget.json
+1
-1
@@ -1,5 +1,5 @@
1
{
2
"claudeSystemAppendBytes": 5153,
3
"codexAdditionalContextBytes": 6883,
4
- "mcpToolListJsonBytes": 47074
4
+ "mcpToolListJsonBytes": 47538
5
}
evals/mcp-tool-use/cases/visual-preview.ndjson
+1
@@ -27,3 +27,4 @@
27
{"id": "proactive-visual-latency-regression", "area": "visual-preview", "kind": "bad", "privacy": "commit-safe", "pattern": "data that reads better as a chart answered in prose only", "rule": "When a chart, diagram, or mockup says more than prose: html_preview, then html_render", "source": {"report": "agents used inline HTML visuals less often after #24850 made the rule ask-only"}, "experience": "The user pasted a latency table across releases and asked where it regressed. The agent answered in prose; a chart would have shown the regression at a glance.", "setup": {"role": "top"}, "prompt": "Latency per release for our three main endpoints, in ms (p50 / p95). Which release regressed, and on which endpoint?\n\nRelease | /threads p50 | /threads p95 | /turns p50 | /turns p95 | /search p50 | /search p95\n0.41 | 38 | 92 | 120 | 310 | 44 | 101\n0.42 | 37 | 95 | 118 | 305 | 46 | 104\n0.43 | 39 | 97 | 121 | 318 | 45 | 99\n0.44 | 41 | 210 | 119 | 312 | 47 | 102\n0.45 | 40 | 236 | 162 | 480 | 46 | 100\n0.46 | 42 | 241 | 165 | 492 | 48 | 103", "expect": {"calls": [{"tool": "html_render"}], "order": ["html_preview", "html_render"], "notCalls": ["preview_open", "preview_navigate"]}}
28
{"id": "proactive-visual-ci-time-breakdown", "area": "visual-preview", "kind": "bad", "privacy": "commit-safe", "pattern": "data that reads better as a chart answered in prose only", "rule": "When a chart, diagram, or mockup says more than prose: html_preview, then html_render", "source": {"report": "agents used inline HTML visuals less often after #24850 made the rule ask-only"}, "experience": "The user shared CI job times over several runs and asked what eats the time. The agent answered in prose; a stacked chart would have shown it.", "setup": {"role": "top"}, "prompt": "CI got slow. Here are job times in minutes for the last 8 runs on main. What's eating the time?\n\nRun | install | typecheck | lint | test-server | test-web | build | e2e\n1 | 2.1 | 3.0 | 1.2 | 6.8 | 4.1 | 3.3 | 7.9\n2 | 2.0 | 3.1 | 1.1 | 6.9 | 4.0 | 3.4 | 8.2\n3 | 2.2 | 3.0 | 1.2 | 7.4 | 4.2 | 3.3 | 8.0\n4 | 2.1 | 3.2 | 1.3 | 9.8 | 4.1 | 3.5 | 8.1\n5 | 2.3 | 3.1 | 1.2 | 12.6 | 4.3 | 3.4 | 8.4\n6 | 2.2 | 3.3 | 1.2 | 13.1 | 4.2 | 3.6 | 12.9\n7 | 2.1 | 3.2 | 1.3 | 13.4 | 4.4 | 3.5 | 13.2\n8 | 2.2 | 3.2 | 1.2 | 13.0 | 4.3 | 3.4 | 13.5", "expect": {"calls": [{"tool": "html_render"}], "order": ["html_preview", "html_render"], "notCalls": ["preview_open", "preview_navigate"]}}
29
{"id": "requested-after-video-for-edit", "area": "visual-preview", "kind": "bad", "privacy": "commit-safe", "pattern": "agent refuses requested browser recording of its own edit", "experience": "A user asked for an after video of a UI fix. The agent declined because the injected instructions prohibited preview for its own edits.", "rule": "Use preview when the user asks for browser work, including recording an edit.", "setup": {"role": "top", "context": "The UI fix is complete and a development server is already running at http://localhost:3000. Browser verification and recording are authorized.", "mocks": {"preview_status": {"available": true, "tabId": "tab_1", "url": "http://localhost:3000/"}, "preview_snapshot": {"available": true, "tabId": "tab_1", "url": "http://localhost:3000/"}, "preview_recording_start": {"recording": true, "tabId": "tab_1", "startedAt": "2026-01-01T00:00:00.000Z"}, "preview_recording_stop": {"id": "recording_1", "tabId": "tab_1", "path": "/tmp/after.webm", "mimeType": "video/webm", "sizeBytes": 1024, "createdAt": "2026-01-01T00:00:01.000Z"}}}, "prompt": "Use the T3 browser to verify the UI fix you just made and record an after video.", "expect": {"calls": [{"tool": "preview_recording_start"}, {"tool": "preview_recording_stop"}], "order": ["preview_recording_start", "preview_recording_stop"]}, "source": {"report": "A user requested an after video of a UI fix; the agent declined because preview was prohibited for its own edits."}}
30
+{"id": "dev-server-opened-blank-then-navigated", "area": "visual-preview", "kind": "bad", "pattern": "preview_open on a blank tab, then preview_navigate to the dev-server port", "experience": "Asked to open a dev server in the T3 preview, agents opened a blank tab and navigated it to the port in a second call. 121 of these pairs in a month of maintainer threads.", "rule": "preview_open takes a url but not a dev-server target", "privacy": "commit-safe", "setup": {"role": "top", "context": "CLAUDE.md says: for t3code browser work, use the server-side preview_* mcp tools, with `target: {kind: \"environment-port\", port: ...}` for dev servers in the current environment. The dev server for this repo is running; `vp run dev` printed `Local: http://localhost:5173/`.", "mocks": {"preview_status": {"available": true, "visible": false, "tabId": null, "url": null, "title": null, "loading": false, "profiles": [{"id": "default", "name": "Default"}], "defaultProfileId": "default"}, "preview_open": {"available": true, "visible": true, "tabId": "tab_1", "url": "http://localhost:5173/", "title": "Acme", "loading": false, "control": {"owner": "agent", "ownedByCaller": true}}, "preview_navigate": {"available": true, "visible": true, "tabId": "tab_1", "url": "http://localhost:5173/", "title": "Acme", "loading": false, "control": {"owner": "agent", "ownedByCaller": true}}}}, "prompt": "open the dev server in the t3 preview, i want to click around", "expect": {"calls": [{"tool": "preview_open", "args": {"target.port": 5173}}], "maxCalls": {"preview_open": 1, "preview_navigate": 0}}, "maxSteps": 6, "source": {"thread": "Maintainer threads, 2026-10: preview_open with no url followed by preview_navigate to an environment-port target, 121 times"}}
evals/mcp-tool-use/run.ts
+14
-2
@@ -362,12 +362,15 @@ export const normalizeToolName = (name: string) => {
362
? bare.slice(T3_PREFIX.length)
363
: (CODEX_NAMES[bare] ?? bare.slice(bare.lastIndexOf("_") + 1));
364
};
365
-export const normalizeToolInput = (name: string, input: unknown) =>
366
- normalizeToolName(name) === "Bash" && isRecord(input)
365
+export const normalizeToolInput = (name: string, input: unknown) => {
366
+ const decode = t3InputDecoders.get(normalizeToolName(name));
367
+ if (decode !== undefined) return Option.getOrElse(decode(input), () => input);
368
+ return normalizeToolName(name) === "Bash" && isRecord(input)
369
? { ...input, command: input.command ?? input.cmd }
370
: typeof input === "string" && normalizeToolName(name) === "Edit"
371
? { patch: input }
372
: input;
373
+};
374
375
// McpHttpServer advertises each tool's JSON schema, and Claude Code passes the MCP name,
376
// description, and schema through unchanged.
@@ -384,6 +387,15 @@ const t3SourceTools: ReadonlyArray<Tool.Any> = [
387
DeviceToolkit,
388
HtmlToolkit,
389
].flatMap((toolkit): ReadonlyArray<Tool.Any> => Object.values(toolkit.tools));
390
+// McpHttpServer decodes arguments with each tool's JSON codec, which drops undeclared keys.
391
+const t3InputDecoders = new Map(
392
+ t3SourceTools.map((tool) => [
393
+ tool.name,
394
+ Schema.decodeUnknownOption(
395
+ Schema.toCodecJson(tool.parametersSchema as Schema.Codec<unknown, unknown>),
396
+ ),
397
+ ]),
398
+);
399
const t3Tools: ReadonlyArray<ApiTool> = t3SourceTools.map((tool) => ({
400
name: `${T3_PREFIX}${tool.name}`,
401
description: Tool.getDescription(tool) ?? "",