@agent-native/core 0.22.18 → 0.22.20

package/docs/content/mcp-protocol.md

@@ -78,13 +78,39 @@ If an action declares `mcpApp`, the server also advertises the official MCP Apps
 
 `embedApp()` is the low-level URL-first MCP App helper. It reads the action
 result's open link, asks the app-only `create_embed_session` tool to mint a
-route-scoped session, then loads the resulting route in an iframe. For normal
-action authoring, use `embedRoute()` when the action's `link` and `mcpApp`
-should come from the same pure route builder. The route itself should derive
-state from the URL and normal app data fetching.
-
-The bridge between the wrapper and the embedded route uses Agent-Native
-postMessage types:
+route-scoped session, then launches the resulting app route. ChatGPT and hosts
+that allow direct route hydration launch the same signed app URL, but ChatGPT
+keeps it in a controlled route iframe to avoid a web-sandbox auto-height
+feedback loop. Claude web currently proxies MCP App content under
+`claudemcpcontent.com`; direct route navigation can fetch app HTML there
+without reliably running the framework bootstrap, and a second nested iframe is
+easy for the host to block. For Claude, `embedApp()` fetches the signed app
+HTML and mounts the real route document into the existing MCP resource frame,
+with app-origin requests routed back to the original app using the embed token.
+For normal action authoring, use `embedRoute()` when the action's
+`link` and `mcpApp` should come from the same pure route builder. The route
+itself should derive state from the URL and normal app data fetching.
+
+The outer MCP resource reports a bounded inline height to the host and the app
+route scrolls internally. Do not rely on host auto-resize measuring the full
+document; in ChatGPT and Claude this can make a normal full-app route appear as
+a huge chat artifact. Host conversations also keep already-rendered iframes, so
+after changing the resource shell or `ui://` version, test a fresh tool call
+rather than re-measuring an old frame.
+
+Default direct embeds talk to the MCP Apps host through standard `ui/*`
+JSON-RPC messages:
+
+| Type                      | Payload shape                      |
+| ------------------------- | ---------------------------------- |
+| `ui/update-model-context` | `{ content?, structuredContent? }` |
+| `ui/message`              | `{ role: "user", content }`        |
+| `ui/open-link`            | `{ url }`                          |
+| `ui/request-display-mode` | `{ mode }`                         |
+
+The ChatGPT controlled-frame path and any explicit `embedMode: "iframe"` /
+`renderMode: "iframe"` diagnostic path use the wrapper-to-route postMessage
+relay:
 
 | Direction       | Type                                     | Payload shape                                 |
 | --------------- | ---------------------------------------- | --------------------------------------------- |
@@ -94,8 +120,17 @@ postMessage types:
 | route → wrapper | `agentNative.mcpHost.requestDisplayMode` | `{ requestId, mode }`                         |
 | wrapper → route | `agentNative.mcpHost.response`           | `{ requestId, ok, result?, error? }`          |
 
+`embedApp()` includes the MCP request origin in the resource CSP so the
+launcher can fetch and, when explicitly requested, frame the signed first-party
+route. Pass additional `frameDomains` only for custom third-party frames.
+
 Host-mediated open links keep the iframe from choosing its own browser target.
 Model context updates are opt-in and hidden from the user-facing transcript.
+`ui/message` is the portable way for an embedded app button to ask the host to
+post a visible user message and continue the chat. In agent-native routes,
+`sendToAgentChat()` uses `ui/update-model-context` plus `ui/message` when
+called from a submitted MCP App embed, while `submit: false` remains an
+in-route draft/prefill path.
 Display mode requests are best-effort: a host can honor, ignore, or reject the
 request. Embedded routes must remain functional in the default inline mode.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.22.18",
+  "version": "0.22.20",
   "type": "module",
   "description": "Framework for agent-native application development — where AI agents and UI share state via files",
   "license": "MIT",