@mastra/mcp-docs-server 0.13.5-alpha.0 → 0.13.6

package/.docs/raw/getting-started/installation.mdx

@@ -79,7 +79,7 @@ OPENAI_API_KEY=<your-api-key>
 ```
 > This example uses OpenAI. Each LLM provider uses a unique name. See [Model Capabilities](/docs/getting-started/model-capability) for more information.
 
-You can now launch the [Mastra Development Server](/docs/local-dev/mastra-dev) and test your agent using the Mastra Playground.
+You can now launch the [Mastra Development Server](/docs/server-db/local-dev-playground) and test your agent using the Mastra Playground.
 
 </Steps>
 
@@ -114,7 +114,7 @@ This helps users manually set up a Mastra project with their preferred package m
 
     npm install typescript tsx @types/node mastra@latest --save-dev
 
-    npm install @mastra/core@latest zod @ai-sdk/openai
+    npm install @mastra/core@latest zod@^3 @ai-sdk/openai
     ```
 
   </Tab>
@@ -124,7 +124,7 @@ This helps users manually set up a Mastra project with their preferred package m
 
     pnpm add typescript tsx @types/node mastra@latest --save-dev
 
-    pnpm add @mastra/core@latest zod @ai-sdk/openai
+    pnpm add @mastra/core@latest zod@^3 @ai-sdk/openai
     ```
 
   </Tab>
@@ -134,7 +134,7 @@ This helps users manually set up a Mastra project with their preferred package m
 
     yarn add typescript tsx @types/node mastra@latest --dev
 
-    yarn add @mastra/core@latest zod @ai-sdk/openai
+    yarn add @mastra/core@latest zod@^3 @ai-sdk/openai
     ```
 
   </Tab>
@@ -144,7 +144,7 @@ This helps users manually set up a Mastra project with their preferred package m
 
     bun add typescript tsx @types/node mastra@latest --dev
 
-    bun add @mastra/core@latest zod @ai-sdk/openai
+    bun add @mastra/core@latest zod@^3 @ai-sdk/openai
     ```
 
   </Tab>
@@ -295,7 +295,7 @@ export const mastra = new Mastra({
 });
 ```
 
-You can now launch the [Mastra Development Server](/docs/local-dev/mastra-dev) and test your agent using the Mastra Playground.
+You can now launch the [Mastra Development Server](/docs/server-db/local-dev-playground) and test your agent using the Mastra Playground.
 
 </Steps>
 
@@ -317,5 +317,8 @@ To install Mastra in an existing project, use the `mastra init` command.
 
 ## Next steps
 
-- [Local Development](/docs/local-dev/mastra-dev)
+- [Local Development](/docs/server-db/local-dev-playground)
 - [Deploy to Mastra Cloud](/docs/deployment/overview)
+
+
+/docs/server-db/local-dev-playground

package/.docs/raw/getting-started/model-capability.mdx

@@ -1,4 +1,4 @@
-## Model Capabilities
+# Model Capabilities
 
 import { ProviderTable } from "@/components/provider-table";
 

package/.docs/raw/memory/overview.mdx

