@assistant-ui/mcp-docs-server 0.1.33 → 0.1.34

package/.docs/raw/docs/runtimes/langgraph/tutorial/part-2.mdx

@@ -94,14 +94,14 @@ This simply displays the tool name and arguments passed to it, but not the resul
 
 import { Thread } from "@/components/assistant-ui/thread";
 import { PriceSnapshotToolUI } from "@/components/tools/price-snapshot/PriceSnapshotTool";
-import { AuiProvider, Tools, type Toolkit, useAui } from "@assistant-ui/react";
+import { AuiProvider, defineToolkit, Tools, useAui } from "@assistant-ui/react";
 
-const toolkit = {
+const toolkit = defineToolkit({
   price_snapshot: {
     type: "backend",
     render: PriceSnapshotToolUI,
   },
-} satisfies Toolkit;
+});
 
 export default function Home() {
   const aui = useAui({ tools: Tools({ toolkit }) });
@@ -326,12 +326,12 @@ export const ToolFallback: ToolCallMessagePartComponent = ({
 ### Bind fallback UI
 
 ```tsx title="@/app/page.tsx"
-const toolkit = {
+const toolkit = defineToolkit({
   price_snapshot: {
     type: "backend",
     render: PriceSnapshotToolUI,
   },
-} satisfies Toolkit;
+});
 
 export default function Home() {
   const aui = useAui({ tools: Tools({ toolkit }) });

package/.docs/raw/docs/runtimes/langgraph/tutorial/part-3.mdx

@@ -212,9 +212,9 @@ export function TransactionConfirmationPending(props: TransactionConfirmation) {
 import { Thread } from "@/components/assistant-ui/thread";
 import { PriceSnapshotToolUI } from "@/components/tools/price-snapshot/PriceSnapshotTool";
 import { PurchaseStockToolUI } from "@/components/tools/purchase-stock/PurchaseStockTool";
-import { AuiProvider, Tools, type Toolkit, useAui } from "@assistant-ui/react";
+import { AuiProvider, defineToolkit, Tools, useAui } from "@assistant-ui/react";
 
-const toolkit = {
+const toolkit = defineToolkit({
   price_snapshot: {
     type: "backend",
     render: PriceSnapshotToolUI,
@@ -223,7 +223,7 @@ const toolkit = {
     type: "backend",
     render: PurchaseStockToolUI,
   },
-} satisfies Toolkit;
+});
 
 export default function Home() {
   const aui = useAui({ tools: Tools({ toolkit }) });

package/.docs/raw/docs/tools/backend.mdx

@@ -1,6 +1,6 @@
 ---
 title: Backend Tools
-description: Wire assistant-ui toolkits into your server with the AI SDK — generativeTools, frontendTools, mixing client and server tools, and multi-modal results.
+description: Wire assistant-ui toolkits into your server with the AI SDK — AISDKToolkit, frontendTools, mixing client and server tools, and multi-modal results.
 platforms: ["react"]
 ---
 
@@ -24,16 +24,18 @@ const {
 } = await req.json();
 ```
 
-## Generative toolkits: `generativeTools`
+## Generative toolkits: `AISDKToolkit`
 
-When you author tools in a [`"use generative"` file](/docs/tools/defining-tools#quick-start-use-generative), the same import resolves to the **server build** inside a route handler — schema plus any backend `execute`, with renderers stripped. Pass it to `generativeTools` together with the uploaded `tools`:
+When you author tools in a [`"use generative"` file](/docs/tools/defining-tools#quick-start-use-generative), the same import resolves to the **server build** inside a route handler — schema plus any backend `execute`, with renderers stripped. Wrap it in an `AISDKToolkit` and call `.tools()` with the uploaded `tools`:
 
 ```ts title="app/api/chat/route.ts"
-import { generativeTools } from "@assistant-ui/react-ai-sdk";
+import { AISDKToolkit } from "@assistant-ui/react-ai-sdk";
 import { streamText, convertToModelMessages, type UIMessage } from "ai";
 import { openai } from "@ai-sdk/openai";
 import toolkit from "../../toolkit";
 
+const aiToolkit = new AISDKToolkit({ toolkit });
+
 export async function POST(req: Request) {
   const { messages, system, tools } = await req.json();
 
@@ -41,24 +43,29 @@ export async function POST(req: Request) {
     model: openai("gpt-5.4-nano"),
     system,
     messages: await convertToModelMessages(messages),
-    tools: generativeTools({ toolkit, frontendTools: tools }),
+    tools: await aiToolkit.tools({ frontend: tools }),
   });
 
   return result.toUIMessageStreamResponse();
 }
 ```
 
-`generativeTools` registers every toolkit tool with the model using its schema, wires the backend `execute` where the server build carries one, and merges in the uploaded `frontendTools`. A server `execute` wins over an uploaded entry of the same name. Frontend and human tools (no server `execute`) are exposed schema-only and left for the client and the user to fulfill.
+`AISDKToolkit.tools()` registers every toolkit tool with the model using its schema, wires the backend `execute` where the server build carries one, and merges in the uploaded frontend tools. A server `execute` wins over an uploaded entry of the same name. Frontend and human tools (no server `execute`) are exposed schema-only and left for the client and the user to fulfill.
 
 <Callout type="info">
-  If your toolkit spreads in MCP server tools (`defineMcpToolkit`), use
-  `new AISDKToolkit({ toolkit }).tools({ frontend })` instead of
-  `generativeTools` — it also opens the MCP connections. See [MCP](/docs/tools/mcp).
+  If your toolkit spreads in MCP server tools (`defineMcpToolkit`), `.tools()`
+  also opens those connections. A module-scope `aiToolkit` pools them across
+  requests; see [MCP](/docs/tools/mcp) for the connection lifecycle and when to
+  call `aiToolkit.close()`. The older
+  `generativeTools({ toolkit, frontendTools })` is deprecated, MCP-less, and
+  superseded by `AISDKToolkit`.
 </Callout>
 
 ## Client-defined tools: `frontendTools`
 
-If you don't use the generative compiler — for example a plain [`satisfies Toolkit`](/docs/tools/defining-tools#render-only-tools-for-externally-executed-tools) with browser-executed tools — the AI SDK adapter still serializes those tools into the request `tools`. Convert them to the AI SDK shape with `frontendTools` and spread your own server tools alongside:
+If a toolkit cannot go through the generative compiler, the AI SDK adapter still
+serializes browser-executed tools into the request `tools`. Convert them to the
+AI SDK shape with `frontendTools` and spread your own server tools alongside:
 
 ```ts title="app/api/chat/route.ts"
 import { frontendTools } from "@assistant-ui/react-ai-sdk";
@@ -86,7 +93,8 @@ export async function POST(req: Request) {
 }
 ```
 
-`generativeTools` calls `frontendTools` for you under the hood; reach for `frontendTools` directly when you're not on the generative build.
+`AISDKToolkit.tools()` calls `frontendTools` for you under the hood; reach for
+`frontendTools` directly when you're not on the generative build.
 
 <Callout type="tip">
   `toToolsJSONSchema` emits the uploaded tools in alphabetical order, so two

package/.docs/raw/docs/tools/defining-tools.mdx

@@ -8,23 +8,25 @@ Tools let the model take actions: fetch data, call an API, query a database, dri
 
 This page covers how to **author** tools. To render a tool call as a custom component, see [Tool UI](/docs/tools/tool-ui). To wire tools into your server, see [Backend tools](/docs/tools/backend).
 
-## Two ways to define a toolkit
+## Define tools with `"use generative"`
 
-There are two authoring models. Most apps use the first; the second is for attaching UI to tools that execute somewhere you don't control.
+Use `"use generative"` + `defineToolkit` for toolkits. The compiler co-locates
+the schema, executor, and renderer in one file and splits them across the
+client/server boundary for you.
 
 <Callout type="info">
-  **Use `"use generative"` + `defineToolkit`** when you author the tool's
-  behavior yourself (it runs in the browser or in your own backend code). The
-  compiler co-locates the schema, the executor, and the renderer in one file and
-  splits them across the client/server boundary for you.
-
-  **Use a plain `satisfies Toolkit` object** when the tool already executes
-  elsewhere — an MCP server, a separate backend route, a LangGraph node — and you
-  only want to attach a renderer. These are render-only entries with an explicit
-  `type`.
+  You can still use the generative toolkit pattern when a tool executes
+  elsewhere:
+
+  - for MCP servers, spread `defineMcpToolkit({ ... })`;
+  - for non-MCP tools defined by another backend or runtime, write
+    `execute: externalTool()` and provide a renderer.
 </Callout>
 
-The difference matters because of one rule: **in a `"use generative"` file every tool must declare an `execute`, and you never write `type` yourself** — the compiler infers it. A render-only `{ type: "backend", render }` entry (no `execute`) is a plain-toolkit construct and will **not** compile inside a `"use generative"` file.
+In a `"use generative"` file every tool declares an `execute`, and you never
+write `type` yourself — the compiler infers it. For render-only external tools,
+`externalTool()` is the escape hatch that satisfies the compiler without
+emitting schema or executable code on the server.
 
 ## Quick start (`"use generative"`)
 
@@ -55,6 +57,17 @@ export default defineConfig({
 });
 ```
 
+For Expo, wrap your Metro config with `withAui`:
+
+```js title="metro.config.js"
+const { getDefaultConfig } = require("expo/metro-config");
+const { withAui } = require("@assistant-ui/metro");
+
+module.exports = withAui(getDefaultConfig(__dirname));
+```
+
+For a bare React Native app, import `getDefaultConfig` from `@react-native/metro-config` instead of `expo/metro-config`.
+
 </Step>
 <Step>
 
@@ -128,21 +141,23 @@ export function MyRuntimeProvider({ children }: { children: React.ReactNode }) {
 
 ### Expose the toolkit to the model on your server
 
-The same import resolves to the **server build** inside a route handler. Pass it to `generativeTools` so the model is configured with every tool's schema:
+The same import resolves to the **server build** inside a route handler. Wrap it in an `AISDKToolkit` so the model is configured with every tool's schema:
 
 ```ts title="app/api/chat/route.ts"
-import { generativeTools } from "@assistant-ui/react-ai-sdk";
+import { AISDKToolkit } from "@assistant-ui/react-ai-sdk";
 import { streamText, convertToModelMessages } from "ai";
 import { openai } from "@ai-sdk/openai";
 import toolkit from "../../toolkit";
 
+const aiToolkit = new AISDKToolkit({ toolkit });
+
 export async function POST(req: Request) {
   const { messages, tools } = await req.json();
 
   const result = streamText({
     model: openai("gpt-5.4-nano"),
     messages: await convertToModelMessages(messages),
-    tools: generativeTools({ toolkit, frontendTools: tools }),
+    tools: await aiToolkit.tools({ frontend: tools }),
   });
 
   return result.toUIMessageStreamResponse();
@@ -164,9 +179,10 @@ The tool's **kind is inferred from its `execute`** and written back as a `type`
 | --- | --- | --- | --- |
 | plain `async () => …` | **backend** | schema + `execute` (guarded `server-only`) | schema + `render` |
 | `async () => { "use client"; … }` | **frontend** | schema only | schema + `execute` + `render`/`renderText` |
-| `hitlTool()` | **human** | schema only | schema + `render` |
+| `humanTool()` | **human** | schema only | schema + `render` |
 | `stubTool()` | **frontend** (executor supplied at runtime) | schema only | schema + `render`/`renderText` |
 | `providerTool({ … })` | **provider** | schema + provider config | schema + provider config |
+| `externalTool()` | **backend** (defined elsewhere) | omitted | `type: "backend"` + `render`/`renderText` |
 
 The compiler also enforces, at build time:
 
@@ -176,6 +192,26 @@ The compiler also enforces, at build time:
 
 ## Tool kinds
 
+### Backend tools
+
+Run on your server. Author a plain `execute` (no `"use client"`); the compiler moves it to the server build behind `import "server-only"` and keeps only the schema and `render` on the client. A backend tool can still carry a `render` to show its call as a trace:
+
+```tsx
+geocode_location: {
+  description: "Geocode a location name into latitude/longitude.",
+  parameters: z.object({ query: z.string() }),
+  execute: async ({ query }) => geocodeLocation(query),
+  render: GeocodeToolUI,
+},
+```
+
+<Callout type="tip">
+  A backend tool authored this way **has** an `execute`. To attach a renderer to
+  a tool whose execution lives entirely elsewhere (an MCP server, a different
+  backend route) — where there is no real executor to write — use
+  `externalTool()` or `defineMcpToolkit()`.
+</Callout>
+
 ### Frontend tools
 
 Run in the browser. Author a real `execute` with a leading `"use client"`:
@@ -196,35 +232,15 @@ copy_to_clipboard: {
 },
 ```
 
-### Backend tools
-
-Run on your server. Author a plain `execute` (no `"use client"`); the compiler moves it to the server build behind `import "server-only"` and keeps only the schema and `render` on the client. A backend tool can still carry a `render` to show its call as a trace:
-
-```tsx
-geocode_location: {
-  description: "Geocode a location name into latitude/longitude.",
-  parameters: z.object({ query: z.string() }),
-  execute: async ({ query }) => geocodeLocation(query),
-  render: GeocodeToolUI,
-},
-```
-
-<Callout type="tip">
-  A backend tool authored this way **has** an `execute`. To attach a renderer to
-  a tool whose execution lives entirely elsewhere (an MCP server, a different
-  backend route) — where there is no `execute` to write — use a [plain
-  toolkit](#render-only-tools-for-externally-executed-tools) instead.
-</Callout>
-
 ### Human tools
 
-Pause the run until the user supplies a result through the rendered UI. Author `execute: hitlTool()` and a `render` that calls `addResult` exactly once:
+Pause the run until the user supplies a result through the rendered UI. Author `execute: humanTool()` and a `render` that calls `addResult` exactly once:
 
 ```tsx
 select_date: {
   description: "Ask the user to select a date.",
   parameters: z.object({ prompt: z.string() }),
-  execute: hitlTool(),
+  execute: humanTool(),
   render: ({ args, result, addResult }) => {
     if (result) return <p>Selected {result.date}</p>;
     return (
@@ -237,7 +253,7 @@ select_date: {
 },
 ```
 
-`hitlTool` is imported from `@assistant-ui/react`. See [Tool UI → Human-in-the-loop](/docs/tools/tool-ui#user-input-collection) for the full pattern.
+`humanTool` is imported from `@assistant-ui/react`. See [Tool UI → Human-in-the-loop](/docs/tools/tool-ui#user-input-collection) for the full pattern.
 
 ### Provider tools
 
@@ -252,9 +268,68 @@ web_search: {
 },
 ```
 
-### Dynamic (stateful) tools
+### Externally defined tools
+
+Use `externalTool()` when a non-MCP tool is already defined and executed by
+another system (for example a separate backend route or LangGraph node), but you
+want assistant-ui to render its tool calls. Import `externalTool` from
+`@assistant-ui/react`:
+
+```tsx
+web_search: {
+  parameters: z.object({ query: z.string() }),
+  execute: externalTool(),
+  render: ({ args, result }) => (
+    <SearchResults query={args.query} results={result?.results ?? []} />
+  ),
+},
+```
+
+The compiler omits this entry from the server build, so the model still gets
+the tool definition from the external system. The client build keeps only
+`type: "backend"` and the renderer (or `renderText`) for matching tool-call
+message parts.
 
-When a tool's executor must close over React state, declare its contract with `execute: stubTool()` and supply the real executor at runtime with `useAuiToolOverrides`. See [Dynamic tools](/docs/tools/dynamic-tools).
+### Tool stubs (supply the executor elsewhere)
+
+Sometimes a tool's executor can't live in the build-split `"use generative"` file, usually because it has to close over React state (a `useState` setter, a ref). Declare the model-facing contract with `execute: stubTool()`, then supply the real executor at runtime with `useAuiToolOverrides` from the component that owns the state:
+
+```tsx title="app/toolkit.tsx"
+"use generative";
+
+import { defineToolkit, stubTool } from "@assistant-ui/react";
+import { manageTasksParameters } from "./state";
+
+export default defineToolkit({
+  manage_tasks: {
+    description: "Add, toggle, or clear tasks on the board.",
+    parameters: manageTasksParameters,
+    execute: stubTool(),
+    renderText: { running: "Updating tasks…", complete: "Tasks updated" },
+  },
+});
+```
+
+```tsx title="app/TaskBoard.tsx"
+import { useAuiToolOverrides } from "@assistant-ui/react";
+
+function TaskBoardToolOverrides({ setTasks }) {
+  useAuiToolOverrides({
+    manage_tasks: {
+      execute: async ({ action, title }) => {
+        // close over setTasks here, then return a payload for the model
+      },
+    },
+  });
+  return null;
+}
+```
+
+`stubTool()` has no runtime implementation: it marks the executor as supplied later, while the compiler still ships the schema to the backend so the model can call the tool. The override registers above the toolkit default, so its `execute` wins for that name. To turn a tool off at runtime instead, see [Disabling a tool](#disabling-a-tool). See [Dynamic tools](/docs/tools/dynamic-tools) for the full walkthrough.
+
+<Callout type="warn">
+  `useAuiToolOverrides` is experimental and its API may change.
+</Callout>
 
 ## Rendering a tool call
 
@@ -271,29 +346,32 @@ If you don't provide a renderer, add the [`ToolFallback`](/docs/ui/tool-fallback
 
 ## Render-only tools (for externally-executed tools)
 
-When the tool already runs somewhere you don't control — an MCP server, a separate backend route, a LangGraph node — there is no `execute` to author. Declare a **plain** toolkit (a `"use client"` file, no `"use generative"`, no `defineToolkit`) with an explicit `type: "backend"` and only a `render`:
+Prefer `"use generative"` with `externalTool()` for non-MCP tools, or
+`defineMcpToolkit()` for MCP servers. If a file cannot go through the generative
+compiler, declare a `"use client"` toolkit object with an explicit
+`type: "backend"` and only a `render`:
 
 ```tsx title="app/tool-ui.tsx"
 "use client";
 
-import type { Toolkit } from "@assistant-ui/react";
+import { defineToolkit } from "@assistant-ui/react";
 
-export const toolkit = {
+export const toolkit = defineToolkit({
   web_search: {
     type: "backend",
     render: ({ args, result }) => (
       <SearchResults query={args.query} results={result?.results ?? []} />
     ),
   },
-} satisfies Toolkit;
+});
 ```
 
 Register it exactly like a generative toolkit: `useAui({ tools: Tools({ toolkit }) })`. The key must match the tool name your backend or MCP server publishes. Render-only entries upload no schema and run no browser code — they only attach UI to matching tool-call message parts.
 
 <Callout type="warn">
-  This `{ type: "backend", render }` shape is **plain-toolkit only**. Putting it
-  inside a `"use generative"` file is a compile error — a generative tool must
-  declare an `execute`, and you never author `type` there.
+  This `{ type: "backend", render }` shape is **plain-toolkit only**. Inside a
+  `"use generative"` file, use `execute: externalTool()` instead; generative
+  tools must declare an `execute`, and you never author `type` there.
 </Callout>
 
 ## Organizing toolkits
@@ -311,12 +389,28 @@ export type GetWeatherArgs = z.infer<typeof getWeatherParameters>;
 
 ### Split tools across files and merge them
 
+Each file you split into is its own `"use generative"` module that default-exports a `defineToolkit(...)`:
+
+```tsx title="app/tools/weather.tsx"
+"use generative";
+
+import { defineToolkit } from "@assistant-ui/react";
+
+export default defineToolkit({
+  get_weather: {
+    /* description, parameters, execute, render */
+  },
+});
+```
+
+Merge them by spreading their default imports into a parent toolkit:
+
 ```tsx title="app/toolkit.tsx"
 "use generative";
 
 import { defineToolkit } from "@assistant-ui/react";
-import { weatherTools } from "./tools/weather";
-import { databaseTools } from "./tools/database";
+import weatherTools from "./tools/weather";
+import databaseTools from "./tools/database";
 
 export default defineToolkit({
   ...weatherTools,
@@ -324,11 +418,26 @@ export default defineToolkit({
 });
 ```
 
-Only spreads the compiler can see through are allowed — a local `defineToolkit(...)` / `defineMcpToolkit(...)` binding, or an inline `...defineMcpToolkit({ … })`. Spreading an opaque import is rejected, because the compiler can't verify a backend `execute` won't leak to the client.
+The compiler splits each file across the client/server boundary on its own, then checks that the spread import resolves to a `"use generative"` module before allowing it, so a backend `execute` can't leak to the client. Two rules follow:
+
+- **Spread a default import** (`import weatherTools from "./tools/weather"`). Relative paths and `tsconfig` path aliases like `@/tools/weather` both resolve. Only the default export crosses the generative-module boundary, so a named import (or any opaque, non-generative import) is rejected.
+- You can also spread a local `defineToolkit(...)` or `defineMcpToolkit(...)` binding declared in the same file.
 
 ### Add MCP server tools
 
-Spread `defineMcpToolkit` to expose tools from an MCP server alongside your own:
+`defineMcpToolkit` exposes tools from an MCP server. For an MCP-only toolkit, export it directly:
+
+```tsx title="app/mcp-toolkit.tsx"
+"use generative";
+
+import { defineMcpToolkit } from "@assistant-ui/react";
+
+export default defineMcpToolkit({
+  docs: { type: "http", url: "https://mcp.example.com/mcp" },
+});
+```
+
+To expose MCP tools alongside your own, spread it into a `defineToolkit`:
 
 ```tsx
 "use generative";
@@ -339,6 +448,7 @@ export default defineToolkit({
   ...defineMcpToolkit({
     docs: { type: "http", url: "https://mcp.example.com/mcp" },
   }),
+  // ...your own tools
 });
 ```
 
@@ -408,6 +518,21 @@ While a tool runs, its arguments arrive as partial JSON. Use [`useToolArgsStatus
 
 Set `disabled: true` to keep a tool known to the client but hidden from the model in the current scope.
 
+To toggle a tool off at runtime without editing the toolkit, register the same flag through `useAuiToolOverrides`:
+
+```tsx
+import { useAuiToolOverrides } from "@assistant-ui/react";
+
+function GuestModeTools() {
+  useAuiToolOverrides({
+    delete_account: { disabled: true },
+  });
+  return null;
+}
+```
+
+The override registers above the toolkit default, so the tool drops out of the set sent to the model. Mount the override only while the tool should be hidden (for example, for signed-out users); unmounting it restores the toolkit default.
+
 ## Migrating from the component APIs
 
 `makeAssistantTool`, `useAssistantTool`, `makeAssistantToolUI`, and `useAssistantToolUI` are deprecated. See [Migrating Tools to Toolkits](/docs/migrations/toolkit-tools) for the mechanical migration.

package/.docs/raw/docs/tools/index.mdx

@@ -13,7 +13,7 @@ Tools are how the model takes action: fetch data, call an API, query a database,
     Author a toolkit with the `"use generative"` directive — frontend, backend, human, and provider tools, with the schema, executor, and renderer in one file.
   </Card>
   <Card title="Backend Tools" href="/docs/tools/backend">
-    Wire a toolkit into your AI SDK route with `generativeTools` / `frontendTools`, mix client and server tools, and round-trip multi-modal results.
+    Wire a toolkit into your AI SDK route with `AISDKToolkit` / `frontendTools`, mix client and server tools, and round-trip multi-modal results.
   </Card>
   <Card title="Tool UI" href="/docs/tools/tool-ui">
     Render tool calls as custom components — loading and result states, human-in-the-loop, approvals, and streaming.
@@ -23,22 +23,17 @@ Tools are how the model takes action: fetch data, call an API, query a database,
   </Card>
 </Cards>
 
-## Two ways to define a toolkit
+## Define tools with `"use generative"`
 
 <Callout type="info">
-  **`"use generative"` + `defineToolkit`** — for tools you author yourself
-  (browser or your own backend). The compiler co-locates the schema, executor,
-  and renderer in one file and splits them across the client/server boundary.
-
-  **Plain `satisfies Toolkit`** — for tools that already execute elsewhere (an
-  MCP server, a separate backend route, a LangGraph node) where you only attach a
-  renderer.
+  Use `"use generative"` + `defineToolkit` for toolkits. For tools that execute
+  elsewhere, spread `defineMcpToolkit({ ... })` for MCP servers or use
+  `execute: externalTool()` to attach a renderer to a non-MCP external tool.
 </Callout>
 
 In a `"use generative"` file every tool declares an `execute` and the kind is
-**inferred** from it (you never write `type`). In a plain toolkit you author
-`type` and write render-only `{ type: "backend", render }` entries. See
-[Defining Tools](/docs/tools/defining-tools#two-ways-to-define-a-toolkit).
+**inferred** from it (you never write `type`). See
+[Defining Tools](/docs/tools/defining-tools#define-tools-with-use-generative).
 
 ## Rendering AI output as UI