feat(mcp-ui): add hook for posting data back to MCP client

src/ui/hooks/index.ts

@@ -1 +1,2 @@
 export { useRenderData } from "./useRenderData.js";
+export { useHostCommunication } from "./useHostCommunication.js";

src/ui/hooks/useHostCommunication.ts

@@ -0,0 +1,140 @@
+import { useCallback, useMemo } from "react";
+
+interface SendMessageOptions {
+    targetOrigin?: string;
+}
+
+/** Return type for the useHostCommunication hook */
+interface UseHostCommunicationResult {
+    /** Sends an intent message for the host to act on */
+    intent: <T = unknown>(intent: string, params?: T) => void;
+    /** Notifies the host of something that happened */
+    notify: (message: string) => void;
+    /** Asks the host to run a prompt */
+    prompt: (prompt: string) => void;
+    /** Asks the host to execute a tool */
+    tool: <T = unknown>(toolName: string, params?: T) => void;
+    /** Asks the host to navigate to a URL */
+    link: (url: string) => void;
+    /** Reports iframe size changes to the host */
+    reportSizeChange: (dimensions: { width?: number; height?: number }) => void;
+}
+
+/**
+ * Hook for sending UI actions to the parent window via postMessage
+ * This is used by iframe-based UI components to communicate back to an MCP client
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { intent, tool, link } = useHostCommunication();
+ *
+ *   return <button onClick={() => intent("create-task", { title: "Buy groceries" })}>Create Task</button>;
+ * }
+ * ```
+ */
+export function useHostCommunication(defaultOptions?: SendMessageOptions): UseHostCommunicationResult {
+    const targetOrigin = defaultOptions?.targetOrigin ?? "*";
+
+    const intent = useCallback(
+        <T = unknown>(intentName: string, params?: T): void => {
+            window.parent.postMessage(
+                {
+                    type: "intent",
+                    payload: {
+                        intent: intentName,
+                        params,
+                    },
+                },
+                targetOrigin
+            );
+        },
+        [targetOrigin]
+    );
+
+    const notify = useCallback(
+        (message: string): void => {
+            window.parent.postMessage(
+                {
+                    type: "notify",
+                    payload: {
+                        message,
+                    },
+                },
+                targetOrigin
+            );
+        },
+        [targetOrigin]
+    );
+
+    const prompt = useCallback(
+        (promptText: string): void => {
+            window.parent.postMessage(
+                {
+                    type: "prompt",
+                    payload: {
+                        prompt: promptText,
+                    },
+                },
+                targetOrigin
+            );
+        },
+        [targetOrigin]
+    );
+
+    const tool = useCallback(
+        <T = unknown>(toolName: string, params?: T): void => {
+            window.parent.postMessage(
+                {
+                    type: "tool",
+                    payload: {
+                        toolName,
+                        params,
+                    },
+                },
+                targetOrigin
+            );
+        },
+        [targetOrigin]
+    );
+
+    const link = useCallback(
+        (url: string): void => {
+            window.parent.postMessage(
+                {
+                    type: "link",
+                    payload: {
+                        url,
+                    },
+                },
+                targetOrigin
+            );
+        },
+        [targetOrigin]
+    );
+
+    const reportSizeChange = useCallback(
+        (dimensions: { width?: number; height?: number }): void => {
+            window.parent.postMessage(
+                {
+                    type: "ui-size-change",
+                    payload: dimensions,
+                },
+                targetOrigin
+            );
+        },
+        [targetOrigin]
+    );
+
+    return useMemo(
+        () => ({
+            intent,
+            notify,
+            prompt,
+            tool,
+            link,
+            reportSizeChange,
+        }),
+        [intent, notify, prompt, tool, link, reportSizeChange]
+    );
+}

src/ui/hooks/useRenderData.ts

@@ -13,6 +13,8 @@ interface UseRenderDataResult<T> {
     data: T | null;
     isLoading: boolean;
     error: string | null;
+    /** The origin of the parent window, captured from the first valid message */
+    parentOrigin: string | null;
 }
 
 /**
@@ -24,6 +26,7 @@ interface UseRenderDataResult<T> {
  *   - data: The received render data (or null if not yet received)
  *   - isLoading: Whether data is still being loaded
  *   - error: Error message if message validation failed
+ *   - parentOrigin: The origin of the parent window (for secure postMessage calls)
  *
  * @example
  * ```tsx
@@ -32,15 +35,17 @@ interface UseRenderDataResult<T> {
  * }
  *
  * function MyComponent() {
- *   const { data, isLoading, error } = useRenderData<MyData>();
- *   // ...
+ *   const { data, isLoading, error, parentOrigin } = useRenderData<MyData>();
+ *   const { intent } = useHostCommunication({ targetOrigin: parentOrigin ?? undefined });
+ *   return <button onClick={() => intent("my-action")}>Click</button>;
  * }
  * ```
  */
 export function useRenderData<T = unknown>(): UseRenderDataResult<T> {
     const [data, setData] = useState<T | null>(null);
     const [isLoading, setIsLoading] = useState(true);
     const [error, setError] = useState<string | null>(null);
+    const [parentOrigin, setParentOrigin] = useState<string | null>(null);
 
     useEffect(() => {
         const handleMessage = (event: MessageEvent<RenderDataMessage>): void => {
@@ -49,6 +54,8 @@ export function useRenderData<T = unknown>(): UseRenderDataResult<T> {
                 return;
             }
 
+            setParentOrigin((current) => current ?? event.origin);
+
             if (!event.data.payload || typeof event.data.payload !== "object") {
                 const errorMsg = "Invalid payload structure received";
                 setError(errorMsg);
@@ -88,5 +95,6 @@ export function useRenderData<T = unknown>(): UseRenderDataResult<T> {
         data,
         isLoading,
         error,
+        parentOrigin,
     };
 }