@@ -156,6 +156,14 @@ const agent = new Agent({
 - [Postgres](/examples/memory/memory-with-pg)
 - [Upstash](/examples/memory/memory-with-upstash)
 
+## Viewing Retrieved Messages
+
+If tracing is enabled in your Mastra deployment and memory is configured either with `lastMessages` and/or `semanticRecall`, the agent’s trace output will show all messages retrieved for context—including both recent conversation history and messages recalled via semantic recall.
+
+This is helpful for debugging, understanding agent decisions, and verifying that the agent is retrieving the right information for each request.
+
+For more details on enabling and configuring tracing, see [Tracing](../observability/tracing).
+
 ## Next Steps
 
 Now that you understand the core concepts, continue to [semantic recall](./semantic-recall.mdx) to learn how to add RAG memory to your Mastra agents.

package/.docs/raw/memory/semantic-recall.mdx

@@ -149,3 +149,9 @@ You might want to disable semantic recall in scenarios like:
 
 - When conversation history provide sufficient context for the current conversation.
 - In performance-sensitive applications, like realtime two-way audio, where the added latency of creating embeddings and running vector queries is noticeable.
+
+## Viewing Recalled Messages
+
+When tracing is enabled, any messages retrieved via semantic recall will appear in the agent’s trace output, alongside recent conversation history (if configured).
+
+For more info on viewing message traces, see [Viewing Retrieved Messages](./overview.mdx#viewing-retrieved-messages).

package/.docs/raw/observability/tracing.mdx

@@ -105,6 +105,36 @@ Here's what a traced agent interaction looks like in [SigNoz](https://signoz.io)
 
 For a complete list of supported observability providers and their configuration details, see the [Observability Providers reference](../../reference/observability/providers/).
 
+### Custom Instrumentation files
+
+You can define custom instrumentation files in your Mastra project by placing them in the `/mastra` folder. Mastra automatically detects and bundles these files instead of using the default instrumentation.
+
+#### Supported File Types
+
+Mastra looks for instrumentation files with these extensions:
+- `instrumentation.js`
+- `instrumentation.ts` 
+- `instrumentation.mjs`
+
+#### Example
+
+```ts filename="/mastra/instrumentation.ts" showLineNumbers copy
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+
+const sdk = new NodeSDK({
+  traceExporter: new OTLPTraceExporter({
+    url: 'http://localhost:4318/v1/traces',
+  }),
+  instrumentations: [getNodeAutoInstrumentations()],
+});
+
+sdk.start();
+```
+
+When Mastra finds a custom instrumentation file, it automatically replaces the default instrumentation and bundles it during the build process.
+
 ### Next.js-specific Tracing steps
 
 If you're using Next.js, you have three additional configuration steps:

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

@@ -456,7 +456,10 @@ Here's how to use re-ranking:
 
 ```ts showLineNumbers copy
 import { openai } from "@ai-sdk/openai";
-import { rerank } from "@mastra/rag";
+import { 
+  rerankWithScorer as rerank, 
+  MastraAgentRelevanceScorer 
+} from "@mastra/rag";
 
 // Get initial results from vector search
 const initialResults = await pgVector.query({
@@ -465,19 +468,35 @@ const initialResults = await pgVector.query({
   topK: 10,
 });
 
+// Create a relevance scorer
+const relevanceProvider = new MastraAgentRelevanceScorer('relevance-scorer', openai("gpt-4o-mini"));
+
 // Re-rank the results
-const rerankedResults = await rerank(
-  initialResults,
+const rerankedResults = await rerank({
+  results: initialResults,
   query,
-  openai("gpt-4o-mini"),
+  provider: relevanceProvider,
+  options: {
+    topK: 10,
+  },
 );
 ```
 
 > **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:
+
+```ts showLineNumbers copy
+const relevanceProvider = new CohereRelevanceScorer('rerank-v3.5');
+```
+
+```ts showLineNumbers copy
+const relevanceProvider = new ZeroEntropyRelevanceScorer('zerank-1');
+```
+
 The re-ranked results combine vector similarity with semantic understanding to improve retrieval quality.
 
-For more details about re-ranking, see the [rerank()](/reference/rag/rerank) method.
+For more details about re-ranking, see the [rerank()](/reference/rag/rerankWithScorer) method.
 
 For an example of how to use the re-ranking method, see the [Re-ranking Results](../../examples/rag/rerank/rerank.mdx) example.
 

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

@@ -88,10 +88,10 @@ constructor(config: AgentConfig<TAgentId, TTools, TMetrics>)
     },
     {
       name: "memory",
-      type: "MastraMemory",
+      type: "MastraMemory | ({ runtimeContext: RuntimeContext }) => MastraMemory | Promise<MastraMemory>",
       isOptional: true,
       description:
-        "Memory system for the agent to store and retrieve information.",
+        "Memory system for the agent to store and retrieve information. Can be a static memory instance or a function that returns a memory instance based on runtime context.",
     },
     {
       name: "voice",

package/.docs/raw/reference/cli/create-mastra.mdx

@@ -68,6 +68,13 @@ create-mastra [options]
       description: "Do not include example code",
       isOptional: true,
     },
+    {
+      name: "--template",
+      type: "string",
+      description:
+        "Create project from a template (use template name, public GitHub URL, or leave blank to select from list)",
+      isOptional: true,
+    },
     {
       name: "--timeout",
       type: "number",

package/.docs/raw/reference/cli/dev.mdx

@@ -44,13 +44,13 @@ mastra dev [options]
     },
     {
       name: "--env",
-      type: "string", 
+      type: "string",
       description: "Path to custom environment file",
       isOptional: true,
     },
     {
       name: "--inspect",
-      type: "boolean", 
+      type: "boolean",
       description: "Start the dev server in inspect mode for debugging (cannot be used with --inspect-brk)",
       isOptional: true,
     },
@@ -123,6 +123,7 @@ Workflows are expected to be exported from `src/mastra/workflows` (or the config
 - **GET `/api/memory/threads`**: Get all threads.
 - **GET `/api/memory/threads/:threadId`**: Get thread by ID.
 - **GET `/api/memory/threads/:threadId/messages`**: Get messages for a thread.
+- **GET `/api/memory/threads/:threadId/messages/paginated`**: Get paginated messages for a thread.
 - **POST `/api/memory/threads`**: Create a new thread.
 - **PATCH `/api/memory/threads/:threadId`**: Update a thread.
 - **DELETE `/api/memory/threads/:threadId`**: Delete a thread.
@@ -154,7 +155,7 @@ Workflows are expected to be exported from `src/mastra/workflows` (or the config
 
 ## Additional Notes
 
-The port defaults to 4111. Both the port and hostname can be configured via the mastra server config. See [Launch Development Server](/docs/local-dev/mastra-dev#launch-development-server) for configuration details.
+The port defaults to 4111. Both the port and hostname can be configured via the mastra server config. See [Launch Development Server](/docs/server-db/local-dev-playground) for configuration details.
 
 Make sure you have your environment variables set up in your `.env.development` or `.env` file for any providers you use (e.g., `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.).
 

package/.docs/raw/reference/client-js/agents.mdx

@@ -89,6 +89,14 @@ response.processDataStream({
   },
 });
 
+// Process text stream with the processTextStream util 
+// (used with structured output)
+ response.processTextStream({
+      onTextPart: text => {
+        process.stdout.write(text);
+      },
+});
+
 // You can also read from response body directly
 const reader = response.body.getReader();
 while (true) {

package/.docs/raw/reference/memory/query.mdx

@@ -1,6 +1,6 @@
 # query
 
-Retrieves messages from a specific thread, with support for pagination and filtering options.
+Retrieves messages from a specific thread, with support for pagination, filtering options, and semantic search.
 
 ## Usage Example
 
@@ -12,7 +12,7 @@ const memory = new Memory({
 });
 
 // Get last 50 messages
-const { messages, uiMessages } = await memory.query({
+const { messages, uiMessages, messagesV2 } = await memory.query({
   threadId: "thread-123",
   selectBy: {
     last: 50,
@@ -43,7 +43,7 @@ const { messages } = await memory.query({
     vectorSearchString: "What was discussed about deployment?",
   },
   threadConfig: {
-    historySearch: true,
+    semanticRecall: true,
   },
 });
 ```
@@ -69,13 +69,13 @@ const { messages } = await memory.query({
     {
       name: "selectBy",
       type: "object",
-      description: "Options for filtering messages",
+      description: "Options for filtering and selecting messages",
       isOptional: true,
     },
     {
       name: "threadConfig",
       type: "MemoryConfig",
-      description: "Configuration options for message retrieval",
+      description: "Configuration options for message retrieval and semantic search",
       isOptional: true,
     },
   ]}
@@ -88,7 +88,7 @@ const { messages } = await memory.query({
     {
       name: "vectorSearchString",
       type: "string",
-      description: "Search string for finding semantically similar messages",
+      description: "Search string for finding semantically similar messages. Requires semantic recall to be enabled in threadConfig.",
       isOptional: true,
     },
     {
@@ -102,9 +102,9 @@ const { messages } = await memory.query({
     {
       name: "include",
       type: "array",
-      description: "Array of message IDs to include with context",
+      description: "Array of specific message IDs to include with optional context messages",
       isOptional: true,
-    },
+    }
   ]}
 />
 
@@ -118,6 +118,12 @@ const { messages } = await memory.query({
       description: "ID of the message to include",
       isOptional: false,
     },
+    {
+      name: "threadId",
+      type: "string",
+      description: "Optional thread ID (defaults to the main threadId parameter)",
+      isOptional: true,
+    },
     {
       name: "withPreviousMessages",
       type: "number",
@@ -142,22 +148,37 @@ const { messages } = await memory.query({
     {
       name: "messages",
       type: "CoreMessage[]",
-      description: "Array of retrieved messages in their core format",
+      description: "Array of retrieved messages in their core format (v1 format for backwards compatibility)",
     },
     {
       name: "uiMessages",
-      type: "AiMessage[]",
-      description: "Array of messages formatted for UI display",
+      type: "UIMessage[]",
+      description: "Array of messages formatted for UI display, including proper threading of tool calls and results",
+    },
+    {
+      name: "messagesV2",
+      type: "MastraMessageV2[]",
+      description: "Array of messages in the v2 format, the current internal message format",
     },
   ]}
 />
 
 ## Additional Notes
 
-The `query` function returns two different message formats:
+The `query` function returns three different message formats:
+
+- `messages`: Core message format (v1) used for backwards compatibility with older APIs
+- `uiMessages`: Formatted messages suitable for UI display, including proper threading of tool calls and results  
+- `messagesV2`: The current internal message format with enhanced structure and metadata
+
+### Semantic Search
+
+When using `vectorSearchString`, ensure that:
+- Semantic recall is enabled in your `threadConfig` 
+- A vector database is configured in your Memory instance
+- An embedding model is provided
 
-- `messages`: Core message format used internally
-- `uiMessages`: Formatted messages suitable for UI display, including proper threading of tool calls and results
+The function will automatically include context messages around semantically similar results based on the configured `messageRange`.
 
 ### Related
 

package/.docs/raw/reference/observability/providers/keywordsai.mdx

@@ -0,0 +1,73 @@
+---
+title: "Reference: Keywords AI Integration | Mastra Observability Docs"
+description: Documentation for integrating Keywords AI (an observability platform for LLM applications) with Mastra.
+---
+
+## Keywords AI
+
+[Keywords AI](https://docs.keywordsai.co/get-started/overview) is a full-stack LLM engineering platform that helps developers and PMs build reliable AI products faster. In a shared workspace, product teams can build, monitor, and improve AI performance.
+
+This tutorial shows how to set up Keywords AI tracing with [Mastra](https://mastra.ai/) to monitor and trace your AI-powered applications.
+
+To help you get started quickly, we’ve provided a pre-built example. You can find the code [on GitHub](https://github.com/Keywords-AI/keywordsai-example-projects/tree/main/mastra-ai-weather-agent).
+
+
+## Setup
+
+Here's the tutorial about the Mastra Weather Agent example.
+
+### 1. Install Dependencies
+
+```bash copy
+pnpm install
+```
+
+### 2. Environment Variables
+
+Copy the example environment file and add your API keys:
+
+```bash copy
+cp .env.local.example .env.local
+```
+
+Update .env.local with your credentials: 
+
+```bash .env.local copy
+OPENAI_API_KEY=your-openai-api-key
+KEYWORDSAI_API_KEY=your-keywordsai-api-key
+KEYWORDSAI_BASE_URL=https://api.keywordsai.co
+```
+
+### 3. Setup Mastra client with Keywords AI tracing
+
+Configure with KeywordsAI telemetry in `src/mastra/index.ts`:
+
+```typescript filename="src/mastra/index.ts" showLineNumbers copy
+
+import { Mastra } from "@mastra/core/mastra";
+import { KeywordsAIExporter } from "@keywordsai/exporter-vercel";
+
+telemetry: {
+  serviceName: "keywordai-mastra-example",
+  enabled: true,
+  export: {
+    type: "custom",
+    exporter: new KeywordsAIExporter({
+      apiKey: process.env.KEYWORDSAI_API_KEY,
+      baseUrl: process.env.KEYWORDSAI_BASE_URL,
+      debug: true,
+    })
+  }
+}
+```
+
+### 3. Run the Project
+
+```bash copy
+mastra dev
+```
+This opens the Mastra playground where you can interact with the weather agent.
+
+## Observability
+
+Once configured, you can view your traces and analytics in the [Keywords AI platform](https://platform.keywordsai.co/platform/traces).

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

@@ -0,0 +1,213 @@
+---
+title: "Reference: Rerank | Document Retrieval | RAG | Mastra Docs"
+description: Documentation for the rerank function in Mastra, which provides advanced reranking capabilities for vector search results.
+---
+
+# rerankWithScorer()
+
+The `rerankWithScorer()` function provides advanced reranking capabilities for vector search results by combining semantic relevance, vector similarity, and position-based scoring.
+
+```typescript
+function rerankWithScorer({
+  results: QueryResult[],
+  query: string,
+  scorer: RelevanceScoreProvider,
+  options?: RerankerFunctionOptions,
+}): Promise<RerankResult[]>;
+```
+
+## Usage Example
+
+```typescript
+import { openai } from "@ai-sdk/openai";
+import { rerankWithScorer as rerank, CohereRelevanceScorer } from "@mastra/rag";
+
+const scorer = new CohereRelevanceScorer('rerank-v3.5');
+
+const rerankedResults = await rerank({
+  results: vectorSearchResults,
+  query: "How do I deploy to production?",
+  scorer,
+  options: {
+    weights: {
+      semantic: 0.5,
+      vector: 0.3,
+      position: 0.2,
+    },
+    topK: 3,
+  },
+});
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "results",
+      type: "QueryResult[]",
+      description: "The vector search results to rerank",
+      isOptional: false,
+    },
+    {
+      name: "query",
+      type: "string",
+      description: "The search query text used to evaluate relevance",
+      isOptional: false,
+    },
+    {
+      name: "scorer",
+      type: "RelevanceScoreProvider",
+      description: "The relevance scorer to use for reranking",
+      isOptional: false,
+    },
+    {
+      name: "options",
+      type: "RerankerFunctionOptions",
+      description: "Options for the reranking model",
+      isOptional: true,
+    },
+  ]}
+/>
+
+The `rerankWithScorer` function accepts any `RelevanceScoreProvider` from @mastra/rag.
+
+> **Note:** For semantic scoring to work properly during re-ranking, each result must include the text content in its `metadata.text` field.
+
+### RerankerFunctionOptions
+
+<PropertiesTable
+  content={[
+    {
+      name: "weights",
+      type: "WeightConfig",
+      description:
+        "Weights for different scoring components (must add up to 1)",
+      isOptional: true,
+      properties: [
+        {
+          type: "number",
+          parameters: [
+            {
+              name: "semantic",
+              description: "Weight for semantic relevance",
+              isOptional: true,
+              type: "number (default: 0.4)",
+            },
+          ],
+        },
+        {
+          type: "number",
+          parameters: [
+            {
+              name: "vector",
+              description: "Weight for vector similarity",
+              isOptional: true,
+              type: "number (default: 0.4)",
+            },
+          ],
+        },
+        {
+          type: "number",
+          parameters: [
+            {
+              name: "position",
+              description: "Weight for position-based scoring",
+              isOptional: true,
+              type: "number (default: 0.2)",
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: "queryEmbedding",
+      type: "number[]",
+      description: "Embedding of the query",
+      isOptional: true,
+    },
+    {
+      name: "topK",
+      type: "number",
+      description: "Number of top results to return",
+      isOptional: true,
+      defaultValue: "3",
+    },
+  ]}
+/>
+
+## Returns
+
+The function returns an array of `RerankResult` objects:
+
+<PropertiesTable
+  content={[
+    {
+      name: "result",
+      type: "QueryResult",
+      description: "The original query result",
+    },
+    {
+      name: "score",
+      type: "number",
+      description: "Combined reranking score (0-1)",
+    },
+    {
+      name: "details",
+      type: "ScoringDetails",
+      description: "Detailed scoring information",
+    },
+  ]}
+/>
+
+### ScoringDetails
+
+<PropertiesTable
+  content={[
+    {
+      name: "semantic",
+      type: "number",
+      description: "Semantic relevance score (0-1)",
+    },
+    {
+      name: "vector",
+      type: "number",
+      description: "Vector similarity score (0-1)",
+    },
+    {
+      name: "position",
+      type: "number",
+      description: "Position-based score (0-1)",
+    },
+    {
+      name: "queryAnalysis",
+      type: "object",
+      description: "Query analysis details",
+      isOptional: true,
+      properties: [
+        {
+          type: "number",
+          parameters: [
+            {
+              name: "magnitude",
+              description: "Magnitude of the query",
+            },
+          ],
+        },
+        {
+          type: "number[]",
+          parameters: [
+            {
+              name: "dominantFeatures",
+              description: "Dominant features of the query",
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+## Related
+
+- [createVectorQueryTool](../tools/vector-query-tool)