Tracking: re-implement PR #1510 (spec-conformant Apps host + programmatic review path) as scoped issues #1579

Background

PR #1510 (@tobinsouth) is a valuable roll-up of gaps hit while using the inspector as the reference host for testing widgets against the @modelcontextprotocol/ext-apps spec — plus a CLI/deep-link path for programmatic review. At +6,551/−453 across 61 files it touches a large amount of code we already have confidence in ahead of the v2 beta, so rather than merging it wholesale we are decomposing it into scoped issues and re-implementing each one deliberately, using the PR's diff (head 33fac3f) as the reference implementation. Each sub-issue links the relevant files/symbols in the PR.

The PR stays open for now as the reference.

Sub-issues

Wave 1 — Foundations (no interdependencies; all 10 can be worked in parallel, e.g. with concurrent subagents — disjoint file sets)

• core: add AppInfo + extractAppInfo() to core/mcp/apps.ts #1556 core: AppInfo + extractAppInfo() (core/mcp/apps.ts)
• test-servers: mcp_app_demo preset + _meta support on tool/resource definitions #1557 test-servers: mcp_app_demo preset + _meta plumbing
• web: sandbox CSP builder library (lib/sandbox-csp.ts) #1558 web: sandbox CSP builder library (lib/sandbox-csp.ts)
• web: extract hostContext utilities for the Apps host (AppRenderer/hostContext.ts) #1559 web: hostContext utilities (AppRenderer/hostContext.ts)
• web: downloadFile.ts enhancements (downloadBlob, fileNameFromUri, isHttpUrl) #1560 web: downloadFile.ts enhancements
• core: redact sensitive headers in the fetch log #1561 core: redact sensitive headers in the fetch log
• auth hardening: generateOAuthState requires WebCrypto; OAuth callback rejects unparseable state #1562 auth hardening: generateOAuthState WebCrypto-only; callback rejects bad state
• core: honor HTTPS_PROXY/HTTP_PROXY/NO_PROXY in the Node transport #1563 core: HTTPS_PROXY/HTTP_PROXY/NO_PROXY support in the Node transport
• cli: exit-code map + structured JSON error envelopes #1564 cli: exit-code map + structured JSON error envelopes
• Web: migrate auth store to shared /store API (RemoteOAuthStorage parity with TUI/CLI) #1548 web: OAuth storage parity via RemoteOAuthStorage + async hydration (pre-existing issue — PR feat(web/apps): spec-conformant Apps host + CLI/deep-link path for programmatic review #1510 contains a complete reference implementation)
• core: redact sensitive fields in fetch-log request/response bodies + URL query strings #1593 core: redact sensitive fields in the fetch-log bodies + URL query strings (follow-up surfaced by the feat(core): redact sensitive headers in the fetch log #1585 review — header redaction alone still leaks client_secret/code/refresh_token/access_token in OAuth request/response bodies & URLs; to be done this wave, tracked in the MCP Apps Extension column)
• test-infra: gate clients/web/src/lib/** under the vitest coverage include globs #1594 test-infra: gate clients/web/src/lib/** under the vitest coverage include globs (follow-up surfaced by the feat(web): downloadFile.ts enhancements (downloadBlob, fileNameFromUri, isHttpUrl) #1586/feat(web): add sandbox CSP builder library (closes #1558) #1588/Web: migrate auth store to shared /store API (RemoteOAuthStorage parity with TUI/CLI) #1592 smoke-audit — src/lib is absent from coverage.include, so downloadFile.ts/sandbox-csp.ts/remoteOAuthStorage.ts aren't gate-enforced; feat(web): add sandbox CSP builder library (closes #1558) #1588 worked around it per-file; Backlog — blocked until the Wave-1 src/lib PRs merge)
• test-stability: eliminate timeout flakiness in the web test suite (zero-flake requirement) #1596 test-stability: eliminate timeout flakiness in the web test suite (follow-up surfaced across the Wave-1 smoke-audit — test:coverage intermittently fails on ServerConfigModal/InspectorView/PromptArgumentsForm/import-modals/useServers/inspectorClient under instrumented load; zero-flake requirement; MCP Apps Extension column)

Wave 2 — Apps host lane (sequential within the lane — shared createAppBridgeFactory.ts / AppRenderer.tsx / AppsScreen.tsx; runs in parallel with Wave 3)

• web: sandbox hardening — opaque-origin inner frame, srcdoc-only delivery, frame-ancestors CSP #1565 web: sandbox hardening — opaque-origin inner frame, srcdoc-only, frame-ancestors
• web: enforce per-app _meta.ui.csp in the app bridge + surface resource-read failures #1566 web: enforce per-app _meta.ui.csp + surface resource-read failures (needs web: sandbox CSP builder library (lib/sandbox-csp.ts) #1558, web: sandbox hardening — opaque-origin inner frame, srcdoc-only delivery, frame-ancestors CSP #1565)
• web: full hostContext delivery + live host-context-changed updates #1567 web: full hostContext delivery + live host-context-changed (needs web: extract hostContext utilities for the Apps host (AppRenderer/hostContext.ts) #1559, web: enforce per-app _meta.ui.csp in the app bridge + surface resource-read failures #1566)
• web: honor ui/notifications/size-changed and ui/request-display-mode #1568 web: size-changed + request-display-mode (needs web: full hostContext delivery + live host-context-changed updates #1567)
• web: honor ui/download-file with confirmation and http(s) allowlist #1569 web: ui/download-file (needs web: downloadFile.ts enhancements (downloadBlob, fileNameFromUri, isHttpUrl) #1560, web: enforce per-app _meta.ui.csp in the app bridge + surface resource-read failures #1566)
• web: surface ui/message and app logging in panels below the running app #1570 web: ui/message + App-logs panels (needs web: enforce per-app _meta.ui.csp in the app bridge + surface resource-read failures #1566)
• web: stage partial input — replay tool-input-partial before final tool input #1571 web: stage partial input (needs web: enforce per-app _meta.ui.csp in the app bridge + surface resource-read failures #1566)
• web: app lifecycle status + machine-readable data attributes on the Apps screen #1572 web: app lifecycle status + machine-readable data attributes (needs web: enforce per-app _meta.ui.csp in the app bridge + surface resource-read failures #1566)

Wave 3 — CLI lane (sequential within the lane — shared cli.ts; runs in parallel with Wave 2)

• cli: programmatic ergonomics — --method initialize, --tool-args-json, --connect-timeout, env-var fixes #1573 cli: programmatic ergonomics — --method initialize, --tool-args-json, --connect-timeout, env-var fixes (needs cli: exit-code map + structured JSON error envelopes #1564)
• cli: --app-info probe + --format json envelope #1574 cli: --app-info probe + --format json envelope (needs core: add AppInfo + extractAppInfo() to core/mcp/apps.ts #1556, test-servers: mcp_app_demo preset + _meta support on tool/resource definitions #1557, cli: exit-code map + structured JSON error envelopes #1564, cli: programmatic ergonomics — --method initialize, --tool-args-json, --connect-timeout, env-var fixes #1573)
• cli: stored-auth suite — --use-stored-auth, --wait-for-auth, --list-stored-auth, --print-handoff #1575 cli: stored-auth suite (needs cli: exit-code map + structured JSON error envelopes #1564, Web: migrate auth store to shared /store API (RemoteOAuthStorage parity with TUI/CLI) #1548; deep-link format from web: deep-link auto-connect (?serverUrl&transport&autoConnect) + machine-readable connection status #1576)

Wave 4 — Integration (after both lanes)

• web: deep-link auto-connect (?serverUrl&transport&autoConnect) + machine-readable connection status #1576 web: deep-link auto-connect + machine-readable connection status (needs Web: migrate auth store to shared /store API (RemoteOAuthStorage parity with TUI/CLI) #1548; refs Support ?autoConnect=true query param to connect on page load #1183)
• web: deep-link openApp/appArgs/autoOpen — pre-select and pre-fill an app from the URL #1577 web: deep-link openApp/appArgs/autoOpen (needs web: deep-link auto-connect (?serverUrl&transport&autoConnect) + machine-readable connection status #1576, web: app lifecycle status + machine-readable data attributes on the Apps screen #1572)
• docs: MCP App review recipe + README updates for new CLI flags, deep-links, and proxy support #1578 docs: MCP App review recipe + README updates (last)
• cli: reconcile --print-handoff deep-link with #1576 canonical format #1666 cli: reconcile --print-handoff deep-link with the web: deep-link auto-connect (?serverUrl&transport&autoConnect) + machine-readable connection status #1576 canonical format (needs web: deep-link auto-connect (?serverUrl&transport&autoConnect) + machine-readable connection status #1576; follow-up surfaced by the cli: Wave 3 — programmatic review path (rollup of #1573–#1575) #1655 review — the --print-handoff deepLink shape shipped in cli: stored-auth suite — --use-stored-auth, --wait-for-auth, --list-stored-auth, --print-handoff #1575 as an interim TODO(#1576))
• cli: stored-auth injection should honor refresh_token, not just access_token #1665 cli: stored-auth injection should honor refresh_token, not just access_token (follow-up surfaced by the cli: Wave 3 — programmatic review path (rollup of #1573–#1575) #1655 review — cli: stored-auth suite — --use-stored-auth, --wait-for-auth, --list-stored-auth, --print-handoff #1575 intentionally deferred the SDK refresh-grant path; related: cli: stored-auth injection should honor refresh_token, not just access_token #1665, Requests to oauth the token endpoint with refresh_token grant type set invalid content-type header #1160)

Dependency graph

Wave 1 (parallel):  1556  1557  1558  1559  1560  1561  1562  1563  1564  1548
                      │     │     │     │     │                       │     │
     ┌────────────────┘     │     │     │     │                       │     │
     │   Apps host lane     │     │     │     │       CLI lane        │     │
     │                      │   1565    │     │                     1573    │
     │                      │     │     │     │                       │     │
     │                      │   1566 ◄──┼─────┼──── (csp lib 1558)    │     │
     │                      │   ┌─┼──┬──┴──┬──┘                       │     │
     │                      │ 1570│1571  1569                       1574 ◄──┼── 1556, 1557
     │                      │     │                                   │     │
     │                      │   1567 (hostContext 1559)             1575 ◄──┴── 1548
     │                      │     │                                   │
     │                      │   1568                                  │
     │                      │   1572 ──────────────┐                  │
     └──────────────────────┴──────────────────────┼──────────────────┘
                                        Wave 4:  1576 ──► 1577 ──► 1578

(1572 feeds 1577; 1576 also informs 1575's --print-handoff link format.)

Parallelization with subagents

• Wave 1: all ten items touch disjoint files — safe to run as concurrent subagents/branches.
• Waves 2 + 3: two independent lanes (web Apps host vs CLI) — one agent per lane in parallel. Within each lane work sequentially: Wave 2 items all edit AppRenderer.tsx/AppsScreen.tsx/createAppBridgeFactory.ts, Wave 3 items all edit cli.ts, so concurrent edits would conflict.
• Wave 4: sequential (#1576 → #1577 → #1578).

Process notes

• Every sub-issue carries a "Reference implementation (PR feat(web/apps): spec-conformant Apps host + CLI/deep-link path for programmatic review #1510)" section with permalinks into 33fac3f — re-implement informed by the contribution, don't cherry-pick blindly; each PR must meet AGENTS.md rules (per-file ≥90 coverage on all four dimensions, Mantine theme/withProps rules, README updates, no any).
• Standard workflow per AGENTS.md: move the item to In Progress, feature branch, PR against v2/main with the v2 label, In Review.