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

package/.docs/models/embeddings.md

@@ -0,0 +1,161 @@
+# 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

@@ -0,0 +1,128 @@
+# ![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.