josemontespg · Oct 29, 2026
diff --git a/catalogs/mcp/README.md b/catalogs/mcp/README.md
@@ -35,7 +35,7 @@ For `updateDataModel`, keys starting with `/` are absolute paths, while relative
 
 ## v1 catalog (protocol v1.0)
 
-The v1 catalog, [v1/catalog.json](v1/catalog.json), targets A2UI protocol v1.0. Its catalog ID is `https://a2ui.org/specification/v1_0/catalogs/mcp/catalog.json`. It declares `callMcpTool` and `updateDataModel`, with argument and return types taken from the v1.0 `common_types.json`, and the `McpApp` component.
+The v1 catalog, [v1/catalog.json](v1/catalog.json), targets A2UI protocol v1.0. Its catalog ID is `https://a2ui.org/specification/v1_0/catalogs/mcp/catalog.json`. It declares `callMcpTool` and the data functions below, with argument and return types taken from the v1.0 `common_types.json`, and the `McpApp` component.
 
 ### Tool data payload
 
@@ -45,11 +45,42 @@ The optional `targetDataPath` argument writes the payload of each successful cal
 
 ### Data functions
 
-| Function          | Arguments | Returns                                                                     |
-| :---------------- | :-------- | :-------------------------------------------------------------------------- |
-| `updateDataModel` | `updates` | Nothing. Writes each key-value pair in `updates` to the surface data model. |
-
-The `updates` argument is a required `DynamicValue`, so it can be a literal object, a `@path` binding or a nested `@call`; a `null` or missing argument is rejected. Keys starting with `/` are absolute paths, while relative keys resolve against the calling data context (such as the current row scope inside a template list). `updateDataModel` does not evaluate `@path` or `@call` objects found inside the values it writes: a tool result is data, not an expression.
+Most MCP tools return plain `content` blocks rather than A2UI resources, so a surface needs to pick the fields it wants out of the payload and write them to the data model. The v1 catalog declares these functions for that:
+
+| Function          | Arguments          | Returns                                                                                                                                   |
+| :---------------- | :----------------- | :---------------------------------------------------------------------------------------------------------------------------------------- |
+| `transformData`   | `jmespath`, `data` | The result of evaluating the [JMESPath](https://jmespath.org/specification.html) expression against `data`, or `null` for missing fields. |
+| `updateDataModel` | `updates`          | Nothing. Writes each key-value pair in `updates` to the surface data model.                                                               |
+
+Every argument is required, and a `null` or missing argument is rejected. `transformData` implements standard JMESPath, with no extensions. `jmespath` is a `DynamicString`; `data` and `updates` are `DynamicValue`, so each can be a literal, a `@path` binding or a nested `@call`. For `updateDataModel`, keys starting with `/` are absolute paths, while relative keys resolve against the calling data context (such as the current row scope inside a template list).
+
+A surface is usually created on the basic catalog, so each call selects the MCP catalog with its own `catalogId`. A button action chains the functions this way:
+
+```json
+{
+  "@call": "updateDataModel",
+  "catalogId": "https://a2ui.org/specification/v1_0/catalogs/mcp/catalog.json",
+  "args": {
+    "updates": {
+      "@call": "transformData",
+      "catalogId": "https://a2ui.org/specification/v1_0/catalogs/mcp/catalog.json",
+      "args": {
+        "jmespath": "{\"/issues\": json[?state == 'open'].{number: to_string(number), title: title}}",
+        "data": {
+          "@call": "callMcpTool",
+          "catalogId": "https://a2ui.org/specification/v1_0/catalogs/mcp/catalog.json",
+          "args": {
+            "name": "list_issues",
+            "arguments": {"repository": {"@path": "/repository"}}
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+`transformData` reads the parsed `json` of the payload and builds the `{path: value}` object, and `updateDataModel` writes it. The functions do not evaluate `@path` or `@call` objects found inside tool output: a tool result is data, not an expression.
 
 ### McpApp component
 

diff --git a/catalogs/mcp/v1/catalog.json b/catalogs/mcp/v1/catalog.json
@@ -3,7 +3,7 @@
   "$id": "https://a2ui.org/specification/v1_0/catalogs/mcp/catalog.json",
   "protocolVersion": "1.0",
   "title": "A2UI MCP Catalog",
-  "description": "A2UI catalog for Model Context Protocol (MCP) integrations. It defines the `callMcpTool` function, the `updateDataModel` function that writes values to the surface data model, and the `McpApp` component that renders a sandboxed MCP App connected to the host through the MCP Apps bridge.",
+  "description": "A2UI catalog for Model Context Protocol (MCP) integrations. It defines the `callMcpTool` function, the data functions that turn a tool result into data model updates, and the `McpApp` component that renders a sandboxed MCP App connected to the host through the MCP Apps bridge.",
   "catalogId": "https://a2ui.org/specification/v1_0/catalogs/mcp/catalog.json",
   "components": {
     "McpApp": {
@@ -147,6 +147,32 @@
       },
       "required": ["@call", "args"]
     },
+    "transformData": {
+      "type": "object",
+      "description": "Evaluates a JMESPath expression (https://jmespath.org/specification.html) against `data`. Standard JMESPath only, no extensions.",
+      "returnType": "any",
+      "properties": {
+        "@call": {
+          "const": "transformData"
+        },
+        "args": {
+          "type": "object",
+          "properties": {
+            "jmespath": {
+              "$ref": "common_types.json#/$defs/DynamicString",
+              "description": "A JMESPath expression (https://jmespath.org/specification.html) evaluated against `data`. Standard JMESPath only, no extensions."
+            },
+            "data": {
+              "$ref": "common_types.json#/$defs/DynamicValue",
+              "description": "The input data to evaluate the expression against."
+            }
+          },
+          "required": ["jmespath", "data"],
+          "additionalProperties": false
+        }
+      },
+      "required": ["@call", "args"]
+    },
     "updateDataModel": {
       "type": "object",
       "description": "Writes key-value pairs to the surface data model.",
@@ -186,6 +212,9 @@
         {
           "$ref": "#/functions/callMcpTool"
         },
+        {
+          "$ref": "#/functions/transformData"
+        },
         {
           "$ref": "#/functions/updateDataModel"
         }

diff --git a/typescript/catalogs/mcp/CHANGELOG.md b/typescript/catalogs/mcp/CHANGELOG.md
@@ -4,7 +4,7 @@
 - The published package contains only the runtime build output; test files and TypeScript build info are no longer included. [#3348](https://github.com/a2ui-project/a2ui/pull/3348)
 - **BREAKING CHANGE**: Hosts set up the catalog once with `configureMcpCatalog`; `createCallMcpToolImplementation`, `CallMcpToolApi` and `A2UI_MIME_TYPE` are removed and `MCP_CATALOG_ID` now identifies the v1.0 catalog (`catalogs/mcp/v1/catalog.json`, bundled as `@a2ui/catalog-mcp/catalog.json`). `callMcpTool` now hands `ui://` MCP App resources to the host. [#3186](https://github.com/a2ui-project/a2ui/pull/3186)
 - `callMcpTool` returns a payload with `toolName`, `toolInput`, `toolResult`, `structuredContent`, `text` and `json`, and writes it to `targetDataPath` when set, where the latest call to a path wins. [#3728](https://github.com/a2ui-project/a2ui/pull/3728)
-- The `updateDataModel` data function writes key-value pairs to the surface data model; its `UpdateDataModelApi` and `UpdateDataModelImplementation` are exported for hosts that register functions one by one. [#3573](https://github.com/a2ui-project/a2ui/pull/3573)
+- The `transformData` (standard JMESPath) and `updateDataModel` data functions shape the `callMcpTool` payload into data model updates; their `*Api` and `*Implementation` are exported for hosts that register functions one by one. [#3573](https://github.com/a2ui-project/a2ui/pull/3573), [#3736](https://github.com/a2ui-project/a2ui/pull/3736)
 - Add `mcpCatalog`, the v1.0 MCP catalog with the `McpApp` universal component (`A2uiMcpApp`) and `callMcpTool`, ready to hand to a `MessageProcessor`. `McpApp` renders an MCP App in the shared sandbox, binds host data through `data.paths` and dispatches the tools it is allowed to call as A2UI actions. [#2799](https://github.com/a2ui-project/a2ui/pull/2799)
 
 ## 0.0.1-alpha.1