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

package/.docs/organized/changelogs/mastra.md

@@ -1,5 +1,74 @@
 # mastra
 
+## 0.10.17-alpha.0
+
+### Patch Changes
+
+- 33dcb07: dependencies updates:
+  - Updated dependency [`@opentelemetry/instrumentation@^0.203.0` ↗︎](https://www.npmjs.com/package/@opentelemetry/instrumentation/v/0.203.0) (from `^0.202.0`, in `dependencies`)
+  - Updated dependency [`@opentelemetry/auto-instrumentations-node@^0.62.0` ↗︎](https://www.npmjs.com/package/@opentelemetry/auto-instrumentations-node/v/0.62.0) (from `^0.60.1`, in `dependencies`)
+  - Updated dependency [`@opentelemetry/exporter-trace-otlp-grpc@^0.203.0` ↗︎](https://www.npmjs.com/package/@opentelemetry/exporter-trace-otlp-grpc/v/0.203.0) (from `^0.202.0`, in `dependencies`)
+  - Updated dependency [`@opentelemetry/exporter-trace-otlp-http@^0.203.0` ↗︎](https://www.npmjs.com/package/@opentelemetry/exporter-trace-otlp-http/v/0.203.0) (from `^0.202.0`, in `dependencies`)
+  - Updated dependency [`@opentelemetry/sdk-node@^0.203.0` ↗︎](https://www.npmjs.com/package/@opentelemetry/sdk-node/v/0.203.0) (from `^0.202.0`, in `dependencies`)
+  - Updated dependency [`@opentelemetry/semantic-conventions@^1.36.0` ↗︎](https://www.npmjs.com/package/@opentelemetry/semantic-conventions/v/1.36.0) (from `^1.34.0`, in `dependencies`)
+- Updated dependencies [33dcb07]
+- Updated dependencies [f90797b]
+- Updated dependencies [d30b1a0]
+- Updated dependencies [bff87f7]
+- Updated dependencies [07fe7a2]
+- Updated dependencies [b4a8df0]
+  - @mastra/core@0.12.1-alpha.0
+  - @mastra/mcp@0.10.9-alpha.0
+  - @mastra/deployer@0.12.1-alpha.0
+
+## 0.10.16
+
+### Patch Changes
+
+- bc6b44a: Extract tools import from `createHonoServer`; the function now receives tools via a prop on the `options` parameter.
+- f442224: speech to text using voice config
+- 7a7754f: Fast follow scorers fixing input types, improve llm scorer reliability, fix ui to display scores that are 0
+- d8dec5e: add a cta to invite to deploy to cloud
+- 6336993: Fix workflow input form overflow
+- d5cc460: This change implements a fix to sourcemap mappings being off due to `removeDeployer` Babel plugin missing source map config.
+- f42c4c2: update peer deps for packages to latest core range
+- a5681f2: fix: pagination breaks trace grouping
+- 89d2f4e: add TTS to the playground
+- Updated dependencies [510e2c8]
+- Updated dependencies [2f72fb2]
+- Updated dependencies [27cc97a]
+- Updated dependencies [832691b]
+- Updated dependencies [557bb9d]
+- Updated dependencies [27cc97a]
+- Updated dependencies [3f89307]
+- Updated dependencies [9eda7d4]
+- Updated dependencies [9d49408]
+- Updated dependencies [bc6b44a]
+- Updated dependencies [41daa63]
+- Updated dependencies [ad0a58b]
+- Updated dependencies [254a36b]
+- Updated dependencies [2ecf658]
+- Updated dependencies [7a7754f]
+- Updated dependencies [fc92d80]
+- Updated dependencies [e0f73c6]
+- Updated dependencies [0b89602]
+- Updated dependencies [4d37822]
+- Updated dependencies [23a6a7c]
+- Updated dependencies [cda801d]
+- Updated dependencies [a77c823]
+- Updated dependencies [ff9c125]
+- Updated dependencies [09bca64]
+- Updated dependencies [9802f42]
+- Updated dependencies [d5cc460]
+- Updated dependencies [f42c4c2]
+- Updated dependencies [b8efbb9]
+- Updated dependencies [71466e7]
+- Updated dependencies [0c99fbe]
+  - @mastra/core@0.12.0
+  - @mastra/deployer@0.12.0
+  - @mastra/loggers@0.10.5
+  - @mastra/mcp@0.10.8
+
 ## 0.10.16-alpha.3
 
 ### Patch Changes
@@ -229,74 +298,5 @@
 - f9b1508: add the same agent table as in cloud and export it from the playground
 - dfbeec6: Fix navigation to vnext AgentNetwork agents
 - Updated dependencies [7776324]
-- Updated dependencies [0b56518]
-- Updated dependencies [db5cc15]
-- Updated dependencies [2ba5b76]
-- Updated dependencies [7b57e2c]
-- Updated dependencies [5237998]
-- Updated dependencies [c3a30de]
-- Updated dependencies [37c1acd]
-- Updated dependencies [1aa60b1]
-- Updated dependencies [89ec9d4]
-- Updated dependencies [cf3a184]
-- Updated dependencies [fe4bbd4]
-- Updated dependencies [d6bfd60]
-- Updated dependencies [626b0f4]
-- Updated dependencies [c22a91f]
-- Updated dependencies [f7403ab]
-- Updated dependencies [6c89d7f]
-  - @mastra/deployer@0.10.15
-  - @mastra/core@0.10.15
-
-## 0.10.13-alpha.2
-
-### Patch Changes
-
-- 794d9f3: Fix thread creation in playground
-- dfbeec6: Fix navigation to vnext AgentNetwork agents
-
-## 0.10.13-alpha.1
-
-### Patch Changes
-
-- d49334d: export tool list for usage in cloud
-- 9cdfcb5: fix infinite rerenders on agents table + share runtime context for cloud
-- 45174f3: share network list between core and cloud
-- 48f5532: export workflow list for usage in cloud
-- 3e484be: Added CLI template option
-- Updated dependencies [0b56518]
-- Updated dependencies [2ba5b76]
-- Updated dependencies [c3a30de]
-- Updated dependencies [cf3a184]
-- Updated dependencies [fe4bbd4]
-- Updated dependencies [d6bfd60]
-  - @mastra/core@0.10.15-alpha.1
-  - @mastra/deployer@0.10.15-alpha.1
 
-## 0.10.13-alpha.0
-
-### Patch Changes
-
-- 593631d: allow to pass ref to the link abstraction
-- 5237998: Fix foreach output
-- 1aa60b1: Pipe runtimeContext to vNext network agent stream and generate steps, wire up runtimeContext for vNext Networks in cliet SDK & playground
-- 5130bcb: dependencies updates:
-  - Updated dependency [`swr@^2.3.4` ↗︎](https://www.npmjs.com/package/swr/v/2.3.4) (from `^2.3.3`, in `dependencies`)
-- 984887a: dependencies updates:
-  - Updated dependency [`prettier@^3.6.2` ↗︎](https://www.npmjs.com/package/prettier/v/3.6.2) (from `^3.5.3`, in `dependencies`)
-- aa9528a: Display reasoning in playground
-- 626b0f4: [Cloud-126] Working Memory Playground - Added working memory to playground to allow users to view/edit working memory
-- e1d0080: abstract Link component between cloud and core
-- f9b1508: add the same agent table as in cloud and export it from the playground
-- Updated dependencies [7776324]
-- Updated dependencies [db5cc15]
-- Updated dependencies [7b57e2c]
-- Updated dependencies [5237998]
-- Updated dependencies [37c1acd]
-- Updated dependencies [1aa60b1]
-- Updated dependencies [89ec9d4]
-- Updated dependencies [626b0f4]
-- Updated dependencies [c22a91f]
-- Updated dependencies [f7403ab]
-
-... 4605 more lines hidden. See full changelog in package directory.
+... 4674 more lines hidden. See full changelog in package directory.

package/.docs/raw/agents/streaming.mdx

@@ -0,0 +1,118 @@
+---
+title: "Using Agent Streaming | Agents | Mastra Docs"
+description: Documentation on how to stream agents
+---
+
+# Agent Streaming
+
+Agents in Mastra have access to a powerful streaming protocol! With seamless integration into tools or agents as a tool, you can stream responses directly back to your clients, creating a more interactive and engaging experience.
+
+## Usage
+
+To use the new protocol, you can use the `streamVNext` method on an agent. This method will return a custom MastraAgentStream. This stream extends a ReadableStream, so all basic stream methods are available.
+
+```typescript
+const stream = await agent.streamVNext({ role: "user", content: "Tell me a story." });
+
+for await (const chunk of stream) {
+  console.log(chunk);
+}
+```
+
+Each chunk is a JSON object with the following properties:
+
+```json
+{
+  type: string;
+  runId: string;
+  from: string;
+  payload: Record<string, any>;
+}
+```
+
+We have a couple of utility functions on the stream to help you with the streaming process.
+
+- `stream.finishReason` - The reason the agent stopped streaming.
+- `stream.toolCalls` - The tool calls made by the agent.
+- `stream.toolResults` - The tool results returned by the agent.
+- `stream.usage` - The total token usage of the agent, including agents/workflows as a tool.
+- `stream.text` - The full text of the agent's response.
+- `stream.object` - The object of the agent's response, if you use output or experimental output.
+- `stream.textStream` - A readable stream that will emit the text of the agent's response.
+
+### How to use the stream in a tool
+
+Each tool gets a `writer` argument, which is a writable stream with a custom write function. This write function is used to write the tool's response to the stream.
+
+```typescript filename="src/mastra/tools/test-tool.ts" showLineNumbers copy
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+
+export const weatherInfo = createTool({
+  id: "Get Weather Information",
+  inputSchema: z.object({
+    city: z.string(),
+  }),
+  outputSchema: z.object({
+    conditions: z.string(),
+    temperature: z.number(),
+  }),
+  description: `Fetches the current weather information for a given city`,
+  execute: async ({ context: { city }, writer }) => {
+    writer.write({
+      type: "weather-data",
+      args: {
+        city
+      },
+      status: "pending"
+    })
+    // Tool logic here (e.g., API call)
+    console.log("Using tool to fetch weather information for", city);
+
+    writer.write({
+      type: "weather-data",
+      args: {
+        city
+      },
+      status: "success",
+      result: {
+        temperature: 20,
+        conditions: "Sunny"
+      }
+    })
+
+    return { temperature: 20, conditions: "Sunny" }; // Example return
+  },
+});
+```
+
+If you want to use the stream in an agent, you can use the `streamVNext` method on the agent and pipe it to the agent's input stream.
+
+```typescript filename="src/mastra/tools/test-tool.ts" showLineNumbers copy
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+
+export const weatherInfo = createTool({
+  id: "Get Weather Information",
+  description: `Fetches the current weather information for a given city`,
+  inputSchema: z.object({
+    city: z.string(),
+  }),
+  outputSchema: z.object({
+    text: z.string(),
+  }),
+  execute: async ({ context: { city }, writer, mastra }) => {
+    const agent = mastra.getAgent('weatherAgent')
+    const stream = await agent.streamVNext(`What is the weather in ${city}?`);
+
+    await stream.pipeTo(writer);
+
+    return {
+      text: await stream.text,
+    }
+  },
+});
+```
+
+Piping the stream to the agent's input stream will allow us to automatically sum up the usage of the agent so the total usage count can be calculated.
+

package/.docs/raw/community/contributing-templates.mdx

@@ -27,6 +27,7 @@ Create your template following the established patterns:
 - Include comprehensive documentation
 - Test thoroughly with fresh installations
 - Follow all technical requirements
+- Ensure the github repo is a template repo. [How to create a template repo](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-template-repository)
 
 ### 3. Submit for Review
 

package/.docs/raw/memory/overview.mdx

@@ -68,7 +68,7 @@ Send a few messages and notice that it remembers information across turns:
 
 Mastra organizes memory into threads, which are records that identify specific conversation histories, using two identifiers:
 
-1.  **`threadId`**: A specific conversation id (e.g., `support_123`).
+1.  **`threadId`**: A globally unique conversation id (e.g., `support_123`). Thread IDs must be unique across all resources.
 2.  **`resourceId`**: The user or entity id that owns each thread (e.g., `user_123`, `org_456`).
 
 The `resourceId` is particularly important for [resource-scoped working memory](./working-memory.mdx#resource-scoped-memory), which allows memory to persist across all conversation threads for the same user.
@@ -82,6 +82,8 @@ const response = await myMemoryAgent.stream("Hello, my name is Alice.", {
 
 **Important:** without these ID's your agent will not use memory, even if memory is properly configured. The playground handles this for you, but you need to add ID's yourself when using memory in your application.
 
+> **Thread ID Uniqueness:** Each thread ID must be globally unique across all resources. A thread is permanently associated with the resource that created it. If you need to have similar thread names for different resources (e.g., a "general" thread for multiple users), include the resource ID in the thread ID: `${resourceId}-general` or `user_alice_general`.
+
 ### Thread Title Generation
 
 Mastra can automatically generate meaningful titles for conversation threads based on the user's first message. This helps organize and identify conversations in your application UI.

package/.docs/raw/memory/working-memory.mdx

@@ -298,6 +298,73 @@ again because it has been stored in working memory.
 If your agent is not properly updating working memory when you expect it to, you can add system
 instructions on _how_ and _when_ to use this template in your agent's `instructions` setting.
 
+## Setting Initial Working Memory
+
+While agents typically update working memory through the `updateWorkingMemory` tool, you can also set initial working memory programmatically when creating or updating threads. This is useful for injecting user data (like their name, preferences, or other info) that you want available to the agent without passing it in every request.
+
+### Setting Working Memory via Thread Metadata
+
+When creating a thread, you can provide initial working memory through the metadata's `workingMemory` key:
+
+```typescript filename="src/app/medical-consultation.ts" showLineNumbers copy
+// Create a thread with initial working memory
+const thread = await memory.createThread({
+  threadId: "thread-123",
+  resourceId: "user-456",
+  title: "Medical Consultation",
+  metadata: {
+    workingMemory: `# Patient Profile
+- Name: John Doe
+- Blood Type: O+
+- Allergies: Penicillin
+- Current Medications: None
+- Medical History: Hypertension (controlled)
+`
+  }
+});
+
+// The agent will now have access to this information in all messages
+await agent.generate("What's my blood type?", {
+  threadId: thread.id,
+  resourceId: "user-456"
+});
+// Response: "Your blood type is O+."
+```
+
+### Updating Working Memory Programmatically
+
+You can also update an existing thread's working memory:
+
+```typescript filename="src/app/medical-consultation.ts" showLineNumbers copy
+// Update thread metadata to add/modify working memory
+await memory.updateThread({
+  id: "thread-123",
+  title: thread.title,
+  metadata: {
+    ...thread.metadata,
+    workingMemory: `# Patient Profile
+- Name: John Doe
+- Blood Type: O+
+- Allergies: Penicillin, Ibuprofen  // Updated
+- Current Medications: Lisinopril 10mg daily  // Added
+- Medical History: Hypertension (controlled)
+`
+  }
+});
+```
+
+### Direct Memory Update
+
+Alternatively, use the `updateWorkingMemory` method directly:
+
+```typescript filename="src/app/medical-consultation.ts" showLineNumbers copy
+await memory.updateWorkingMemory({
+  threadId: "thread-123",
+  resourceId: "user-456", // Required for resource-scoped memory
+  workingMemory: "Updated memory content..."
+});
+```
+
 ## Examples
 
 - [Streaming working memory](/examples/memory/streaming-working-memory)

package/.docs/raw/observability/logging.mdx

@@ -1,38 +1,113 @@
 ---
 title: "Logging | Mastra Observability Documentation"
-description: Documentation on effective logging in Mastra, crucial for understanding application behavior and improving AI accuracy.
+description: Learn how to use logging in Mastra to monitor execution, capture application behavior, and improve the accuracy of AI applications.
 ---
 
-import Image from "next/image";
-
 # Logging
 
-In Mastra, logs can detail when certain functions run, what input data they receive, and how they respond.
+Mastra's logging system captures function execution, input data, and output responses in a structured format.
+
+When deploying to Mastra Cloud, logs are shown on the [Logs](../mastra-cloud/observability.mdx) page. In self-hosted or custom environments, logs can be directed to files or external services depending on the configured transports.
 
-## Basic Setup
+## PinoLogger
 
-Here's a minimal example that sets up a **console logger** at the `INFO` level. This will print out informational messages and above (i.e., `DEBUG`, `INFO`, `WARN`, `ERROR`) to the console.
+When [initializing a new Mastra project](../getting-started/installation.mdx) using the CLI, `PinoLogger` is included by default.
 
-```typescript filename="mastra.config.ts" showLineNumbers copy
-import { Mastra } from "@mastra/core";
-import { PinoLogger } from "@mastra/loggers";
+```typescript filename="src/mastra/index.ts" showLineNumbers copy
+import { Mastra } from '@mastra/core/mastra';
+import { PinoLogger } from '@mastra/loggers';
 
 export const mastra = new Mastra({
-  // Other Mastra configuration...
+  // ...
   logger: new PinoLogger({
-    name: "Mastra",
-    level: "info",
+    name: 'Mastra',
+    level: 'info',
   }),
 });
 ```
 
-In this configuration:
+> See the [PinoLogger](../../reference/observability/logger.mdx) API reference for all available configuration options.
+
+## Logging from workflows and tools
+
+Mastra provides access to a logger instance via the `mastra.getLogger()` method, available inside both workflow steps and tools. The logger supports standard severity levels: `debug`, `info`, `warn`, and `error`.
+
+### Logging from workflow steps
+
+Within a workflow step, access the logger via the `mastra` parameter inside the `execute` function. This allows you to log messages relevant to the step’s execution.
+
+
+```typescript {8-9} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+import { createWorkflow, createStep } from "@mastra/core/workflows";
+import { z } from "zod";
+
+const step1 = createStep({
+  //...
+  execute: async ({ mastra }) => {
+
+    const logger = mastra.getLogger();
+    logger.info("workflow info log");
+
+    return {
+      output: ""
+    };
+  }
+});
+
+export const testWorkflow = createWorkflow({...})
+  .then(step1)
+  .commit();
+```
+
+### Logging from tools
+
+Similarly, tools have access to the logger instance via the `mastra` parameter. Use this to log tool specific activity during execution.
 
-- `name: "Mastra"` specifies the name to group logs under.
-- `level: "info"` sets the minimum severity of logs to record.
+```typescript {8-9} filename="src/mastra/tools/test-tool.ts" showLineNumbers copy
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
 
-## Configuration
+export const testTool = createTool({
+  // ...
+  execute: async ({ mastra }) => {
 
-- For more details on the options you can pass to `PinoLogger()`, see the [PinoLogger reference documentation](/reference/observability/logger).
-- Once you have a `Logger` instance, you can call its methods (e.g., `.info()`, `.warn()`, `.error()`) in the [Logger instance reference documentation](/reference/observability/logger).
-- If you want to send your logs to an external service for centralized collection, analysis, or storage, you can configure other logger types such as Upstash Redis. Consult the [Logger reference documentation](/reference/observability/logger) for details on parameters like `url`, `token`, and `key` when using the `UPSTASH` logger type.
+    const logger = mastra?.getLogger();
+    logger?.info("tool info log");
+
+    return {
+      output: ""
+    };
+  }
+});
+```
+
+
+## Logging with additional data
+
+Logger methods accept an optional second argument for additional data. This can be any value, such as an object, string, or number.
+
+In this example, the log message includes an object with a key of `agent` and a value of the `testAgent` instance.
+
+```typescript {11} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+import { createWorkflow, createStep } from "@mastra/core/workflows";
+import { z } from "zod";
+
+const step1 = createStep({
+  //...
+  execute: async ({ mastra }) => {
+
+    const testAgent = mastra.getAgent("testAgent");
+
+    const logger = mastra.getLogger();
+    logger.info("workflow info log", { agent: testAgent });
+
+    return {
+      output: ""
+    };
+  }
+});
+
+export const testWorkflow = createWorkflow({...})
+  .then(step1)
+  .commit();
+```