feat: add WebMCP client tool registration

.changeset/webmcp-tools.md

@@ -0,0 +1,13 @@
+---
+'@tanstack/ai-client': minor
+'@tanstack/ai-react': minor
+'@tanstack/ai-preact': minor
+'@tanstack/ai-solid': minor
+'@tanstack/ai-vue': minor
+'@tanstack/ai-svelte': minor
+'@tanstack/ai-angular': minor
+'@tanstack/ai-octane': minor
+'@tanstack/ai-remix': minor
+---
+
+Add the `registerWebMCPTools` registrar to `@tanstack/ai-client`. Each framework package adds a lifecycle wrapper through `useWebMCPTools`, `createWebMCPTools`, or `injectWebMCPTools`.

docs/api/ai-angular.md

@@ -25,6 +25,37 @@ angular: @tanstack/ai-angular
 
 <!-- ::end:tabs -->
 
+## `injectWebMCPTools(tools, options?)`
+
+Register executable client tools for the current Angular injection owner. Angular removes them when it destroys that owner.
+
+For a complete setup and behavior guide, see [WebMCP Tools](../tools/webmcp).
+
+```typescript
+import { Component } from "@angular/core";
+import {
+  injectWebMCPTools,
+  type InjectWebMCPToolsOptions,
+} from "@tanstack/ai-angular";
+import { searchProducts } from "./tools";
+
+const tools = [searchProducts];
+const options: InjectWebMCPToolsOptions<typeof tools> = {
+  onError(error) {
+    console.error(error);
+  },
+};
+
+@Component({ selector: "app-products", standalone: true, template: "" })
+export class ProductsComponent {
+  registration = injectWebMCPTools(tools, options);
+}
+```
+
+`InjectWebMCPToolsOptions<TTools, TContext>` contains `toolOptions`, `context`, and `onError`. The injectable owns the registration signal.
+
+The `context` field is required when a tool declares a required runtime context. Call this function only in an Angular injection context.
+
 ## `injectChat(options?)`
 
 Main injectable for managing chat state in Angular with full type safety.

docs/api/ai-client.md

@@ -32,6 +32,50 @@ octane: @tanstack/ai-client
 
 <!-- ::end:tabs -->
 
+## `registerWebMCPTools(tools, options)`
+
+Expose executable client tools through the browser WebMCP API. Abort the required signal to remove all tools from this registration.
+
+For a complete setup and behavior guide, see [WebMCP Tools](../tools/webmcp).
+
+```typescript
+import {
+  registerWebMCPTools,
+  type RegisterWebMCPToolsOptions,
+} from "@tanstack/ai-client";
+import { searchProducts } from "./tools";
+
+const controller = new AbortController();
+const tools = [searchProducts];
+const options: RegisterWebMCPToolsOptions<typeof tools> = {
+  signal: controller.signal,
+  toolOptions: {
+    searchProducts: {
+      title: "Search products",
+      annotations: { readOnlyHint: true },
+    },
+  },
+};
+
+await registerWebMCPTools(tools, options);
+
+// Remove these tools when their owner is no longer active.
+controller.abort();
+```
+
+The function returns `Promise<void>`. It resolves without registration during server rendering, in an insecure context, or when WebMCP is unavailable.
+
+It validates Standard Schema inputs and outputs. A tool with `needsApproval: true` causes registration to fail.
+
+### Public option types
+
+- `RegisterWebMCPToolsOptions<TTools, TContext>` - Requires `signal`. It also contains `toolOptions` and the client tool runtime `context`.
+- `WebMCPToolOptionsByName<TTools>` - A partial options map keyed by the inferred tool names.
+- `WebMCPToolOptions` - Contains the optional `title` and `annotations` fields for one tool.
+- `WebMCPToolAnnotations` - Contains the optional `readOnlyHint` and `untrustedContentHint` fields.
+
+`context` is required when a tool declares a required runtime context. If registration fails, the function removes tools that it registered during the call.
+
 ## `ChatClient`
 
 The main client class for managing chat state.

docs/api/ai-octane.md

@@ -24,6 +24,36 @@ octane: @tanstack/ai-octane octane
 
 `octane` is a required peer. This package publishes uncompiled source, like Svelte packages that ship `.svelte`.
 
