@mastra/mcp-docs-server 1.0.0-beta.9 → 1.0.1

package/.docs/raw/reference/cli/mastra.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: CLI Commands | CLI"
 description: Documentation for the Mastra CLI to develop, build, and start your project.
+packages:
+  - "@mastra/core"
 ---
 
 # CLI Commands
@@ -19,7 +21,7 @@ The command accepts [common flags][common-flags] and the following additional fl
 
 #### `--https`
 
-Enable local HTTPS support. [Learn more](/docs/v1/getting-started/studio#local-https).
+Enable local HTTPS support. [Learn more](/reference/v1/configuration#serverhttps).
 
 #### `--inspect`
 
@@ -41,7 +43,7 @@ You can set certain environment variables to modify the behavior of `mastra dev`
 
 Set `MASTRA_DEV_NO_CACHE=1` to force a full rebuild rather than using the cached assets under `.mastra/`:
 
-```bash copy
+```bash
 MASTRA_DEV_NO_CACHE=1 mastra dev
 ```
 
@@ -51,7 +53,7 @@ This helps when you are debugging bundler plugins or suspect stale output.
 
 `MASTRA_CONCURRENCY` caps how many expensive operations run in parallel (primarily build and evaluation steps). For example:
 
-```bash copy
+```bash
 MASTRA_CONCURRENCY=4 mastra dev
 ```
 
@@ -61,7 +63,7 @@ Leave it unset to let the CLI pick a sensible default for the machine.
 
 When using providers supported by the Vercel AI SDK you can redirect requests through proxies or internal gateways by setting a base URL. For OpenAI:
 
-```bash copy
+```bash
 OPENAI_API_KEY=<your-api-key> \
 OPENAI_BASE_URL=https://openrouter.example/v1 \
 mastra dev
@@ -69,7 +71,7 @@ mastra dev
 
 For Anthropic:
 
-```bash copy
+```bash
 ANTHROPIC_API_KEY=<your-api-key> \
 ANTHROPIC_BASE_URL=https://anthropic.internal \
 mastra dev
@@ -86,10 +88,16 @@ Under the hood Mastra's Rollup server locates your Mastra entry file and bundles
 
 The output in `.mastra` can be deployed to any cloud server using [`mastra start`](#mastra-start).
 
-If you're deploying to a [serverless platform](/docs/v1/deployment/cloud-providers) you need to install the correct deployer in order to receive the correct output in `.mastra`.
+If you're deploying to a [serverless platform](/guides/v1/deployment) you need to install the correct deployer in order to receive the correct output in `.mastra`.
 
 It accepts [common flags][common-flags].
 
+### Flags
+
+#### `--studio`
+
+Bundle the Studio UI with the build.
+
 ### Configs
 
 You can set certain environment variables to modify the behavior of `mastra build`.
@@ -98,7 +106,7 @@ You can set certain environment variables to modify the behavior of `mastra buil
 
 For CI or when running in resource constrained environments you can cap how many expensive tasks run at once by setting `MASTRA_CONCURRENCY`.
 
-```bash copy
+```bash
 MASTRA_CONCURRENCY=2 mastra build
 ```
 
@@ -124,6 +132,30 @@ The path to your built Mastra output directory. Defaults to `.mastra/output`.
 
 Disable the [OTEL Tracing](/docs/v1/observability/tracing/overview).
 
+## `mastra studio`
+
+Starts [Mastra Studio](/docs/v1/getting-started/studio) as a static server. After starting, you can enter your Mastra instance URL (e.g. `http://localhost:4111`) to connect Studio to your Mastra backend.
+
+### Flags
+
+The command accepts [common flags][common-flags] and the following additional flags:
+
+#### `--port`
+
+The port to run Studio on. Defaults to `3000`.
+
+#### `--server-host`
+
+The host of the Mastra API server to connect to. Defaults to `localhost`.
+
+#### `--server-port`
+
+The port of the Mastra API server to connect to. Defaults to `4111`.
+
+#### `--server-protocol`
+
+The protocol of the Mastra API server to connect to. Defaults to `http`.
+
 ## `mastra lint`
 
 The `mastra lint` command validates the structure and code of your Mastra project to ensure it follows best practices and is error-free.
@@ -140,13 +172,13 @@ Read the [Scorers overview](/docs/v1/evals/overview) to learn more.
 
 Add a new scorer to your project. You can use an interactive prompt:
 
-```bash copy
+```bash
 mastra scorers add
 ```
 
 Or provide a scorer name directly:
 
-```bash copy
+```bash
 mastra scorers add answer-relevancy
 ```
 
@@ -196,29 +228,45 @@ Do not include example code. Useful when using the `--default` flag.
 
 Configure your code editor with Mastra's MCP server. Choose from: `"cursor" | "cursor-global" | "windsurf" | "vscode"`.
 
+## `mastra migrate`
+
+Runs database migrations to update your storage schema. This command is useful when upgrading Mastra versions that include storage schema changes.
+
+The command bundles your project, connects to your configured storage backend, and executes any pending migrations. Currently supports:
+
+- **Duplicate spans migration**: Removes duplicate `(traceId, spanId)` entries and adds a unique constraint to ensure data integrity.
+
+```bash
+mastra migrate
+```
+
+See the [Storage migration guide](/guides/v1/migrations/upgrade-to-v1/storage#duplicate-spans-migration) for details on when migrations are needed.
+
+It accepts [common flags][common-flags].
+
 ## Common flags
 
 ### `--dir`
 
-**Available in:** `dev`, `build`, `lint`
+**Available in:** `dev`, `build`, `lint`, `migrate`
 
 The path to your Mastra folder. Defaults to `src/mastra`.
 
 ### `--debug`
 
-**Available in:** `dev`, `build`
+**Available in:** `dev`, `build`, `migrate`
 
 Enable verbose logging for Mastra's internals. Defaults to `false`.
 
 ### `--env`
 
-**Available in:** `dev`, `start`
+**Available in:** `dev`, `start`, `studio`, `migrate`
 
 Custom environment variables file to include. By default, includes `.env.development`, `.env.local`, and `.env`.
 
 ### `--root`
 
-**Available in:** `dev`, `build`, `lint`
+**Available in:** `dev`, `build`, `lint`, `migrate`
 
 Path to your root folder. Defaults to `process.cwd()`.
 
@@ -246,13 +294,13 @@ By default, Mastra collects anonymous information about your project like your O
 
 You can opt out of the CLI analytics by setting an environment variable:
 
-```bash copy
+```bash
 MASTRA_TELEMETRY_DISABLED=1
 ```
 
 You can also set this while using other `mastra` commands:
 
-```bash copy
+```bash
 MASTRA_TELEMETRY_DISABLED=1 mastra dev
 ```
 

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

@@ -1,6 +1,10 @@
 ---
 title: "Reference: Agents API | Client SDK"
 description: Learn how to interact with Mastra AI agents, including generating responses, streaming interactions, and managing agent tools using the client-js SDK.
+packages:
+  - "@mastra/ai-sdk"
+  - "@mastra/client-js"
+  - "@mastra/core"
 ---
 
 # Agents API
@@ -24,7 +28,6 @@ Get an instance of a specific agent by its ID:
 ```typescript title="src/mastra/agents/my-agent.ts"
 export const myAgent = new Agent({
   id: "my-agent",
-  // ...
 });
 ```
 
@@ -47,25 +50,31 @@ const details = await agent.details();
 Generate a response from the agent:
 
 ```typescript
-const response = await agent.generate({
-  messages: [
+const response = await agent.generate(
+  [
     {
       role: "user",
       content: "Hello, how are you?",
     },
   ],
-  threadId: "thread-1", // Optional: Thread ID for conversation context
-  resourceId: "resource-1", // Optional: Resource ID
-  output: {}, // Optional: Output configuration
-});
+  {
+    memory: {
+      thread: "thread-abc", // Optional: Thread ID for conversation context
+      resource: "user-123", // Optional: Resource ID
+    },
+    structuredOutput: {}    // Optional: Structured Output configuration
+  }
+);
 ```
 
-You can also use the simplified string format:
+You can also use the simplified string format with memory options:
 
 ```typescript
 const response = await agent.generate("Hello, how are you?", {
-  threadId: "thread-1",
-  resourceId: "resource-1",
+  memory: {
+    thread: "thread-1",
+    resource: "resource-1",
+  },
 });
 ```
 
@@ -74,14 +83,7 @@ const response = await agent.generate("Hello, how are you?", {
 Stream responses from the agent for real-time interactions:
 
 ```typescript
-const response = await agent.stream({
-  messages: [
-    {
-      role: "user",
-      content: "Tell me a story",
-    },
-  ],
-});
+const response = await agent.stream("Tell me a story");
 
 // Process data stream with the processDataStream util
 response.processDataStream({
@@ -91,11 +93,14 @@ response.processDataStream({
 });
 ```
 
-You can also use the simplified string format:
+You can also use the simplified string format with memory options:
 
 ```typescript
 const response = await agent.stream("Tell me a story", {
-  threadId: "thread-1",
+  memory: {
+    thread: "thread-1",
+    resource: "resource-1",
+  },
   clientTools: { colorChangeTool },
 });
 
@@ -123,12 +128,12 @@ while (true) {
 
 To stream AI SDK-formatted parts on the client from an `agent.stream(...)` response, wrap `response.processDataStream` into a `ReadableStream<ChunkType>` and use `toAISdkStream`:
 
-```typescript title="client-ai-sdk-transform.ts" copy
+```typescript title="client-ai-sdk-transform.ts"
 import { createUIMessageStream } from "ai";
 import { toAISdkStream } from "@mastra/ai-sdk";
 import type { ChunkType, MastraModelOutput } from "@mastra/core/stream";
 
-const response = await agent.stream({ messages: "Tell me a story" });
+const response = await agent.stream("Tell me a story");
 
 const chunkStream: ReadableStream<ChunkType> = new ReadableStream<ChunkType>({
   start(controller) {
@@ -179,14 +184,7 @@ const result = await agent.executeTool("tool-id", {
 Stream responses from an agent network for multi-agent interactions:
 
 ```typescript
-const response = await agent.network({
-  messages: [
-    {
-      role: "user",
-      content: "Research this topic and write a summary",
-    },
-  ],
-});
+const response = await agent.network("Research this topic and write a summary");
 
 response.processDataStream({
   onChunk: async (chunk) => {
@@ -229,6 +227,44 @@ response.processDataStream({
 });
 ```
 
+### approveToolCallGenerate()
+
+Approve a pending tool call when using `generate()` (non-streaming). Returns the complete response:
+
+```typescript
+const output = await agent.generate("Find user John", {
+  requireToolApproval: true,
+});
+
+if (output.finishReason === "suspended") {
+  const result = await agent.approveToolCallGenerate({
+    runId: output.runId,
+    toolCallId: output.suspendPayload.toolCallId,
+  });
+
+  console.log(result.text);
+}
+```
+
+### declineToolCallGenerate()
+
+Decline a pending tool call when using `generate()` (non-streaming). Returns the complete response:
+
+```typescript
+const output = await agent.generate("Find user John", {
+  requireToolApproval: true,
+});
+
+if (output.finishReason === "suspended") {
+  const result = await agent.declineToolCallGenerate({
+    runId: output.runId,
+    toolCallId: output.suspendPayload.toolCallId,
+  });
+
+  console.log(result.text);
+}
+```
+
 ## Client Tools
 
 Client-side tools allow you to execute custom functions on the client side when the agent requests them.
@@ -250,14 +286,16 @@ const colorChangeTool = createTool({
 });
 
 // Use with generate
-const response = await agent.generate({
-  messages: "Change the background to blue",
+const response = await agent.generate("Change the background to blue", {
   clientTools: { colorChangeTool },
 });
 
 // Use with stream
-const response = await agent.stream({
-  messages: "Change the background to green",
+const response = await agent.stream("Tell me a story", {
+  memory: {
+    thread: "thread-1",
+    resource: "resource-1",
+  },
   clientTools: { colorChangeTool },
 });
 
@@ -267,7 +305,11 @@ response.processDataStream({
       console.log(chunk.payload.text);
     } else if (chunk.type === "tool-call") {
       console.log(
-        `calling tool ${chunk.payload.toolName} with args ${JSON.stringify(chunk.payload.args, null, 2)}`,
+        `calling tool ${chunk.payload.toolName} with args ${JSON.stringify(
+          chunk.payload.args,
+          null,
+          2
+        )}`
       );
     }
   },

package/.docs/raw/reference/client-js/error-handling.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Error Handling | Client SDK"
 description: Learn about the built-in retry mechanism and error handling capabilities in the Mastra client-js SDK.
+packages:
+  - "@mastra/client-js"
 ---
 
 # Error Handling
@@ -14,9 +16,7 @@ All API methods can throw errors that you can catch and handle:
 ```typescript
 try {
   const agent = mastraClient.getAgent("agent-id");
-  const response = await agent.generate({
-    messages: [{ role: "user", content: "Hello" }],
-  });
+  const response = await agent.generate("Hello");
 } catch (error) {
   console.error("An error occurred:", error.message);
 }

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

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Logs API | Client SDK"
 description: Learn how to access and query system logs and debugging information in Mastra using the client-js SDK.
+packages:
+  - "@mastra/client-js"
 ---
 
 # Logs API

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

@@ -1,15 +1,17 @@
 ---
 title: "Reference: Mastra Client SDK | Client SDK"
 description: Learn how to interact with Mastra using the client-js SDK.
+packages:
+  - "@mastra/client-js"
 ---
 
 # Mastra Client SDK
 
-The Mastra Client SDK provides a simple and type-safe interface for interacting with your [Mastra Server](/docs/v1/deployment/building-mastra) from your client environment.
+The Mastra Client SDK provides a simple and type-safe interface for interacting with your [Mastra Server](/docs/v1/deployment/mastra-server) from your client environment.
 
 ## Usage example
 
-```typescript title="lib/mastra/mastra-client.ts" showLineNumbers copy
+```typescript title="lib/mastra/mastra-client.ts"
 import { MastraClient } from "@mastra/client-js";
 
 export const mastraClient = new MastraClient({

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

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Memory API | Client SDK"
 description: Learn how to manage conversation threads and message history in Mastra using the client-js SDK.
+packages:
+  - "@mastra/client-js"
 ---
 
 # Memory API
@@ -14,10 +16,12 @@ Retrieve all memory threads for a specific resource:
 ```typescript
 const threads = await mastraClient.getMemoryThreads({
   resourceId: "resource-1",
-  agentId: "agent-1",
+  agentId: "agent-1", // Optional - can be omitted if storage is configured
 });
 ```
 
+When `agentId` is omitted and storage is configured on the server, threads will be retrieved using storage directly. This is useful when multiple agents share the same threads (e.g., in workflows with multiple agent steps).
+
 ### Create a New Thread
 
 Create a new memory thread:
@@ -69,6 +73,44 @@ Delete a thread and its messages:
 await thread.delete();
 ```
 
+### Clone Thread
+
+Create a copy of a thread with all its messages:
+
+```typescript
+const { thread: clonedThread, clonedMessages } = await thread.clone();
+```
+
+Clone with options:
+
+```typescript
+const { thread: clonedThread, clonedMessages } = await thread.clone({
+  newThreadId: "custom-clone-id",
+  title: "Cloned Conversation",
+  metadata: { branch: "experiment-1" },
+  options: {
+    messageLimit: 10, // Only clone last 10 messages
+  },
+});
+```
+
+Clone with message filtering:
+
+```typescript
+const { thread: clonedThread } = await thread.clone({
+  options: {
+    messageFilter: {
+      startDate: new Date("2024-01-01"),
+      endDate: new Date("2024-01-31"),
+    },
+  },
+});
+```
+
+The clone response includes:
+- `thread`: The newly created cloned thread with clone metadata
+- `clonedMessages`: Array of the cloned messages with new IDs
+
 ## Message Operations
 
 ### Save Messages

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

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Observability API | Client SDK"
 description: Learn how to retrieve traces, monitor application performance, and score traces using the client-js SDK.
+packages:
+  - "@mastra/client-js"
 ---
 
 # Observability API

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

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Telemetry API | Client SDK"
 description: Learn how to retrieve and analyze traces from your Mastra application for monitoring and debugging using the client-js SDK.
+packages:
+  - "@mastra/client-js"
 ---
 
 # Telemetry API

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

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Tools API | Client SDK"
 description: Learn how to interact with and execute tools available in the Mastra platform using the client-js SDK.
+packages:
+  - "@mastra/client-js"
 ---
 
 # Tools API

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

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Vectors API | Client SDK"
 description: Learn how to work with vector embeddings for semantic search and similarity matching in Mastra using the client-js SDK.
+packages:
+  - "@mastra/client-js"
 ---
 
 # Vectors API

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

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Workflows API | Client SDK"
 description: Learn how to interact with and execute automated workflows in Mastra using the client-js SDK.
+packages:
+  - "@mastra/client-js"
 ---
 
 # Workflows API
@@ -48,8 +50,16 @@ const run = await workflow.createRun();
 
 // Or with an existing runId
 const run = await workflow.createRun({ runId: "existing-run-id" });
+
+// Or with a resourceId to associate the run with a specific resource
+const run = await workflow.createRun({
+  runId: "my-run-id",
+  resourceId: "user-123"
+});
 ```
 
+The `resourceId` parameter associates the workflow run with a specific resource (e.g., user ID, tenant ID). This value is persisted with the run and can be used for filtering and querying runs later.
+
 ### startAsync()
 
 Start a workflow run and await the full result:
@@ -80,6 +90,18 @@ const result = await run.startAsync({
 
 The `initialState` object should match the structure defined in the workflow's `stateSchema`. See [Workflow State](/docs/v1/workflows/workflow-state) for more details.
 
+To associate a run with a specific resource, pass `resourceId` to `createRun()`:
+
+```typescript
+const run = await workflow.createRun({ resourceId: "user-123" });
+
+const result = await run.startAsync({
+  inputData: {
+    city: "New York",
+  },
+});
+```
+
 ### start()
 
 Start a workflow run without waiting for completion:
@@ -94,7 +116,7 @@ await run.start({
 });
 
 // Poll for results later
-const result = await workflow.runExecutionResult(run.runId);
+const result = await workflow.runById(run.runId);
 ```
 
 This is useful for long-running workflows where you want to start execution and check results later.
@@ -125,6 +147,21 @@ await run.resume({
 });
 ```
 
+### cancel()
+
+Cancel a running workflow:
+
+```typescript
+const run = await workflow.createRun({ runId: existingRunId });
+
+const result = await run.cancel();
+// Returns: { message: 'Workflow run canceled' }
+```
+
+This method stops any running steps and prevents subsequent steps from executing. Steps that check the `abortSignal` parameter can respond to cancellation by cleaning up resources (timeouts, network requests, etc.).
+
+See the [Run.cancel()](/reference/v1/workflows/run-methods/cancel) reference for detailed information about how cancellation works and how to write steps that respond to cancellation.
+
 ### stream()
 
 Stream workflow execution for real-time updates:
@@ -143,12 +180,19 @@ for await (const chunk of stream) {
 }
 ```
 
-### runExecutionResult()
+### runById()
 
 Get the execution result for a workflow run:
 
 ```typescript
-const result = await workflow.runExecutionResult(runId);
+const result = await workflow.runById(runId);
+
+// Or with options for performance optimization:
+const result = await workflow.runById(runId, {
+  fields: ['status', 'result'],  // Only fetch specific fields
+  withNestedWorkflows: false,    // Skip expensive nested workflow data
+  requestContext: { userId: 'user-123' }, // Optional request context
+});
 ```
 
 <h3>Run result format</h3>