@devries-cameron20 / t3code Mirror · read-only / commits / 6328c84722
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 22, 08:15 UTC

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) ?? "",