+## `useWebMCPTools(tools, options?)`
+
+Register executable client tools after the Octane component mounts. Octane removes them on cleanup and replaces them when `tools` or `options` change.
+
+For a complete setup and behavior guide, see [WebMCP Tools](../tools/webmcp).
+
+```tsx
+import {
+  useWebMCPTools,
+  type UseWebMCPToolsOptions,
+} from '@tanstack/ai-octane'
+import { searchProducts } from './tools'
+
+const tools = [searchProducts]
+const options: UseWebMCPToolsOptions<typeof tools> = {
+  onError(error) {
+    console.error(error)
+  },
+}
+
+function ProductsPage() {
+  useWebMCPTools(tools, options)
+  return null
+}
+```
+
+`UseWebMCPToolsOptions<TTools, TContext>` contains `toolOptions`, `context`, and `onError`. The hook owns the registration signal.
+
+The `context` field is required when a tool declares a required runtime context. Keep `tools` and `options` stable when their values do not change.
+
 ## `useChat(options)`
 
 Manages chat state in an Octane component.

docs/api/ai-preact.md

@@ -22,6 +22,36 @@ preact: @tanstack/ai-preact
 
 <!-- ::end:tabs -->
 
+## `useWebMCPTools(tools, options?)`
+
+Register executable client tools after the Preact component mounts. Preact removes them on cleanup and replaces them when `tools` or `options` change.
+
+For a complete setup and behavior guide, see [WebMCP Tools](../tools/webmcp).
+
+```tsx
+import {
+  useWebMCPTools,
+  type UseWebMCPToolsOptions,
+} from "@tanstack/ai-preact";
+import { searchProducts } from "./tools";
+
+const tools = [searchProducts];
+const options: UseWebMCPToolsOptions<typeof tools> = {
+  onError(error) {
+    console.error(error);
+  },
+};
+
+function ProductsPage() {
+  useWebMCPTools(tools, options);
+  return null;
+}
+```
+
+`UseWebMCPToolsOptions<TTools, TContext>` contains `toolOptions`, `context`, and `onError`. The hook owns the registration signal.
+
+The `context` field is required when a tool declares a required runtime context. Keep `tools` and `options` stable when their values do not change.
+
 ## `useChat(options?)`
 
 Main hook for managing chat state in Preact with full type safety.

docs/api/ai-react.md

@@ -30,6 +30,36 @@ react: @tanstack/ai-react
 
 <!-- ::end:tabs -->
 
+## `useWebMCPTools(tools, options?)`
+
+Register executable client tools after the React component mounts. React removes them on cleanup and replaces them when `tools` or `options` change.
+
+For a complete setup and behavior guide, see [WebMCP Tools](../tools/webmcp).
+
+```tsx
+import {
+  useWebMCPTools,
+  type UseWebMCPToolsOptions,
+} from "@tanstack/ai-react";
+import { searchProducts } from "./tools";
+
+const tools = [searchProducts];
+const options: UseWebMCPToolsOptions<typeof tools> = {
+  onError(error) {
+    console.error(error);
+  },
+};
+
+function ProductsPage() {
+  useWebMCPTools(tools, options);
+  return null;
+}
+```
+
+`UseWebMCPToolsOptions<TTools, TContext>` contains `toolOptions`, `context`, and `onError`. The hook owns the registration signal.
+
+The `context` field is required when a tool declares a required runtime context. Keep `tools` and `options` stable when their values do not change.
+
 ## `createChatHook(options)`
 
 Bind `chatOptions` once at module scope. Call `useChat()` in the screen to create the instance. Per-call overrides may set `threadId`, `initialMessages`, `live`, and `forwardedProps`. They must not change `tools`, `interrupts`, or `outputSchema`.

docs/api/ai-remix.md

@@ -26,6 +26,40 @@ remix: @tanstack/ai-remix remix
 
 `remix` is a required peer.
 
+## `createWebMCPTools(handle, tools, options?)`
+
+Register executable client tools for a Remix component. Remix removes them when the component `Handle` signal aborts.
+
+For a complete setup and behavior guide, see [WebMCP Tools](../tools/webmcp).
+
+```tsx
+import {
+  createWebMCPTools,
+  type CreateWebMCPToolsOptions,
+} from '@tanstack/ai-remix'
+import { clientEntry, type Handle } from 'remix/ui'
+import { searchProducts } from './tools'
+
+const tools = [searchProducts]
+const options: CreateWebMCPToolsOptions<typeof tools> = {
+  onError(error) {
+    console.error(error)
+  },
+}
+
+export const ProductsPage = clientEntry(
+  import.meta.url,
+  function ProductsPage(handle: Handle) {
+    createWebMCPTools(handle, tools, options)
+    return () => null
+  },
+)
+```
+
+`CreateWebMCPToolsOptions<TTools, TContext>` contains `toolOptions`, `context`, and `onError`. The helper uses `handle.signal` for registration.
+
+The `context` field is required when a tool declares a required runtime context.
+
 ## Server
 
 A Remix controller action can return the same SSE `Response` as any other host.

