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

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

@@ -9,14 +9,14 @@ Mastra is an open-source TypeScript agent framework.
 
 It's designed to give you the primitives you need to build AI applications and features.
 
-You can use Mastra to build [AI agents](/docs/agents/overview.mdx) that have memory and can execute functions, or chain LLM calls in deterministic [workflows](/docs/workflows/overview.mdx). You can chat with your agents in Mastra's [local dev environment](/docs/local-dev/mastra-dev.mdx), feed them application-specific knowledge with [RAG](/docs/rag/overview.mdx), and score their outputs with Mastra's [evals](/docs/evals/overview.mdx).
+You can use Mastra to build [AI agents](/docs/agents/overview.mdx) that have memory and can execute functions, or chain LLM calls in deterministic [workflows](/docs/workflows/overview.mdx). You can chat with your agents in Mastra's [local dev playground](/docs/server-db/local-dev-playground.mdx), feed them application-specific knowledge with [RAG](/docs/rag/overview.mdx), and score their outputs with Mastra's [evals](/docs/evals/overview.mdx).
 
 The main features include:
 
 - **[Model routing](https://sdk.vercel.ai/docs/introduction)**: Mastra uses the [Vercel AI SDK](https://sdk.vercel.ai/docs/introduction) for model routing, providing a unified interface to interact with any LLM provider including OpenAI, Anthropic, and Google Gemini.
 - **[Agent memory and tool calling](/docs/agents/agent-memory.mdx)**: With Mastra, you can give your agent tools (functions) that it can call. You can persist agent memory and retrieve it based on recency, semantic similarity, or conversation thread.
 - **[Workflow graphs](/docs/workflows/overview.mdx)**: When you want to execute LLM calls in a deterministic way, Mastra gives you a graph-based workflow engine. You can define discrete steps, log inputs and outputs at each step of each run, and pipe them into an observability tool. Mastra workflows have a simple syntax for control flow (`.then()`, `.branch()`, `.parallel()`) that allows branching and chaining.
-- **[Agent development environment](/docs/local-dev/mastra-dev.mdx)**: When you're developing an agent locally, you can chat with it and see its state and memory in Mastra's agent development environment.
+- **[Agent development playground](/docs/server-db/local-dev-playground.mdx)**: When you're developing an agent locally, you can chat with it and see its state and memory in Mastra's agent development environment.
 - **[Retrieval-augmented generation (RAG)](/docs/rag/overview.mdx)**: Mastra gives you APIs to process documents (text, HTML, Markdown, JSON) into chunks, create embeddings, and store them in a vector database. At query time, it retrieves relevant chunks to ground LLM responses in your data, with a unified API on top of multiple vector stores (Pinecone, pgvector, etc) and embedding providers (OpenAI, Cohere, etc).
 - **[Deployment](/docs/deployment/deployment.mdx)**: Mastra supports bundling your agents and workflows within an existing React, Next.js, or Node.js application, or into standalone endpoints. The Mastra deploy helper lets you easily bundle agents and workflows into a Node.js server using Hono, or deploy it onto a serverless platform like Vercel, Cloudflare Workers, or Netlify.
 - **[Evals](/docs/evals/overview.mdx)**: Mastra provides automated evaluation metrics that use model-graded, rule-based, and statistical methods to assess LLM outputs, with built-in metrics for toxicity, bias, relevance, and factual accuracy. You can also define your own evals.

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/auth/jwt.mdx

@@ -0,0 +1,42 @@
+---
+title: "MastraJwtAuth"
+description: "API reference for the MastraJwtAuth class, which authenticates Mastra applications using JSON Web Tokens."
+---
+
+# MastraJwtAuth
+
+The `MastraJwtAuth` class provides a lightweight authentication mechanism for Mastra using JSON Web Tokens (JWTs). It verifies incoming requests based on a shared secret and integrates with the Mastra server using the `experimental_auth` option.
+
+## Usage example
+
+```typescript filename="src/mastra/index.ts" showLineNumbers copy
+import { Mastra } from "@mastra/core/mastra";
+import { MastraJwtAuth } from '@mastra/auth';
+
+export const mastra = new Mastra({
+  // ..
+  server: {
+    experimental_auth: new MastraJwtAuth({
+        secret: "<your-secret>"
+    }),
+  },
+});
+```
+
+## Constructor parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "secret",
+      type: "string",
+      description: "A unique string used to sign and verify JSON Web Tokens (JWTs) for authenticating incoming requests.",
+      isOptional: false,
+    },
+  ]}
+/>
+
+
+## Related
+
+[MastraJwtAuth](/docs/auth/jwt.mdx)

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

