@mastra/mcp-docs-server 1.1.4 → 1.1.5-alpha.0

package/.docs/guides/migrations/vnext-to-standard-apis.md

@@ -1,364 +0,0 @@
-# Migrate from VNext to Standard APIs
-
-As of `v0.20.0` for `@mastra/core`, the following changes apply.
-
-## Legacy APIs (AI SDK v4)
-
-The original methods have been renamed and maintain backward compatibility with **AI SDK v4** and `v1` models.
-
-- `.stream()` → `.streamLegacy()`
-- `.generate()` → `.generateLegacy()`
-
-## Standard APIs (AI SDK v5)
-
-These are now the current APIs with full **AI SDK v5** and `v2` model compatibility.
-
-- `.streamVNext()` → `.stream()`
-- `.generateVNext()` → `.generate()`
-
-## Migration paths
-
-If you're already using `.streamVNext()` and `.generateVNext()` use find/replace to change methods to `.stream()` and `.generate()` respectively.
-
-If you're using the old `.stream()` and `.generate()`, decide whether you want to upgrade or not. If you don't, use find/replace to change to `.streamLegacy()` and `.generateLegacy()`.
-
-Choose the migration path that fits your needs:
-
-### Keep using AI SDK v4 models
-
-- Rename all your `.stream()` and `.generate()` calls to `.streamLegacy()` and `.generateLegacy()` respectively.
-
-> No further changes required.
-
-### Keep using AI SDK v5 models
-
-- Rename all your `.streamVNext()` and `.generateVNext()` calls to `.stream()` and `.generate()` respectively.
-
-> No further changes required.
-
-### Upgrade from AI SDK v4 to v5
-
-- Bump all your model provider packages by a major version.
-
-> This will ensure that they are all v5 models now. Follow the guide below to understand the key differences and update your code accordingly.
-
-## Key differences
-
-The updated `.stream()` and `.generate()` methods differ from their legacy counterparts in behavior, compatibility, return types, and available options. This section highlights the most important changes you need to understand when migrating.
-
-### Model version support
-
-**Legacy APIs**
-
-- `.generateLegacy()`
-- `.streamLegacy()`
-
-Only support **AI SDK v4** models (`specificationVersion: 'v1'`)
-
-**Standard APIs**
-
-- `.generate()`
-- `.stream()`
-
-Only support **AI SDK v5** models (`specificationVersion: 'v2'`)
-
-> This is enforced at runtime with clear error messages.
-
-### Return types
-
-**Legacy APIs**
-
-- `.generateLegacy()` Returns: `GenerateTextResult` or `GenerateObjectResult`
-
-- `.streamLegacy()` Returns: `StreamTextResult` or `StreamObjectResult`
-
-See the following API references for more information:
-
-- [Agent.generateLegacy()](https://mastra.ai/reference/agents/generateLegacy)
-- [Agent.streamLegacy()](https://mastra.ai/reference/streaming/agents/streamLegacy)
-
-**Standard APIs**
-
-- `.generate()`
-
-  - `format: 'mastra'` (default): Returns `MastraModelOutput.getFullOutput()`
-  - `format: 'aisdk'`: Returns `AISDKV5OutputStream.getFullOutput()`
-  - Internally calls `.stream()` and awaits `.getFullOutput()`
-
-- `.stream()`
-
-  - `format: 'mastra'` (default): Returns `MastraModelOutput<OUTPUT>`
-  - `format: 'aisdk'`: Returns `AISDKV5OutputStream<OUTPUT>`
-
-See the following API references for more information:
-
-- [Agent.generate()](https://mastra.ai/reference/agents/generate)
-- [Agent.stream()](https://mastra.ai/reference/streaming/agents/stream)
-
-### Format control
-
-**Legacy APIs**
-
-No `format` option: Always return AI SDK v4 types
-
-```typescript
-// Mastra native format (default)
-const result = await agent.stream(messages);
-```
-
-**Standard APIs**
-
-Use `format` option to choose output:
-
-- `'mastra'` (default)
-- `'aisdk'` (AI SDK v5 compatible)
-
-```typescript
-// AI SDK v5 compatibility
-const result = await agent.stream(messages, {
-  format: "aisdk",
-});
-```
-
-### New options in standard APIs
-
-The following options are available in the standard `.stream()` and `generate()`, but **NOT** in their legacy counterparts:
-
-- `format` - Choose between 'mastra' or 'aisdk' output format:
-
-  ```typescript
-  const result = await agent.stream(messages, {
-    format: "aisdk", // or 'mastra' (default)
-  });
-  ```
-
-- `system` - Custom system message (separate from instructions).
-
-  ```typescript
-  const result = await agent.stream(messages, {
-    system: "You are a helpful assistant",
-  });
-  ```
-
-- `structuredOutput` - Enhanced structured output with model override and custom options.
-
-  - `jsonPromptInjection` - Used to override the default behaviour of passing response\_format to the model. This will inject context into the prompt to coerce the model into returning structured outputs.
-
-  - `model` - If a model is added this will create a sub agent to structure the response from the main agent. The main agent will call tools and return text, and the sub agent will return an object that conforms to your schema provided. This is a replacement for `experimental_output`.
-
-  - `errorStrategy` - Determines what happens when the output doesn’t match the schema:
-
-    - 'warn' - log a warning
-    - 'error' - throw an error
-    - 'fallback' - return a fallback value you provide
-
-    ```typescript
-    const result = await agent.generate(messages, {
-      structuredOutput: {
-        schema: z.object({
-          name: z.string(),
-          age: z.number(),
-        }),
-        model: "openai/gpt-5.1", // Optional model override for structuring
-        errorStrategy: "fallback",
-        fallbackValue: { name: "unknown", age: 0 },
-        instructions: "Extract user information", // Override default structuring instructions
-      },
-    });
-    ```
-
-- `stopWhen` - Flexible stop conditions (step count, token limit, etc).
-
-  ```typescript
-  const result = await agent.stream(messages, {
-    stopWhen: ({ steps, totalTokens }) => steps >= 5 || totalTokens >= 10000,
-  });
-  ```
-
-- `providerOptions` - Provider-specific options (e.g., OpenAI-specific settings)
-
-  ```typescript
-  const result = await agent.stream(messages, {
-    providerOptions: {
-      openai: {
-        store: true,
-        metadata: { userId: "123" },
-      },
-    },
-  });
-  ```
-
-- `onChunk` - Callback for each streaming chunk.
-
-  ```typescript
-  const result = await agent.stream(messages, {
-    onChunk: (chunk) => {
-      console.log("Received chunk:", chunk);
-    },
-  });
-  ```
-
-- `onError` - Error callback.
-
-  ```typescript
-  const result = await agent.stream(messages, {
-    onError: (error) => {
-      console.error("Stream error:", error);
-    },
-  });
-  ```
-
-- `onAbort` - Abort callback.
-
-  ```typescript
-  const result = await agent.stream(messages, {
-    onAbort: () => {
-      console.log("Stream aborted");
-    },
-  });
-  ```
-
-- `activeTools` - Specify which tools are active for this execution.
-
-  ```typescript
-  const result = await agent.stream(messages, {
-    activeTools: ["search", "calculator"], // Only these tools will be available
-  });
-  ```
-
-- `abortSignal` - AbortSignal for cancellation.
-
-  ```typescript
-  const controller = new AbortController();
-  const result = await agent.stream(messages, {
-    abortSignal: controller.signal,
-  });
-
-  // Later: controller.abort();
-  ```
-
-- `prepareStep` - Callback before each step in multi-step execution.
-
-  ```typescript
-  const result = await agent.stream(messages, {
-    prepareStep: ({ step, state }) => {
-      console.log("About to execute step:", step);
-      return {
-        /* modified state */
-      };
-    },
-  });
-  ```
-
-- `requireToolApproval` - Require approval for all tool calls.
-
-  ```typescript
-  const result = await agent.stream(messages, {
-    requireToolApproval: true,
-  });
-  ```
-
-### Legacy options that moved
-
-- `temperature` and other `modelSettings`.
-
-  Unified in `modelSettings`
-
-  ```typescript
-  const result = await agent.stream(messages, {
-    modelSettings: {
-      temperature: 0.7,
-      maxTokens: 1000,
-      topP: 0.9,
-    },
-  });
-  ```
-
-- `resourceId` and `threadId`.
-
-  Moved to memory object.
-
-  ```typescript
-  const result = await agent.stream(messages, {
-    memory: {
-      resource: "user-123",
-      thread: "thread-456",
-    },
-  });
-  ```
-
-### Deprecated or removed options
-
-- `experimental_output`
-
-  Use `structuredOutput` instead to allow for tool calls and an object return.
-
-  ```typescript
-  const result = await agent.generate(messages, {
-    structuredOutput: {
-      schema: z.object({
-        summary: z.string(),
-      }),
-      model: "openai/gpt-5.1",
-    },
-  });
-  ```
-
-- `output`
-
-  The `output` property is deprecated in favor of `structuredOutput`, to achieve the same results, omit the model and only pass `structuredOutput.schema`, optionally add `jsonPromptInjection: true` if your model does not natively support `response_format`.
-
-  ```typescript
-  const result = await agent.generate(messages, {
-    structuredOutput: {
-      schema: {
-        z.object({
-          name: z.string()
-        })
-      }
-    },
-  });
-  ```
-
-- `memoryOptions`
-
-  Use `memory` instead.
-
-  ```typescript
-  const result = await agent.generate(messages, {
-    memory: {},
-  });
-  ```
-
-### Type changes
-
-**Legacy APIs**
-
-- `CoreMessage[]`
-
-See the following API references for more information:
-
-- [Agent.generateLegacy()](https://mastra.ai/reference/agents/generateLegacy)
-- [Agent.streamLegacy()](https://mastra.ai/reference/streaming/agents/streamLegacy)
-
-**Standard APIs**
-
-- `ModelMessage[]`
-
-  `toolChoice` uses the AI SDK v5 `ToolChoice` type.
-
-  ```typescript
-  type ToolChoice<TOOLS extends Record<string, unknown>> =
-    | "auto"
-    | "none"
-    | "required"
-    | {
-        type: "tool";
-        toolName: Extract<keyof TOOLS, string>;
-      };
-  ```
-
-See the following API references for more information:
-
-- [Agent.generate()](https://mastra.ai/reference/agents/generate)
-- [Agent.stream()](https://mastra.ai/reference/streaming/agents/stream)

package/.docs/models/embeddings.md

@@ -1,161 +0,0 @@
-# Embedding Models
-
-Mastra's model router supports embedding models using the same `provider/model` string format as language models. This provides a unified interface for both chat and embedding models with TypeScript autocomplete support.
-
-## Quick Start
-
-```typescript
-import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
-import { embedMany } from "ai";
-
-// Generate embeddings
-const { embeddings } = await embedMany({
-  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
-  values: ["Hello world", "Semantic search is powerful"],
-});
-```
-
-## Supported Models
-
-### OpenAI
-
-- `text-embedding-3-small` - 1536 dimensions, 8191 max tokens
-- `text-embedding-3-large` - 3072 dimensions, 8191 max tokens
-- `text-embedding-ada-002` - 1536 dimensions, 8191 max tokens
-
-```typescript
-const embedder = new ModelRouterEmbeddingModel("openai/text-embedding-3-small");
-```
-
-### Google
-
-- `gemini-embedding-001` - 768 dimensions, 2048 max tokens
-
-```typescript
-const embedder = new ModelRouterEmbeddingModel("google/gemini-embedding-001");
-```
-
-## Authentication
-
-The model router automatically detects API keys from environment variables:
-
-- **OpenAI**: `OPENAI_API_KEY`
-- **Google**: `GOOGLE_GENERATIVE_AI_API_KEY`
-
-```bash
-# .env
-OPENAI_API_KEY=sk-...
-GOOGLE_GENERATIVE_AI_API_KEY=...
-```
-
-## Custom Providers
-
-You can use any OpenAI-compatible embedding endpoint with a custom URL:
-
-```typescript
-import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
-
-const embedder = new ModelRouterEmbeddingModel({
-  providerId: "ollama",
-  modelId: "nomic-embed-text",
-  url: "http://localhost:11434/v1",
-  apiKey: "not-needed", // Some providers don't require API keys
-});
-```
-
-## Usage with Memory
-
-The embedding model router integrates seamlessly with Mastra's memory system:
-
-```typescript
-import { Memory } from "@mastra/memory";
-import { Agent } from "@mastra/core/agent";
-import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
-
-const agent = new Agent({
-  id: "my-agent",
-  name: "my-agent",
-  instructions: "You are a helpful assistant",
-  model: "openai/gpt-5.1",
-  memory: new Memory({
-    embedder: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
-  }),
-});
-```
-
-> **Info:** The `embedder` field accepts:
->
-> - `EmbeddingModelId` (string with autocomplete)
-> - `EmbeddingModel<string>` (AI SDK v1)
-> - `EmbeddingModelV2<string>` (AI SDK v2)
-
-## Usage with RAG
-
-Use embedding models for document chunking and retrieval:
-
-```typescript
-import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
-import { embedMany } from "ai";
-
-// Embed document chunks
-const { embeddings } = await embedMany({
-  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
-  values: chunks.map((chunk) => chunk.text),
-});
-
-// Store embeddings in your vector database
-await vectorStore.upsert(
-  chunks.map((chunk, i) => ({
-    id: chunk.id,
-    vector: embeddings[i],
-    metadata: chunk.metadata,
-  })),
-);
-```
-
-## TypeScript Support
-
-The model router provides full TypeScript autocomplete for embedding model IDs:
-
-```typescript
-import type { EmbeddingModelId } from "@mastra/core";
-
-// Type-safe embedding model selection
-const modelId: EmbeddingModelId = "openai/text-embedding-3-small";
-//                                  ^ Autocomplete shows all supported models
-
-const embedder = new ModelRouterEmbeddingModel(modelId);
-```
-
-## Error Handling
-
-The model router validates provider and model IDs at construction time:
-
-```typescript
-try {
-  const embedder = new ModelRouterEmbeddingModel("invalid/model");
-} catch (error) {
-  console.error(error.message);
-  // "Unknown provider: invalid. Available providers: openai, google"
-}
-```
-
-Missing API keys are also caught early:
-
-```typescript
-try {
-  const embedder = new ModelRouterEmbeddingModel(
-    "openai/text-embedding-3-small",
-  );
-  // Throws if OPENAI_API_KEY is not set
-} catch (error) {
-  console.error(error.message);
-  // "API key not found for provider openai. Set OPENAI_API_KEY environment variable."
-}
-```
-
-## Next Steps
-
-- [Memory & Semantic Recall](https://mastra.ai/docs/memory/semantic-recall) - Use embeddings for agent memory
-- [RAG & Chunking](https://mastra.ai/docs/rag/chunking-and-embedding) - Build retrieval-augmented generation systems
-- [Vector Databases](https://mastra.ai/docs/rag/vector-databases) - Store and query embeddings

package/.docs/models/gateways/azure-openai.md

@@ -1,128 +0,0 @@
-# ![Azure OpenAI logo](https://models.dev/logos/azure.svg)Azure OpenAI
-
-Azure OpenAI provides enterprise-grade access to OpenAI models through dedicated deployments with security, compliance, and SLA guarantees.
-
-Unlike other providers that have fixed model names, Azure uses **deployment names** that you configure in the Azure Portal.
-
-## How Azure Deployments Work
-
-Azure model IDs follow this pattern: `azure-openai/your-deployment-name`
-
-The deployment name is **specific to your Azure account** and chosen when you create a deployment in Azure Portal. Common examples:
-
-- `azure-openai/my-gpt4-deployment`
-- `azure-openai/production-gpt-35-turbo`
-- `azure-openai/staging-gpt-4o`
-
-## Setup
-
-Create deployments in [Azure OpenAI Studio](https://oai.azure.com/). The resource name and API key are in Azure Portal under "Keys and Endpoint".
-
-## Configuration
-
-Instantiate the gateway and pass it to Mastra. Three configuration modes are available.
-
-### Static Deployments
-
-Provide deployment names from Azure Portal.
-
-```typescript
-import { Mastra } from "@mastra/core";
-import { AzureOpenAIGateway } from "@mastra/core/llm";
-
-export const mastra = new Mastra({
-  gateways: [
-    new AzureOpenAIGateway({
-      resourceName: "my-openai-resource",
-      apiKey: process.env.AZURE_API_KEY!,
-      deployments: ["gpt-4-prod", "gpt-35-turbo-dev"],
-    }),
-  ],
-});
-```
-
-### Dynamic Discovery
-
-Provide Management API credentials. The gateway queries Azure Management API to list deployments.
-
-```typescript
-import { Mastra } from "@mastra/core";
-import { AzureOpenAIGateway } from "@mastra/core/llm";
-
-export const mastra = new Mastra({
-  gateways: [
-    new AzureOpenAIGateway({
-      resourceName: "my-openai-resource",
-      apiKey: process.env.AZURE_API_KEY!,
-      management: {
-        tenantId: process.env.AZURE_TENANT_ID!,
-        clientId: process.env.AZURE_CLIENT_ID!,
-        clientSecret: process.env.AZURE_CLIENT_SECRET!,
-        subscriptionId: process.env.AZURE_SUBSCRIPTION_ID!,
-        resourceGroup: "my-resource-group",
-      },
-    }),
-  ],
-});
-```
-
-The Service Principal requires "Cognitive Services User" role. See [Azure documentation](https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal).
-
-### Manual Deployment Names
-
-Provide resource name and API key only. Specify deployment names when creating agents. No IDE autocomplete.
-
-```typescript
-import { Mastra } from "@mastra/core";
-import { AzureOpenAIGateway } from "@mastra/core/llm";
-
-export const mastra = new Mastra({
-  gateways: [
-    new AzureOpenAIGateway({
-      resourceName: "my-openai-resource",
-      apiKey: process.env.AZURE_API_KEY!,
-    }),
-  ],
-});
-```
-
-## Configuration Reference
-
-| Option                      | Type       | Required | Description                                 |
-| --------------------------- | ---------- | -------- | ------------------------------------------- |
-| `resourceName`              | `string`   | Yes      | Azure OpenAI resource name                  |
-| `apiKey`                    | `string`   | Yes      | API key from "Keys and Endpoint"            |
-| `apiVersion`                | `string`   | No       | API version (default: `2024-04-01-preview`) |
-| `deployments`               | `string[]` | No       | Deployment names for static mode            |
-| `management`                | `object`   | No       | Management API credentials                  |
-| `management.tenantId`       | `string`   | Yes\*    | Azure AD tenant ID                          |
-| `management.clientId`       | `string`   | Yes\*    | Service Principal client ID                 |
-| `management.clientSecret`   | `string`   | Yes\*    | Service Principal secret                    |
-| `management.subscriptionId` | `string`   | Yes\*    | Azure subscription ID                       |
-| `management.resourceGroup`  | `string`   | Yes\*    | Resource group name                         |
-
-\* Required if `management` is provided
-
-## Usage
-
-```typescript
-import { Agent } from "@mastra/core/agent";
-
-const agent = new Agent({
-  id: "my-agent",
-  name: "My Agent",
-  instructions: "You are a helpful assistant",
-  model: "azure-openai/my-gpt4-deployment"  // Use your Azure deployment name (autocompleted in dev mode)
-});
-
-// Generate a response
-const response = await agent.generate("Hello!");
-
-// Stream a response
-const stream = await agent.stream("Tell me a story");
-for await (const chunk of stream) {
-  console.log(chunk);
-}
-```
-
-Check [Azure OpenAI model availability](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models) for region-specific options.