Merge remote-tracking branch 'upstream/main' into formatting-tweaks

Author: josemontespg

agent_sdks/kotlin/build.gradle.kts

@@ -73,8 +73,8 @@ val copySpecs by tasks.registering(Copy::class) {
   from(File(repoRoot, "specification/v0_9/json/common_types.json")) {
     into("com/google/a2ui/assets/0.9")
   }
-  from(File(repoRoot, "specification/v0_9/json/basic_catalog.json")) {
-    into("com/google/a2ui/assets/0.9")
+  from(File(repoRoot, "specification/v0_9/catalogs/basic/catalog.json")) {
+    into("com/google/a2ui/assets/0.9/catalogs/basic")
   }
 
   into(layout.buildDirectory.dir("generated/resources/specs"))

agent_sdks/kotlin/src/main/kotlin/com/google/a2ui/basic_catalog/BasicCatalogProvider.kt

@@ -38,7 +38,12 @@ class BundledCatalogProvider(private val version: A2uiVersion) : A2uiCatalogProv
   override fun load(): JsonObject {
     val specMap = BasicCatalog.BASIC_CATALOG_PATHS[version] ?: emptyMap()
     val relPath = specMap[A2uiConstants.CATALOG_SCHEMA_KEY] ?: ""
-    val filename = relPath.substringAfterLast('/')
+    val filename =
+      if (version == A2uiVersion.VERSION_0_9) {
+        relPath.substringAfter("specification/v0_9/")
+      } else {
+        relPath.substringAfterLast('/')
+      }
 
     val resource =
       SchemaResourceLoader.loadFromBundledResource(version.value, filename)?.toMutableMap()
@@ -75,7 +80,7 @@ object BasicCatalog {
             "specification/v0_8/json/standard_catalog_definition.json"
         ),
       A2uiVersion.VERSION_0_9 to
-        mapOf(A2uiConstants.CATALOG_SCHEMA_KEY to "specification/v0_9/json/basic_catalog.json"),
+        mapOf(A2uiConstants.CATALOG_SCHEMA_KEY to "specification/v0_9/catalogs/basic/catalog.json"),
     )
 
   /**

agent_sdks/kotlin/src/test/kotlin/com/google/a2ui/core/schema/ValidatorTest.kt

@@ -124,7 +124,7 @@ class ValidatorTest {
           """
       {
         "${"\$schema"}": "https://json-schema.org/draft/2020-12/schema",
-        "${"\$id"}": "https://a2ui.org/specification/v0_9/basic_catalog.json",
+        "${"\$id"}": "https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json",
         "catalogId": "basic",
         "components": {
           "Text": {

agent_sdks/python/tests/integration/verify_load_real.py

@@ -403,7 +403,9 @@ def verify():
             'version': 'v0.9',
             'createSurface': {
                 'surfaceId': 'contact_form_1',
-                'catalogId': 'https://a2ui.dev/specification/v0_9/basic_catalog.json',
+                'catalogId': (
+                    'https://a2ui.dev/specification/v0_9/catalogs/basic/catalog.json'
+                ),
                 'fakeProperty': 'should be allowed',
             },
         },

agent_sdks/python/tests/schema/test_catalog.py

@@ -27,7 +27,7 @@
 
 
 def test_catalog_id_property():
-  catalog_id = "https://a2ui.org/basic_catalog.json"
+  catalog_id = "https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json"
   catalog = A2uiCatalog(
       version=VERSION_0_8,
       name=BASIC_CATALOG_NAME,

agent_sdks/python/tests/schema/test_validator.py

@@ -130,9 +130,9 @@ def catalog_0_9(self):
     }
     catalog_schema = {
         "$schema": "https://json-schema.org/draft/2020-12/schema",
-        "$id": "https://a2ui.org/specification/v0_9/basic_catalog.json",
+        "$id": "https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json",
         "title": "A2UI Basic Catalog",
-        "catalogId": "https://a2ui.dev/specification/v0_9/basic_catalog.json",
+        "catalogId": "https://a2ui.dev/specification/v0_9/catalogs/basic/catalog.json",
         "components": {
             "Text": {
                 "type": "object",
@@ -449,7 +449,9 @@ def test_pretty_error_messages(self, catalog_0_9):
             "version": "v0.9",
             "createSurface": {
                 "surfaceId": "recipe-card",
-                "catalogId": "https://a2ui.org/specification/v0_9/basic_catalog.json",
+                "catalogId": (
+                    "https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json"
+                ),
             },
         },
         {

docs/assets/recipe_sample.gif

@@ -28,6 +28,8 @@ cd A2UI/samples/mcp/a2ui-over-mcp-recipe
 uv run .
 ```
 
+### Option A: Interacting via the MCP Inspector
+
 In a separate terminal, launch the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) to interact with the server:
 
 ```bash
@@ -38,8 +40,10 @@ In the Inspector:
 
 1. Set **Transport Type** to `SSE`
 2. Connect to `http://localhost:8000/sse`
-3. Click **List Tools** → you'll see `get_recipe_a2ui`
-4. Run the tool → the response contains A2UI JSON that renders a recipe card
+3. Click **List Resources** → you'll see "Recipe Form" resource.
+4. Read the `a2ui://recipe-form` resource → the resource content is the A2UI JSON that renders the simple form.
+5. Click **List Tools** → you'll see `get_recipe_a2ui`
+6. Run the tool → the response contains A2UI JSON that renders a recipe card
 
 > NOTE: Note
 >
@@ -49,11 +53,57 @@ In the Inspector:
 > pip install a2ui-agent-sdk
 > ```
 
+### Option B: Running the Recipe Client Web App
+
+For a fully rendered interactive experience that visually demonstrates A2UI over MCP, run the included web application:
+
+1. In a new terminal window, navigate to the client directory:
+    ```bash
+    cd client
+    ```
+2. Install Node.js dependencies:
+    ```bash
+    npm install
+    ```
+3. Start the Vite development server:
+    ```bash
+    npm run dev
+    ```
+4. Open your browser to the URL displayed in your terminal (usually `http://localhost:5173`).
+
+You will see a premium, responsive dual-column interface where the left column renders the Selection Form from MCP Resource (`a2ui://recipe-form`). Picking options and clicking **"Get Recipe"** executes the MCP Tool (`get_recipe_a2ui`), dynamically rendering the returned custom A2UI recipe card in the right column.
+
+![Dynamic Recipe Studio demo showing selection form on the left and dynamic recipe card generation on the right](../assets/recipe_sample.gif)
+
 See all samples at [`samples/mcp/`](https://github.com/google/A2UI/tree/main/samples/mcp).
 
 ## How It Works
 
-An MCP server returns A2UI content as **Embedded Resources** inside tool responses. The client detects the `application/json+a2ui` MIME type and routes the payload to an A2UI renderer.
+There are two primary ways an MCP server can deliver A2UI content to a client:
+
+1. **Via Reading a Resource (`resources/read`)**: The client reads an MCP resource directly (e.g., `a2ui://recipe-form`). The server returns the A2UI JSON payload directly.
+2. **Via Calling a Tool (`tools/call`)**: The client calls an MCP tool (e.g., `get_recipe_a2ui`). The server returns the A2UI JSON payload wrapped as an **Embedded Resource** inside the tool response.
+
+In both cases, the client detects the `application/json+a2ui` MIME type and routes the payload to an A2UI renderer.
+
+> [!IMPORTANT]
+> **MIME Type Uniformity**
+> Regardless of the delivery channel (whether fetched directly as a Resource or returned inside a Tool's `CallToolResult`), the A2UI JSON payload is always identified by the `application/json+a2ui` MIME type. In Tool responses, the payload must be wrapped inside an `EmbeddedResource` carrying this MIME type. This uniform identification allows client-side middleware to seamlessly intercept and route both static resources and dynamic tool responses to A2UI.
+
+### 1. Resource-based Delivery Flow (`resources/read`)
+
+```
+Client → resources/read → MCP Server
+                             ↓
+                 Retrieve A2UI JSON
+                             ↓
+Client ← ResourceContents ← MCP Server
+          (application/json+a2ui)
+   ↓
+A2UI Renderer displays UI
+```
+
+### 2. Tool-based Delivery Flow (`tools/call`)
 
 ```
 Client → tools/call → MCP Server
@@ -68,6 +118,83 @@ Client ← CallToolResult ← MCP Server
 A2UI Renderer displays UI
 ```
 
+## Resources vs. Tools: Separation of Utility Focus
+
+When designing an A2UI integration over MCP, you should choose between **Resources** and **Tools** depending on whether the UI payload is static or dynamic.
+
+### 1. Static UI via MCP Resources (`resources/read`)
+
+For simple, static user interfaces that do not depend on user prompt inputs or conversation history, you should serve A2UI directly as an MCP Resource.
+
+- **Concept**: The client reads a pre-defined A2UI resource using a standard resource URI (e.g., `a2ui://recipe-form`).
+- **Use Case**: Ideal for static configuration forms, selection screens, settings dashboards, or stable layouts.
+- **Benefit**: Extremely simple to implement, low overhead, and doesn't require the LLM/Agent to make a tool call to fetch the structure.
+
+**Python Server Example:**
+
+```python
+@app.list_resources()
+async def list_resources() -> list[types.Resource]:
+    return [
+        types.Resource(
+            uri="a2ui://recipe-form",
+            name="Recipe Form",
+            mimeType="application/json+a2ui",
+            description="Static form allowing users to pick options.",
+        )
+    ]
+
+@app.read_resource()
+async def read_resource(uri: str) -> list[ReadResourceContents]:
+    if uri == "a2ui://recipe-form":
+        return [
+            ReadResourceContents(
+                content=json.dumps(recipe_form_json),
+                mime_type="application/json+a2ui",
+            )
+        ]
+    raise ValueError(f"Unknown resource: {uri}")
+```
+
+### 2. Dynamic UI via MCP Tools (`tools/call`)
+
+For user interfaces that need to be generated dynamically based on the conversational context, user parameters, or real-time data, you should serve A2UI inside an MCP Tool's response.
+
+- **Concept**: The client/Agent calls a tool with specific arguments (e.g., chosen ingredients, preferences), and the server returns a customized A2UI JSON wrapped inside an `EmbeddedResource` in the `CallToolResult`.
+- **Use Case**: Ideal for content that depends on live database queries, previous inputs, interactive step-by-step wizard state, or personalized recommendations (e.g., a customized recipe card).
+- **Benefit**: Maximizes flexibility, context-awareness, and supports highly dynamic flows.
+- **Best Practice (Fallback Text)**: Always include a `TextContent` alongside your `EmbeddedResource` in the `CallToolResult`. Clients that don't support A2UI will fall back to displaying this text to the user.
+
+**Python Server Example:**
+
+```python
+@app.call_tool()
+async def handle_call_tool(name: str, arguments: dict[str, Any]) -> types.CallToolResult:
+    if name == "get_recipe_a2ui":
+        # Resolve dynamic selections from client parameters
+        style = arguments.get("cookingStyle", "Baked")
+        protein = arguments.get("protein", "Salmon")
+
+        # Retrieve customized recipe database entry
+        recipe_data = RECIPES.get((style, protein))
+
+        # Customize base A2UI schema dynamically
+        custom_recipe_json = copy.deepcopy(recipe_a2ui_json)
+        custom_recipe_json[1]["updateComponents"]["components"][0]["text"] = recipe_data["title"]
+
+        # Return customized recipe card as EmbeddedResource
+        return types.CallToolResult(content=[
+            types.EmbeddedResource(
+                type="resource",
+                resource=types.TextResourceContents(
+                    uri="a2ui://recipe-card",
+                    mimeType="application/json+a2ui",
+                    text=json.dumps(custom_recipe_json),
+                )
+            )
+        ])
+```
+
 ## Catalog Negotiation
 
 Before a server can send A2UI to a client, they must establish which catalogs are available. Depending on your architecture, this can happen in one of two ways.
@@ -132,68 +259,6 @@ If your server must remain stateless, the client can pass A2UI capabilities in t
 }
 ```
 
-## Returning A2UI Content
-
-A2UI content is returned as **Embedded Resources** inside a `CallToolResult`. Key rules:
-
-- **URI**: Must use the `a2ui://` prefix with a descriptive name (e.g., `a2ui://training-plan-page`)
-- **MIME Type**: Must be `application/json+a2ui` — this tells the client to route the payload to an A2UI renderer
-
-### Python Example
-
-```python
-import json
-import mcp.types as types
-
-@self.tool()
-def get_hello_world_ui():
-    """Returns a simple A2UI hello world interface."""
-    a2ui_payload = [
-        {
-            "version": "v0.9",
-            "createSurface": {
-                "surfaceId": "default",
-                "catalogId": "https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json"
-            }
-        },
-        {
-            "version": "v0.9",
-            "updateComponents": {
-                "surfaceId": "default",
-                "components": [
-                    {
-                        "id": "root",
-                        "component": "Text",
-                        "text": "Hello World!"
-                    }
-                ]
-            }
-        }
-    ]
-
-    # Wrap A2UI as an Embedded Resource
-    a2ui_resource = types.EmbeddedResource(
-        type="resource",
-        resource=types.TextResourceContents(
-            uri="a2ui://hello-world",
-            mimeType="application/json+a2ui",
-            text=json.dumps(a2ui_payload),
-        )
-    )
-
-    # Include a text summary alongside the UI
-    text_content = types.TextContent(
-        type="text",
-        text="Here is a hello world UI."
-    )
-
-    return types.CallToolResult(content=[text_content, a2ui_resource])
-```
-
-> TIP: Tip
->
-> Always include a `TextContent` alongside your A2UI resource. Clients that don't support A2UI will fall back to showing the text.
-
 ## Handling User Actions
 
 Interactive components like `Button` can trigger actions that are sent back to the server as MCP tool calls.

docs/guides/a2ui_over_mcp.md

@@ -1,5 +1,6 @@
 ## Unreleased
 
+- (v0_9) Fix null de-referencing TypeError in `ComponentBinder` when `children` property is null or undefined. [#1472](https://github.com/google/A2UI/pull/1472)
 - (v0_8) Fix Icon component to handle camelCase and TitleCase names by converting them to snake_case for `g-icon`.
 - (v0_8) Fix Modal component styling and position fixed for overlay.
 - (v0_9) Remove `placeholder` prop support from the `TextField` component, since it was not part of the v0_9 basic catalog schema. [#1372](https://github.com/google/A2UI/pull/1372)