@mastra/mcp-docs-server 1.0.0-beta.4 → 1.0.0-beta.5

package/.docs/raw/reference/rag/rerank.mdx

@@ -19,10 +19,9 @@ function rerank(
 ## Usage Example
 
 ```typescript
-import { openai } from "@ai-sdk/openai";
 import { rerank } from "@mastra/rag";
 
-const model = openai("gpt-4o-mini");
+const model = "openai/gpt-5.1";
 
 const rerankedResults = await rerank(
   vectorSearchResults,

package/.docs/raw/reference/rag/rerankWithScorer.mdx

@@ -19,7 +19,6 @@ function rerankWithScorer({
 ## Usage Example
 
 ```typescript
-import { openai } from "@ai-sdk/openai";
 import { rerankWithScorer as rerank, CohereRelevanceScorer } from "@mastra/rag";
 
 const scorer = new CohereRelevanceScorer("rerank-v3.5");

package/.docs/raw/reference/streaming/agents/stream.mdx

@@ -254,6 +254,13 @@ const aiSdkStream = await agent.stream("message for agent", {
       description:
         "Overrides the output processors set on the agent. Output processors that can modify or validate messages from the agent before they are returned to the user. Must implement either (or both) of the `processOutputResult` and `processOutputStream` functions.",
     },
+    {
+      name: "includeRawChunks",
+      type: "boolean",
+      isOptional: true,
+      description:
+        "Whether to include raw chunks in the stream output (not available on all model providers).",
+    },
     {
       name: "inputProcessors",
       type: "Processor[]",
@@ -701,7 +708,7 @@ await agent.stream("message for agent", {
       sentiment: z.enum(["positive", "negative", "neutral"]),
       confidence: z.number(),
     }),
-    model: "openai/gpt-4o-mini",
+    model: "openai/gpt-5.1",
     errorStrategy: "warn",
   },
   // Output processors for streaming response validation

package/.docs/raw/reference/templates/overview.mdx

@@ -118,13 +118,10 @@ We recommend using OpenAI, Anthropic, or Google model providers for templates. C
 
 ```typescript title="src/mastra/agents/example-agent.ts"
 import { Agent } from "@mastra/core/agent";
-import { openai } from "@ai-sdk/openai";
-// Or use: import { anthropic } from '@ai-sdk/anthropic';
-// Or use: import { google } from '@ai-sdk/google';
 
 const agent = new Agent({
   name: "example-agent",
-  model: openai("gpt-4"), // or anthropic('') or google('')
+  model: "openai/gpt-5.1", // or other provider strings
   instructions: "Your agent instructions here",
   // ... other configuration
 });

package/.docs/raw/reference/tools/client.mdx

@@ -230,7 +230,6 @@ Returns an object mapping tool names to their corresponding Mastra tool implemen
 ```typescript
 import { Agent } from "@mastra/core/agent";
 import { MastraMCPClient } from "@mastra/mcp";
-import { openai } from "@ai-sdk/openai";
 
 // Initialize the MCP client using mcp/fetch as an example https://hub.docker.com/r/mcp/fetch
 // Visit https://github.com/docker/mcp-servers for other reference docker mcp servers
@@ -250,7 +249,7 @@ const agent = new Agent({
   name: "Fetch agent",
   instructions:
     "You are able to fetch data from URLs on demand and discuss the response data with the user.",
-  model: openai("gpt-4o-mini"),
+  model: "openai/gpt-5.1",
 });
 
 try {

package/.docs/raw/reference/tools/create-tool.mdx

@@ -131,6 +131,34 @@ export const tool = createTool({
         },
       ],
     },
+    {
+      name: "onInputStart",
+      type: "function",
+      description:
+        "Optional callback invoked when the tool call input streaming begins. Receives `toolCallId`, `messages`, and `abortSignal`.",
+      isOptional: true,
+    },
+    {
+      name: "onInputDelta",
+      type: "function",
+      description:
+        "Optional callback invoked for each incremental chunk of input text as it streams in. Receives `inputTextDelta`, `toolCallId`, `messages`, and `abortSignal`.",
+      isOptional: true,
+    },
+    {
+      name: "onInputAvailable",
+      type: "function",
+      description:
+        "Optional callback invoked when the complete tool input is available and parsed. Receives the validated `input` object, `toolCallId`, `messages`, and `abortSignal`.",
+      isOptional: true,
+    },
+    {
+      name: "onOutput",
+      type: "function",
+      description:
+        "Optional callback invoked after the tool has successfully executed and returned output. Receives the tool's `output`, `toolCallId`, `messages`, and `abortSignal`.",
+      isOptional: true,
+    },
   ]}
 />
 