@@ -7,20 +7,12 @@ description: Learn how to interact with Mastra AI agents, including generating r
 
 The Agents API provides methods to interact with Mastra AI agents, including generating responses, streaming interactions, and managing agent tools.
 
-## Initialize Mastra Client
-
-```typescript
-import { MastraClient } from "@mastra/client-js";
-
-const client = new MastraClient();
-```
-
 ## Getting All Agents
 
 Retrieve a list of all available agents:
 
 ```typescript
-const agents = await client.getAgents();
+const agents = await mastraClient.getAgents();
 ```
 
 ## Working with a Specific Agent
@@ -28,7 +20,7 @@ const agents = await client.getAgents();
 Get an instance of a specific agent:
 
 ```typescript
-const agent = client.getAgent("agent-id");
+const agent = mastraClient.getAgent("agent-id");
 ```
 
 ## Agent Methods
@@ -89,6 +81,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/client-js/error-handling.mdx

@@ -13,7 +13,7 @@ All API methods can throw errors that you can catch and handle:
 
 ```typescript
 try {
-  const agent = client.getAgent("agent-id");
+  const agent = mastraClient.getAgent("agent-id");
   const response = await agent.generate({
     messages: [{ role: "user", content: "Hello" }],
   });
@@ -21,23 +21,3 @@ try {
   console.error("An error occurred:", error.message);
 }
 ```
-
-## Retry Mechanism
-
-The client automatically retries failed requests with exponential backoff:
-
-```typescript
-const client = new MastraClient({
-  baseUrl: "http://localhost:4111",
-  retries: 3, // Number of retry attempts
-  backoffMs: 300, // Initial backoff time
-  maxBackoffMs: 5000, // Maximum backoff time
-});
-```
-
-### How Retries Work
-
-1. First attempt fails → Wait 300ms
-2. Second attempt fails → Wait 600ms
-3. Third attempt fails → Wait 1200ms
-4. Final attempt fails → Throw error

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

@@ -7,20 +7,12 @@ description: Learn how to access and query system logs and debugging information
 
 The Logs API provides methods to access and query system logs and debugging information in Mastra.
 
-## Initialize Mastra Client
-
-```typescript
-import { MastraClient } from "@mastra/client-js";
-
-const client = new MastraClient();
-```
-
 ## Getting Logs
 
 Retrieve system logs with optional filtering:
 
 ```typescript
-const logs = await client.getLogs({
+const logs = await mastraClient.getLogs({
   transportId: "transport-1",
 });
 ```
