@fondation-io/ai 7.0.0-beta.45

package/docs/07-reference/01-ai-sdk-core/22-dynamic-tool.mdx

@@ -0,0 +1,223 @@
+---
+title: dynamicTool
+description: Helper function for creating dynamic tools with unknown types
+---
+
+# `dynamicTool()`
+
+The `dynamicTool` function creates tools where the input and output types are not known at compile time. This is useful for scenarios such as:
+
+- MCP (Model Context Protocol) tools without schemas
+- User-defined functions loaded at runtime
+- Tools loaded from external sources or databases
+- Dynamic tool generation based on user input
+
+Unlike the regular `tool` function, `dynamicTool` accepts and returns `unknown` types, allowing you to work with tools that have runtime-determined schemas.
+
+```ts highlight={"1,4,9,10,11"}
+import { dynamicTool } from 'ai';
+import { z } from 'zod';
+
+export const customTool = dynamicTool({
+  description: 'Execute a custom user-defined function',
+  inputSchema: z.object({}),
+  // input is typed as 'unknown'
+  execute: async input => {
+    const { action, parameters } = input as any;
+
+    // Execute your dynamic logic
+    return {
+      result: `Executed ${action} with ${JSON.stringify(parameters)}`,
+    };
+  },
+});
+```
+
+## Import
+
+<Snippet text={`import { dynamicTool } from "ai"`} prompt={false} />
+
+## API Signature
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'tool',
+      type: 'Object',
+      description: 'The dynamic tool definition.',
+      properties: [
+        {
+          type: 'Object',
+          parameters: [
+            {
+              name: 'description',
+              isOptional: true,
+              type: 'string',
+              description:
+                'Information about the purpose of the tool including details on how and when it can be used by the model.'
+            },
+            {
+              name: 'title',
+              isOptional: true,
+              type: 'string',
+              description:
+                'A human-readable title for the tool.'
+            },
+            {
+              name: 'needsApproval',
+              isOptional: true,
+              type: 'boolean | ((options: { args: unknown }) => boolean | Promise<boolean>)',
+              description:
+                'Whether the tool needs user approval before execution. Can be a boolean or a function that receives the tool arguments and returns a boolean.'
+            },
+            {
+              name: 'inputSchema',
+              type: 'FlexibleSchema<unknown>',
+              description:
+                'The schema of the input that the tool expects. While the type is unknown, a schema is still required for validation. You can use Zod schemas with z.unknown() or z.any() for fully dynamic inputs.'
+            },
+            {
+              name: 'execute',
+              type: 'ToolExecuteFunction<unknown, unknown>',
+              description:
+                'An async function that is called with the arguments from the tool call. The input is typed as unknown and must be validated/cast at runtime.',
+                properties: [
+                  {
+                    type: "ToolExecutionOptions",
+                    parameters: [
+                      {
+                      name: 'toolCallId',
+                      type: 'string',
+                      description: 'The ID of the tool call.',
+                    },
+                    {
+                        name: "messages",
+                        type: "ModelMessage[]",
+                        description: "Messages that were sent to the language model."
+                      },
+                      {
+                        name: "abortSignal",
+                        type: "AbortSignal",
+                        isOptional: true,
+                        description: "An optional abort signal."
+                      },
+                      {
+                        name: "experimental_context",
+                        type: "unknown",
+                        isOptional: true,
+                        description: "Context that is passed into tool execution. Experimental (can break in patch releases)."
+                      }
+                    ]
+                  }
+                ]
+            },
+            {
+              name: 'outputSchema',
+              isOptional: true,
+              type: 'Zod Schema | JSON Schema',
+              description:
+                'The schema of the output that the tool produces. Used for validation and type inference.'
+            },
+            {
+              name: 'toModelOutput',
+              isOptional: true,
+              type: '({toolCallId: string; input: unknown; output: unknown}) => ToolResultOutput | PromiseLike<ToolResultOutput>',
+              description: 'Optional conversion function that maps the tool result to an output that can be used by the language model.'
+            },
+            {
+              name: 'onInputStart',
+              isOptional: true,
+              type: '(options: ToolExecutionOptions) => void | PromiseLike<void>',
+              description:
+                'Optional function that is called when the argument streaming starts. Only called when the tool is used in a streaming context.'
+            },
+            {
+              name: 'onInputDelta',
+              isOptional: true,
+              type: '(options: { inputTextDelta: string } & ToolExecutionOptions) => void | PromiseLike<void>',
+              description:
+                'Optional function that is called when an argument streaming delta is available. Only called when the tool is used in a streaming context.'
+            },
+            {
+              name: 'onInputAvailable',
+              isOptional: true,
+              type: '(options: { input: unknown } & ToolExecutionOptions) => void | PromiseLike<void>',
+              description:
+                'Optional function that is called when a tool call can be started, even if the execute function is not provided.'
+            },
+            {
+              name: 'providerOptions',
+              isOptional: true,
+              type: 'ProviderOptions',
+              description: 'Additional provider-specific metadata.'
+            }
+          ]
+        }
+      ]
+    }
+
+]}
+/>
+
+### Returns
+
+A `Tool<unknown, unknown>` with `type: 'dynamic'` that can be used with `generateText`, `streamText`, and other AI SDK functions.
+
+## Type-Safe Usage
+
+When using dynamic tools alongside static tools, you need to check the `dynamic` flag for proper type narrowing:
+
+```ts
+const result = await generateText({
+  model: __MODEL__,
+  tools: {
+    // Static tool with known types
+    weather: weatherTool,
+    // Dynamic tool with unknown types
+    custom: dynamicTool({
+      /* ... */
+    }),
+  },
+  onStepFinish: ({ toolCalls, toolResults }) => {
+    for (const toolCall of toolCalls) {
+      if (toolCall.dynamic) {
+        // Dynamic tool: input/output are 'unknown'
+        console.log('Dynamic tool:', toolCall.toolName);
+        console.log('Input:', toolCall.input);
+        continue;
+      }
+
+      // Static tools have full type inference
+      switch (toolCall.toolName) {
+        case 'weather':
+          // TypeScript knows the exact types
+          console.log(toolCall.input.location); // string
+          break;
+      }
+    }
+  },
+});
+```
+
+## Usage with `useChat`
+
+When used with useChat (`UIMessage` format), dynamic tools appear as `dynamic-tool` parts:
+
+```tsx
+{
+  message.parts.map(part => {
+    switch (part.type) {
+      case 'dynamic-tool':
+        return (
+          <div>
+            <h4>Tool: {part.toolName}</h4>
+            <pre>{JSON.stringify(part.input, null, 2)}</pre>
+          </div>
+        );
+      // ... handle other part types
+    }
+  });
+}
+```