@@ -149,8 +177,112 @@ The `createTool()` function returns a `Tool` object.
   ]}
 />
 
+## Tool Lifecycle Hooks
+
+Tools support lifecycle hooks that allow you to monitor and react to different stages of tool execution. These hooks are particularly useful for logging, analytics, validation, and real-time updates during streaming.
+
+### Available Hooks
+
+#### onInputStart
+
+Called when tool call input streaming begins, before any input data is received.
+
+```typescript
+export const tool = createTool({
+  id: "example-tool",
+  description: "Example tool with hooks",
+  onInputStart: ({ toolCallId, messages, abortSignal }) => {
+    console.log(`Tool ${toolCallId} input streaming started`);
+  },
+  // ... other properties
+});
+```
+
+#### onInputDelta
+
+Called for each incremental chunk of input text as it streams in. Useful for showing real-time progress or parsing partial JSON.
+
+```typescript
+export const tool = createTool({
+  id: "example-tool",
+  description: "Example tool with hooks",
+  onInputDelta: ({ inputTextDelta, toolCallId, messages, abortSignal }) => {
+    console.log(`Received input chunk: ${inputTextDelta}`);
+  },
+  // ... other properties
+});
+```
+
+#### onInputAvailable
+
+Called when the complete tool input is available and has been parsed and validated against the `inputSchema`.
+
+```typescript
+export const tool = createTool({
+  id: "example-tool",
+  description: "Example tool with hooks",
+  inputSchema: z.object({
+    city: z.string(),
+  }),
+  onInputAvailable: ({ input, toolCallId, messages, abortSignal }) => {
+    console.log(`Tool received complete input:`, input);
+    // input is fully typed based on inputSchema
+  },
+  // ... other properties
+});
+```
+
+#### onOutput
+
+Called after the tool has successfully executed and returned output. Useful for logging results, triggering follow-up actions, or analytics.
+
+```typescript
+export const tool = createTool({
+  id: "example-tool",
+  description: "Example tool with hooks",
+  outputSchema: z.object({
+    result: z.string(),
+  }),
+  execute: async (input) => {
+    return { result: "Success" };
+  },
+  onOutput: ({ output, toolCallId, toolName, abortSignal }) => {
+    console.log(`${toolName} execution completed:`, output);
+    // output is fully typed based on outputSchema
+  },
+});
+```
+
+### Hook Execution Order
+
+For a typical streaming tool call, the hooks are invoked in this order:
+
+1. **onInputStart** - Input streaming begins
+2. **onInputDelta** - Called multiple times as chunks arrive
+3. **onInputAvailable** - Complete input is parsed and validated
+4. Tool's **execute** function runs
+5. **onOutput** - Tool has completed successfully
+
+### Hook Parameters
+
+All hooks receive a parameter object with these common properties:
+
+- `toolCallId` (string): Unique identifier for this specific tool call
+- `abortSignal` (AbortSignal): Signal for detecting if the operation should be cancelled
+
+Additionally:
+- `onInputStart`, `onInputDelta`, and `onInputAvailable` receive `messages` (array): The conversation messages at the time of the tool call
+- `onInputDelta` receives `inputTextDelta` (string): The incremental text chunk
+- `onInputAvailable` receives `input`: The validated input data (typed according to `inputSchema`)
+- `onOutput` receives `output`: The tool's return value (typed according to `outputSchema`) and `toolName` (string): The name of the tool
+
+### Error Handling
+
+Hook errors are caught and logged automatically, but do not prevent tool execution from continuing. If a hook throws an error, it will be logged to the console but will not fail the tool call.
+
 ## Related
 
 - [MCP Overview](/docs/v1/mcp/overview)
 - [Using Tools with Agents](/docs/v1/agents/using-tools)
