@mastra/mcp-docs-server 0.13.6 → 0.13.7-alpha.1

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

@@ -0,0 +1,95 @@
+---
+title: "Templates | Getting Started | Mastra Docs"
+description: Pre-built project structures that demonstrate common Mastra use cases and patterns
+---
+
+import { Callout } from "nextra/components";
+import { Tabs, Tab } from "@/components/tabs";
+
+# Templates
+
+Templates are pre-built Mastra projects that demonstrate specific use cases and patterns. They provide working examples you can run immediately and customize for your needs.
+
+## What Templates Offer
+
+Templates include:
+
+- **Complete working examples** - Functional code demonstrating specific patterns
+- **Best practices** - Proper project structure and Mastra conventions  
+- **Educational value** - Learn different Mastra features through examples
+- **Quick start** - Bootstrap projects faster than starting from scratch
+
+## Using Templates
+
+Install a template using the `create-mastra` command:
+
+<Tabs items={["npx", "npm", "yarn", "pnpm", "bun"]}>
+  <Tab>
+    ```bash copy
+    npx create-mastra@latest --template template-name
+    ```
+  </Tab>
+  <Tab>
+    ```bash copy
+    npm create mastra@latest --template template-name
+    ```
+  </Tab>
+  <Tab>
+    ```bash copy
+    yarn create mastra@latest --template template-name
+    ```
+  </Tab>
+  <Tab>
+    ```bash copy
+    pnpm create mastra@latest --template template-name
+    ```
+  </Tab>
+  <Tab>
+    ```bash copy
+    bun create mastra@latest --template template-name
+    ```
+  </Tab>
+</Tabs>
+
+For example, to create a text-to-SQL application:
+
+```bash copy
+npx create-mastra@latest --template text-to-sql
+```
+
+## Setting Up a Template
+
+After installation:
+
+1. **Navigate to your project**:
+   ```bash copy
+   cd your-project-name
+   ```
+
+2. **Configure environment variables**:
+   ```bash copy
+   cp .env.example .env
+   ```
+   Edit `.env` with your API keys as specified in the template's README.
+
+3. **Start development**:
+   ```bash copy
+   npm run dev
+   ```
+
+<Callout type="info">
+  Each template includes a comprehensive README with specific setup instructions and usage examples.
+</Callout>
+
+## Available Templates
+
+Browse available templates in the [templates directory](https://github.com/mastra-ai/mastra/tree/main/templates) on GitHub.
+
+## Next Steps
+
+- **Explore code** - Understand how templates implement functionality
+- **Customize** - Modify agents, tools, and workflows for your use case
+- **Learn patterns** - Study templates to understand Mastra best practices
+- **Contribute** - Create your own templates for the community
+
+For detailed information on creating templates, see the [Templates Reference](/reference/templates).

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/reference/agents/generate.mdx

@@ -16,16 +16,27 @@ The `messages` parameter can be:
 - A single string
 - An array of strings
 - An array of message objects with `role` and `content` properties
+- An array of `UIMessageWithMetadata` objects (for messages with metadata)
 
-The message object structure:
+The message object structures:
 
 ```typescript
 interface Message {
   role: "system" | "user" | "assistant";
   content: string;
 }
+
+// For messages with metadata
+interface UIMessageWithMetadata {
+  role: "user" | "assistant";
+  content: string;
+  parts: Array<{ type: string; text?: string; [key: string]: any }>;
+  metadata?: Record<string, unknown>; // Optional metadata field
+}
 ```
 
+When using `UIMessageWithMetadata`, the metadata will be preserved throughout the conversation and stored with the messages in memory.
+
 ### `options` (Optional)
 
 An optional object that can include configuration for output structure, memory management, tool usage, telemetry, and more.
@@ -175,6 +186,12 @@ An optional object that can include configuration for output structure, memory m
       description:
         "Tools that are executed on the 'client' side of the request. These tools do not have execute functions in the definition.",
     },
+    {
+      name: "savePerStep",
+      type: "boolean",
+      isOptional: true,
+      description: "Save messages incrementally after each stream step completes (default: false).",
+    }
   ]}
 />
 

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

@@ -16,16 +16,27 @@ The `messages` parameter can be:
 - A single string
 - An array of strings
 - An array of message objects with `role` and `content` properties
+- An array of `UIMessageWithMetadata` objects (for messages with metadata)
 
-The message object structure:
+The message object structures:
 
 ```typescript
 interface Message {
   role: "system" | "user" | "assistant";
   content: string;
 }
+
+// For messages with metadata
+interface UIMessageWithMetadata {
+  role: "user" | "assistant";
+  content: string;
+  parts: Array<{ type: string; text?: string; [key: string]: any }>;
+  metadata?: Record<string, unknown>; // Optional metadata field
+}
 ```
 
+When using `UIMessageWithMetadata`, the metadata will be preserved throughout the conversation and stored with the messages in memory.
+
 ### `options` (Optional)
 
 An optional object that can include configuration for output structure, memory management, tool usage, telemetry, and more.
@@ -181,6 +192,12 @@ An optional object that can include configuration for output structure, memory m
       description:
         "Tools that are executed on the 'client' side of the request. These tools do not have execute functions in the definition.",
     },
+    {
+      name: "savePerStep",
+      type: "boolean",
+      isOptional: true,
+      description: "Save messages incrementally after each generation step completes (default: false)",
+    }
   ]}
 />
 

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/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,7 +81,7 @@ response.processDataStream({
   },
 });
 
-// Process text stream with the processTextStream util 
+// Process text stream with the processTextStream util
 // (used with structured output)
  response.processTextStream({
       onTextPart: text => {

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

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();