@mastra/mcp-docs-server 1.0.0-beta.0 → 1.0.0-beta.10

package/.docs/raw/rag/overview.mdx

@@ -1,5 +1,5 @@
 ---
-title: "RAG (Retrieval-Augmented Generation) in Mastra | RAG | Mastra Docs"
+title: "RAG (Retrieval-Augmented Generation) in Mastra | RAG"
 description: Overview of Retrieval-Augmented Generation (RAG) in Mastra, detailing its capabilities for enhancing LLM outputs with relevant context.
 ---
 
@@ -20,7 +20,6 @@ To implement RAG, you process your documents into chunks, create embeddings, sto
 
 ```ts showLineNumbers copy
 import { embedMany } from "ai";
-import { openai } from "@ai-sdk/openai";
 import { PgVector } from "@mastra/pg";
 import { MDocument } from "@mastra/rag";
 import { z } from "zod";
@@ -36,9 +35,11 @@ const chunks = await doc.chunk({
 });
 
 // 3. Generate embeddings; we need to pass the text of each chunk
+import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
+
 const { embeddings } = await embedMany({
   values: chunks.map((chunk) => chunk.text),
-  model: openai.embedding("text-embedding-3-small"),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small")
 });
 
 // 4. Store in vector database
@@ -73,5 +74,5 @@ Mastra supports multiple vector stores for embedding persistence and similarity
 
 ## More resources
 
-- [Chain of Thought RAG Example]/examples/v1/rag/usage/cot-rag)
+- [Chain of Thought RAG Example](/examples/v1/rag/usage/cot-rag)
 - [All RAG Examples](/examples/v1/) (including different chunking strategies, embedding models, and vector stores)

package/.docs/raw/rag/retrieval.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Retrieval, Semantic Search, Reranking | RAG | Mastra Docs"
+title: "Retrieval, Semantic Search, Reranking | RAG"
 description: Guide on retrieval processes in Mastra's RAG systems, including semantic search, filtering, and re-ranking.
 ---
 
@@ -27,14 +27,14 @@ Mastra provides flexible retrieval options with support for semantic search, fil
 The simplest approach is direct semantic search. This method uses vector similarity to find chunks that are semantically similar to the query:
 
 ```ts showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
 import { embed } from "ai";
 import { PgVector } from "@mastra/pg";
+import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
 
 // Convert query to embedding
 const { embedding } = await embed({
   value: "What are the main points in the article?",
-  model: openai.embedding("text-embedding-3-small"),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
 });
 
 // Query vector store
