@tanstack/ai-react 0.27.3 → 0.29.1

package/src/use-web-mcp-tools.ts

@@ -1,13 +1,14 @@
-import { useEffect } from 'react'
-import { registerWebMCPTools } from '@tanstack/ai-client'
+import { useEffect, useRef, useState } from 'react'
+import { registerWebMCPTools, subscribeWebMCPTools } from '@tanstack/ai-client'
 import type {
   AnyClientTool,
   InferredClientContext,
   RegisterWebMCPToolsOptions,
+  SubscribeWebMCPToolsOptions,
 } from '@tanstack/ai-client'
 
-/** Options for the React {@link useWebMCPTools} lifecycle hook. */
-export type UseWebMCPToolsOptions<
+/** Options for the React {@link useRegisterWebMCPTools} lifecycle hook. */
+export type UseRegisterWebMCPToolsOptions<
   TTools extends ReadonlyArray<AnyClientTool>,
   TContext = InferredClientContext<TTools>,
 > = Omit<RegisterWebMCPToolsOptions<TTools, TContext>, 'signal'> & {
@@ -15,13 +16,19 @@ export type UseWebMCPToolsOptions<
   onError?: (error: unknown) => void
 }
 
-type UseWebMCPToolsArguments<
+/** @deprecated Use `UseRegisterWebMCPToolsOptions`. Removed in 1.0.0. */
+export type UseWebMCPToolsOptions<
+  TTools extends ReadonlyArray<AnyClientTool>,
+  TContext = InferredClientContext<TTools>,
+> = UseRegisterWebMCPToolsOptions<TTools, TContext>
+
+type UseRegisterWebMCPToolsArguments<
   TTools extends ReadonlyArray<AnyClientTool>,
   TContext,
 > =
   RegisterWebMCPToolsOptions<TTools, TContext> extends { context: unknown }
-    ? [options: UseWebMCPToolsOptions<TTools, TContext>]
-    : [options?: UseWebMCPToolsOptions<TTools, TContext>]
+    ? [options: UseRegisterWebMCPToolsOptions<TTools, TContext>]
+    : [options?: UseRegisterWebMCPToolsOptions<TTools, TContext>]
 
 /**
  * Registers client tools with WebMCP for the lifetime of a React component.
@@ -34,15 +41,18 @@ type UseWebMCPToolsArguments<
  *
  * @example
  * ```tsx
- * useWebMCPTools([searchProducts], {
+ * useRegisterWebMCPTools([searchProducts], {
  *   toolOptions: { searchProducts: { title: 'Search products' } },
  * })
  * ```
  */
-export function useWebMCPTools<
+export function useRegisterWebMCPTools<
   const TTools extends ReadonlyArray<AnyClientTool>,
   TContext = InferredClientContext<TTools>,
->(tools: TTools, ...[options]: UseWebMCPToolsArguments<TTools, TContext>) {
+>(
+  tools: TTools,
+  ...[options]: UseRegisterWebMCPToolsArguments<TTools, TContext>
+) {
   useEffect(() => {
     const controller = new AbortController()
     const { onError, ...registrationOptions } = options ?? {}
@@ -57,3 +67,52 @@ export function useWebMCPTools<
     return () => controller.abort()
   }, [tools, options])
 }
+
+/**
+ * @deprecated Use `useRegisterWebMCPTools`. Removed in 1.0.0.
+ * @alias
+ */
+export const useWebMCPTools = useRegisterWebMCPTools
+
+/** Options for {@link usePageWebMCPTools}. */
+export type UsePageWebMCPToolsOptions = Omit<
+  SubscribeWebMCPToolsOptions,
+  'signal'
+>
+
+/**
+ * Returns the WebMCP tools on the page as client tools for `useChat`.
+ *
+ * The list starts empty and updates when the page registers or removes a
+ * tool. The hook reads the latest `filter` and `onError` on each update.
+ * Unsupported browsers and server rendering return an empty array.
+ *
+ * @param options - A filter that skips tools, and an error callback.
+ *
+ * @example
+ * ```tsx
+ * const pageTools = usePageWebMCPTools({
+ *   filter: (tool) => tool.origin === location.origin,
+ * })
+ * const chat = useChat({ connection, tools: pageTools })
+ * ```
+ */
+export function usePageWebMCPTools(
+  options?: UsePageWebMCPToolsOptions,
+): Array<AnyClientTool> {
+  const [tools, setTools] = useState<Array<AnyClientTool>>([])
+  const optionsRef = useRef(options)
+  optionsRef.current = options
+
+  useEffect(() => {
+    const controller = new AbortController()
+    subscribeWebMCPTools(setTools, {
+      signal: controller.signal,
+      filter: (tool) => optionsRef.current?.filter?.(tool) ?? true,
+      onError: (error) => optionsRef.current?.onError?.(error),
+    })
+    return () => controller.abort()
+  }, [])
+
+  return tools
+}