feat(apps): Integrate AppRenderer from @mcp-ui/client SDK

[aharvard]

Summary

Refactors McpAppRenderer to use the @mcp-ui/client SDK's AppRenderer component, replacing the custom iframe/sandbox bridge implementation. This significantly simplifies the codebase while adding proper support for MCP Apps spec features.

Changes

Major Refactor:

• Replace custom useSandboxBridge hook with @mcp-ui/client's AppRenderer component
• Remove useSandboxBridge.ts and utils.ts (no longer needed)
• Update sandbox proxy message format to match @mcp-ui/client protocol

New Features:

• Add displayMode prop (inline, fullscreen, pip, standalone) replacing boolean fullscreen
• Pass structuredContent in tool results per MCP Apps spec
• Implement full hostContext properties: locale, timeZone, userAgent, platform, deviceCapabilities
• Smart width handling: respect explicit app-declared width, fluid (100%) when not provided

Type Improvements:

• Add ToolResult type for tool execution results
• Add GooseDisplayMode type for Goose-specific display modes
• Add SandboxPermissions type for iframe sandbox attributes
• Use SDK types (ToolInput, ToolInputPartial, ToolCancelled) directly from @modelcontextprotocol/ext-apps
• Remove unused custom types

Code Quality:

• Add comprehensive JSDoc comments throughout
• Reorganize into logical sections with clear separation of concerns
• Simplify error/loading/content rendering with renderContent() helper

Follow-up TODOs

• Add onFallbackRequest handler when SDK supports it (mcp-ui#176) - needed for sampling/createMessage
• Add toolInfo to hostContext
• Add styles (CSS variables) to hostContext
• Add containerDimensions to hostContext (depends on displayMode)
• Add hostInfo and hostCapabilities props when available in client SDK (mcp-ui#175)

Testing

• TypeScript compiles with no errors
• Manual testing of MCP Apps in inline and standalone modes

[Copilot]

Pull request overview

Copilot reviewed 11 out of 12 changed files in this pull request and generated 2 comments.

Files not reviewed (1)

• ui/desktop/package-lock.json: Language not supported

Comments suppressed due to low confidence (1)

ui/desktop/src/components/ToolCallWithResponse.tsx:129

• toolResult passed to McpAppRenderer is currently the raw CallToolResponse (snake_case structured_content), so McpAppRenderer never forwards structuredContent to the SDK; convert the result here to the ToolResult shape expected by McpAppRenderer (including mapping structured_content -> structuredContent).

  const toolResult = useMemo(() => {
    if (!toolResponse) {
      return undefined;
    }
    const resultWithMeta = toolResponse.toolResult as ToolResultWithMeta;
    if (resultWithMeta?.status === 'success' && resultWithMeta.value) {
      return resultWithMeta.value;
    }
    return undefined;

[DOsinga]

not part of this change, but what ?

[aharvard]

Good catch. We don't need to memoize this. The toolRequest should be stable.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 12 changed files in this pull request and generated 4 comments.

Files not reviewed (1)

• ui/desktop/package-lock.json: Language not supported

[Copilot]

The cachedHtml dependency causes unnecessary refetches. When cachedHtml changes (e.g., from undefined to a value), the effect runs again even though resourceUri, extensionName, and sessionId haven't changed. This can trigger duplicate network requests. Remove cachedHtml from the dependency array since it's only used as a fallback value within the effect, not as a trigger.

Suggested change

	}, [resourceUri, extensionName, sessionId, cachedHtml]);
	}, [resourceUri, extensionName, sessionId]);

[aharvard]

Disagree — cachedHtml is used as a fallback inside the effect (if the fetch fails or returns no content). If it arrives after the initial render, we want the effect to re-run so the fallback is available. In practice it's a stable prop set once, so this doesn't cause extra fetches.

[aharvard]

Disagreed — it's a fallback used inside the effect, and it's a stable prop in practice

[Copilot]

Unsafe type assertion. The cast as unknown as CallToolResult['content'] bypasses TypeScript's type safety. If the wire format doesn't match CallToolResult.content, this will cause runtime errors in the SDK. Consider creating a proper type guard or validation function to verify the structure before passing to AppRenderer.

[aharvard]

Acknowledged — the cast is intentional and documented in the comment above it. The wire format from rmcp uses #[serde(tag = "type")] which produces the same shape as CallToolResult.content, but our generated TS types don't reflect the discriminator. A runtime validation function would be nice but is out of scope for this PR.

[aharvard]

Acknowledged — cast is intentional, wire format matches, documented in code

[Copilot]

Unsafe type assertion. The cast as unknown as CallToolResult['content'] bypasses TypeScript's type safety. If the wire format from toolResult.content doesn't match the SDK's expected structure, this will cause runtime errors. Consider validating the structure or creating a conversion function.

Suggested change

	return {
	content: toolResult.content as unknown as CallToolResult['content'],
	structuredContent: toolResult.structuredContent as { [key: string]: unknown } | undefined,
	};
	}, [toolResult]);
	const normalizedContent = normalizeCallToolResultContent(toolResult.content);
	if (!normalizedContent) {
	// If the content shape is unexpected, avoid passing malformed data to the AppRenderer.
	return undefined;
	}
	return {
	content: normalizedContent,
	structuredContent: toolResult.structuredContent as { [key: string]: unknown } | undefined,
	};
	}, [toolResult]);
	function normalizeCallToolResultContent(
	content: unknown
	): CallToolResult['content'] | undefined {
	if (
	Array.isArray(content) &&
	content.every(
	(item) =>
	item !== null &&
	typeof item === 'object' &&
	'type' in item &&
	typeof (item as { type?: unknown }).type === 'string'
	)
	) {
	// At this point we've established a minimal structural match with the expected content format.
	return content as CallToolResult['content'];
	}
	console.warn(
	'Received toolResult.content with unexpected shape; dropping content for MCP app rendering.'
	);
	return undefined;
	}