docs/api/ai-solid.md

@@ -25,6 +25,36 @@ solid: @tanstack/ai-solid
 
 <!-- ::end:tabs -->
 
+## `useWebMCPTools(tools, options?)`
+
+Register executable client tools for the current Solid owner. Solid removes them when the owner is cleaned up.
+
+For a complete setup and behavior guide, see [WebMCP Tools](../tools/webmcp).
+
+```tsx
+import {
+  useWebMCPTools,
+  type UseWebMCPToolsOptions,
+} from "@tanstack/ai-solid";
+import { searchProducts } from "./tools";
+
+const tools = [searchProducts];
+const options: UseWebMCPToolsOptions<typeof tools> = {
+  onError(error) {
+    console.error(error);
+  },
+};
+
+function ProductsPage() {
+  useWebMCPTools(tools, options);
+  return null;
+}
+```
+
+`UseWebMCPToolsOptions<TTools, TContext>` contains `toolOptions`, `context`, and `onError`. The primitive owns the registration signal.
+
+The `context` field is required when a tool declares a required runtime context.
+
 ## `createChatHook(options)`
 
 Bind `chatOptions` once at module scope. Call `useChat()` in the screen to create the instance. Per-call overrides may set `threadId`, `initialMessages`, `live`, and `forwardedProps`. They must not change `tools`, `interrupts`, or `outputSchema`.

docs/api/ai-svelte.md

@@ -25,6 +25,35 @@ svelte: @tanstack/ai-svelte
 
 <!-- ::end:tabs -->
 
+## `createWebMCPTools(tools, options?)`
+
+Register executable client tools during Svelte component initialization. Svelte removes them when the component is destroyed.
+
+For a complete setup and behavior guide, see [WebMCP Tools](../tools/webmcp).
+
+```svelte
+<script lang="ts">
+  import {
+    createWebMCPTools,
+    type CreateWebMCPToolsOptions,
+  } from "@tanstack/ai-svelte";
+  import { searchProducts } from "./tools";
+
+  const tools = [searchProducts];
+  const options: CreateWebMCPToolsOptions<typeof tools> = {
+    onError(error) {
+      console.error(error);
+    },
+  };
+
+  createWebMCPTools(tools, options);
+</script>
+```
+
+`CreateWebMCPToolsOptions<TTools, TContext>` contains `toolOptions`, `context`, and `onError`. The factory owns the registration signal.
+
+The `context` field is required when a tool declares a required runtime context.
+
 ## `createChatHook(options)`
 
 Bind `chatOptions` once at module scope. Call `createChat()` to create the instance. Per-call overrides may set `threadId`, `initialMessages`, `live`, and `forwardedProps`. They must not change `tools`, `interrupts`, or `outputSchema`.

docs/api/ai-vue.md

@@ -25,6 +25,35 @@ vue: @tanstack/ai-vue
 
 <!-- ::end:tabs -->
 
+## `useWebMCPTools(tools, options?)`
+
+Register executable client tools for the current Vue scope. Vue removes them when the scope is disposed.
+
+For a complete setup and behavior guide, see [WebMCP Tools](../tools/webmcp).
+
+```vue
+<script setup lang="ts">
+import {
+  useWebMCPTools,
+  type UseWebMCPToolsOptions,
+} from "@tanstack/ai-vue";
+import { searchProducts } from "./tools";
+
+const tools = [searchProducts];
+const options: UseWebMCPToolsOptions<typeof tools> = {
+  onError(error) {
+    console.error(error);
+  },
+};
+
+useWebMCPTools(tools, options);
+</script>
+```
+
+`UseWebMCPToolsOptions<TTools, TContext>` contains `toolOptions`, `context`, and `onError`. The composable owns the registration signal.
+
+The `context` field is required when a tool declares a required runtime context.
+
 ## `createChatHook(options)`
 
 Bind `chatOptions` once at module scope. Call `useChat()` in the screen to create the instance. Per-call overrides may set `threadId`, `initialMessages`, `live`, and `forwardedProps`. They must not change `tools`, `interrupts`, or `outputSchema`.