@mastra/mcp-docs-server 0.13.5 → 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/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/storage/mssql.mdx

@@ -0,0 +1,108 @@
+---
+title: "MSSQL Storage | Storage System | Mastra Core"
+description: Documentation for the MSSQL storage implementation in Mastra.
+---
+
+# MSSQL Storage
+
+The MSSQL storage implementation provides a production-ready storage solution using Microsoft SQL Server databases.
+
+## Installation
+
+```bash copy
+npm install @mastra/mssql@latest
+```
+
+## Usage
+
+```typescript copy showLineNumbers
+import { MSSQLStore } from "@mastra/mssql";
+
+const storage = new MSSQLStore({
+  connectionString: process.env.DATABASE_URL,
+});
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "connectionString",
+      type: "string",
+      description:
+        "MSSQL connection string (e.g., mssql://user:pass@host:1433/dbname)",
+      isOptional: false,
+    },
+    {
+      name: "schemaName",
+      type: "string",
+      description:
+        "The name of the schema you want the storage to use. Will use the default schema if not provided.",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## Constructor Examples
+
+You can instantiate `MSSQLStore` in the following ways:
+
+```ts
+import { MSSQLStore } from "@mastra/mssql";
+
+// Using a connection string only
+const store1 = new MSSQLStore({
+  connectionString: "mssql://user:password@localhost:1433/mydb",
+});
+
+// Using a connection string with a custom schema name
+const store2 = new MSSQLStore({
+  connectionString: "mssql://user:password@localhost:1433/mydb",
+  schemaName: "custom_schema", // optional
+});
+
+// Using individual connection parameters
+const store4 = new MSSQLStore({
+  server: "localhost",
+  port: 1433,
+  database: "mydb",
+  user: "user",
+  password: "password",
+});
+
+// Individual parameters with schemaName
+const store5 = new MSSQLStore({
+  server: "localhost",
+  port: 1433,
+  database: "mydb",
+  user: "user",
+  password: "password",
+  schemaName: "custom_schema", // optional
+});
+```
+
+## Additional Notes
+
+### Schema Management
+
+The storage implementation handles schema creation and updates automatically. It creates the following tables:
+
+- `threads`: Stores conversation threads
+- `messages`: Stores individual messages
+- `metadata`: Stores additional metadata for threads and messages
+
+### Direct Database and Pool Access
+
+`MSSQLStore` exposes the mssql connection pool as public fields:
+
+```typescript
+store.pool // mssql connection pool instance
+```
+
+This enables direct queries and custom transaction management. When using these fields:
+- You are responsible for proper connection and transaction handling.
+- Closing the store (`store.close()`) will destroy the associated connection pool.
+- Direct access bypasses any additional logic or validation provided by MSSQLStore methods.
+
+This approach is intended for advanced scenarios where low-level access is required. 

package/.docs/raw/server-db/custom-api-routes.mdx

@@ -5,18 +5,16 @@ description: "Expose additional HTTP endpoints from your Mastra server."
 
 # Custom API Routes
 
-By default Mastra automatically exposes registered agents and workflows via the
-server. For additional behaviour you can define your own HTTP routes.
+By default Mastra automatically exposes registered agents and workflows via the server. For additional behavior you can define your own HTTP routes.
 
-Routes are provided with a helper `registerApiRoute` from `@mastra/core/server`.
-Routes can live in the same file as the `Mastra` instance but separating them
-helps keep configuration concise.
+Routes are provided with a helper `registerApiRoute` from `@mastra/core/server`. Routes can live in the same file as the `Mastra` instance but separating them helps keep configuration concise.
 
-```typescript copy showLineNumbers
-import { Mastra } from "@mastra/core";
+```typescript filename="src/mastra/index.ts" copy showLineNumbers
+import { Mastra } from "@mastra/core/mastra";
 import { registerApiRoute } from "@mastra/core/server";
 
 export const mastra = new Mastra({
+  // ...
   server: {
     apiRoutes: [
       registerApiRoute("/my-custom-route", {
@@ -25,7 +23,7 @@ export const mastra = new Mastra({
           const mastra = c.get("mastra");
           const agents = await mastra.getAgent("my-agent");
 
-          return c.json({ message: "Hello, world!" });
+          return c.json({ message: "Custom route" });
         },
       }),
     ],
@@ -33,23 +31,37 @@ export const mastra = new Mastra({
 });
 ```
 
-Each route's handler receives the Hono `Context`. Within the handler you can
-access the `Mastra` instance to fetch or call agents and workflows.
-
-To add route-specific middleware pass a `middleware` array when calling
-`registerApiRoute`.
-
-```typescript copy showLineNumbers
-registerApiRoute("/my-custom-route", {
-  method: "GET",
-  middleware: [
-    async (c, next) => {
-      console.log(`${c.req.method} ${c.req.url}`);
-      await next();
-    },
-  ],
-  handler: async (c) => {
-    return c.json({ message: "My route with custom middleware" });
-  },
+Once registered, a custom route will be accessible from the root of the server. For example:
+
+```bash
+curl http://localhost:4111/my-custom-route
+```
+
+Each route's handler receives the Hono `Context`. Within the handler you can access the `Mastra` instance to fetch or call agents and workflows.
+
+To add route-specific middleware pass a `middleware` array when calling `registerApiRoute`.
+
+```typescript filename="src/mastra/index.ts" copy showLineNumbers
+import { Mastra } from "@mastra/core/mastra";
+import { registerApiRoute } from "@mastra/core/server";
+
+export const mastra = new Mastra({
+  // ...
+  server: {
+    apiRoutes: [
+      registerApiRoute("/my-custom-route", {
+        method: "GET",
+        middleware: [
+          async (c, next) => {
+            console.log(`${c.req.method} ${c.req.url}`);
+            await next();
+          }
+        ],
+        handler: async (c) => {
+          return c.json({ message: "Custom route with middleware" });
+        }
+      })
+    ]
+  }
 });
 ```

package/.docs/raw/tools-mcp/mcp-overview.mdx

@@ -122,7 +122,30 @@ The tabs help users understand how to connect to various MCP server providers an
 Each tab shows the specific URL patterns and configuration needed for that registry service.
 */}
 
-<Tabs items={["mcp.run", "Composio.dev", "Smithery.ai", "Ampersand"]}>
+<Tabs items={["Klavis AI", "mcp.run", "Composio.dev", "Smithery.ai", "Ampersand"]}>
+  <Tabs.Tab>
+    [Klavis AI](https://klavis.ai) provides hosted, enterprise-authenticated, high-quality MCP servers.
+
+    ```typescript
+    import { MCPClient } from "@mastra/mcp";
+
+    const mcp = new MCPClient({
+      servers: {
+        salesforce: {
+          url: new URL("https://salesforce-mcp-server.klavis.ai/mcp/?instance_id={private-instance-id}"),
+        },
+        hubspot: {
+          url: new URL("https://hubspot-mcp-server.klavis.ai/mcp/?instance_id={private-instance-id}"),
+        },
+      },
+    });
+    ```
+
+    Klavis AI offers enterprise-grade authentication and security for production deployments.
+
+    For more details on how to integrate Mastra with Klavis, check out their [documentation](https://docs.klavis.ai/documentation/ai-platform-integration/mastra).
+
+  </Tabs.Tab>
   <Tabs.Tab>
     [mcp.run](https://www.mcp.run/) provides pre-authenticated, managed MCP servers. Tools are grouped into Profiles, each with a unique, signed URL.