Add support for MCP Apps capabilities and versioning (#56)

* Add host capabilities and version support, including new hooks and types for MCP Apps

* Add unit tests for MCP Apps API methods and enhance existing tests for adapters

* Enhance host capabilities across MCP and OpenAI adapters, adding comprehensive support for common and platform-specific features. Update tests to reflect new capabilities structure.

* Add core dependency and improve error handling in MCP and mock adapters

* Enhance MCP and OpenAI adapters to derive host capabilities from runtime context, including available display modes and dynamic feature detection. Update unit tests to validate new capability detection logic.

* Enhance README documentation to include host capabilities, bidirectional tools, and theme/style utilities for MCP applications. Update API sections with examples for new features.

* Improve error handling in McpAdapter for tool invocation, adding try-catch logic and informative error messages when no handler is registered or an error occurs.

Author: gabe4coding

packages/ui-react/README.md

@@ -28,6 +28,9 @@ React widgets often need host-aware APIs for tool calls and UI state. This packa
 - Hooks for tools, host context, and widget state
 - Typed tool calls with generics
 - Optional debug logger hook
+- **Host capabilities** - Query what the host supports (theming, display modes, file upload, etc.)
+- **Size notifications** - Automatic resize observer integration
+- **Partial tool input** - React to streaming tool inputs
 
 ## Compatibility
 
@@ -96,12 +99,109 @@ export function App() {
 
 ## API
 
-Key exports include:
+### Provider
 
-- `AppsProvider`
-- `useAppsClient`, `useToolResult`, `useHostContext`
-- `useToolInput`, `useWidgetState`, `useDebugLogger`
-- `useFileUpload`, `useFileDownload` (ChatGPT only)
+- `AppsProvider` - Context wrapper for all hooks
+
+### Core Hooks
+
+| Hook             | Description                               |
+| ---------------- | ----------------------------------------- |
+| `useAppsClient`  | Client instance for tool calls            |
+| `useToolResult`  | Current tool result data                  |
+| `useToolInput`   | Tool input parameters                     |
+| `useHostContext` | Host info (theme, viewport, locale, etc.) |
+| `useWidgetState` | Persisted state across reloads            |
+| `useDisplayMode` | Fullscreen/panel mode control             |
+| `useDebugLogger` | Debug logging configuration               |
+
+### Host Capabilities & Version
+
+```tsx
+import { useHostCapabilities, useHostVersion } from "@mcp-apps-kit/ui-react";
+
+function Widget() {
+  const capabilities = useHostCapabilities();
+  const version = useHostVersion();
+
+  // Common capabilities (both platforms)
+  const themes = capabilities?.theming?.themes; // ["light", "dark"]
+  const modes = capabilities?.displayModes?.modes; // ["inline", "fullscreen", "pip"]
+
+  // MCP Apps specific
+  const hasPartialInput = !!capabilities?.partialToolInput;
+
+  // ChatGPT specific
+  const hasFileUpload = !!capabilities?.fileUpload;
+
+  // Host version (MCP Apps only)
+  // { name: "Claude Desktop", version: "1.0.0" }
+  return <div>Host: {version?.name}</div>;
+}
+```
+
+### Size Notifications (MCP Apps)
+
+```tsx
+import { useSizeChangedNotifications } from "@mcp-apps-kit/ui-react";
+
+function Widget() {
+  // Attach to container to auto-report size changes
+  const containerRef = useSizeChangedNotifications();
+
+  return <div ref={containerRef}>Content that may resize</div>;
+}
+```
+
+### Partial Tool Input (MCP Apps)
+
+```tsx
+import { useOnToolInputPartial } from "@mcp-apps-kit/ui-react";
+
+function Widget() {
+  useOnToolInputPartial((input) => {
+    // React to streaming partial input from the model
+    console.log("Partial input:", input);
+  });
+
+  return <div>Streaming input widget</div>;
+}
+```
+
+### Theme & Style Hooks
+
+| Hook                    | Description                       |
+| ----------------------- | --------------------------------- |
+| `useHostStyleVariables` | Apply host-provided CSS variables |
+| `useDocumentTheme`      | Sync document theme with host     |
+| `useSafeAreaInsets`     | Safe area insets (ChatGPT)        |
+
+### Lifecycle Hooks
+
+| Hook                 | Description                            |
+| -------------------- | -------------------------------------- |
+| `useOnToolCancelled` | Callback when tool is cancelled        |
+| `useOnTeardown`      | Cleanup callback before widget removal |
+
+### File Operations (ChatGPT)
+
+| Hook              | Description            |
+| ----------------- | ---------------------- |
+| `useFileUpload`   | Upload files to host   |
+| `useFileDownload` | Get file download URLs |
+
+### Layout (ChatGPT)
+
+| Hook                 | Description                 |
+| -------------------- | --------------------------- |
+| `useIntrinsicHeight` | Set widget intrinsic height |
+| `useView`            | View management             |
+
+### Modals (ChatGPT)
+
+| Hook       | Description             |
+| ---------- | ----------------------- |
+| `useModal` | Modal dialog management |
 
 ## Contributing
 

packages/ui-react/src/hooks.ts

@@ -11,6 +11,8 @@ import type {
   ClientDebugConfig,
   ModalOptions,
   ModalResult,
+  HostCapabilities,
+  HostVersion,
 } from "@mcp-apps-kit/ui";
 import { clientDebugLogger, type ClientDebugLogger } from "@mcp-apps-kit/ui";
 import { useAppsContext } from "./context";
@@ -420,6 +422,172 @@ export function useOnTeardown(handler: (reason?: string) => void): void {
   }, [client, handler]);
 }
 
