feat: Integrate MCP Apps into A2UI

agent_sdks/python/src/a2ui/core/schema/manager.py

@@ -19,7 +19,7 @@
 import importlib.resources
 from typing import List, Dict, Any, Optional, Callable
 from dataclasses import dataclass, field
-from .utils import load_from_bundled_resource
+from .utils import load_from_bundled_resource, deep_update
 from ..inference_strategy import InferenceStrategy
 from .constants import *
 from .catalog import CatalogConfig, A2uiCatalog
@@ -146,10 +146,15 @@ def _select_catalog(
       # Load the first inline catalog schema.
       inline_catalog_schema = inline_catalogs[0]
       inline_catalog_schema = self._apply_modifiers(inline_catalog_schema)
+
+      # Deep merge the standard catalog properties with the inline catalog
+      merged_schema = copy.deepcopy(self._supported_catalogs[0].catalog_schema)
+      deep_update(merged_schema, inline_catalog_schema)
+
       return A2uiCatalog(
           version=self._version,
           name=INLINE_CATALOG_NAME,
-          catalog_schema=inline_catalog_schema,
+          catalog_schema=merged_schema,
           s2c_schema=self._server_to_client_schema,
           common_types_schema=self._common_types_schema,
       )

agent_sdks/python/src/a2ui/core/schema/utils.py

@@ -117,3 +117,13 @@ def wrap_as_json_array(a2ui_schema: dict[str, Any]) -> dict[str, Any]:
   if not a2ui_schema:
     raise ValueError("A2UI schema is empty")
   return {"type": "array", "items": a2ui_schema}
+
+
+def deep_update(d: dict, u: dict) -> dict:
+  """Recursively update a dict with another dict."""
+  for k, v in u.items():
+    if isinstance(v, dict):
+      d[k] = deep_update(d.get(k, {}), v)
+    else:
+      d[k] = v
+  return d

agent_sdks/python/src/a2ui/core/schema/validator.py

@@ -274,44 +274,54 @@ def validate(self, a2ui_json: Union[Dict[str, Any], List[Any]]) -> None:
           msg += f"\n  - {sub_error.message}"
       raise ValueError(msg)
 
-    root_id = _find_root_id(messages)
-
     for message in messages:
       if not isinstance(message, dict):
         continue
 
       components = None
+      surface_id = None
       if "surfaceUpdate" in message:  # v0.8
         components = message["surfaceUpdate"].get(COMPONENTS)
+        surface_id = message["surfaceUpdate"].get("surfaceId")
       elif "updateComponents" in message and isinstance(
           message["updateComponents"], dict
       ):  # v0.9
         components = message["updateComponents"].get(COMPONENTS)
+        surface_id = message["updateComponents"].get("surfaceId")
 
       if components:
         ref_map = _extract_component_ref_fields(self._catalog)
+        root_id = _find_root_id(messages, surface_id)
         _validate_component_integrity(root_id, components, ref_map)
         _validate_topology(root_id, components, ref_map)
 
       _validate_recursion_and_paths(message)
 
 
-def _find_root_id(messages: List[Dict[str, Any]]) -> str:
+def _find_root_id(
+    messages: List[Dict[str, Any]], surface_id: Optional[str] = None
+) -> Optional[str]:
   """
-  Finds the root id from a list of A2UI messages.
+  Finds the root id from a list of A2UI messages for a given surface.
   - For v0.8, the root id is in the beginRendering message.
   - For v0.9+, the root id is 'root'.
   """
   for message in messages:
     if not isinstance(message, dict):
       continue
     if "beginRendering" in message:
+      if surface_id and message["beginRendering"].get("surfaceId") != surface_id:
+        continue
       return message["beginRendering"].get(ROOT, ROOT)
-  return ROOT
+    if "createSurface" in message:
+      if surface_id and message["createSurface"].get("surfaceId") != surface_id:
+        continue
+      return ROOT
+  return None
 
 
 def _validate_component_integrity(
-    root_id: str,
+    root_id: Optional[str],
     components: List[Dict[str, Any]],
     ref_fields_map: Dict[str, tuple[Set[str], Set[str]]],
 ) -> None:
@@ -334,21 +344,23 @@ def _validate_component_integrity(
     ids.add(comp_id)
 
   # 2. Check for root component
-  if root_id not in ids:
+  if root_id is not None and root_id not in ids:
     raise ValueError(f"Missing root component: No component has id='{root_id}'")
 
   # 3. Check for dangling references using helper
-  for comp in components:
-    for ref_id, field_name in _get_component_references(comp, ref_fields_map):
-      if ref_id not in ids:
-        raise ValueError(
-            f"Component '{comp.get(ID)}' references non-existent component '{ref_id}'"
-            f" in field '{field_name}'"
-        )
+  # In an incremental update (root_id is None), components may reference IDs already on the client.
+  if root_id is not None:
+    for comp in components:
+      for ref_id, field_name in _get_component_references(comp, ref_fields_map):
+        if ref_id not in ids:
+          raise ValueError(
+              f"Component '{comp.get(ID)}' references non-existent component '{ref_id}'"
+              f" in field '{field_name}'"
+          )
 
 
 def _validate_topology(
-    root_id: str,
+    root_id: Optional[str],
     components: List[Dict[str, Any]],
     ref_fields_map: Dict[str, tuple[Set[str], Set[str]]],
 ) -> None:
@@ -401,16 +413,22 @@ def dfs(node_id: str, depth: int):
 
     recursion_stack.remove(node_id)
 
-  if root_id in all_ids:
-    dfs(root_id, 0)
+  if root_id is not None:
+    if root_id in all_ids:
+      dfs(root_id, 0)
 
-  # Check for Orphans
-  orphans = all_ids - visited
-  if orphans:
-    sorted_orphans = sorted(list(orphans))
-    raise ValueError(
-        f"Component '{sorted_orphans[0]}' is not reachable from '{root_id}'"
-    )
+    # Check for Orphans
+    orphans = all_ids - visited
+    if orphans:
+      sorted_orphans = sorted(list(orphans))
+      raise ValueError(
+          f"Component '{sorted_orphans[0]}' is not reachable from '{root_id}'"
+      )
+  else:
+    # Partial update: we cannot check root reachability, but we still check for cycles
+    for node_id in all_ids:
+      if node_id not in visited:
+        dfs(node_id, 0)
 
 
 def _extract_component_ref_fields(

agent_sdks/python/tests/core/schema/test_validator.py

@@ -48,7 +48,10 @@ def catalog_0_9(self):
                             "catalogId": {
                                 "type": "string",
                             },
-                            "theme": {"type": "object", "additionalProperties": True},
+                            "theme": {
+                                "type": "object",
+                                "additionalProperties": True,
+                            },
                         },
                         "required": ["surfaceId", "catalogId"],
                         "additionalProperties": False,
@@ -495,7 +498,10 @@ def test_custom_catalog_0_8(self, catalog_0_8):
                 "children": {
                     "type": "object",
                     "properties": {
-                        "explicitList": {"type": "array", "items": {"type": "string"}}
+                        "explicitList": {
+                            "type": "array",
+                            "items": {"type": "string"},
+                        }
                     },
                     "required": ["explicitList"],
                 }
@@ -723,30 +729,53 @@ def make_payload(self, catalog, components=None, data_model=None):
             processed.append(comp)
 
       if catalog.version == VERSION_0_8:
-        payload = {
-            "surfaceUpdate": {"surfaceId": "test-surface", "components": processed}
-        }
+        payload = [
+            {"beginRendering": {"surfaceId": "test-surface", "root": "root"}},
+            {
+                "surfaceUpdate": {
+                    "surfaceId": "test-surface",
+                    "components": processed,
+                }
+            },
+        ]
       else:
-        payload = {
-            "version": "v0.9",
-            "updateComponents": {"surfaceId": "test-surface", "components": processed},
-        }
+        payload = [
+            {
+                "version": "v0.9",
+                "createSurface": {"surfaceId": "test-surface", "catalogId": "std"},
+            },
+            {
+                "version": "v0.9",
+                "updateComponents": {
+                    "surfaceId": "test-surface",
+                    "components": processed,
+                },
+            },
+        ]
 
     elif data_model:
       if catalog.version == VERSION_0_8:
-        payload = {
-            "dataModelUpdate": {"surfaceId": "test-surface", "contents": data_model}
-        }
+        payload = [
+            {
+                "dataModelUpdate": {
+                    "surfaceId": "test-surface",
+                    "contents": data_model,
+                }
+            }
+        ]
       else:
-        payload = {
+        payload = [{
             "version": "v0.9",
-            "updateDataModel": {"surfaceId": "test-surface", "value": data_model},
-        }
+            "updateDataModel": {
+                "surfaceId": "test-surface",
+                "value": data_model,
+            },
+        }]
 
     if payload is None:
-      return [] if catalog.version == VERSION_0_9 else {}
+      return []
 
-    return [payload] if catalog.version == VERSION_0_9 else payload
+    return payload
 
   def test_validate_duplicate_ids(self, test_catalog):
     components = [
@@ -762,20 +791,29 @@ def test_validate_missing_root(self, test_catalog):
     # This payload has components but none are 'root'
     # bypass make_payload as it adds root if missing
     if test_catalog.version == VERSION_0_8:
-      payload = {
-          "surfaceUpdate": {
-              "surfaceId": "test",
-              "components": [{"id": "c1", "component": {"Text": {"text": "hi"}}}],
-          }
-      }
+      payload = [
+          {"beginRendering": {"surfaceId": "test", "root": "root"}},
+          {
+              "surfaceUpdate": {
+                  "surfaceId": "test",
+                  "components": [{"id": "c1", "component": {"Text": {"text": "hi"}}}],
+              }
+          },
+      ]
     else:
-      payload = [{
-          "version": "v0.9",
-          "updateComponents": {
-              "surfaceId": "test",
-              "components": [{"id": "c1", "component": "Text", "text": "hi"}],
+      payload = [
+          {
+              "version": "v0.9",
+              "createSurface": {"surfaceId": "test", "catalogId": "std"},
+          },
+          {
+              "version": "v0.9",
+              "updateComponents": {
+                  "surfaceId": "test",
+                  "components": [{"id": "c1", "component": "Text", "text": "hi"}],
+              },
           },
-      }]
+      ]
 
     with pytest.raises(ValueError, match="Missing root component"):
       test_catalog.validator.validate(payload)
@@ -915,12 +953,9 @@ def test_validate_v08_custom_root_reachability(self, test_catalog):
         {"id": "custom-root", "component": "Text", "text": "I am the root"},
         {"id": "orphan", "component": "Text", "text": "I am an orphan"},
     ]
-    # make_payload only gives us surfaceUpdate, we need to wrap it with beginRendering
-    surface_update = self.make_payload(test_catalog, components=components)
-    payload = [
-        {"beginRendering": {"surfaceId": "test-surface", "root": "custom-root"}},
-        surface_update,
-    ]
+    # make_payload gives us both beginRendering and surfaceUpdate. We just need to change root.
+    payload = self.make_payload(test_catalog, components=components)
+    payload[0]["beginRendering"]["root"] = "custom-root"
 
     # This should fail because 'orphan' is not reachable from 'custom-root'
     with pytest.raises(
@@ -933,13 +968,8 @@ def test_validate_v08_custom_root_reachability(self, test_catalog):
         {"id": "custom-root", "component": "Card", "child": "orphan"},
         {"id": "orphan", "component": "Text", "text": "I am no longer an orphan"},
     ]
-    surface_update_connected = self.make_payload(
-        test_catalog, components=components_connected
-    )
-    payload_connected = [
-        {"beginRendering": {"surfaceId": "test-surface", "root": "custom-root"}},
-        surface_update_connected,
-    ]
+    payload_connected = self.make_payload(test_catalog, components=components_connected)
+    payload_connected[0]["beginRendering"]["root"] = "custom-root"
     test_catalog.validator.validate(payload_connected)
 
   @pytest.mark.parametrize(
@@ -985,8 +1015,8 @@ def test_validate_invalid_paths(self, test_catalog, payload):
         p[0]["updateDataModel"]["path"] = data.get("path")
         p[0]["updateDataModel"]["surfaceId"] = data.get("surfaceId", "surface1")
       else:
-        p["dataModelUpdate"]["path"] = data.get("path")
-        p["dataModelUpdate"]["surfaceId"] = data.get("surfaceId", "surface1")
+        p[0]["dataModelUpdate"]["path"] = data.get("path")
+        p[0]["dataModelUpdate"]["surfaceId"] = data.get("surfaceId", "surface1")
 
     with pytest.raises(
         ValueError,

samples/agent/adk/contact_multiple_surfaces/README.md

@@ -28,6 +28,12 @@ This sample uses the Agent Development Kit (ADK) along with the A2A protocol to
    uv run .
    ```
 
+4. (Optional) Run the server with standard `WebFrame` instead of the custom `McpAppsCustomComponent`:
+
+   ```bash
+   USE_MCP_SANDBOX=false uv run .
+   ```
+
 
 ## Disclaimer