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

package/.docs/raw/reference/client-js/workflows-legacy.mdx

@@ -7,20 +7,12 @@ description: Learn how to interact with and execute automated legacy workflows i
 
 The Workflows (Legacy) API provides methods to interact with and execute automated legacy workflows in Mastra.
 
-## Initialize Mastra Client
-
-```typescript
-import { MastraClient } from "@mastra/client-js";
-
-const client = new MastraClient();
-```
-
 ## Getting All Legacy Workflows
 
 Retrieve a list of all available legacy workflows:
 
 ```typescript
-const workflows = await client.getLegacyWorkflows();
+const workflows = await mastraClient.getLegacyWorkflows();
 ```
 
 ## Working with a Specific Legacy Workflow
@@ -28,7 +20,7 @@ const workflows = await client.getLegacyWorkflows();
 Get an instance of a specific legacy workflow:
 
 ```typescript
-const workflow = client.getLegacyWorkflow("workflow-id");
+const workflow = mastraClient.getLegacyWorkflow("workflow-id");
 ```
 
 ## Legacy Workflow Methods
@@ -78,7 +70,7 @@ Watch legacy workflow transitions
 ```typescript
 try {
   // Get workflow instance
-  const workflow = client.getLegacyWorkflow("workflow-id");
+  const workflow = mastraClient.getLegacyWorkflow("workflow-id");
 
   // Create a workflow run
   const { runId } = workflow.createRun();

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

@@ -7,20 +7,12 @@ description: Learn how to interact with and execute automated workflows in Mastr
 
 The Workflows API provides methods to interact with and execute automated workflows in Mastra.
 
-## Initialize Mastra Client
-
-```typescript
-import { MastraClient } from "@mastra/client-js";
-
-const client = new MastraClient();
-```
-
 ## Getting All Workflows
 
 Retrieve a list of all available workflows:
 
 ```typescript
-const workflows = await client.getWorkflows();
+const workflows = await mastraClient.getWorkflows();
 ```
 
 ## Working with a Specific Workflow
@@ -34,7 +26,7 @@ export const testWorkflow = createWorkflow({
 ```
 
 ```typescript
-const workflow = client.getWorkflow("testWorkflow");
+const workflow = mastraClient.getWorkflow("testWorkflow");
 ```
 
 ## Workflow Methods
@@ -82,7 +74,7 @@ Watch workflow transitions:
 
 ```typescript
 try {
-  const workflow = client.getWorkflow("testWorkflow");
+  const workflow = mastraClient.getWorkflow("testWorkflow");
 
   const run = await workflow.createRun();
 
@@ -107,7 +99,7 @@ Resume workflow run and watch workflow step transitions:
 
 ```typescript
 try {
-  const workflow = client.getWorkflow("testWorkflow");
+  const workflow = mastraClient.getWorkflow("testWorkflow");
 
   const run = await workflow.createRun({ runId: prevRunId });
 
@@ -131,7 +123,7 @@ Get the result of a workflow run:
 
 ```typescript
 try  {
-  const workflow = client.getWorkflow("testWorkflow");
+  const workflow = mastraClient.getWorkflow("testWorkflow");
 
   const run = await workflow.createRun();
 

package/.docs/raw/reference/core/mastra-class.mdx

@@ -87,6 +87,12 @@ The constructor accepts an optional `Config` object to customize its behavior an
       isOptional: true,
       defaultValue: "Console logger with INFO level",
     },
+    {
+      name: "idGenerator",
+      type: "() => string",
+      description: "Custom ID generator function. Used by agents, workflows, memory, and other components to generate unique identifiers.",
+      isOptional: true,
+    },
     {
       name: "workflows",
       type: "Record<string, Workflow>",

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/dash0.mdx

@@ -1,11 +1,11 @@
 ---
 title: "Reference: Dash0 Integration | Mastra Observability Docs"
-description: Documentation for integrating Mastra with Dash0, an Open Telementry native observability solution.
+description: Documentation for integrating Mastra with Dash0, an Open Telemetry native observability solution.
 ---
 
 # Dash0
 
-Dash0, an Open Telementry native observability solution that provides full-stack monitoring capabilities as well as integrations with other CNCF projects like Perses and Prometheus.
+Dash0, an Open Telemetry native observability solution that provides full-stack monitoring capabilities as well as integrations with other CNCF projects like Perses and Prometheus.
 
 ## Configuration
 

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/reference/tools/vector-query-tool.mdx

@@ -554,6 +554,35 @@ For more information on runtime context, please see:
 - [Runtime Variables](../../docs/agents/runtime-variables)
 - [Dynamic Context](../../docs/tools-mcp/dynamic-context)
 
+## Usage Without a Mastra Server
+
+The tool can be used by itself to retrieve documents matching a query:
+```typescript copy showLineNumbers filename="src/index.ts"
+import { openai } from "@ai-sdk/openai";
+import { RuntimeContext } from "@mastra/core/runtime-context";
+import { createVectorQueryTool } from "@mastra/rag";
+import { PgVector } from "@mastra/pg";
+
+const pgVector = new PgVector({
+  connectionString: process.env.POSTGRES_CONNECTION_STRING!,
+});
+
+const vectorQueryTool = createVectorQueryTool({
+  vectorStoreName: "pgVector", // optional since we're passing in a store
+  vectorStore: pgVector,
+  indexName: "embeddings",
+  model: openai.embedding("text-embedding-3-small"),
+});
+
+const runtimeContext = new RuntimeContext();
+const queryResult = await vectorQueryTool.execute({
+  context: { queryText: "foo", topK: 1 },
+  runtimeContext,
+});
+
+console.log(queryResult.sources);
+```
+
 ## Tool Details
 
 The tool is created with:

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.
 

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

@@ -56,7 +56,7 @@ To make tools available to an agent, you configure them in the agent's definitio
 
 ## Compatibility Layer for Tool Schemas
 
-Different models interpret schemas differely. Some error when certain schema properties are passed and some ignore certain schema properties but don't throw an error. Mastra adds a compatibility layer for tool schemas, ensuring tools work consistently across different model providers and that the schema constraints are respected.
+Different models interpret schemas differently. Some error when certain schema properties are passed and some ignore certain schema properties but don't throw an error. Mastra adds a compatibility layer for tool schemas, ensuring tools work consistently across different model providers and that the schema constraints are respected.
 
 Some providers that we include this layer for: