@mastra/mcp-docs-server 1.0.0-beta.1 → 1.0.0-beta.10

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

@@ -1,5 +1,5 @@
 ---
-title: "Reference: CLI Commands | CLI | Mastra Docs"
+title: "Reference: CLI Commands | CLI"
 description: Documentation for the Mastra CLI to develop, build, and start your project.
 ---
 
@@ -23,11 +23,11 @@ Enable local HTTPS support. [Learn more](/docs/v1/getting-started/studio#local-h
 
 #### `--inspect`
 
-Start the development server in inspect mode, helpful for debugging. This can't be used together with `--inspect-brk`.
+Start the development server in inspect mode, helpful for debugging. Optionally specify a custom host and port (e.g., `--inspect=0.0.0.0:9229` for Docker). This can't be used together with `--inspect-brk`.
 
 #### `--inspect-brk`
 
-Start the development server in inspect mode and break at the beginning of the script. This can't be used together with `--inspect`.
+Start the development server in inspect mode and break at the beginning of the script. Optionally specify a custom host and port (e.g., `--inspect-brk=0.0.0.0:9229`). This can't be used together with `--inspect`.
 
 #### `--custom-args`
 
@@ -75,7 +75,8 @@ ANTHROPIC_BASE_URL=https://anthropic.internal \
 mastra dev
 ```
 
-These are forwarded by the AI SDK and work with any `openai()` or `anthropic()` calls.
+These are forwarded to the Mastra model router and will work with any `"openai/..."`
+or `"anthropic/..."` model selections.
 
 ## `mastra build`
 
@@ -85,7 +86,7 @@ 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/serverless-platforms) you need to install the correct deployer in order to receive the correct output in `.mastra`.
+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`.
 
 It accepts [common flags][common-flags].
 
@@ -123,6 +124,18 @@ 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`.
+
 ## `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.
@@ -211,7 +224,7 @@ Enable verbose logging for Mastra's internals. Defaults to `false`.
 
 ### `--env`
 
-**Available in:** `dev`, `start`
+**Available in:** `dev`, `start`, `studio`
 
 Custom environment variables file to include. By default, includes `.env.development`, `.env.local`, and `.env`.
 

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

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Agents API | Client SDK | Mastra Docs"
+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.
 ---
 
@@ -15,19 +15,26 @@ Retrieve a list of all available agents:
 const agents = await mastraClient.listAgents();
 ```
 
-Returns a record of agent IDs to their serialized agent configurations. See the [Agent class reference](/reference/v1/agents/agent) for details on agent properties.
+Returns a record of agent IDs to their serialized agent configurations.
 
 ## Working with a Specific Agent
 
-Get an instance of a specific agent:
+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",
+  // ...
+});
+```
 
 ```typescript
-const agent = mastraClient.getAgent("agent-id");
+const agent = mastraClient.getAgent("my-agent");
 ```
 
 ## Agent Methods
 
-### Get Agent Details
+### details()
 
 Retrieve detailed information about an agent:
 
@@ -35,9 +42,7 @@ Retrieve detailed information about an agent:
 const details = await agent.details();
 ```
 
-Returns the serialized agent configuration. See the [Agent class reference](/reference/v1/agents/agent) for details on agent properties.
-
-### Generate Response
+### generate()
 
 Generate a response from the agent:
 
@@ -55,7 +60,16 @@ const response = await agent.generate({
 });
 ```
 
-### Stream Response
+You can also use the simplified string format:
+
+```typescript
+const response = await agent.generate("Hello, how are you?", {
+  threadId: "thread-1",
+  resourceId: "resource-1",
+});
+```
+
+### stream()
 
 Stream responses from the agent for real-time interactions:
 
@@ -75,8 +89,28 @@ response.processDataStream({
     console.log(chunk);
   },
 });
+```
+
+You can also use the simplified string format:
+
+```typescript
+const response = await agent.stream("Tell me a story", {
+  threadId: "thread-1",
+  clientTools: { colorChangeTool },
+});
 
