finish all instructions

Author: kentcdodds

exercises/05.advanced/01.problem.tool-results/README.mdx

@@ -1 +1,53 @@
 # Tool Results
+
+👨‍💼 When users interact with our journal entries, they expect immediate feedback and reliable actions. If a user deletes an entry, they need to know it actually worked - not just hope for the best. The problem is: how do we get structured, validated data back from our MCP tools so we can build intelligent workflows that respond appropriately to different outcomes?
+
+```ts
+// Tool returns both human-readable and structured data
+const result = await sendMcpMessage(
+	'tool',
+	{
+		toolName: 'analyze_code',
+		params: { filePath: 'src/utils/validation.ts' },
+	},
+	{ schema: codeAnalysisSchema, signal: unmountSignal },
+)
+
+// Client can access structured data and respond intelligently
+const { metrics, suggestions, complexity } = result.structuredContent
+if (complexity > 10) {
+	showRefactorWarning(suggestions)
+}
+updateCodeMetrics(metrics)
+```
+
+To make this happen, we use Zod schemas to validate and type the structured content returned by MCP tools. This enables rich integrations where the client can understand and act on tool results programmatically, rather than requiring manual user intervention for every step.
+
+The structured content is defined by the tool's `outputSchema` and validated using Zod schemas on the client side, ensuring type safety and reliable data flow between the MCP server and client applications.
+
+<callout-info>
+	With structured content, MCP clients can build sophisticated workflows where
+	tools can trigger automatic actions based on their results, creating a more
+	intelligent and responsive user experience.
+</callout-info>
+
+```mermaid
+sequenceDiagram
+    User->>Iframe: Click "Delete Entry"
+    Iframe->>App: Send tool message via postMessage
+    App->>MCP: Call delete_entry tool
+    MCP->>MCP: Process deletion
+    MCP->>App: Return structured result
+    App->>Iframe: Send result via postMessage
+    Iframe->>Iframe: Validate with Zod schema
+    Iframe->>Iframe: Check success status
+    Iframe->>User: Update UI based on result
+```
+
+The goal is to make tool interactions feel intelligent and responsive, so users can trust that their actions have real consequences and get immediate, accurate feedback about what happened.
+
+Remember, our `delete_entry` tool returns structured content with a `success` boolean. You'll need to create a Zod schema to validate this data and use it in your `sendMcpMessage` call to get type-safe access to the result!
+
+👨‍💼 Thanks Kellie!
+
+Now, start by creating the schema, implement the tool call, and handle both success and failure cases to make your journal deletion feel reliable and responsive.

exercises/05.advanced/01.problem.tool-results/app/routes/ui/journal-viewer.tsx

