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

package/.docs/raw/deployment/cloud-providers/digital-ocean.mdx

@@ -4,7 +4,6 @@ description: "Deploy your Mastra applications to Digital Ocean."
 ---
 
 import { Callout, Steps, Tabs } from "nextra/components";
-import ServerConfig from "@/components/content-blocks/server-config.mdx";
 
 ## Digital Ocean
 
@@ -25,8 +24,8 @@ Deploy your Mastra applications to Digital Ocean's App Platform and Droplets.
 
 #### Prerequisites [#app-platform-prerequisites]
 
-- A Git repository containing your Mastra application. This can be a GitHub repository, GitLab repository, or any other compatible source provider.
-- A Digital Ocean account
+- A Git repository containing your Mastra application. This can be a [GitHub](https://github.com/) repository, [GitLab](https://gitlab.com/) repository, or any other compatible source provider.
+- A [Digital Ocean account](https://www.digitalocean.com/)
 
 #### Deployment Steps
 
@@ -34,8 +33,8 @@ Deploy your Mastra applications to Digital Ocean's App Platform and Droplets.
 
 #### Create a new App
 
-- Log in to your Digital Ocean dashboard.
-- Navigate to the App Platform service.
+- Log in to your [Digital Ocean dashboard](https://cloud.digitalocean.com/).
+- Navigate to the [App Platform](https://docs.digitalocean.com/products/app-platform/) service.
 - Select your source provider and create a new app.
 
 #### Configure Deployment Source
@@ -76,21 +75,86 @@ such as `LibSQLStore` with a file URL.
 ### Droplets
 
 Deploy your Mastra application to Digital Ocean's Droplets.
-This guide will cover setting up a droplet, a reverse proxy using Nginx, and running your Mastra application.
-
-<Callout>
-The guide assumes your droplet runs Ubuntu 24+.
-</Callout>
 
 #### Prerequisites [#droplets-prerequisites]
 
-- A Digital Ocean account
-- A droplet running Ubuntu 24+
+- A [Digital Ocean account](https://www.digitalocean.com/)
+- A [Droplet](https://docs.digitalocean.com/products/droplets/) running Ubuntu 24+
 - A domain name with an A record pointing to your droplet
+- A reverse proxy configured (e.g., using [nginx](https://nginx.org/))
+- SSL certificate configured (e.g., using [Let's Encrypt](https://letsencrypt.org/))
+- Node.js 18+ installed on your droplet
+
+#### Deployment Steps
+
+<Steps>
+
+#### Clone your Mastra application
+
+Connect to your Droplet and clone your repository:
+
+<Tabs items={["Public Repository", "Private Repository"]}>
+<Tabs.Tab>
+
+```bash copy
+git clone https://github.com/<your-username>/<your-repository>.git
+```
+
+</Tabs.Tab>
+
+<Tabs.Tab>
+
+```bash copy
+git clone https://<your-username>:<your-personal-access-token>@github.com/<your-username>/<your-repository>.git
+```
+
+</Tabs.Tab>
+</Tabs>
+
+Navigate to the repository directory:
 
-#### Setting up the droplet
+```bash copy
+cd "<your-repository>"
+```
+
+#### Install dependencies
+
+```bash copy
+npm install
+```
+
+#### Set up environment variables
+
+Create a `.env` file and add your environment variables:
 
-<ServerConfig />
+```bash copy
+touch .env
+```
+
+Edit the `.env` file and add your environment variables:
+
+```bash copy
+OPENAI_API_KEY=<your-openai-api-key>
+# Add other required environment variables
+```
+
+#### Build the application
+
+```bash copy
+npm run build
+```
+
+#### Run the application
+
+```bash copy
+node --import=./.mastra/output/instrumentation.mjs --env-file=".env" .mastra/output/index.mjs
+```
+
+<Callout>
+Your Mastra application will run on port 4111 by default. Ensure your reverse proxy is configured to forward requests to this port.
+</Callout>
+
+</Steps>
 
 </Tabs.Tab>
 
@@ -109,3 +173,9 @@ const mastraClient = new MastraClient({
   baseUrl: "https://<your-domain-name>",
 });
 ```
+
+## Next steps
+
+- [Mastra Client SDK](/docs/client-js/overview)
+- [Digital Ocean App Platform documentation](https://docs.digitalocean.com/products/app-platform/)
+- [Digital Ocean Droplets documentation](https://docs.digitalocean.com/products/droplets/)

package/.docs/raw/evals/custom-eval.mdx

@@ -1,22 +1,22 @@
 ---
-title: "Create your own Eval"
-description: "Mastra allows so create your own evals, here is how."
+title: "Create a custom eval"
+description: "Mastra allows you to create your own evals, here is how."
 ---
 
-# Create your own Eval
+# Create a Custom Eval
 
-Creating your own eval is as easy as creating a new function. You simply create a class that extends the `Metric` class and implement the `measure` method.
+Create a custom eval by extending the `Metric` class and implementing the `measure` method. This gives you full control over how scores are calculated and what information is returned. For LLM-based evaluations, extend the `MastraAgentJudge` class to define how the model reasons and scores output.
 
-## Basic example
+## Native JavaScript evaluation
 
-For a simple example of creating a custom metric that checks if the output contains certain words, see our [Word Inclusion example](/examples/evals/word-inclusion).
+You can write lightweight custom metrics using plain JavaScript/TypeScript. These are ideal for simple string comparisons, pattern checks, or other rule-based logic.
 
-## Creating a custom LLM-Judge
+See our [Word Inclusion example](/examples/evals/custom-native-javascript-eval.mdx), which scores responses based on the number of reference words found in the output.
 
-A custom LLM judge helps evaluate specific aspects of your AI's responses. Think of it like having an expert reviewer for your particular use case:
+## LLM as a judge evaluation
+
+For more complex evaluations, you can build a judge powered by an LLM. This lets you capture more nuanced criteria, like factual accuracy, tone, or reasoning.
+
+See the [Real World Countries example](/examples/evals/custom-llm-judge-eval.mdx) for a complete walkthrough of building a custom judge and metric that evaluates real-world factual accuracy.
 
-- Medical Q&A → Judge checks for medical accuracy and safety
-- Customer Service → Judge evaluates tone and helpfulness
-- Code Generation → Judge verifies code correctness and style
 
-For a practical example, see how we evaluate [Chef Michel's](/docs/guides/chef-michel) recipes for gluten content in our [Gluten Checker example](/examples/evals/custom-eval).

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