-// You can also read from response body directly
+response.processDataStream({
+  onChunk: async (chunk) => {
+    if (chunk.type === "text-delta") {
+      console.log(chunk.payload.text);
+    }
+  },
+});
+```
+
+You can also read from response body directly:
+
+```typescript
 const reader = response.body.getReader();
 while (true) {
   const { done, value } = await reader.read();
@@ -85,11 +119,119 @@ while (true) {
 }
 ```
 
-### Client tools
+#### AI SDK compatible format
 
-Client-side tools allow you to execute custom functions on the client side when the agent requests them.
+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
+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 chunkStream: ReadableStream<ChunkType> = new ReadableStream<ChunkType>({
+  start(controller) {
+    response
+      .processDataStream({
+        onChunk: async (chunk) => controller.enqueue(chunk as ChunkType),
+      })
+      .finally(() => controller.close());
+  },
+});
+
+const uiMessageStream = createUIMessageStream({
+  execute: async ({ writer }) => {
+    for await (const part of toAISdkStream(
+      chunkStream as unknown as MastraModelOutput,
+      { from: "agent" },
+    )) {
+      writer.write(part);
+    }
+  },
+});
+
+for await (const part of uiMessageStream) {
+  console.log(part);
+}
+```
+
+### getTool()
+
+Retrieve information about a specific tool available to the agent:
+
+```typescript
+const tool = await agent.getTool("tool-id");
+```
+
+### executeTool()
+
+Execute a specific tool for the agent:
+
+```typescript
+const result = await agent.executeTool("tool-id", {
+  data: { input: "value" },
+});
+```
+
+### network()
+
+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",
+    },
+  ],
+});
+
+response.processDataStream({
+  onChunk: async (chunk) => {
+    console.log(chunk);
+  },
+});
+```
+
+### approveToolCall()
+
+Approve a pending tool call that requires human confirmation:
+
+```typescript
+const response = await agent.approveToolCall({
+  runId: "run-123",
+  toolCallId: "tool-call-456",
+});
+
+response.processDataStream({
+  onChunk: async (chunk) => {
+    console.log(chunk);
+  },
+});
+```
+
+### declineToolCall()
 
-#### Basic Usage
+Decline a pending tool call that requires human confirmation:
+
+```typescript
+const response = await agent.declineToolCall({
+  runId: "run-123",
+  toolCallId: "tool-call-456",
+});
+
+response.processDataStream({
+  onChunk: async (chunk) => {
+    console.log(chunk);
+  },
+});
+```
+
+## Client Tools
+
+Client-side tools allow you to execute custom functions on the client side when the agent requests them.
 
 ```typescript
 import { createTool } from "@mastra/client-js";
@@ -132,90 +274,132 @@ response.processDataStream({
 });
 ```
 
-### Get Agent Tool
+## Stored Agents
 
-Retrieve information about a specific tool available to the agent:
+Stored agents are agent configurations stored in a database that can be created, updated, and deleted at runtime. They reference primitives (tools, workflows, other agents, memory, scorers) by key, which are resolved from the Mastra registry when the agent is instantiated.
+
+### listStoredAgents()
+
+Retrieve a paginated list of all stored agents:
 
 ```typescript
-const tool = await agent.getTool("tool-id");
+const result = await mastraClient.listStoredAgents();
+console.log(result.agents); // Array of stored agents
+console.log(result.total); // Total count
 ```
 
-### Get Agent Evaluations
-
-Get evaluation results for the agent:
+With pagination and ordering:
 
 ```typescript
-// Get CI evaluations
-const evals = await agent.evals();
-
-// Get live evaluations
-const liveEvals = await agent.liveEvals();
+const result = await mastraClient.listStoredAgents({
+  page: 0,
+  perPage: 20,
+  orderBy: {
+    field: "createdAt",
+    direction: "DESC",
+  },
+});
 ```
 
-### Stream
+### createStoredAgent()
 
-Stream responses using the enhanced API with improved method signatures. This method provides enhanced capabilities and format flexibility, with support for Mastra's native format.
+Create a new stored agent:
 
 ```typescript
