@guuey/mcp-apps-host
The Host role of MCP Apps (SEP-1865) for guuey's chat surfaces — and for any host that mounts MCP Apps views.
The spec's constant refrain is "Host MUST …". This package implements that role's client-side narrowing and mount contract:
- View-mount dispatch (
toolResultViewMount,snapshotViewMount): one narrowing that answers "what, if anything, does this block mount?" across the UI channels a transcript carries — an inlineui://resource payload, or a bareui://locator (fromuiData.resourceUri, elsestructuredContent.resourceUri). Everyui://producer, ggui'sggui_renderincluded, is a locator producer: the ggui vendor fast-path retired 2026-08-16 (guuey#209) once the pod's live read door and ggui's read-time mint made the spec's read path strictly fresher than any inlined bootstrap. Its helpers stay exported one minor as@deprecated. - Locator rehydration: a persisted
ui://locator remounts by a fresh, authenticatedresources/readof the uri — the spec-consistent template fetch (the spec itself defers persistence/restoration; a full remount additionally owes the Viewui/notifications/tool-input+ its tool result) — never by replaying stored mount material. The read transport is injected (UiResourceReader); the host owns auth and user-ownership enforcement, and a deny is byte-identical to a miss. - Generic reader assembly (
createMcpUiResourceReader): hand it one host-ownedresources/readcallable (a raw MCP client, an authenticated proxy — no SDK dependency imposed) and get aUiResourceReaderback, with the trust rules built in: deny == miss == placeholder, and the sandbox channel derives from the requested locator uri, never the response (uiResourceChannel).@guuey/agent-client'screateUiResourceReaderis this assembly over guuey's platform proxy. - Sandbox-trust channels (
ViewMountChannel): which sandbox host page a payload may mount in, until per-resource declared-CSP construction lands. - The host itself (
attachViewHost, and<GuueyView>from@guuey/mcp-apps-host/react): a spec-following view opens with theui/initializeApp handshake and blocks on it — mount material alone renders a blank frame forever.attachViewHost(iframe, config)answers that handshake for any embedder (framework-agnostic, one call); the React component additionally owns iframe creation, lifecycle, and the safe sandbox default (allow-scriptswithoutallow-same-origin— with it, agent-generated HTML would run as your origin — plusallow="clipboard-write"so generated copy buttons work). Configurable where a host genuinely varies:hostCapabilities(default{}— advertise only what you implement), an optionaltools/callrelay hook (privilege boundary, default off; pair withcreateMcpUiActionRelay),hostContext, and the negotiation timeout. While a frame negotiates, the state is labeled (negotiating/connected/no-handshake), never a blank page. - Resolved-only mount walk (
resolveViewMount): chain it offtoolResultViewMount/snapshotViewMountwith your reader and render onlyResolvedViewMounts — the locator round-trip is folded in.
Vendor-neutral by principle: ggui's MCP Apps run on any spec-following host (claude.ai, chatgpt.com, guuey) precisely because they follow the spec; this package is guuey's OSS host-side support for the same spec.
Conformance status and roadmap: docs/development/mcp-apps-host-conformance.md
in the guuey monorepo (guuey#123).
Support
Questions and help: the guuey community on Discord — https://guuey.com/discord. Bugs and feature requests: https://github.com/withguuey/guuey-sdks/issues.