@@ -30,7 +22,7 @@ const logs = await client.getLogs({
 Retrieve logs for a specific execution run:
 
 ```typescript
-const runLogs = await client.getLogForRun({
+const runLogs = await mastraClient.getLogForRun({
   runId: "run-1",
   transportId: "transport-1",
 });

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

@@ -0,0 +1,141 @@
+---
+title: MastraClient
+description: Learn how to interact with Mastra using the client-js SDK.
+---
+
+# Mastra Client SDK
+
+The Mastra Client SDK provides a simple and type-safe interface for interacting with your [Mastra Server](/docs/deployment/server-deployment.mdx) from your client environment.
+
+## Usage example
+
+```typescript filename="lib/mastra/mastra-client.ts" showLineNumbers copy
+import { MastraClient } from "@mastra/client-js";
+
+export const mastraClient = new MastraClient({
+  baseUrl: "http://localhost:4111/",
+});
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "baseUrl",
+      type: "string",
+      description: "The base URL for the Mastra API. All requests will be sent relative to this URL.",
+      isOptional: false,
+    },
+    {
+      name: "retries",
+      type: "number",
+      description: "The number of times a request will be retried on failure before throwing an error.",
+      isOptional: true,
+      defaultValue: "3",
+    },
+    {
+      name: "backoffMs",
+      type: "number",
+      description: "The initial delay in milliseconds before retrying a failed request. This value is doubled with each retry (exponential backoff).",
+      isOptional: true,
+      defaultValue: "300",
+    },
+    {
+      name: "maxBackoffMs",
+      type: "number",
+      description: "The maximum backoff time in milliseconds. Prevents retries from waiting too long between attempts.",
+      isOptional: true,
+      defaultValue: "5000",
+    },
+    {
+      name: "headers",
+      type: "Record<string, string>",
+      description: "An object containing custom HTTP headers to include with every request.",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## Methods
+
+<PropertiesTable
+  content={[
+    {
+      name: "getAgents()",
+      type: "Promise<Record<string, GetAgentResponse>>",
+      description: "Returns all available agent instances.",
+    },
+    {
+      name: "getAgent(agentId)",
+      type: "Agent",
+      description: "Retrieves a specific agent instance by ID.",
+    },
+    {
+      name: "getMemoryThreads(params)",
+      type: "Promise<StorageThreadType[]>",
+      description: "Retrieves memory threads for the specified resource and agent. Requires a `resourceId` and an `agentId`.",
+    },
+    {
+      name: "createMemoryThread(params)",
+      type: "Promise<MemoryThread>",
+      description: "Creates a new memory thread with the given parameters.",
+    },
+    {
+      name: "getMemoryThread(threadId)",
+      type: "Promise<MemoryThread>",
+      description: "Fetches a specific memory thread by ID.",
+    },
+    {
+      name: "saveMessageToMemory(params)",
+      type: "Promise<void>",
+      description: "Saves one or more messages to the memory system.",
+    },
+    {
+      name: "getMemoryStatus()",
+      type: "Promise<MemoryStatus>",
+      description: "Returns the current status of the memory system.",
+    },
+    {
+      name: "getTools()",
+      type: "Record<string, Tool>",
+      description: "Returns all available tools.",
+    },
+    {
+      name: "getTool(toolId)",
+      type: "Tool",
+      description: "Retrieves a specific tool instance by ID.",
+    },
+    {
+      name: "getWorkflows()",
+      type: "Record<string, Workflow>",
+      description: "Returns all available workflow instances.",
+    },
+    {
+      name: "getWorkflow(workflowId)",
+      type: "Workflow",
+      description: "Retrieves a specific workflow instance by ID.",
+    },
+    {
+      name: "getVector(vectorName)",
+      type: "MastraVector",
+      description: "Returns a vector store instance by name.",
+    },
+    {
+      name: "getLogs(params)",
+      type: "Promise<LogEntry[]>",
+      description: "Fetches system logs matching the provided filters.",
+    },
+    {
+      name: "getLog(params)",
+      type: "Promise<LogEntry>",
+      description: "Retrieves a specific log entry by ID or filter.",
+    },
+    {
+      name: "getLogTransports()",
+      type: "string[]",
+      description: "Returns the list of configured log transport types.",
+    },
+  ]}
+/>
+

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

@@ -7,22 +7,12 @@ description: Learn how to manage conversation threads and message history in Mas
 
 The Memory API provides methods to manage conversation threads and message history in Mastra.
 
-## Initialize Mastra Client
-
-```typescript
-import { MastraClient } from "@mastra/client-js";
-
-const client = new MastraClient();
-```
-
-## Memory Thread Operations
-
 ### Get All Threads
 
 Retrieve all memory threads for a specific resource:
 
 ```typescript
-const threads = await client.getMemoryThreads({
+const threads = await mastraClient.getMemoryThreads({
   resourceId: "resource-1",
   agentId: "agent-1",
 });
@@ -33,10 +23,10 @@ const threads = await client.getMemoryThreads({
 Create a new memory thread:
 
 ```typescript
-const thread = await client.createMemoryThread({
+const thread = await mastraClient.createMemoryThread({
   title: "New Conversation",
   metadata: { category: "support" },
-  resourceid: "resource-1",
+  resourceId: "resource-1",
   agentId: "agent-1",
 });
 ```
@@ -46,7 +36,7 @@ const thread = await client.createMemoryThread({
 Get an instance of a specific memory thread:
 
 ```typescript
-const thread = client.getMemoryThread("thread-id", "agent-id");
+const thread = mastraClient.getMemoryThread("thread-id", "agent-id");
 ```
 
 ## Thread Methods
@@ -79,8 +69,6 @@ Delete a thread and its messages:
 await thread.delete();
 ```
 
-
-
 ## Message Operations
 
 ### Save Messages
@@ -88,7 +76,7 @@ await thread.delete();
 Save messages to memory:
 
 ```typescript
-const savedMessages = await client.saveMessageToMemory({
+const savedMessages = await mastraClient.saveMessageToMemory({
   messages: [
     {
       role: "user",
@@ -120,5 +108,5 @@ const { messages } = await thread.getMessages({ limit: 10 });
 Check the status of the memory system:
 
 ```typescript
-const status = await client.getMemoryStatus("agent-id");
+const status = await mastraClient.getMemoryStatus("agent-id");
 ```

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

@@ -7,20 +7,12 @@ description: Learn how to retrieve and analyze traces from your Mastra applicati
 
 The Telemetry API provides methods to retrieve and analyze traces from your Mastra application. This helps you monitor and debug your application's behavior and performance.
 
-## Initialize Mastra Client
-
-```typescript
-import { MastraClient } from "@mastra/client-js";
-
-const client = new MastraClient();
-```
-
 ## Getting Traces
 
 Retrieve traces with optional filtering and pagination:
 
 ```typescript
-const telemetry = await client.getTelemetry({
+const telemetry = await mastraClient.getTelemetry({
   name: "trace-name", // Optional: Filter by trace name
   scope: "scope-name", // Optional: Filter by scope
   page: 1, // Optional: Page number for pagination

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

@@ -7,20 +7,12 @@ description: Learn how to interact with and execute tools available in the Mastr
 
 The Tools API provides methods to interact with and execute tools available in the Mastra platform.
 
-## Initialize Mastra Client
-
-```typescript
-import { MastraClient } from "@mastra/client-js";
-
-const client = new MastraClient();
-```
-
 ## Getting All Tools
 
 Retrieve a list of all available tools:
 
 ```typescript
-const tools = await client.getTools();
+const tools = await mastraClient.getTools();
 ```
 
 ## Working with a Specific Tool
@@ -28,7 +20,7 @@ const tools = await client.getTools();
 Get an instance of a specific tool:
 
 ```typescript
-const tool = client.getTool("tool-id");
+const tool = mastraClient.getTool("tool-id");
 ```
 
 ## Tool Methods

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

@@ -7,20 +7,12 @@ description: Learn how to work with vector embeddings for semantic search and si
 
 The Vectors API provides methods to work with vector embeddings for semantic search and similarity matching in Mastra.
 
-## Initialize Mastra Client
-
-```typescript
-import { MastraClient } from "@mastra/client-js";
-
-const client = new MastraClient();
-```
-
 ## Working with Vectors
 
 Get an instance of a vector store:
 
 ```typescript
-const vector = client.getVector("vector-name");
+const vector = mastraClient.getVector("vector-name");
 ```
 
 ## Vector Methods