-const response = await agent.stream("Tell me a story", {
-  threadId: "thread-1",
-  clientTools: { colorChangeTool },
+const agent = await mastraClient.createStoredAgent({
+  id: "my-agent",
+  name: "My Assistant",
+  instructions: "You are a helpful assistant.",
+  model: {
+    provider: "openai",
+    name: "gpt-4",
+  },
 });
+```
 
-// Process the stream
-response.processDataStream({
-  onChunk: async (chunk) => {
-    if (chunk.type === "text-delta") {
-      console.log(chunk.payload.text);
-    }
+With all options:
+
+```typescript
+const agent = await mastraClient.createStoredAgent({
+  id: "full-agent",
+  name: "Full Agent",
+  description: "A fully configured agent",
+  instructions: "You are a helpful assistant.",
+  model: {
+    provider: "openai",
+    name: "gpt-4",
+  },
+  tools: ["calculator", "weather"],
+  workflows: ["data-processing"],
+  agents: ["sub-agent-1"],
+  memory: "my-memory",
+  scorers: {
+    "quality-scorer": {
+      sampling: { type: "ratio", rate: 0.1 },
+    },
+  },
+  defaultOptions: {
+    maxSteps: 10,
+  },
+  metadata: {
+    version: "1.0",
+    team: "engineering",
   },
 });
 ```
 
-#### AI SDK compatible format
+### getStoredAgent()
 
-To stream AI SDK-formatted parts on the client from an `agent.stream(...)` response, wrap `response.processDataStream` into a `ReadableStream<ChunkType>` and use `toAISdkFormat`:
+Get an instance of a specific stored agent:
 
-```typescript title="client-ai-sdk-transform.ts" copy
-import { createUIMessageStream } from "ai";
-import { toAISdkFormat } from "@mastra/ai-sdk";
-import type { ChunkType, MastraModelOutput } from "@mastra/core/stream";
+```typescript
+const storedAgent = mastraClient.getStoredAgent("my-agent");
+```
 
-const response = await agent.stream({ messages: "Tell me a story" });
+## Stored Agent Methods
 
-const chunkStream: ReadableStream<ChunkType> = new ReadableStream<ChunkType>({
-  start(controller) {
-    response
-      .processDataStream({
-        onChunk: async (chunk) => controller.enqueue(chunk as ChunkType),
-      })
-      .finally(() => controller.close());
-  },
+### details()
+
+Retrieve the stored agent configuration:
+
+```typescript
+const details = await storedAgent.details();
+console.log(details.name);
+console.log(details.instructions);
+console.log(details.model);
+```
+
+### update()
+
+Update specific fields of a stored agent. All fields are optional:
+
+```typescript
+const updated = await storedAgent.update({
+  name: "Updated Agent Name",
+  instructions: "New instructions for the agent.",
 });
+```
 
-const uiMessageStream = createUIMessageStream({
-  execute: async ({ writer }) => {
-    for await (const part of toAISdkFormat(
-      chunkStream as unknown as MastraModelOutput,
-      { from: "agent" },
-    )) {
-      writer.write(part);
-    }
-  },
+```typescript
+// Update just the tools
+await storedAgent.update({
+  tools: ["new-tool-1", "new-tool-2"],
 });
 
-for await (const part of uiMessageStream) {
-  console.log(part);
-}
+// Update metadata
+await storedAgent.update({
+  metadata: {
+    version: "2.0",
+    lastModifiedBy: "admin",
+  },
+});
 ```
 
-### Generate
+### delete()
 
-Generate a response using the enhanced API with improved method signatures and AI SDK v5 compatibility:
+Delete a stored agent:
 
 ```typescript
-const response = await agent.generate("Hello, how are you?", {
-  threadId: "thread-1",
-  resourceId: "resource-1",
-});
+const result = await storedAgent.delete();
+console.log(result.success); // true
 ```

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

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Error Handling | Client SDK | Mastra Docs"
+title: "Reference: Error Handling | Client SDK"
 description: Learn about the built-in retry mechanism and error handling capabilities in the Mastra client-js SDK.
 ---
 

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

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Logs API | Client SDK | Mastra Docs"
+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.
 ---
 

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

@@ -1,11 +1,11 @@
 ---
-title: "Reference: Mastra Client SDK | Client SDK | Mastra Docs"
+title: "Reference: Mastra Client SDK | Client SDK"
 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/v1/deployment/server-deployment) from your client environment.
+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.
 
 ## Usage example
 
@@ -101,8 +101,8 @@ export const mastraClient = new MastraClient({
     },
     {
       name: "saveMessageToMemory(params)",
-      type: "Promise<void>",
-      description: "Saves one or more messages to the memory system.",
+      type: "Promise<{ messages: (MastraMessageV1 | MastraDBMessage)[] }>",
+      description: "Saves one or more messages to the memory system. Returns the saved messages.",
     },
     {
       name: "getMemoryStatus()",

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

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Memory API | Client SDK | Mastra Docs"
+title: "Reference: Memory API | Client SDK"
 description: Learn how to manage conversation threads and message history in Mastra using the client-js SDK.
 ---
 
@@ -76,7 +76,7 @@ await thread.delete();
 Save messages to memory:
 
 ```typescript
-const savedMessages = await mastraClient.saveMessageToMemory({
+const result = await mastraClient.saveMessageToMemory({
   messages: [
     {
       role: "user",
@@ -90,6 +90,9 @@ const savedMessages = await mastraClient.saveMessageToMemory({
   ],
   agentId: "agent-1",
 });
+
+// result.messages contains the saved messages
+console.log(result.messages);
 ```
 
 ### Retrieve Thread Messages
@@ -133,6 +136,49 @@ const result = await thread.deleteMessages([
 // Returns: { success: true, message: "Message deleted successfully" }
 ```
 
+## Working Memory
+
+Working memory allows agents to maintain persistent information about users across interactions. It can be scoped to either a specific thread or across all threads for a resource (user).
+
+### Get Working Memory
+
+Retrieve the current working memory for a thread:
+
+```typescript
+const workingMemory = await mastraClient.getWorkingMemory({
+  agentId: "agent-1",
+  threadId: "thread-1",
+  resourceId: "user-123", // Optional, required for resource-scoped memory
+});
+```
+
+The response includes:
+- `workingMemory`: The current working memory content (string or null)
+- `source`: Whether the memory is from `"thread"` or `"resource"` scope
+- `workingMemoryTemplate`: The template used for working memory (if configured)
+- `threadExists`: Whether the thread exists
+
+### Update Working Memory
+
+Update the working memory content for a thread:
+
+```typescript
+await mastraClient.updateWorkingMemory({
+  agentId: "agent-1",
+  threadId: "thread-1",
+  workingMemory: `# User Profile
+- Name: John Doe
+- Location: New York
+- Preferences: Prefers formal communication
+`,
+  resourceId: "user-123", // Optional, required for resource-scoped memory
+});
+
+// Returns: { success: true }
+```
+
+**Note:** For resource-scoped working memory, you must provide the `resourceId` parameter. This allows the memory to persist across all conversation threads for that user.
+
 ### Get Memory Status
 
 Check the status of the memory system:

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

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Observability API | Client SDK | Mastra Docs"
+title: "Reference: Observability API | Client SDK"
 description: Learn how to retrieve traces, monitor application performance, and score traces using the client-js SDK.
 ---
 

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

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Telemetry API | Client SDK | Mastra Docs"
+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.
 ---
 

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

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Tools API | Client SDK | Mastra Docs"
+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.
 ---
 

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

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Vectors API | Client SDK | Mastra Docs"
+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.
 ---