[Bug]: void preview tools emit `structuredContent: null`, which violates the MCP spec and makes every client report a failure

[JorgeMenaDev]

Before submitting

• I searched existing issues and did not find a duplicate.
• I included enough detail to reproduce or investigate the problem.

Area

apps/server

Summary

The five void-returning preview tools declare success: Schema.Null. That produces an outputSchema of {"type": "null"} and a response with structuredContent: null.

Per the MCP spec, structuredContent is "returned as a JSON object", and "Servers MUST provide structured results that conform to this schema. Clients SHOULD validate structured results against this schema." (spec 2025-06-18, Tools § Structured Content / Output Schema)

null is not a JSON object, so conformant clients reject the response:

MCP server "t3-code" returned a malformed result that failed schema validation: [
  {
    "expected": "record",
    "code": "invalid_type",
    "path": ["structuredContent"],
    "message": "Invalid input: expected record, received null"
  }
]

The damaging part: the underlying action actually succeeds. The agent is told it failed. In a visible tab, preview_click navigates the page correctly and still reports this error — so agents retry, conclude the browser tooling is broken, and abandon the lane. I watched two separate models do exactly that today before I traced it.

Affected tools

All five that .pipe(Effect.as(null)) in apps/server/src/mcp/toolkits/preview/handlers.ts and declare success: Schema.Null in tools.ts:

• preview_click (tools.ts:120)
• preview_type (tools.ts:131)
• preview_press (tools.ts:142)
• preview_scroll (tools.ts:153)
• preview_wait_for (tools.ts:175)

preview_evaluate declares success: Schema.Unknown and is unaffected in practice.

Steps to reproduce

1. Start T3 Code Desktop (reproduced on server 0.0.32-nightly.20260806.1015).
2. From any MCP client, preview_open on https://example.com — succeeds.
3. Call preview_click with locator: "role=link[name='Learn more']" — returns the schema error above.
4. Call preview_evaluate with location.href — the page has navigated to https://www.iana.org/help/example-domains. The click worked.
5. preview_scroll with deltaY: 100 — same error, confirming it is the whole Schema.Null class and not click-specific.

Reproduced across

3 models, 4 threads, 2 independent MCP clients (Claude Code and OpenCode), every targeting style — Playwright locator, legacy selector, and raw x/y coordinates:

Client	Model	Result
OpenCode	opencode-go/deepseek-v4-flash	schema error, 4 targeting styles
OpenCode	opencode-go/grok-4.5	schema error, 3 targeting styles
Claude Code	claude-opus-5	schema error, click + scroll, visible and hidden tabs

Expected

Void tools return an empty JSON object rather than null — e.g. success: Schema.Struct({}), or a small record such as { ok: true } if a positive signal is preferred. Either conforms to the spec and lets clients see the success the server already achieved.

Related

• [Bug]: preview_click returns success in hidden tabs but does not dispatch the click #3717 — preview_click does not dispatch in hidden tabs. Separate root cause, and I can confirm it independently: in a tab opened with open: false, the click does not navigate; in a visible tab it does. The two bugs compound — in a hidden tab the click both fails to fire and reports a schema error.
• [Bug]: preview_snapshot can fail or time out on loaded pages and leave tab automation unusable #3713 — preview_snapshot failures. Also worth noting for triage: snapshot fails with the opaque "Preview snapshot failed." in a hidden tab but works perfectly in a visible one, returning the PNG plus the accessibility tree. previewSnapshotFailure in apps/server/src/mcp/McpHttpServer.ts:98 logs the real errorTag server-side but sends only that fixed string to the client, so callers cannot tell a visibility problem from a real capture failure.

[JorgeMenaDev]

Re-confirmed on 0.0.32-nightly.20260807.1022 (today's nightly) — unchanged:

preview_click {"tabId": "tab_2", "locator": "role=link[name='Learn more']"}
→ MCP server "t3-code" returned a malformed result that failed schema validation:
  [{"expected":"record","code":"invalid_type","path":["structuredContent"],
    "message":"Invalid input: expected record, received null"}]

Real-world impact, observed today: three separate agent runs hit this. Two concluded the browser tooling was broken and abandoned the task entirely — the schema error reads like a hard failure, so the agent stops rather than checking whether the action landed. The third only succeeded because it had been told in advance to verify with preview_evaluate and ignore the error.

So the cost isn't just a noisy log line: it silently removes browser automation from any agent that trusts its tool results, which is all of them by default.

Related: #3717 (hidden-tab clicks don't dispatch) and #3713 (snapshot needs a visible tab). All three compound in background agent threads.

— Jorge Mena