feat: Dynamic View Content SDK support (types, helpers, example)

[liady]

Note

Stacked on #699 (the spec change) - this PR's base is liady/dynamic-view-content-spec, so the diff here shows only the SDK implementation. Retarget to main once #699 merges.

SDK implementation of Dynamic View Content: typed presentation payloads carried in tool results as embedded resource content blocks marked with _meta.ui.content, forwarded by hosts to the tool's predeclared renderer view.

Three commits, layered:

1. Types + schemas (src/spec.types.ts, regenerated src/generated/)

• McpUiResourceMeta.contentMimeTypes?: string[] - the renderer declaration
• McpUiContentBlockMeta - the _meta.ui.content marker interface (optional rendererUri for future multi-view results)
• McpUiClientCapabilities.contentMimeTypes?: string[] - the extension setting (supports the ["*"] opaque-forwarding wildcard)
• Zod schemas regenerated from the spec types; re-exports through src/types.ts

Notably, App and AppBridge need no behavioral changes: both already transport CallToolResult opaquely, so the payload channel exists - the spec constrains hosts from filtering it and keeps payloads out of model context.

2. Helpers (src/ui-content.ts, re-exported from the app, app-bridge, and server entry points)

• createViewContentBlock() - server-side: builds a correctly-marked embedded resource block; validates text/blob exclusivity and rejects ui:// payload URIs (reserved for renderable UI resources)
• getViewContentBlocks() / isViewContentBlock() - view-side: extracts marked payloads from tool results in array order, with mimeType/rendererUri filters; works on both ontoolresult params and callServerTool() results
• supportsContentMimeType() - capability check honoring the ["*"] wildcard, for servers gating renderer-pattern tools and hosts type-filtering payloads

With unit tests and type-checked JSDoc examples (ui-content.examples.ts companions, synced via sync:snippets).

3. Worked example (examples/dynamic-content-server)

A generic renderer view with no domain-specific presentation logic, driven end-to-end by declarative payloads:

• The renderer resource declares contentMimeTypes in its _meta.ui
• search-flights (model-visible) returns a text fallback for model context plus a marked payload built with createViewContentBlock()
• select-flight (visibility: ["app"], hidden from the model) is called by the renderer's event bridge - payload-level button actions become tools/call requests, and responses carry the next payload, closing the interactive loop
• Payloads are treated as untrusted input: DOM is built with createElement/textContent only, never innerHTML of payload-derived strings

The example uses a deliberately tiny stand-in format (application/vnd.example.dynamic-ui+json, defined in dynamic-ui.ts) so the plumbing stays easy to follow - the pattern is identical for real generative UI formats like application/a2ui+json.

Testing

• 14 new unit tests for the helpers + regenerated schema round-trip tests (389 total passing)
• E2E: the example is wired into tests/e2e/servers.spec.ts, exercising the full pipeline (server → marked embedded resource → host forwards via sendToolResult → renderer extracts and renders). Golden screenshot generated and verified in the CI-identical Linux Playwright container.
• typedoc --treatValidationWarningsAsErrors clean

Also includes a small basic-host fix discovered while testing: res.sendFile with an absolute path applies express's dotfiles: "ignore" rule to every path segment, 404ing sandbox.html in any checkout under a dot-directory (e.g. git worktrees under .claude/worktrees); passing the file relative to a root fixes it. package-lock.json picks up the new workspace entry plus an npm dedup of nested @types/node/undici-types entries.

Follow-ups (out of scope here)

• basic-host advertising contentMimeTypes in its client capabilities, to model the negotiation as a reference host (forwarding already works unmodified today)
• Adding the example to the README grid (grid-cell.png + table placement)
• Optional A2UI-specific renderer/SDK guidance (payload semantics, userAction ↔ tool-call mapping conventions) layered on this generic mechanism

🤖 Generated with Claude Code

[github-actions]

📖 Docs Preview Deployed

Preview (stable)	https://pr-700.mcp-ext-apps-docs-preview.pages.dev
This commit	https://f4393655.mcp-ext-apps-docs-preview.pages.dev
Commit	269fa40

Includes drafts and future-dated posts. All pages served with noindex, nofollow — search engines will not crawl this preview.

[pkg-pr-new]

Open in StackBlitz

@modelcontextprotocol/ext-apps

npm i https://pkg.pr.new/@modelcontextprotocol/ext-apps@700

@modelcontextprotocol/server-basic-preact

npm i https://pkg.pr.new/@modelcontextprotocol/server-basic-preact@700

@modelcontextprotocol/server-basic-react

npm i https://pkg.pr.new/@modelcontextprotocol/server-basic-react@700

@modelcontextprotocol/server-basic-solid

npm i https://pkg.pr.new/@modelcontextprotocol/server-basic-solid@700

@modelcontextprotocol/server-basic-svelte

npm i https://pkg.pr.new/@modelcontextprotocol/server-basic-svelte@700

@modelcontextprotocol/server-basic-vanillajs

npm i https://pkg.pr.new/@modelcontextprotocol/server-basic-vanillajs@700

@modelcontextprotocol/server-basic-vue

npm i https://pkg.pr.new/@modelcontextprotocol/server-basic-vue@700

@modelcontextprotocol/server-budget-allocator

npm i https://pkg.pr.new/@modelcontextprotocol/server-budget-allocator@700

@modelcontextprotocol/server-cohort-heatmap

npm i https://pkg.pr.new/@modelcontextprotocol/server-cohort-heatmap@700

@modelcontextprotocol/server-customer-segmentation

npm i https://pkg.pr.new/@modelcontextprotocol/server-customer-segmentation@700

@modelcontextprotocol/server-debug

npm i https://pkg.pr.new/@modelcontextprotocol/server-debug@700

@modelcontextprotocol/server-lazy-auth

npm i https://pkg.pr.new/@modelcontextprotocol/server-lazy-auth@700

@modelcontextprotocol/server-map

npm i https://pkg.pr.new/@modelcontextprotocol/server-map@700

@modelcontextprotocol/server-pdf

npm i https://pkg.pr.new/@modelcontextprotocol/server-pdf@700

@modelcontextprotocol/server-scenario-modeler

npm i https://pkg.pr.new/@modelcontextprotocol/server-scenario-modeler@700

@modelcontextprotocol/server-shadertoy

npm i https://pkg.pr.new/@modelcontextprotocol/server-shadertoy@700

@modelcontextprotocol/server-sheet-music

npm i https://pkg.pr.new/@modelcontextprotocol/server-sheet-music@700

@modelcontextprotocol/server-system-monitor

npm i https://pkg.pr.new/@modelcontextprotocol/server-system-monitor@700

@modelcontextprotocol/server-threejs

npm i https://pkg.pr.new/@modelcontextprotocol/server-threejs@700

@modelcontextprotocol/server-transcript

npm i https://pkg.pr.new/@modelcontextprotocol/server-transcript@700

@modelcontextprotocol/server-video-resource

npm i https://pkg.pr.new/@modelcontextprotocol/server-video-resource@700

@modelcontextprotocol/server-wiki-explorer

npm i https://pkg.pr.new/@modelcontextprotocol/server-wiki-explorer@700

commit: 2cdc509