ai 6.0.31 → 6.0.33

package/docs/03-ai-sdk-core/16-mcp-tools.mdx

@@ -0,0 +1,375 @@
+---
+title: Model Context Protocol (MCP)
+description: Learn how to connect to Model Context Protocol (MCP) servers and use their tools with AI SDK Core.
+---
+
+# Model Context Protocol (MCP)
+
+The AI SDK supports connecting to [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) servers to access their tools, resources, and prompts.
+This enables your AI applications to discover and use capabilities across various services through a standardized interface.
+
+<Note>
+  If you're using OpenAI's Responses API, you can also use the built-in
+  `openai.tools.mcp` tool, which provides direct MCP server integration without
+  needing to convert tools. See the [OpenAI provider
+  documentation](/providers/ai-sdk-providers/openai#mcp-tool) for details.
+</Note>
+
+## Initializing an MCP Client
+
+We recommend using HTTP transport (like `StreamableHTTPClientTransport`) for production deployments. The stdio transport should only be used for connecting to local servers as it cannot be deployed to production environments.
+
+Create an MCP client using one of the following transport options:
+
+- **HTTP transport (Recommended)**: Either configure HTTP directly via the client using `transport: { type: 'http', ... }`, or use MCP's official TypeScript SDK `StreamableHTTPClientTransport`
+- SSE (Server-Sent Events): An alternative HTTP-based transport
+- `stdio`: For local development only. Uses standard input/output streams for local MCP servers
+
+### HTTP Transport (Recommended)
+
+For production deployments, we recommend using the HTTP transport. You can configure it directly on the client:
+
+```typescript
+import { createMCPClient } from '@ai-sdk/mcp';
+
+const mcpClient = await createMCPClient({
+  transport: {
+    type: 'http',
+    url: 'https://your-server.com/mcp',
+
+    // optional: configure HTTP headers
+    headers: { Authorization: 'Bearer my-api-key' },
+
+    // optional: provide an OAuth client provider for automatic authorization
+    authProvider: myOAuthClientProvider,
+  },
+});
+```
+
+Alternatively, you can use `StreamableHTTPClientTransport` from MCP's official TypeScript SDK:
+
+```typescript
+import { createMCPClient } from '@ai-sdk/mcp';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+
+const url = new URL('https://your-server.com/mcp');
+const mcpClient = await createMCPClient({
+  transport: new StreamableHTTPClientTransport(url, {
+    sessionId: 'session_123',
+  }),
+});
+```
+
+### SSE Transport
+
+SSE provides an alternative HTTP-based transport option. Configure it with a `type` and `url` property. You can also provide an `authProvider` for OAuth:
+
+```typescript
+import { createMCPClient } from '@ai-sdk/mcp';
+
+const mcpClient = await createMCPClient({
+  transport: {
+    type: 'sse',
+    url: 'https://my-server.com/sse',
+
+    // optional: configure HTTP headers
+    headers: { Authorization: 'Bearer my-api-key' },
+
+    // optional: provide an OAuth client provider for automatic authorization
+    authProvider: myOAuthClientProvider,
+  },
+});
+```
+
+### Stdio Transport (Local Servers)
+
+<Note type="warning">
+  The stdio transport should only be used for local servers.
+</Note>
+
+The Stdio transport can be imported from either the MCP SDK or the AI SDK:
+
+```typescript
+import { createMCPClient } from '@ai-sdk/mcp';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+// Or use the AI SDK's stdio transport:
+// import { Experimental_StdioMCPTransport as StdioClientTransport } from '@ai-sdk/mcp/mcp-stdio';
+
+const mcpClient = await createMCPClient({
+  transport: new StdioClientTransport({
+    command: 'node',
+    args: ['src/stdio/dist/server.js'],
+  }),
+});
+```
+
+### Custom Transport
+
+You can also bring your own transport by implementing the `MCPTransport` interface for specific requirements not covered by the standard transports.
+
+<Note>
+  The client returned by the `createMCPClient` function is a
+  lightweight client intended for use in tool conversion. It currently does not
+  support all features of the full MCP client, such as: session
+  management, resumable streams, and receiving notifications.
+
+Authorization via OAuth is supported when using the AI SDK MCP HTTP or SSE
+transports by providing an `authProvider`.
+
+</Note>
+
+### Closing the MCP Client
+
+After initialization, you should close the MCP client based on your usage pattern:
+
+- For short-lived usage (e.g., single requests), close the client when the response is finished
+- For long-running clients (e.g., command line apps), keep the client open but ensure it's closed when the application terminates
+
+When streaming responses, you can close the client when the LLM response has finished. For example, when using `streamText`, you should use the `onFinish` callback:
+
+```typescript
+const mcpClient = await createMCPClient({
+  // ...
+});
+
+const tools = await mcpClient.tools();
+
+const result = await streamText({
+  model: __MODEL__,
+  tools,
+  prompt: 'What is the weather in Brooklyn, New York?',
+  onFinish: async () => {
+    await mcpClient.close();
+  },
+});
+```
+
+When generating responses without streaming, you can use try/finally or cleanup functions in your framework:
+
+```typescript
+let mcpClient: MCPClient | undefined;
+
+try {
+  mcpClient = await createMCPClient({
+    // ...
+  });
+} finally {
+  await mcpClient?.close();
+}
+```
+
+## Using MCP Tools
+
+The client's `tools` method acts as an adapter between MCP tools and AI SDK tools. It supports two approaches for working with tool schemas:
+
+### Schema Discovery
+
+With schema discovery, all tools offered by the server are automatically listed, and input parameter types are inferred based on the schemas provided by the server:
+
+```typescript
+const tools = await mcpClient.tools();
+```
+
+This approach is simpler to implement and automatically stays in sync with server changes. However, you won't have TypeScript type safety during development, and all tools from the server will be loaded
+
+### Schema Definition
+
+For better type safety and control, you can define the tools and their input schemas explicitly in your client code:
+
+```typescript
+import { z } from 'zod';
+
+const tools = await mcpClient.tools({
+  schemas: {
+    'get-data': {
+      inputSchema: z.object({
+        query: z.string().describe('The data query'),
+        format: z.enum(['json', 'text']).optional(),
+      }),
+    },
+    // For tools with zero inputs, you should use an empty object:
+    'tool-with-no-args': {
+      inputSchema: z.object({}),
+    },
+  },
+});
+```
+
+This approach provides full TypeScript type safety and IDE autocompletion, letting you catch parameter mismatches during development. When you define `schemas`, the client only pulls the explicitly defined tools, keeping your application focused on the tools it needs
+
+### Typed Tool Outputs
+
+When MCP servers return `structuredContent` (per the [MCP specification](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#structured-content)), you can define an `outputSchema` to get typed tool results:
+
+```typescript
+import { z } from 'zod';
+
+const tools = await mcpClient.tools({
+  schemas: {
+    'get-weather': {
+      inputSchema: z.object({
+        location: z.string(),
+      }),
+      // Define outputSchema for typed results
+      outputSchema: z.object({
+        temperature: z.number(),
+        conditions: z.string(),
+        humidity: z.number(),
+      }),
+    },
+  },
+});
+
+const result = await tools['get-weather'].execute(
+  { location: 'New York' },
+  { messages: [], toolCallId: 'weather-1' },
+);
+
+console.log(`Temperature: ${result.temperature}°C`);
+```
+
+When `outputSchema` is provided:
+
+- The client extracts `structuredContent` from the tool result
+- The output is validated against your schema at runtime
+- You get full TypeScript type safety for the result
+
+If the server doesn't return `structuredContent`, the client falls back to parsing JSON from the text content. If neither is available or validation fails, an error is thrown.
+
+<Note>
+  Without `outputSchema`, the tool returns the raw `CallToolResult` object
+  containing `content` and optional `isError` fields.
+</Note>
+
+## Using MCP Resources
+
+According to the [MCP specification](https://modelcontextprotocol.io/docs/learn/server-concepts#resources), resources are **application-driven** data sources that provide context to the model. Unlike tools (which are model-controlled), your application decides when to fetch and pass resources as context.
+
+The MCP client provides three methods for working with resources:
+
+### Listing Resources
+
+List all available resources from the MCP server:
+
+```typescript
+const resources = await mcpClient.listResources();
+```
+
+### Reading Resource Contents
+
+Read the contents of a specific resource by its URI:
+
+```typescript
+const resourceData = await mcpClient.readResource({
+  uri: 'file:///example/document.txt',
+});
+```
+
+### Listing Resource Templates
+
+Resource templates are dynamic URI patterns that allow flexible queries. List all available templates:
+
+```typescript
+const templates = await mcpClient.listResourceTemplates();
+```
+
+## Using MCP Prompts
+
+<Note type="warning">
+  MCP Prompts is an experimental feature and may change in the future.
+</Note>
+
+According to the MCP specification, prompts are user-controlled templates that servers expose for clients to list and retrieve with optional arguments.
+
+### Listing Prompts
+
+```typescript
+const prompts = await mcpClient.experimental_listPrompts();
+```
+
+### Getting a Prompt
+
+Retrieve prompt messages, optionally passing arguments defined by the server:
+
+```typescript
+const prompt = await mcpClient.experimental_getPrompt({
+  name: 'code_review',
+  arguments: { code: 'function add(a, b) { return a + b; }' },
+});
+```
+
+## Handling Elicitation Requests
+
+Elicitation is a mechanism where MCP servers can request additional information from the client during tool execution. For example, a server might need user input to complete a registration form or confirmation for a sensitive operation.
+
+<Note type="warning">
+  It is up to the client application to handle elicitation requests properly.
+  The MCP client simply surfaces these requests from the server to your
+  application code.
+</Note>
+
+### Enabling Elicitation Support
+
+To enable elicitation, you need to advertise the capability when creating the MCP client:
+
+```typescript
+const mcpClient = await createMCPClient({
+  transport: {
+    type: 'sse',
+    url: 'https://your-server.com/sse',
+  },
+  capabilities: {
+    elicitation: {},
+  },
+});
+```
+
+### Registering an Elicitation Handler
+
+Use the `onElicitationRequest` method to register a handler that will be called when the server requests input:
+
+```typescript
+import { ElicitationRequestSchema } from '@ai-sdk/mcp';
+
+mcpClient.onElicitationRequest(ElicitationRequestSchema, async request => {
+  // request.params.message: A message describing what input is needed
+  // request.params.requestedSchema: JSON schema defining the expected input structure
+
+  // Get input from the user (implement according to your application's needs)
+  const userInput = await getInputFromUser(
+    request.params.message,
+    request.params.requestedSchema,
+  );
+
+  // Return the result with one of three actions:
+  return {
+    action: 'accept', // or 'decline' or 'cancel'
+    content: userInput, // only required when action is 'accept'
+  };
+});
+```
+
+### Elicitation Response Actions
+
+Your handler must return an object with an `action` field that can be one of:
+
+- `'accept'`: User provided the requested information. Must include `content` with the data.
+- `'decline'`: User chose not to provide the information.
+- `'cancel'`: User cancelled the operation entirely.
+
+## Examples
+
+You can see MCP in action in the following examples:
+
+<ExampleLinks
+  examples={[
+    {
+      title: 'Learn to use MCP tools in Node.js',
+      link: '/cookbook/node/mcp-tools',
+    },
+    {
+      title: 'Learn to handle MCP elicitation requests in Node.js',
+      link: '/cookbook/node/mcp-elicitation',
+    },
+  ]}
+/>

package/docs/03-ai-sdk-core/20-prompt-engineering.mdx

@@ -0,0 +1,144 @@
+---
+title: Prompt Engineering
+description: Learn how to develop prompts with AI SDK Core.
+---
+
+# Prompt Engineering
+
+## Tips
+
+### Prompts for Tools
+
+When you create prompts that include tools, getting good results can be tricky as the number and complexity of your tools increases.
+
+Here are a few tips to help you get the best results:
+
+1. Use a model that is strong at tool calling, such as `gpt-5` or `gpt-4.1`. Weaker models will often struggle to call tools effectively and flawlessly.
+1. Keep the number of tools low, e.g. to 5 or less.
+1. Keep the complexity of the tool parameters low. Complex Zod schemas with many nested and optional elements, unions, etc. can be challenging for the model to work with.
+1. Use semantically meaningful names for your tools, parameters, parameter properties, etc. The more information you pass to the model, the better it can understand what you want.
+1. Add `.describe("...")` to your Zod schema properties to give the model hints about what a particular property is for.
+1. When the output of a tool might be unclear to the model and there are dependencies between tools, use the `description` field of a tool to provide information about the output of the tool execution.
+1. You can include example input/outputs of tool calls in your prompt to help the model understand how to use the tools. Keep in mind that the tools work with JSON objects, so the examples should use JSON.
+
+In general, the goal should be to give the model all information it needs in a clear way.
+
+### Tool & Structured Data Schemas
+
+The mapping from Zod schemas to LLM inputs (typically JSON schema) is not always straightforward, since the mapping is not one-to-one.
+
+#### Zod Dates
+
+Zod expects JavaScript Date objects, but models return dates as strings.
+You can specify and validate the date format using `z.string().datetime()` or `z.string().date()`,
+and then use a Zod transformer to convert the string to a Date object.
+
+```ts highlight="7-10"
+const result = await generateObject({
+  model: __MODEL__,
+  schema: z.object({
+    events: z.array(
+      z.object({
+        event: z.string(),
+        date: z
+          .string()
+          .date()
+          .transform(value => new Date(value)),
+      }),
+    ),
+  }),
+  prompt: 'List 5 important events from the year 2000.',
+});
+```
+
+#### Optional Parameters
+
+When working with tools that have optional parameters, you may encounter compatibility issues with certain providers that use strict schema validation.
+
+<Note>
+  This is particularly relevant for OpenAI models with structured outputs
+  (strict mode).
+</Note>
+
+For maximum compatibility, optional parameters should use `.nullable()` instead of `.optional()`:
+
+```ts highlight="6,7,16,17"
+// This may fail with strict schema validation
+const failingTool = tool({
+  description: 'Execute a command',
+  inputSchema: z.object({
+    command: z.string(),
+    workdir: z.string().optional(), // This can cause errors
+    timeout: z.string().optional(),
+  }),
+});
+
+// This works with strict schema validation
+const workingTool = tool({
+  description: 'Execute a command',
+  inputSchema: z.object({
+    command: z.string(),
+    workdir: z.string().nullable(), // Use nullable instead
+    timeout: z.string().nullable(),
+  }),
+});
+```
+
+#### Temperature Settings
+
+For tool calls and object generation, it's recommended to use `temperature: 0` to ensure deterministic and consistent results:
+
+```ts highlight="3"
+const result = await generateText({
+  model: __MODEL__,
+  temperature: 0, // Recommended for tool calls
+  tools: {
+    myTool: tool({
+      description: 'Execute a command',
+      inputSchema: z.object({
+        command: z.string(),
+      }),
+    }),
+  },
+  prompt: 'Execute the ls command',
+});
+```
+
+Lower temperature values reduce randomness in model outputs, which is particularly important when the model needs to:
+
+- Generate structured data with specific formats
+- Make precise tool calls with correct parameters
+- Follow strict schemas consistently
+
+## Debugging
+
+### Inspecting Warnings
+
+Not all providers support all AI SDK features.
+Providers either throw exceptions or return warnings when they do not support a feature.
+To check if your prompt, tools, and settings are handled correctly by the provider, you can check the call warnings:
+
+```ts
+const result = await generateText({
+  model: __MODEL__,
+  prompt: 'Hello, world!',
+});
+
+console.log(result.warnings);
+```
+
+### HTTP Request Bodies
+
+You can inspect the raw HTTP request bodies for models that expose them, e.g. [OpenAI](/providers/ai-sdk-providers/openai).
+This allows you to inspect the exact payload that is sent to the model provider in the provider-specific way.
+
+Request bodies are available via the `request.body` property of the response:
+
+```ts highlight="6"
+const result = await generateText({
+  model: __MODEL__,
+  prompt: 'Hello, world!',
+});
+
+console.log(result.request.body);
+```