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

package/.docs/raw/guides/migrations/upgrade-to-v1/tools.mdx

@@ -11,11 +11,11 @@ Tool execution signatures have been updated to use separate input and context pa
 
 ### `createTool` execute signature to `(inputData, context)` format
 
-All **`createTool`** execute functions now use a new signature with separate `inputData` and `context` parameters instead of a single destructured object. This change provides clearer separation between tool inputs and execution context.
+All `createTool` execute functions now use a new signature with separate `inputData` and `context` parameters instead of a single destructured object. This change provides clearer separation between tool inputs and execution context.
 
 **Note:** This change only applies to `createTool`. If you're using `createStep` for workflows, the signature remains `async (inputData, context)` and does not need to be changed.
 
-To migrate, update **`createTool`** signatures to use `inputData` as the first parameter (typed from `inputSchema`) and `context` as the second parameter.
+To migrate, update `createTool` signatures to use `inputData` as the first parameter (typed from `inputSchema`) and `context` as the second parameter.
 
 ```diff
   createTool({
@@ -35,7 +35,7 @@ To migrate, update **`createTool`** signatures to use `inputData` as the first p
 
 ### `createTool` context properties organization
 
-Context properties in **`createTool`** are now organized into namespaces. Agent-specific properties are under `context.agent`, workflow-specific properties are under `context.workflow`, and MCP-specific properties are under `context.mcp`. This change provides better organization and clearer API surface.
+Context properties in `createTool` are now organized into namespaces. Agent-specific properties are under `context.agent`, workflow-specific properties are under `context.workflow`, and MCP-specific properties are under `context.mcp`. This change provides better organization and clearer API surface.
 
 For tools that are executed inside an agent, access agent-specific properties through `context.agent`.
 

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

@@ -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 },
+});
+
+response.processDataStream({
+  onChunk: async (chunk) => {
+    if (chunk.type === "text-delta") {
+      console.log(chunk.payload.text);
+    }
+  },
+});
+```
+
+You can also read from response body directly:
 
-// 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()
+
+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
 
-#### Basic Usage
+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 `toAISdkStream`:
+Get an instance of a specific stored agent:
 
-```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";
+```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 toAISdkStream(
-      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/mastra-client.mdx

@@ -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

@@ -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

package/.docs/raw/reference/core/getMemory.mdx

@@ -0,0 +1,73 @@
+---
+title: "Reference: Mastra.getMemory() | Core"
+description: "Documentation for the `Mastra.getMemory()` method in Mastra, which retrieves a registered memory instance by its registry key."
+---
+
+# Mastra.getMemory()
+
+The `.getMemory()` method retrieves a memory instance from the Mastra registry by its key. Memory instances are registered in the Mastra constructor and can be referenced by stored agents.
+
+## Usage example
+
+```typescript copy
+const memory = mastra.getMemory("conversationMemory");
+
+// Use the memory instance
+const thread = await memory.createThread({
+  resourceId: "user-123",
+  title: "New Conversation",
+});
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "key",
+      type: "TMemoryKey extends keyof TMemory",
+      description:
+        "The registry key of the memory instance to retrieve. Must match a key used when registering memory in the Mastra constructor.",
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "memory",
+      type: "TMemory[TMemoryKey]",
+      description:
+        "The memory instance with the specified key. Throws an error if the memory is not found.",
+    },
+  ]}
+/>
+
+## Example: Registering and Retrieving Memory
+
+```typescript copy
+import { Mastra } from "@mastra/core";
+import { Memory } from "@mastra/memory";
+import { LibSQLStore } from "@mastra/libsql";
+
+const conversationMemory = new Memory({
+  storage: new LibSQLStore({ url: ":memory:" }),
+});
+
+const mastra = new Mastra({
+  memory: {
+    conversationMemory,
+  },
+});
+
+// Later, retrieve the memory instance
+const memory = mastra.getMemory("conversationMemory");
+```
+
+## Related
+
+- [Mastra.listMemory()](/reference/v1/core/listMemory)
+- [Memory overview](/docs/v1/memory/overview)
+- [Agent Memory](/docs/v1/agents/agent-memory)