+/**
+ * Subscribe to partial/streaming tool input
+ *
+ * Called when the host sends partial tool arguments during streaming.
+ * Useful for showing real-time input as the user types or as the model generates.
+ *
+ * @param handler - Callback for partial input
+ *
+ * @example
+ * ```tsx
+ * function StreamingInput() {
+ *   const [partialInput, setPartialInput] = useState<Record<string, unknown>>({});
+ *
+ *   useOnToolInputPartial((input) => {
+ *     setPartialInput(input);
+ *   });
+ *
+ *   return <pre>{JSON.stringify(partialInput, null, 2)}</pre>;
+ * }
+ * ```
+ */
+export function useOnToolInputPartial(handler: (input: Record<string, unknown>) => void): void {
+  const { client } = useAppsContext();
+
+  useEffect(() => {
+    if (!client) return;
+
+    const unsubscribe = client.onToolInputPartial(handler);
+    return unsubscribe;
+  }, [client, handler]);
+}
+
+// =============================================================================
+// HOST INFORMATION HOOKS
+// =============================================================================
+
+/**
+ * Access host capabilities
+ *
+ * Returns the capabilities advertised by the host during handshake.
+ * Use this to check if features like logging or server tools are supported.
+ *
+ * @returns Host capabilities or undefined if not yet connected
+ *
+ * @example
+ * ```tsx
+ * function CapabilitiesDisplay() {
+ *   const capabilities = useHostCapabilities();
+ *
+ *   return (
+ *     <div>
+ *       <p>Logging: {capabilities?.logging ? "Supported" : "Not supported"}</p>
+ *       <p>Open Links: {capabilities?.openLinks ? "Supported" : "Not supported"}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useHostCapabilities(): HostCapabilities | undefined {
+  const { client } = useAppsContext();
+  const [capabilities, setCapabilities] = useState<HostCapabilities | undefined>(
+    client?.getHostCapabilities()
+  );
+
+  useEffect(() => {
+    if (!client) return;
+    setCapabilities(client.getHostCapabilities());
+  }, [client]);
+
+  return capabilities;
+}
+
+/**
+ * Access host version information
+ *
+ * Returns the name and version of the host application.
+ *
+ * @returns Host version info or undefined if not yet connected
+ *
+ * @example
+ * ```tsx
+ * function HostInfo() {
+ *   const hostVersion = useHostVersion();
+ *
+ *   if (!hostVersion) return <div>Loading...</div>;
+ *
+ *   return (
+ *     <div>
+ *       Running on {hostVersion.name} v{hostVersion.version}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useHostVersion(): HostVersion | undefined {
+  const { client } = useAppsContext();
+  const [version, setVersion] = useState<HostVersion | undefined>(client?.getHostVersion());
+
+  useEffect(() => {
+    if (!client) return;
+    setVersion(client.getHostVersion());
+  }, [client]);
+
+  return version;
+}
+
+// =============================================================================
+// SIZE NOTIFICATION HOOKS
+// =============================================================================
+
+/**
+ * Hook to set up automatic size change notifications
+ *
+ * Creates a ResizeObserver that automatically sends size changed
+ * notifications to the host when the observed element resizes.
+ *
+ * @returns Ref to attach to the element to observe
+ *
+ * @example
+ * ```tsx
+ * function AutoSizeWidget() {
+ *   const containerRef = useSizeChangedNotifications();
+ *
+ *   return (
+ *     <div ref={containerRef}>
+ *       <p>Content that may change size...</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useSizeChangedNotifications(): React.RefObject<HTMLElement | null> {
+  const { client } = useAppsContext();
+  const containerRef = useRef<HTMLElement | null>(null);
+
+  useEffect(() => {
+    if (!client || typeof ResizeObserver === "undefined") return;
+
+    const element = containerRef.current;
+    if (!element) return;
+
+    const observer = new ResizeObserver((entries) => {
+      for (const entry of entries) {
+        const { width, height } = entry.contentRect;
+        void client.sendSizeChanged({
+          width: Math.round(width),
+          height: Math.round(height),
+        });
+      }
+    });
+
+    observer.observe(element);
+
+    // Report initial size
+    const rect = element.getBoundingClientRect();
+    void client.sendSizeChanged({
+      width: Math.round(rect.width),
+      height: Math.round(rect.height),
+    });
+
+    return () => observer.disconnect();
+  }, [client]);
+
+  return containerRef;
+}
+
 // =============================================================================
 // FILE OPERATION HOOKS
 // =============================================================================

packages/ui-react/src/index.ts

@@ -5,7 +5,19 @@
  */
 
 // Re-export types from @mcp-apps-kit/ui
-export type { HostContext, ToolResult, AppsClient } from "@mcp-apps-kit/ui";
+export type {
+  HostContext,
+  ToolResult,
+  AppsClient,
+  // New MCP Apps API types
+  HostCapabilities,
+  HostVersion,
+  AppCapabilities,
+  SizeChangedParams,
+  AppToolDefinition,
+  CallToolHandler,
+  ListToolsHandler,
+} from "@mcp-apps-kit/ui";
 
 // Context (placeholder - will be implemented in Phase 6)
 export { AppsProvider } from "./context";
@@ -34,6 +46,11 @@ export {
   useModal,
   // Debug logging
   useDebugLogger,
+  // New MCP Apps API hooks
+  useOnToolInputPartial,
+  useHostCapabilities,
+  useHostVersion,
+  useSizeChangedNotifications,
 } from "./hooks";
 
 // File operation types