@@ -236,6 +236,7 @@ function DeleteEntryButtonImpl({
 				// pass the schema you created above
 				// 🦉 the result of the sendMcpMessage call should be type safe thanks to your schema
 				// 🐨 if the result.structuredContent.success is true, call onDeleted
+				// 🐨 if the result.structuredContent.success is false, use showBoundary to show an error
 				throw new Error('Calling tools is not yet supported')
 			} catch (err) {
 				showBoundary(err)

exercises/05.advanced/01.solution.tool-results/README.mdx

@@ -1 +1,5 @@
 # Tool Results
+
+👨‍💼 Great work! We've successfully implemented structured tool results that enable intelligent, data-driven workflows in our journal application. Our MCP UI is now more responsive. Woo!
+
+🧝‍♀️ I'm going to prep us for a new requirement we have for the entry viewer. <NextDiffLink>Check out my changes</NextDiffLink> if you'd like.

exercises/05.advanced/01.solution.tool-results/app/routes/ui/journal-viewer.tsx

@@ -237,6 +237,8 @@ function DeleteEntryButtonImpl({
 				)
 				if (result.structuredContent.success) {
 					onDeleted()
+				} else {
+					showBoundary(new Error('Failed to delete entry'))
 				}
 			} catch (err) {
 				showBoundary(err)

exercises/05.advanced/02.problem.render-data/README.mdx

@@ -1 +1,42 @@
 # Render Data
+
+👨‍💼 We've got a new requirement coming up. We're going to be adding authorization to the MCP server, but our UI has no way to identify the user securely.
+
+The problem is that we need a way to pass protected data directly from the MCP server to the iframe component, eliminating the need for additional API calls while maintaining security boundaries.
+
+Instead, we can use MCP UI's **render data** to pass initial data directly to iframe components. This allows the server to provide all necessary context when creating UI resources.
+
+```ts
+// Server provides initial data with the UI resource
+return {
+	content: [
+		{
+			type: 'resource',
+			resource: {
+				uri: iframeUrl.toString(),
+				mimeType: 'text/html',
+				uiMetadata: {
+					'initial-render-data': { bookmarks },
+				},
+			},
+		},
+	],
+}
+
+// Client receives data as soon as it emits the `ui-lifecycle-iframe-ready` event
+window.addEventListener('message', function handleMessage(event: MessageEvent) {
+	if (event.data?.type !== 'ui-lifecycle-iframe-render-data') return
+	if (event.data.error) {
+		// event.data.error... handle it
+	} else {
+		const { bookmarks } = event.data.payload
+		// do stuff with this
+	}
+})
+```
+
+You need to implement render data for the entry viewer. The server should pass the entry data via `uiMetadata`, and the client should use `waitForRenderData` to receive it.
+
+Your implementation of `waitForRenderData` should be a little more complete. If you need help, your AI assistant can help you with that! Just ask it!
+
+📜 [Passing Render Data to the iframe](https://mcpui.dev/guide/embeddable-ui#passing-render-data-to-the-iframe)

exercises/05.advanced/02.problem.render-data/app/routes/ui/journal-viewer.tsx

@@ -237,6 +237,8 @@ function DeleteEntryButtonImpl({
 				)
 				if (result.structuredContent.success) {
 					onDeleted()
+				} else {
+					showBoundary(new Error('Failed to delete entry'))
 				}
 			} catch (err) {
 				showBoundary(err)

exercises/05.advanced/02.solution.render-data/README.mdx

@@ -1 +1,5 @@
 # Render Data
+
+👨‍💼 Great work! We've successfully implemented render data for our journal entry viewer, solving a critical security problem. Now we can securely pass protected data from our MCP server to the iframe component.
+
+Well done!

exercises/05.advanced/02.solution.render-data/app/routes/ui/journal-viewer.tsx

@@ -237,6 +237,8 @@ function DeleteEntryButtonImpl({
 				)
 				if (result.structuredContent.success) {
 					onDeleted()
+				} else {
+					showBoundary(new Error('Failed to delete entry'))
 				}
 			} catch (err) {
 				showBoundary(err)

exercises/05.advanced/02.solution.render-data/app/utils/mcp.ts

@@ -109,15 +109,11 @@ const renderDataQueue: Array<{ type: string; payload: any }> = []
 
 // Set up global listener immediately when module loads (only in the client)
 if (typeof document !== 'undefined') {
-	window.addEventListener(
-		'message',
-		(event) => {
-			if (event.data?.type === 'ui-lifecycle-iframe-render-data') {
-				renderDataQueue.push(event.data)
-			}
-		},
-		{ once: false },
-	)
+	window.addEventListener('message', (event) => {
+		if (event.data?.type === 'ui-lifecycle-iframe-render-data') {
+			renderDataQueue.push(event.data)
+		}
+	})
 }
 
 export function waitForRenderData<RenderData>(
@@ -152,6 +148,6 @@ export function waitForRenderData<RenderData>(
 			return result.success ? resolve(result.data) : reject(result.error)
 		}
 
-		window.addEventListener('message', handleMessage, { once: true })
+		window.addEventListener('message', handleMessage)
 	})
 }

exercises/05.advanced/FINISHED.mdx

@@ -1 +1,7 @@
 # Advanced
+
+Congratulations! You've successfully implemented two powerful advanced features that make MCP UI significantly more capable.
+
+These advanced features transform your MCP UI from simple display components into intelligent, data-driven interfaces that can build sophisticated workflows.
+
+You're now ready to build production-ready MCP UI applications!