Skip to content

Commit 6328c84

Browse files
authored
feat(mcp): preview_open goes straight to a dev-server port (#28027)
Co-authored-by: maria-rcks <[email protected]>
1 parent 7195b69 commit 6328c84

7 files changed

Lines changed: 147 additions & 9 deletions

File tree

‎apps/server/src/mcp/toolkits/preview/handlers.test.ts‎

Lines changed: 92 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,107 @@
11
import { describe, expect, it } from "@effect/vitest";
22
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";
411
import * as Effect from "effect/Effect";
512
import * as FileSystem from "effect/FileSystem";
613
import * as Layer from "effect/Layer";
714
import * as Path from "effect/Path";
15+
import * as Stream from "effect/Stream";
816

917
import {
1018
createPendingAttachmentId,
1119
parseThreadSegmentFromAttachmentId,
1220
} from "../../../attachmentStore.ts";
1321
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+
);
15105

16106
describe("claimPreviewRecording", () => {
17107
it.effect("overlapping and repeated claims return the same retained recording", () =>

‎apps/server/src/mcp/toolkits/preview/handlers.ts‎

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -195,8 +195,21 @@ const handlers = {
195195
preview_status: McpToolAccess.readsAsCaller((input) =>
196196
invokeTargeted<PreviewAutomationStatus>("status", input ?? {}),
197197
),
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+
}),
200213
),
201214
preview_navigate: McpToolAccess.actsAsCaller((input) =>
202215
invokeTargeted<PreviewAutomationStatus>("navigate", input, input.timeoutMs),

‎apps/server/src/mcp/toolkits/preview/tools.test.ts‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
import { expect, it } from "@effect/vitest";
2+
import * as Schema from "effect/Schema";
23
import { Tool } from "effect/ai";
34

45
import { PreviewToolkit } from "./tools.ts";
@@ -36,3 +37,17 @@ it("exports provider-compatible object schemas", () => {
3637
).toBeDefined();
3738
}
3839
});
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‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
import {
2+
BrowserNavigationTarget,
23
OrchestratorMcpFailure,
34
ToolActivityIcon,
45
PreviewAutomationActInput,
@@ -62,11 +63,17 @@ const PreviewStatusTool = Tool.make("preview_status", {
6263
.annotate(Tool.Destructive, false)
6364
.annotate(Tool.Idempotent, true);
6465

66+
// `url` already covers websites, so open only adds the dev-server target.
67+
const EnvironmentPortTarget = BrowserNavigationTarget.members[1];
68+
6569
const PreviewOpenTool = browserTool(
6670
Tool.make("preview_open", {
6771
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+
),
7077
success: PreviewAutomationStatus,
7178
failure: PreviewToolFailure,
7279
dependencies,
Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
22
"claudeSystemAppendBytes": 5153,
33
"codexAdditionalContextBytes": 6883,
4-
"mcpToolListJsonBytes": 47074
4+
"mcpToolListJsonBytes": 47538
55
}

‎evals/mcp-tool-use/cases/visual-preview.ndjson‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,3 +27,4 @@
2727
{"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"]}}
2828
{"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"]}}
2929
{"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‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -362,12 +362,15 @@ export const normalizeToolName = (name: string) => {
362362
? bare.slice(T3_PREFIX.length)
363363
: (CODEX_NAMES[bare] ?? bare.slice(bare.lastIndexOf("_") + 1));
364364
};
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)
367369
? { ...input, command: input.command ?? input.cmd }
368370
: typeof input === "string" && normalizeToolName(name) === "Edit"
369371
? { patch: input }
370372
: input;
373+
};
371374

372375
// McpHttpServer advertises each tool's JSON schema, and Claude Code passes the MCP name,
373376
// description, and schema through unchanged.
@@ -384,6 +387,15 @@ const t3SourceTools: ReadonlyArray<Tool.Any> = [
384387
DeviceToolkit,
385388
HtmlToolkit,
386389
].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+
);
387399
const t3Tools: ReadonlyArray<ApiTool> = t3SourceTools.map((tool) => ({
388400
name: `${T3_PREFIX}${tool.name}`,
389401
description: Tool.getDescription(tool) ?? "",

0 commit comments

Comments
 (0)