+- [Tool Streaming](/docs/v1/streaming/tool-streaming)
 - [Request Context](/docs/v1/server-db/request-context#accessing-values-with-tools)

package/.docs/raw/reference/tools/graph-rag-tool.mdx

@@ -10,13 +10,13 @@ The `createGraphRAGTool()` creates a tool that enhances RAG by building a graph
 ## Usage Example
 
 ```typescript
-import { openai } from "@ai-sdk/openai";
 import { createGraphRAGTool } from "@mastra/rag";
+import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
 
 const graphTool = createGraphRAGTool({
   vectorStoreName: "pinecone",
   indexName: "docs",
-  model: openai.embedding("text-embedding-3-small"),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
   graphOptions: {
     dimension: 1536,
     threshold: 0.7,
@@ -193,7 +193,7 @@ The default description focuses on:
 const graphTool = createGraphRAGTool({
   vectorStoreName: "pinecone",
   indexName: "docs",
-  model: openai.embedding("text-embedding-3-small"),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
   graphOptions: {
     dimension: 1536,
     threshold: 0.8, // Higher similarity threshold
@@ -209,7 +209,7 @@ const graphTool = createGraphRAGTool({
 const graphTool = createGraphRAGTool({
   vectorStoreName: "pinecone",
   indexName: "docs",
-  model: openai.embedding("text-embedding-3-small"),
+  model: "openai/text-embedding-3-small	",
   description:
     "Analyze document relationships to find complex patterns and connections in our company's historical data",
 });
@@ -223,7 +223,7 @@ This example shows how to customize the tool description for a specific use case
 const graphTool = createGraphRAGTool({
   vectorStoreName: "pinecone",
   indexName: "docs",
-  model: openai.embedding("text-embedding-3-small"),
+  model: "openai/text-embedding-3-small	",
 });
 ```
 

package/.docs/raw/reference/tools/mcp-client.mdx

@@ -632,7 +632,6 @@ For tools where you have a single connection to the MCP server for you entire ap
 ```typescript
 import { MCPClient } from "@mastra/mcp";
 import { Agent } from "@mastra/core/agent";
-import { openai } from "@ai-sdk/openai";
 
 const mcp = new MCPClient({
   servers: {
@@ -657,7 +656,7 @@ const mcp = new MCPClient({
 const agent = new Agent({
   name: "Multi-tool Agent",
   instructions: "You have access to multiple tool servers.",
-  model: openai("gpt-4"),
+  model: "openai/gpt-5.1",
   tools: await mcp.listTools(),
 });
 
@@ -707,13 +706,12 @@ When you need a new MCP connection for each user, use `listToolsets()` and add t
 ```typescript
 import { Agent } from "@mastra/core/agent";
 import { MCPClient } from "@mastra/mcp";
-import { openai } from "@ai-sdk/openai";
 
 // Create the agent first, without any tools
 const agent = new Agent({
   name: "Multi-tool Agent",
   instructions: "You help users check stocks and weather.",
-  model: openai("gpt-4"),
+  model: "openai/gpt-5.1",
 });
 
 // Later, configure MCP with user-specific settings

package/.docs/raw/reference/tools/mcp-server.mdx

@@ -16,7 +16,6 @@ It supports both [stdio (subprocess) and SSE (HTTP) MCP transports](https://mode
 To create a new `MCPServer`, you need to provide some basic information about your server, the tools it will offer, and optionally, any agents you want to expose as tools.
 
 ```typescript
-import { openai } from "@ai-sdk/openai";
 import { Agent } from "@mastra/core/agent";
 import { createTool } from "@mastra/core/tools";
 import { MCPServer } from "@mastra/mcp";
@@ -28,7 +27,7 @@ const myAgent = new Agent({
   name: "MyExampleAgent",
   description: "A generalist to help with basic questions."
   instructions: "You are a helpful assistant.",
-  model: openai("gpt-4o-mini"),
+  model: "openai/gpt-5.1",
 });
 
 const weatherTool = createTool({

package/.docs/raw/reference/tools/vector-query-tool.mdx

@@ -13,13 +13,13 @@ The `createVectorQueryTool()` function creates a tool for semantic search over v
 ## Basic Usage
 
 ```typescript
-import { openai } from "@ai-sdk/openai";
 import { createVectorQueryTool } from "@mastra/rag";
+import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
 
 const queryTool = createVectorQueryTool({
   vectorStoreName: "pinecone",
   indexName: "docs",
-  model: openai.embedding("text-embedding-3-small"),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
 });
 ```
 
@@ -303,7 +303,7 @@ The tool determines the number of results to return based on the user's query, w
 const queryTool = createVectorQueryTool({
   vectorStoreName: "pinecone",
   indexName: "docs",
-  model: openai.embedding("text-embedding-3-small"),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
   enableFilter: true,
 });
 ```
@@ -334,9 +334,9 @@ For an example of how agent-driven filtering works, see the [Agent-Driven Metada
 const queryTool = createVectorQueryTool({
   vectorStoreName: "milvus",
   indexName: "documentation",
-  model: openai.embedding("text-embedding-3-small"),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
   reranker: {
-    model: openai("gpt-4o-mini"),
+    model: "openai/gpt-5.1",
     options: {
       weights: {
         semantic: 0.5, // Semantic relevance weight
@@ -364,7 +364,7 @@ The reranker processes the initial vector search results and returns a reordered
 const queryTool = createVectorQueryTool({
   vectorStoreName: "pinecone",
   indexName: "docs",
-  model: openai.embedding("text-embedding-3-small"),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
   description:
     "Search through document archives to find relevant information for answering questions about company policies and procedures",
 });
@@ -384,7 +384,7 @@ The `databaseConfig` parameter allows you to leverage unique features and optimi
     const pineconeQueryTool = createVectorQueryTool({
       vectorStoreName: "pinecone",
       indexName: "docs",
-      model: openai.embedding("text-embedding-3-small"),
+      model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
       databaseConfig: {
         pinecone: {
           namespace: "production",  // Organize vectors by environment
@@ -411,7 +411,7 @@ The `databaseConfig` parameter allows you to leverage unique features and optimi
     const pgVectorQueryTool = createVectorQueryTool({
       vectorStoreName: "postgres",
       indexName: "embeddings",
-      model: openai.embedding("text-embedding-3-small"),
+      model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
       databaseConfig: {
         pgvector: {
           minScore: 0.7,    // Only return results above 70% similarity
@@ -437,7 +437,7 @@ The `databaseConfig` parameter allows you to leverage unique features and optimi
     const chromaQueryTool = createVectorQueryTool({
       vectorStoreName: "chroma",
       indexName: "documents",
-      model: openai.embedding("text-embedding-3-small"),
+      model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
       databaseConfig: {
         chroma: {
           where: {                    // Metadata filtering
@@ -467,7 +467,7 @@ The `databaseConfig` parameter allows you to leverage unique features and optimi
     const multiDbQueryTool = createVectorQueryTool({
       vectorStoreName: "dynamic-store", // Will be set at runtime
       indexName: "docs",
-      model: openai.embedding("text-embedding-3-small"),
+      model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
       databaseConfig: {
         pinecone: {
           namespace: "default"
@@ -501,7 +501,7 @@ import { RequestContext } from "@mastra/core/request-context";
 const queryTool = createVectorQueryTool({
   vectorStoreName: "pinecone",
   indexName: "docs",
-  model: openai.embedding("text-embedding-3-small"),
+      model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
   databaseConfig: {
     pinecone: {
       namespace: "development",
@@ -534,7 +534,7 @@ This approach allows you to:
 const queryTool = createVectorQueryTool({
   vectorStoreName: "pinecone",
   indexName: "docs",
-  model: openai.embedding("text-embedding-3-small"),
+      model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
 });
 ```
 
@@ -555,7 +555,7 @@ requestContext.set("filter", { category: "docs" });
 requestContext.set("databaseConfig", {
   pinecone: { namespace: "runtime-namespace" },
 });
-requestContext.set("model", openai.embedding("text-embedding-3-small"));
+requestContext.set("model", "openai/text-embedding-3-small");
 
 const response = await agent.generate(
   "Find documentation from the knowledge base.",
@@ -575,7 +575,6 @@ For more information on request context, please see:
 The tool can be used by itself to retrieve documents matching a query:
 
 ```typescript copy showLineNumbers title="src/index.ts"
-import { openai } from "@ai-sdk/openai";
 import { RequestContext } from "@mastra/core/request-context";
 import { createVectorQueryTool } from "@mastra/rag";
 import { PgVector } from "@mastra/pg";
@@ -589,7 +588,7 @@ const vectorQueryTool = createVectorQueryTool({
   vectorStoreName: "pgVector", // optional since we're passing in a store
   vectorStore: pgVector,
   indexName: "embeddings",
-  model: openai.embedding("text-embedding-3-small"),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
 });
 
 const requestContext = new RequestContext();

package/.docs/raw/reference/vectors/chroma.mdx

@@ -335,6 +335,8 @@ interface IndexStats {
 
 ### updateVector()
 
+Update a single vector by ID or by metadata filter. Either `id` or `filter` must be provided, but not both.
+
 <PropertiesTable
   content={[
     {
@@ -345,7 +347,14 @@ interface IndexStats {
     {
       name: "id",
       type: "string",
-      description: "ID of the vector to update",
+      isOptional: true,
+      description: "ID of the vector to update (mutually exclusive with filter)",
+    },
+    {
+      name: "filter",
+      type: "Record<string, any>",
+      isOptional: true,
+      description: "Metadata filter to identify vector(s) to update (mutually exclusive with id)",
     },
     {
       name: "update",
@@ -374,6 +383,24 @@ The `update` object can contain:
   ]}
 />
 
+Example:
+
+```typescript
+// Update by ID
+await vectorStore.updateVector({
+  indexName: 'docs',
+  id: 'vec_123',
+  update: { metadata: { status: 'reviewed' } }
+});
+
+// Update by filter
+await vectorStore.updateVector({
+  indexName: 'docs',
+  filter: { source_id: 'manual.pdf' },
+  update: { metadata: { version: 2 } }
+});
+```
+
 ### deleteVector()
 
 <PropertiesTable
@@ -391,6 +418,59 @@ The `update` object can contain:
   ]}
 />
 
+### deleteVectors()
+
+Delete multiple vectors by IDs or by metadata filter. This method enables bulk deletion and source-based vector management. Either `ids` or `filter` must be provided, but not both.
+
+<PropertiesTable
+  content={[
+    {
+      name: "indexName",
+      type: "string",
+      description: "Name of the index containing the vectors to delete",
+    },
+    {
+      name: "ids",
+      type: "string[]",
+      isOptional: true,
+      description: "Array of vector IDs to delete (mutually exclusive with filter)",
+    },
+    {
+      name: "filter",
+      type: "Record<string, any>",
+      isOptional: true,
+      description: "Metadata filter to identify vectors to delete (mutually exclusive with ids)",
+    },
+  ]}
+/>
+
+Example:
+
+```typescript
+// Delete all chunks from a document
+await vectorStore.deleteVectors({
+  indexName: 'docs',
+  filter: { source_id: 'manual.pdf' }
+});
+
+// Delete multiple vectors by ID
+await vectorStore.deleteVectors({
+  indexName: 'docs',
+  ids: ['vec_1', 'vec_2', 'vec_3']
+});
+
+// Delete old temporary documents
+await vectorStore.deleteVectors({
+  indexName: 'docs',
+  filter: {
+    $and: [
+      { bucket: 'temp' },
+      { indexed_at: { $lt: '2025-01-01' } }
+    ]
+  }
+});
+```
+
 ## Response Types
 
 Query results are returned in this format:

package/.docs/raw/reference/vectors/couchbase.mdx

@@ -239,7 +239,7 @@ Returns: `Promise<string[]>`
 
 ### updateVector()
 
-Updates a specific vector entry by its ID with new vector data and/or metadata.
+Updates a specific vector entry by its ID with new vector data and/or metadata. **Note:** Filter-based updates are not yet implemented for Couchbase.
 
 <PropertiesTable
   content={[
@@ -255,27 +255,15 @@ Updates a specific vector entry by its ID with new vector data and/or metadata.
     },
     {
       name: "update",
-      type: "object",
-      description: "Update data containing vector and/or metadata",
-    },
-    {
-      name: "update.vector",
-      type: "number[]",
-      isOptional: true,
-      description: "New vector data to update",
-    },
-    {
-      name: "update.metadata",
-      type: "Record<string, any>",
-      isOptional: true,
-      description: "New metadata to update",
+      type: "{ vector?: number[]; metadata?: Record<string, any>; }",
+      description: "Object containing the vector and/or metadata to update",
     },
   ]}
 />
 
 ### deleteVector()
 
-Deletes a specific vector entry from an index by its ID.
+Deletes a single vector by its ID from the index.
 
 <PropertiesTable
   content={[
@@ -287,7 +275,26 @@ Deletes a specific vector entry from an index by its ID.
     {
       name: "id",
       type: "string",
-      description: "ID of the vector entry to delete",
+      description: "ID of the vector to delete",
+    },
+  ]}
+/>
+
+### deleteVectors()
+
+Deletes multiple vectors by their IDs. **Note:** Filter-based deletion is not yet implemented for Couchbase.
+
+<PropertiesTable
+  content={[
+    {
+      name: "indexName",
+      type: "string",
+      description: "Name of the index containing the vectors to delete",
+    },
+    {
+      name: "ids",
+      type: "string[]",
+      description: "Array of vector IDs to delete",
     },
   ]}
 />