package/docs/07-reference/01-ai-sdk-core/23-create-mcp-client.mdx

@@ -0,0 +1,423 @@
+---
+title: createMCPClient
+description: Create a client for connecting to MCP servers
+---
+
+# `createMCPClient()`
+
+Creates a lightweight Model Context Protocol (MCP) client that connects to an MCP server. The client provides:
+
+- **Tools**: Automatic conversion between MCP tools and AI SDK tools
+- **Resources**: Methods to list, read, and discover resource templates from MCP servers
+- **Prompts**: Methods to list available prompts and retrieve prompt messages
+- **Elicitation**: Support for handling server requests for additional input during tool execution
+
+It currently does not support accepting notifications from an MCP server, and custom configuration of the client.
+
+## Import
+
+<Snippet
+  text={`import { createMCPClient } from "@ai-sdk/mcp"`}
+  prompt={false}
+/>
+
+## API Signature
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'config',
+      type: 'MCPClientConfig',
+      description: 'Configuration for the MCP client.',
+      properties: [
+        {
+          type: 'MCPClientConfig',
+          parameters: [
+            {
+              name: 'transport',
+              type: 'MCPTransportConfig | MCPTransport',
+              description: 'Configuration for the message transport layer.',
+              properties: [
+                {
+                  type: 'MCPTransport',
+                  description:
+                    'A client transport instance, used explicitly for stdio or custom transports',
+                  parameters: [
+                    {
+                      name: 'start',
+                      type: '() => Promise<void>',
+                      description: 'A method that starts the transport',
+                    },
+                    {
+                      name: 'send',
+                      type: '(message: JSONRPCMessage) => Promise<void>',
+                      description:
+                        'A method that sends a message through the transport',
+                    },
+                    {
+                      name: 'close',
+                      type: '() => Promise<void>',
+                      description: 'A method that closes the transport',
+                    },
+                    {
+                      name: 'onclose',
+                      type: '() => void',
+                      description:
+                        'A method that is called when the transport is closed',
+                    },
+                    {
+                      name: 'onerror',
+                      type: '(error: Error) => void',
+                      description:
+                        'A method that is called when the transport encounters an error',
+                    },
+                    {
+                      name: 'onmessage',
+                      type: '(message: JSONRPCMessage) => void',
+                      description:
+                        'A method that is called when the transport receives a message',
+                    },
+                  ],
+                },
+                {
+                  type: 'MCPTransportConfig',
+                  parameters: [
+                    {
+                      name: 'type',
+                      type: "'sse' | 'http",
+                      description: 'Use Server-Sent Events for communication',
+                    },
+                    {
+                      name: 'url',
+                      type: 'string',
+                      description: 'URL of the MCP server',
+                    },
+                    {
+                      name: 'headers',
+                      type: 'Record<string, string>',
+                      isOptional: true,
+                      description:
+                        'Additional HTTP headers to be sent with requests.',
+                    },
+                    {
+                      name: 'authProvider',
+                      type: 'OAuthClientProvider',
+                      isOptional: true,
+                      description:
+                        'Optional OAuth provider for authorization to access protected remote MCP servers.',
+                    },
+                    {
+                      name: 'redirect',
+                      type: "'follow' | 'error'",
+                      isOptional: true,
+                      description:
+                        "Controls how HTTP redirects are handled for transport requests. Set to 'follow' to allow redirect responses. Defaults to 'error' to reject any redirect response, preventing servers from redirecting requests to unintended hosts.",
+                    },
+                  ],
+                },
+              ],
+            },
+            {
+              name: 'name',
+              type: 'string',
+              isOptional: true,
+              description: 'Client name. Defaults to "ai-sdk-mcp-client"',
+            },
+            {
+              name: 'version',
+              type: 'string',
+              isOptional: true,
+              description: 'Client version. Defaults to "1.0.0"',
+            },
+            {
+              name: 'onUncaughtError',
+              type: '(error: unknown) => void',
+              isOptional: true,
+              description: 'Handler for uncaught errors',
+            },
+            {
+              name: 'capabilities',
+              type: 'ClientCapabilities',
+              isOptional: true,
+              description:
+                'Optional client capabilities to advertise during initialization. For example, set { elicitation: {} } to enable handling elicitation requests from the server.',
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+### Returns
+
+Returns a Promise that resolves to an `MCPClient` with the following methods:
+
+<PropertiesTable
+  content={[
+    {
+      name: 'tools',
+      type: `async (options?: {
+        schemas?: TOOL_SCHEMAS
+      }) => Promise<McpToolSet<TOOL_SCHEMAS>>`,
+      description: 'Gets the tools available from the MCP server.',
+      properties: [
+        {
+          type: 'options',
+          parameters: [
+            {
+              name: 'schemas',
+              type: 'TOOL_SCHEMAS',
+              isOptional: true,
+              description:
+                'Schema definitions for compile-time type checking. When not provided, schemas are inferred from the server. Each tool schema can include inputSchema for typed inputs, and optionally outputSchema for typed outputs when the server returns structuredContent.',
+            },
+          ],
+        },
+        {
+          type: 'TOOL_SCHEMAS',
+          parameters: [
+            {
+              name: 'inputSchema',
+              type: 'FlexibleSchema',
+              description:
+                'Zod schema or JSON schema defining the expected input parameters for the tool.',
+            },
+            {
+              name: 'outputSchema',
+              type: 'FlexibleSchema',
+              isOptional: true,
+              description:
+                'Zod schema or JSON schema defining the expected output structure. When provided, the client extracts and validates structuredContent from tool results, giving you typed outputs.',
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: 'listResources',
+      type: `async (options?: {
+        params?: PaginatedRequest['params'];
+        options?: RequestOptions;
+      }) => Promise<ListResourcesResult>`,
+      description: 'Lists all available resources from the MCP server.',
+      properties: [
+        {
+          type: 'options',
+          parameters: [
+            {
+              name: 'params',
+              type: "PaginatedRequest['params']",
+              isOptional: true,
+              description: 'Optional pagination parameters including cursor.',
+            },
+            {
+              name: 'options',
+              type: 'RequestOptions',
+              isOptional: true,
+              description:
+                'Optional request options including signal and timeout.',
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: 'readResource',
+      type: `async (args: {
+        uri: string;
+        options?: RequestOptions;
+      }) => Promise<ReadResourceResult>`,
+      description: 'Reads the contents of a specific resource by URI.',
+      properties: [
+        {
+          type: 'args',
+          parameters: [
+            {
+              name: 'uri',
+              type: 'string',
+              description: 'The URI of the resource to read.',
+            },
+            {
+              name: 'options',
+              type: 'RequestOptions',
+              isOptional: true,
+              description:
+                'Optional request options including signal and timeout.',
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: 'listResourceTemplates',
+      type: `async (options?: {
+        options?: RequestOptions;
+      }) => Promise<ListResourceTemplatesResult>`,
+      description:
+        'Lists all available resource templates from the MCP server.',
+      properties: [
+        {
+          type: 'options',
+          parameters: [
+            {
+              name: 'options',
+              type: 'RequestOptions',
+              isOptional: true,
+              description:
+                'Optional request options including signal and timeout.',
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: 'experimental_listPrompts',
+      type: `async (options?: {
+        params?: PaginatedRequest['params'];
+        options?: RequestOptions;
+      }) => Promise<ListPromptsResult>`,
+      description:
+        'Lists available prompts from the MCP server. This method is experimental and may change in the future.',
+      properties: [
+        {
+          type: 'options',
+          parameters: [
+            {
+              name: 'params',
+              type: "PaginatedRequest['params']",
+              isOptional: true,
+              description: 'Optional pagination parameters including cursor.',
+            },
+            {
+              name: 'options',
+              type: 'RequestOptions',
+              isOptional: true,
+              description:
+                'Optional request options including signal and timeout.',
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: 'experimental_getPrompt',
+      type: `async (args: {
+        name: string;
+        arguments?: Record<string, unknown>;
+        options?: RequestOptions;
+      }) => Promise<GetPromptResult>`,
+      description:
+        'Retrieves a prompt by name, optionally passing arguments. This method is experimental and may change in the future.',
+      properties: [
+        {
+          type: 'args',
+          parameters: [
+            {
+              name: 'name',
+              type: 'string',
+              description: 'Prompt name to retrieve.',
+            },
+            {
+              name: 'arguments',
+              type: 'Record<string, unknown>',
+              isOptional: true,
+              description: 'Optional arguments to fill into the prompt.',
+            },
+            {
+              name: 'options',
+              type: 'RequestOptions',
+              isOptional: true,
+              description:
+                'Optional request options including signal and timeout.',
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: 'onElicitationRequest',
+      type: `(
+        schema: typeof ElicitationRequestSchema,
+        handler: (request: ElicitationRequest) => Promise<ElicitResult> | ElicitResult
+      ) => void`,
+      description:
+        'Registers a handler for elicitation requests from the MCP server. The handler receives requests when the server needs additional input during tool execution.',
+      properties: [
+        {
+          type: 'parameters',
+          parameters: [
+            {
+              name: 'schema',
+              type: 'typeof ElicitationRequestSchema',
+              description:
+                'The schema to validate requests against. Must be ElicitationRequestSchema.',
+            },
+            {
+              name: 'handler',
+              type: '(request: ElicitationRequest) => Promise<ElicitResult> | ElicitResult',
+              description:
+                'A function that handles the elicitation request. The request contains a message and requestedSchema. The handler must return an object with an action ("accept", "decline", or "cancel") and optionally content when accepting.',
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: 'close',
+      type: '() => Promise<void>',
+      description:
+        'Closes the connection to the MCP server and cleans up resources.',
+    },
+  ]}
+/>
+
+## Example
+
+```typescript
+import { createMCPClient } from '@ai-sdk/mcp';
+import { generateText } from 'ai';
+import { Experimental_StdioMCPTransport } from '@ai-sdk/mcp/mcp-stdio';
+
+let client;
+
+try {
+  client = await createMCPClient({
+    transport: new Experimental_StdioMCPTransport({
+      command: 'node server.js',
+    }),
+  });
+
+  const tools = await client.tools();
+
+  const response = await generateText({
+    model: __MODEL__,
+    tools,
+    messages: [{ role: 'user', content: 'Query the data' }],
+  });
+
+  console.log(response);
+} catch (error) {
+  console.error('Error:', error);
+} finally {
+  // ensure the client is closed even if an error occurs
+  if (client) {
+    await client.close();
+  }
+}
+```
+
+## Error Handling
+
+The client throws `MCPClientError` for:
+
+- Client initialization failures
+- Protocol version mismatches
+- Missing server capabilities
+- Connection failures
+
+For tool execution, errors are propagated as `CallToolError` errors.
+
+For unknown errors, the client exposes an `onUncaughtError` callback that can be used to manually log or handle errors that are not covered by known error types.