@@ -52,6 +52,8 @@ const results = await pgVector.query({
 console.log(results);
 ```
 
+The `topK` parameter specifies the maximum number of most similar results to return from the vector search.
+
 Results include both the text content and a similarity score:
 
 ```ts showLineNumbers copy
@@ -70,8 +72,6 @@ Results include both the text content and a similarity score:
 ];
 ```
 
-For an example of how to use the basic retrieval method, see the [Retrieve Results](/examples/v1/rag/query/retrieve-results) example.
-
 ## Advanced Retrieval options
 
 ### Metadata Filtering
@@ -156,7 +156,7 @@ Sometimes you want to give your agent the ability to query a vector database dir
 const vectorQueryTool = createVectorQueryTool({
   vectorStoreName: "pgVector",
   indexName: "embeddings",
-  model: openai.embedding("text-embedding-3-small"),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
 });
 ```
 
@@ -170,14 +170,21 @@ This is particularly useful when:
 
 #### Database-Specific Configurations
 
-The Vector Query Tool supports database-specific configurations that enable you to leverage unique features and optimizations of different vector stores:
+The Vector Query Tool supports database-specific configurations that enable you to leverage unique features and optimizations of different vector stores.
+
+:::note
+These configurations are for **query-time options** like namespaces, performance tuning, and filtering—not for database connection setup. 
+
+
+Connection credentials (URLs, auth tokens) are configured when you instantiate the vector store class (e.g., `new LibSQLVector({ connectionUrl: '...' })`).
+:::
 
 ```ts showLineNumbers copy
 // Pinecone with namespace
 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", // Isolate data by environment
@@ -189,7 +196,7 @@ const pineconeQueryTool = createVectorQueryTool({
 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, // Filter low-quality results
@@ -203,7 +210,7 @@ const pgVectorQueryTool = createVectorQueryTool({
 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: { category: "technical" },
@@ -216,7 +223,7 @@ const chromaQueryTool = createVectorQueryTool({
 const lanceQueryTool = createVectorQueryTool({
   vectorStoreName: "lance",
   indexName: "documents",
-  model: openai.embedding("text-embedding-3-small"),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
   databaseConfig: {
     lance: {
       tableName: "myVectors", // Specify which table to query
@@ -272,13 +279,12 @@ When implementing filtering, these prompts are required in the agent's instructi
   <TabItem value="pgvector" label="pgVector">
 
 ```ts showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
 import { PGVECTOR_PROMPT } from "@mastra/pg";
 
 export const ragAgent = new Agent({
   id: "rag-agent",
   name: "RAG Agent",
-  model: openai("gpt-4o-mini"),
+  model: "openai/gpt-5.1",
   instructions: `
   Process queries using the provided context. Structure responses to be concise and relevant.
   ${PGVECTOR_PROMPT}
@@ -292,13 +298,12 @@ export const ragAgent = new Agent({
   <TabItem value="pinecone" label="Pinecone">
 
 ```ts title="vector-store.ts" showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
 import { PINECONE_PROMPT } from "@mastra/pinecone";
 
 export const ragAgent = new Agent({
   id: "rag-agent",
   name: "RAG Agent",
-  model: openai("gpt-4o-mini"),
+  model: "openai/gpt-5.1",
   instructions: `
   Process queries using the provided context. Structure responses to be concise and relevant.
   ${PINECONE_PROMPT}
@@ -312,13 +317,12 @@ export const ragAgent = new Agent({
   <TabItem value="qdrant" label="Qdrant">
 
 ```ts title="vector-store.ts" showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
 import { QDRANT_PROMPT } from "@mastra/qdrant";
 
 export const ragAgent = new Agent({
   id: "rag-agent",
   name: "RAG Agent",
-  model: openai("gpt-4o-mini"),
+  model: "openai/gpt-5.1",
   instructions: `
   Process queries using the provided context. Structure responses to be concise and relevant.
   ${QDRANT_PROMPT}
@@ -332,13 +336,12 @@ export const ragAgent = new Agent({
   <TabItem value="chroma" label="Chroma">
 
 ```ts title="vector-store.ts" showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
 import { CHROMA_PROMPT } from "@mastra/chroma";
 
 export const ragAgent = new Agent({
   id: "rag-agent",
   name: "RAG Agent",
-  model: openai("gpt-4o-mini"),
+  model: "openai/gpt-5.1",
   instructions: `
   Process queries using the provided context. Structure responses to be concise and relevant.
   ${CHROMA_PROMPT}
@@ -352,13 +355,12 @@ export const ragAgent = new Agent({
   <TabItem value="astra" label="Astra">
 
 ```ts title="vector-store.ts" showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
 import { ASTRA_PROMPT } from "@mastra/astra";
 
 export const ragAgent = new Agent({
   id: "rag-agent",
   name: "RAG Agent",
-  model: openai("gpt-4o-mini"),
+  model: "openai/gpt-5.1",
   instructions: `
   Process queries using the provided context. Structure responses to be concise and relevant.
   ${ASTRA_PROMPT}
@@ -372,13 +374,12 @@ export const ragAgent = new Agent({
   <TabItem value="libsql" label="LibSQL">
 
 ```ts title="vector-store.ts" showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
 import { LIBSQL_PROMPT } from "@mastra/libsql";
 
 export const ragAgent = new Agent({
   id: "rag-agent",
   name: "RAG Agent",
-  model: openai("gpt-4o-mini"),
+  model: "openai/gpt-5.1",
   instructions: `
   Process queries using the provided context. Structure responses to be concise and relevant.
   ${LIBSQL_PROMPT}
@@ -392,13 +393,12 @@ export const ragAgent = new Agent({
   <TabItem value="upstash" label="Upstash">
 
 ```ts title="vector-store.ts" showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
 import { UPSTASH_PROMPT } from "@mastra/upstash";
 
 export const ragAgent = new Agent({
   id: "rag-agent",
   name: "RAG Agent",
-  model: openai("gpt-4o-mini"),
+  model: "openai/gpt-5.1",
   instructions: `
   Process queries using the provided context. Structure responses to be concise and relevant.
   ${UPSTASH_PROMPT}
@@ -412,13 +412,12 @@ export const ragAgent = new Agent({
   <TabItem value="vectorize" label="Vectorize">
 
 ```ts title="vector-store.ts" showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
 import { VECTORIZE_PROMPT } from "@mastra/vectorize";
 
 export const ragAgent = new Agent({
   id: "rag-agent",
   name: "RAG Agent",
-  model: openai("gpt-4o-mini"),
+  model: "openai/gpt-5.1",
   instructions: `
   Process queries using the provided context. Structure responses to be concise and relevant.
   ${VECTORIZE_PROMPT}
@@ -432,13 +431,12 @@ export const ragAgent = new Agent({
   <TabItem value="mongodb" label="MongoDB">
 
 ```ts title="vector-store.ts" showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
 import { MONGODB_PROMPT } from "@mastra/mongodb";
 
 export const ragAgent = new Agent({
   id: "rag-agent",
   name: "RAG Agent",
-  model: openai("gpt-4o-mini"),
+  model: "openai/gpt-5.1",
   instructions: `
   Process queries using the provided context. Structure responses to be concise and relevant.
   ${MONGODB_PROMPT}
@@ -452,13 +450,12 @@ export const ragAgent = new Agent({
   <TabItem value="opensearch" label="OpenSearch">
 
 ```ts title="vector-store.ts" showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
 import { OPENSEARCH_PROMPT } from "@mastra/opensearch";
 
 export const ragAgent = new Agent({
   id: "rag-agent",
   name: "RAG Agent",
-  model: openai("gpt-4o-mini"),
+  model: "openai/gpt-5.1",
   instructions: `
   Process queries using the provided context. Structure responses to be concise and relevant.
   ${OPENSEARCH_PROMPT}
@@ -472,13 +469,12 @@ export const ragAgent = new Agent({
   <TabItem value="s3vectors" label="S3Vectors">
 
 ```ts title="vector-store.ts" showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
 import { S3VECTORS_PROMPT } from "@mastra/s3vectors";
 
 export const ragAgent = new Agent({
   id: "rag-agent",
   name: "RAG Agent",
-  model: openai("gpt-4o-mini"),
+  model: "openai/gpt-5.1",
   instructions: `
   Process queries using the provided context. Structure responses to be concise and relevant.
   ${S3VECTORS_PROMPT}
@@ -502,7 +498,6 @@ Initial vector similarity search can sometimes miss nuanced relevance. Re-rankin
 Here's how to use re-ranking:
 
 ```ts showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
 import {
   rerankWithScorer as rerank,
   MastraAgentRelevanceScorer
@@ -516,19 +511,31 @@ const initialResults = await pgVector.query({
 });
 
 // Create a relevance scorer
-const relevanceProvider = new MastraAgentRelevanceScorer('relevance-scorer', openai("gpt-4o-mini"));
+const relevanceProvider = new MastraAgentRelevanceScorer('relevance-scorer', "openai/gpt-5.1");
 
 // Re-rank the results
 const rerankedResults = await rerank({
   results: initialResults,
   query,
-  provider: relevanceProvider,
+  scorer: relevanceProvider,
   options: {
+    weights: {
+      semantic: 0.5, // How well the content matches the query semantically
+      vector: 0.3, // Original vector similarity score
+      position: 0.2, // Preserves original result ordering
+    },
     topK: 10,
   },
 );
 ```
 
+The weights control how different factors influence the final ranking:
+
+- `semantic`: Higher values prioritize semantic understanding and relevance to the query
+- `vector`: Higher values favor the original vector similarity scores
+- `position`: Higher values help maintain the original ordering of results
+
+
 > **Note:** For semantic scoring to work properly during re-ranking, each result must include the text content in its `metadata.text` field.
 
 You can also use other relevance score providers like Cohere or ZeroEntropy:
@@ -545,8 +552,6 @@ The re-ranked results combine vector similarity with semantic understanding to i
 
 For more details about re-ranking, see the [rerank()](/reference/v1/rag/rerankWithScorer) method.
 
-For an example of how to use the re-ranking method, see the Re-ranking Results example in the examples section.
-
 ### Graph-based Retrieval
 
 For documents with complex relationships, graph-based retrieval can follow connections between chunks. This helps when:
@@ -561,7 +566,7 @@ Example setup:
 const graphQueryTool = createGraphQueryTool({
   vectorStoreName: "pgVector",
   indexName: "embeddings",
-  model: openai.embedding("text-embedding-3-small"),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
   graphOptions: {
     threshold: 0.7,
   },

package/.docs/raw/rag/vector-databases.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Storing Embeddings in A Vector Database | RAG | Mastra Docs"
+title: "Storing Embeddings in A Vector Database | RAG"
 description: Guide on vector storage options in Mastra, including embedded and dedicated vector databases for similarity search.
 ---
 
@@ -252,6 +252,27 @@ await store.createIndex({
   dimension: 1536,
 });
 
+await store.upsert({
+  indexName: "my-collection",
+  vectors: embeddings,
+  metadata: chunks.map((chunk) => ({ text: chunk.text })),
+});
+```
+
+  </TabItem>
+
+  <TabItem value="elasticsearch" label="ElasticSearch">
+
+```ts title="vector-store.ts" showLineNumbers copy
+import { ElasticSearchVector } from "@mastra/elasticsearch";
+
+const store = new ElasticSearchVector({ url: process.env.ELASTICSEARCH_URL });
+
+await store.createIndex({
+  indexName: "my-collection",
+  dimension: 1536,
+});
+
 await store.upsert({
   indexName: "my-collection",
   vectors: embeddings,
@@ -459,6 +480,20 @@ Each vector database enforces specific naming conventions for indexes and collec
     - Example: `My_Index` is not valid (contains uppercase letters)
     - Example: `_myindex` is not valid (begins with underscore)
   </TabItem>
+  <TabItem value="elasticsearch" label="ElasticSearch">
+    Index names must:
+    - Use only lowercase letters
+    - Not exceed 255 bytes (counting multi-byte characters)
+    - Not begin with underscores, hyphens, or plus signs
+    - Not contain spaces, commas
+    - Not contain special characters (e.g. `:`, `"`, `*`, `+`, `/`, `\`, `|`, `?`, `#`, `>`, `<`)
+    - Not be "." or ".."
+    - Not start with "." (deprecated except for system/hidden indices)
+    - Example: `my-index-123` is valid
+    - Example: `My_Index` is not valid (contains uppercase letters)
+    - Example: `_myindex` is not valid (begins with underscore)
+    - Example: `.myindex` is not valid (begins with dot, deprecated)
+  </TabItem>
   <TabItem value="s3vectors" label="S3 Vectors">
     Index names must:
     - Be unique within the same vector bucket
@@ -496,8 +531,6 @@ The upsert operation:
 - Creates new vectors if they don't exist
 - Automatically handles batching for large datasets
 
-For complete examples of upserting embeddings in different vector stores, see the [Upsert Embeddings](/examples/v1/rag/upsert/upsert-embeddings) guide.
-
 ## Adding Metadata
 
 Vector stores support rich metadata (any JSON-serializable fields) for filtering and organization. Since metadata is stored with no fixed schema, use consistent field naming to avoid unexpected query results.
@@ -536,6 +569,64 @@ Key metadata considerations:
 - Only include fields you plan to filter or sort by - extra fields add overhead
 - Add timestamps (e.g., 'createdAt', 'lastUpdated') to track content freshness
 
+## Deleting Vectors
+
+When building RAG applications, you often need to clean up stale vectors when documents are deleted or updated. Mastra provides the `deleteVectors` method that supports deleting vectors by metadata filters, making it easy to remove all embeddings associated with a specific document.
+
+### Delete by Metadata Filter
+
+The most common use case is deleting all vectors for a specific document when a user deletes it:
+
+```ts title="delete-vectors.ts" showLineNumbers copy
+// Delete all vectors for a specific document
+await store.deleteVectors({
+  indexName: "myCollection",
+  filter: { docId: "document-123" },
+});
+```
+
+This is particularly useful when:
+- A user deletes a document and you need to remove all its chunks
+- You're re-indexing a document and want to remove old vectors first
+- You need to clean up vectors for a specific user or tenant
+
+### Delete Multiple Documents
+
+You can also use complex filters to delete vectors matching multiple conditions:
+
+```ts title="delete-vectors-advanced.ts" showLineNumbers copy
+// Delete all vectors for multiple documents
+await store.deleteVectors({
+  indexName: "myCollection",
+  filter: {
+    docId: { $in: ["doc-1", "doc-2", "doc-3"] },
+  },
+});
+
+// Delete vectors for a specific user's documents
+await store.deleteVectors({
+  indexName: "myCollection",
+  filter: {
+    $and: [
+      { userId: "user-123" },
+      { status: "archived" },
+    ],
+  },
+});
+```
+
+### Delete by Vector IDs
+
+If you have specific vector IDs to delete, you can pass them directly:
+
+```ts title="delete-by-ids.ts" showLineNumbers copy
+// Delete specific vectors by their IDs
+await store.deleteVectors({
+  indexName: "myCollection",
+  ids: ["vec-1", "vec-2", "vec-3"],
+});
+```
+
 ## Best Practices
 
 - Create indexes before bulk insertions

package/.docs/raw/reference/agents/agent.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Agent Class | Agents | Mastra Docs"
+title: "Reference: Agent Class | Agents"
 description: "Documentation for the `Agent` class in Mastra, which provides the foundation for creating AI agents with various capabilities."
 ---
 
@@ -12,7 +12,6 @@ The `Agent` class is the foundation for creating AI agents in Mastra. It provide
 ### Basic string instructions
 
 ```typescript title="src/mastra/agents/string-agent.ts" showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
 import { Agent } from "@mastra/core/agent";
 
 // String instructions
@@ -20,7 +19,7 @@ export const agent = new Agent({
   id: "test-agent",
   name: "Test Agent",
   instructions: "You are a helpful assistant that provides concise answers.",
-  model: openai("gpt-4o"),
+  model: "openai/gpt-5.1",
 });
 
 // System message object
@@ -31,7 +30,7 @@ export const agent2 = new Agent({
     role: "system",
     content: "You are an expert programmer",
   },
-  model: openai("gpt-4o"),
+  model: "openai/gpt-5.1",
 });
 
 // Array of system messages
@@ -42,7 +41,7 @@ export const agent3 = new Agent({
     { role: "system", content: "You are a helpful assistant" },
     { role: "system", content: "You have expertise in TypeScript" },
   ],
-  model: openai("gpt-4o"),
+  model: "openai/gpt-5.1",
 });
 ```
 
@@ -51,7 +50,6 @@ export const agent3 = new Agent({
 Use CoreSystemMessage format to access additional properties like `providerOptions` for provider-specific configurations:
 
 ```typescript title="src/mastra/agents/core-message-agent.ts" showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
 import { Agent } from "@mastra/core/agent";
 
 export const agent = new Agent({
@@ -67,14 +65,13 @@ export const agent = new Agent({
       },
     },
   },
-  model: openai("gpt-5"),
+  model: "openai/gpt-5.1",
 });
 ```
 
 ### Multiple CoreSystemMessages
 
 ```typescript title="src/mastra/agents/multi-message-agent.ts" showLineNumbers copy
-import { anthropic } from "@ai-sdk/anthropic";
 import { Agent } from "@mastra/core/agent";
 
 // This could be customizable based on the user
@@ -97,7 +94,7 @@ export const agent = new Agent({
       },
     },
   ],
-  model: anthropic("claude-sonnet-4-20250514"),
+  model: "anthropic/claude-sonnet-4-20250514",
 });
 ```
 
@@ -110,13 +107,13 @@ export const agent = new Agent({
       type: "string",
       isOptional: true,
       description:
-        "Optional unique identifier for the agent. Defaults to `name` if not provided.",
+        "Unique identifier for the agent. Defaults to `name` if not provided.",
     },
     {
       name: "name",
       type: "string",
       isOptional: false,
-      description: "Unique identifier for the agent.",
+      description: "Display name for the agent. Used as the identifier if `id` is not provided.",
     },
     {
       name: "description",
@@ -129,8 +126,8 @@ export const agent = new Agent({
       name: "instructions",
       type: "SystemMessage | ({ requestContext: RequestContext }) => SystemMessage | Promise<SystemMessage>",
       isOptional: false,
-      description: `Instructions that guide the agent's behavior. Can be a string, array of strings, system message object, 
-        array of system messages, or a function that returns any of these types dynamically. 
+      description: `Instructions that guide the agent's behavior. Can be a string, array of strings, system message object,
+        array of system messages, or a function that returns any of these types dynamically.
         SystemMessage types: string | string[] | CoreSystemMessage | CoreSystemMessage[] | SystemModelMessage | SystemModelMessage[]`,
     },
     {
@@ -245,4 +242,3 @@ export const agent = new Agent({
 ## Related
 
 - [Agents overview](/docs/v1/agents/overview)
-- [Calling Agents](/examples/v1/agents/calling-agents)