[aharvard]

Same as above — the cast is intentional. The rmcp wire format matches CallToolResult.content structurally but our generated types don't capture the serde discriminator. A proper validation layer is a good idea for a follow-up.

[aharvard]

Same — intentional cast, follow-up for validation layer

[Copilot]

Non-null assertion on potentially null value. If isReady is true but sandboxConfig is still null (which shouldn't happen but isn't prevented by the type system), this will cause a runtime error. Add a safety check: if (!sandboxConfig) return null; before rendering AppRenderer.

Suggested change

	return (
	<AppRenderer
	sandbox={sandboxConfig!}
	if (!sandboxConfig) {
	return null;
	}
	return (
	<AppRenderer
	sandbox={sandboxConfig}

[aharvard]

Good call — replaced the ! assertion with an explicit if (!sandboxConfig) return null; guard. The state machine guarantees it's non-null when isReady is true, but the guard is cheap insurance and cleaner.

[aharvard]

Agreed — replaced with if (!sandboxConfig) return null; guard

[Copilot]

Pull request overview

Copilot reviewed 11 out of 12 changed files in this pull request and generated 2 comments.

Files not reviewed (1)

• ui/desktop/package-lock.json: Language not supported

[Copilot]

The pendingCsp dependency can cause unnecessary effect re-runs. Since state.meta.csp is an object that may be recreated with the same values during state updates, pendingCsp will fail referential equality checks even when CSP hasn't meaningfully changed. This defeats the purpose of "Fetched only once" (line 243). Consider using only state.status in the dependency array—when status is 'loading_sandbox', the effect naturally has access to the current state.meta.csp via closure, and adding it as a dependency doesn't provide additional correctness.

Suggested change

	const pendingCsp = state.status === 'loading_sandbox' ? state.meta.csp : null;
	useEffect(() => {
	if (state.status !== 'loading_sandbox') return;
	fetchMcpAppProxyUrl(pendingCsp).then((url) => {
	if (url) {
	dispatch({ type: 'SANDBOX_READY', sandboxUrl: url, sandboxCsp: pendingCsp });
	} else {
	dispatch({ type: 'SANDBOX_FAILED', message: 'Failed to initialize sandbox proxy' });
	}
	});
	}, [state.status, pendingCsp]);
	useEffect(() => {
	if (state.status !== 'loading_sandbox') return;
	const currentCsp = state.meta.csp;
	fetchMcpAppProxyUrl(currentCsp).then((url) => {
	if (url) {
	dispatch({ type: 'SANDBOX_READY', sandboxUrl: url, sandboxCsp: currentCsp });
	} else {
	dispatch({ type: 'SANDBOX_FAILED', message: 'Failed to initialize sandbox proxy' });
	}
	});
	}, [state.status]);

[aharvard]

The effect already guards with if (state.status !== 'loading_sandbox') return, so it only fires once when entering that status. pendingCsp cannot change without state.status also changing, making re-runs a non-issue in practice.

The suggested fix moves CSP access inside the effect via closure, which would trigger the same ESLint react-hooks/exhaustive-deps warning we extracted pendingCsp to fix in the first place. Keeping it in the dep array is harmless and keeps the linter happy.

[Copilot]

Potential version conflict: @mcp-ui/client@6.0.0 depends on @modelcontextprotocol/ext-apps@^0.3.1, but the project directly installs @modelcontextprotocol/ext-apps@^1.0.1. This creates two separate copies of ext-apps in node_modules (see package-lock.json lines 3049-3091 and 3170-3211). If there are type incompatibilities between 0.3.1 and 1.0.1, runtime errors could occur when passing types between SDK components and your code. Verify that the SDK's 6.0.0 release is compatible with ext-apps 1.0.1, or align your direct dependency to match the SDK's requirement.

Suggested change

	"@modelcontextprotocol/ext-apps": "^1.0.1",
	"@modelcontextprotocol/ext-apps": "^0.3.1",

[aharvard]

Tracking that feedback here: MCP-UI-Org/mcp-ui#180 (comment)

[aharvard]

@DOsinga I slimmed down comments and set up a state machine for lifecycle

[michaelneale]

qwen3 is a bit flaky, I don't think is related. wonder if we should bump that to qwen3-coder-next as more modern

[aharvard]

claude sonnet and opus 5.5 were flaky in the re-run

[DOsinga]

we should probably rename these sine they are just for MCP-UI/APPS, no? can do in a follow up of course

[DOsinga]

nice! I saw somebody on github claim that fullscreen and standalone is actually the same thing? #7142 if so would be nice to address

[aharvard]

I'd like to address all displayMode options holistically, and that can be something that we prioritize sooner rather than later.

And yeah, I'm not certain if goose adds standalone on top of the core display modes, or if since goose is a desktop application, we should treat fullscreen as standalone. There might be some UX implications of how chat functionality would persist in fullscreen, whereas chat functionality might go away and standalone. We need to workshop this a little bit.