@mastra/mcp-docs-server 0.0.0-error-handler-fix-20251020202607 → 0.0.0-execa-dynamic-import-20260304221256

package/.docs/guides/migrations/upgrade-to-v1/tools.md

@@ -0,0 +1,180 @@
+# Tools
+
+Tool execution signatures have been updated to use separate input and context parameters with reorganized context properties.
+
+## Changed
+
+### `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.
+
+**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.
+
+```diff
+createTool({
+    id: 'weather-tool',
+-   execute: async ({ context, requestContext, mastra }) => {
+-     const location = context.location;
+-     const userTier = requestContext.get('userTier');
+-     return getWeather(location, userTier);
+-   },
++   execute: async (inputData, context) => {
++     const location = inputData.location;
++     const userTier = context?.requestContext?.get('userTier');
++     return getWeather(location, userTier);
++   },
+  });
+```
+
+### `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.
+
+For tools that are executed inside an agent, access agent-specific properties through `context.agent`.
+
+```diff
+createTool({
+    id: 'suspendable-tool',
+    suspendSchema: z.object({ message: z.string() }),
+    resumeSchema: z.object({ approval: z.boolean() }),
+-   execute: async ({ context, suspend, resumeData }) => {
+-     if (!resumeData) {
+-       return await suspend({ message: 'Waiting for approval' });
+-     }
+-     if (resumeData.approval) {
+-       return { success: true };
+-     }
+-   },
++   execute: async (inputData, context) => {
++     if (!context?.agent?.resumeData) {
++       return await context?.agent?.suspend({
++         message: 'Waiting for approval',
++       });
++     }
++     if (context.agent.resumeData.approval) {
++       return { success: true };
++     }
++   },
+  });
+```
+
+For tools that are executed inside a workflow, access workflow-specific properties through `context.workflow`.
+
+```diff
+createTool({
+    id: 'workflow-tool',
+-   execute: async ({ workflowId, runId, state, setState }) => {
+-     const currentState = state;
+-     setState({ step: 'completed' });
+-     return { result: 'done' };
+-   },
++   execute: async (inputData, context) => {
++     const currentState = context?.workflow?.state;
++     context?.workflow?.setState({ step: 'completed' });
++     return { result: 'done' };
++   },
+  });
+```
+
+The `suspendPayload` gets validated against the `suspendSchema` when the tool is executed. If the suspendPayload doesn't match the `suspendSchema`, a warning is logged and the error is returned as tool output, but suspension continues. Also, when the tool is resumed, the `resumeData` gets validated against the `resumeSchema`. If the resumeData doesn't match the `resumeSchema`, the tool will return a `ValidationError`, preventing the tool resumption.
+
+To skip the `suspendSchema` or `resumeSchema` validation, do not define `suspendSchema` or `resumeSchema` in the tool creation.
+
+> **Note:** For MCP-specific tool context changes, see the [MCP migration guide](https://mastra.ai/guides/migrations/upgrade-to-v1/mcp).
+
+### `RuntimeContext` to `RequestContext`
+
+The `RuntimeContext` class has been renamed to `RequestContext` throughout the tool execution context. This change provides clearer naming that better describes its purpose as request-specific data.
+
+To migrate, update references from `runtimeContext` to `requestContext` in tool execution functions.
+
+```diff
+createTool({
+    id: 'my-tool',
+    execute: async (inputData, context) => {
+-     const userTier = context?.runtimeContext?.get('userTier');
++     const userTier = context?.requestContext?.get('userTier');
+      return { result: userTier };
+    },
+  });
+```
+
+> **Codemod:** You can use Mastra's codemod CLI to update your imports automatically:
+>
+> ```bash
+> npx @mastra/codemod@latest v1/runtime-context .
+> ```
+
+This applies to all tool executions, whether called directly or through agents and workflows. The type narrowing ensures you handle validation errors appropriately and prevents runtime errors when accessing output properties.
+
+### Tool output validation with `outputSchema`
+
+Tools with an `outputSchema` now validate their return values at runtime. Previously, `outputSchema` was only used for type inference - the output was never validated.
+
+If your tool returns data that doesn't match its `outputSchema`, it will now return a `ValidationError` instead of the invalid data.
+
+To fix validation errors, ensure the tool's output matches the schema definition:
+
+```diff
+const getUserTool = createTool({
+    id: "get-user",
+    outputSchema: z.object({
+      id: z.string(),
+      name: z.string(),
+      email: z.string().email(),
+    }),
+    execute: async (inputData) => {
+-     return { id: "123", name: "John" }; // Missing email
++     return { id: "123", name: "John", email: "john@example.com" };
+    },
+  });
+```
+
+When validation fails, the tool returns a `ValidationError`:
+
+```diff
++ // Before v1 - invalid output would silently pass through
+  await getUserTool.execute({});
+- // { id: "123", name: "John" } - missing email
++ // {
++ //   error: true,
++ //   message: "Tool output validation failed for get-user. The tool returned invalid output:\n- email: Required\n\nReturned output: {...}",
++ //   validationErrors: { ... }
++ // }
+```
+
+### `tool.execute` return type includes `ValidationError`
+
+The return type of `tool.execute` now includes `ValidationError` to handle validation failures. You must narrow the result type before accessing output schema properties to satisfy TypeScript's type checking.
+
+When calling `tool.execute`, check if the result contains an error before accessing output properties:
+
+```typescript
+const result = await getUserTool.execute({})
+
+// Type-safe check for validation errors
+if ('error' in result && result.error) {
+  console.error('Validation failed:', result.message)
+  console.error('Details:', result.validationErrors)
+  return
+}
+
+// TypeScript knows result is valid here
+console.log(result.id, result.name, result.email)
+```
+
+Alternatively, update the `outputSchema` to match your actual output, or remove `outputSchema` entirely if you don't need validation.
+
+### Direct tool execution
+
+The `tool.execute` property is optional in the type system to support client-side tool definitions where execution logic is handled separately. When calling `execute` directly on a tool instance (rather than through agents or workflows), use optional chaining or non-null assertion:
+
+```typescript
+// Optional chaining (recommended)
+const result = await weatherTool.execute?.({ location: 'New York' }, {})
+
+// Non-null assertion (when you know execute exists)
+const result = await weatherTool.execute!({ location: 'New York' }, {})
+```

package/.docs/guides/migrations/upgrade-to-v1/tracing.md

@@ -0,0 +1,412 @@
+# Tracing
+
+The observability system has been restructured in v1 with a dedicated `@mastra/observability` package. This guide covers two migration paths depending on which version you're upgrading from.
+
+## Migration Paths
+
+### From OTEL-based Telemetry (0.x)
+
+If you're using the old `telemetry:` configuration in Mastra, the system has been completely redesigned.
+
+**Before (0.x with OTEL telemetry):**
+
+```typescript
+import { Mastra } from '@mastra/core'
+
+export const mastra = new Mastra({
+  telemetry: {
+    serviceName: 'my-app',
+    enabled: true,
+    sampling: {
+      type: 'always_on',
+    },
+    export: {
+      type: 'otlp',
+      endpoint: 'http://localhost:4318',
+    },
+  },
+})
+```
+
+**After (v1 with observability):**
+
+```typescript
+import { Mastra } from '@mastra/core'
+import {
+  Observability,
+  DefaultExporter,
+  CloudExporter,
+  SensitiveDataFilter,
+} from '@mastra/observability'
+
+export const mastra = new Mastra({
+  observability: new Observability({
+    configs: {
+      default: {
+        serviceName: 'mastra',
+        exporters: [
+          new DefaultExporter(), // Persists traces to storage for Mastra Studio
+          new CloudExporter(), // Sends traces to Mastra Cloud (if MASTRA_CLOUD_ACCESS_TOKEN is set)
+        ],
+        spanOutputProcessors: [
+          new SensitiveDataFilter(), // Redacts sensitive data like passwords, tokens, keys
+        ],
+      },
+    },
+  }),
+})
+```
+
+This configuration includes `DefaultExporter`, `CloudExporter`, and `SensitiveDataFilter` processor. See the [observability tracing documentation](https://mastra.ai/docs/observability/tracing/overview) for full configuration options.
+
+#### After (v1 with custom configuration)
+
+If you need to configure specific exporters (like OTLP), install the exporter package and configure it:
+
+**npm**:
+
+```bash
+npm install @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-proto
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-proto
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-proto
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-proto
+```
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { Observability } from '@mastra/observability'
+import { OtelExporter } from '@mastra/otel-exporter'
+
+export const mastra = new Mastra({
+  observability: new Observability({
+    configs: {
+      production: {
+        serviceName: 'my-app',
+        sampling: { type: 'always' },
+        exporters: [
+          new OtelExporter({
+            provider: {
+              custom: {
+                endpoint: 'http://localhost:4318/v1/traces',
+                protocol: 'http/protobuf',
+              },
+            },
+          }),
+        ],
+      },
+    },
+  }),
+})
+```
+
+Key changes:
+
+1. Install `@mastra/observability` package
+2. Replace `telemetry:` with `observability: new Observability()`
+3. Use explicit `configs:` with `DefaultExporter`, `CloudExporter`, and `SensitiveDataFilter`
+4. Export types change from string literals (`'otlp'`) to exporter class instances (`new OtelExporter()`)
+
+See the [exporters documentation](https://mastra.ai/docs/observability/tracing/overview) for all available exporters.
+
+### From AI Tracing
+
+If you already upgraded to AI tracing (the intermediate system), you need to install the new package and use the explicit configuration.
+
+**Before (AI tracing):**
+
+```typescript
+import { Mastra } from '@mastra/core'
+
+export const mastra = new Mastra({
+  observability: {
+    default: { enabled: true },
+  },
+})
+```
+
+**After (v1 observability):**
+
+```typescript
+import { Mastra } from '@mastra/core'
+import {
+  Observability,
+  DefaultExporter,
+  CloudExporter,
+  SensitiveDataFilter,
+} from '@mastra/observability'
+
+export const mastra = new Mastra({
+  observability: new Observability({
+    configs: {
+      default: {
+        serviceName: 'mastra',
+        exporters: [new DefaultExporter(), new CloudExporter()],
+        spanOutputProcessors: [new SensitiveDataFilter()],
+      },
+    },
+  }),
+})
+```
+
+Key changes:
+
+1. Install `@mastra/observability` package
+2. Import `Observability`, exporters, and processors from `@mastra/observability`
+3. Use explicit `configs` with `DefaultExporter`, `CloudExporter`, and `SensitiveDataFilter`
+
+## Changed
+
+### Package import path
+
+The observability functionality has moved to a dedicated `@mastra/observability` package.
+
+To migrate, install the package and update your import statements:
+
+**npm**:
+
+```bash
+npm install @mastra/observability@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/observability@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/observability@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/observability@latest
+```
+
+```diff
+- import { Tracing } from '@mastra/core/observability';
++ import { Observability } from '@mastra/observability';
+```
+
+### Registry configuration
+
+The observability registry is now configured using an `Observability` class instance with explicit configs instead of a plain object.
+
+To migrate, use `new Observability()` with explicit exporters and processors.
+
+```diff
++ import {
++   Observability,
++   DefaultExporter,
++   CloudExporter,
++   SensitiveDataFilter,
++ } from '@mastra/observability';
+
+  export const mastra = new Mastra({
+-   observability: {
+-     default: { enabled: true },
+-   },
++   observability: new Observability({
++     configs: {
++       default: {
++         serviceName: 'mastra',
++         exporters: [new DefaultExporter(), new CloudExporter()],
++         spanOutputProcessors: [new SensitiveDataFilter()],
++       },
++     },
++   }),
+  });
+```
+
+### Configuration property `processors` to `spanOutputProcessors`
+
+The configuration property for span processors has been renamed from `processors` to `spanOutputProcessors`.
+
+To migrate, rename the property in your configuration objects.
+
+```diff
++ import { SensitiveDataFilter } from '@mastra/observability';
+
+  export const mastra = new Mastra({
+    observability: new Observability({
+      configs: {
+        production: {
+          serviceName: 'my-app',
+-         processors: [new SensitiveDataFilter()],
++         spanOutputProcessors: [new SensitiveDataFilter()],
+          exporters: [...],
+        },
+      },
+    }),
+  });
+```
+
+### Exporter method `exportEvent` to `exportTracingEvent`
+
+If you built custom exporters, the exporter method has been renamed from `exportEvent` to `exportTracingEvent`.
+
+To migrate, update method implementations in custom exporters.
+
+```diff
+export class MyExporter implements ObservabilityExporter {
+-   exportEvent(event: TracingEvent): void {
++   exportTracingEvent(event: TracingEvent): void {
+      // export logic
+    }
+  }
+```
+
+## Removed
+
+### OTEL-based `telemetry` configuration
+
+The OTEL-based `telemetry` configuration from 0.x has been removed. The old system with `serviceName`, `sampling.type`, and `export.type` properties is no longer supported.
+
+To migrate, follow the "From OTEL-based Telemetry" section above. For detailed configuration options, see the [observability tracing documentation](https://mastra.ai/docs/observability/tracing/overview).
+
+### Custom instrumentation files
+
+The automatic detection of instrumentation files in `/mastra` (with `.ts`, `.js`, or `.mjs` extensions) has been removed. Custom instrumentation is no longer supported through separate files.
+
+To migrate, use the built-in exporter system or implement custom exporters using the `ObservabilityExporter` interface. See the [exporters documentation](https://mastra.ai/docs/observability/tracing/overview) for details.
+
+### `instrumentation.mjs` files
+
+If you were using `instrumentation.mjs` files to initialize OpenTelemetry instrumentation (common in deployment setups like AWS Lambda), these are no longer needed. The new observability system is configured directly in your Mastra instance.
+
+#### Before (0.x)
+
+You needed an instrumentation file:
+
+```javascript
+// instrumentation.mjs
+import { NodeSDK } from '@opentelemetry/sdk-node'
+// ... OTEL setup
+```
+
+And had to import it when starting your process:
+
+```bash
+node --import=./.mastra/output/instrumentation.mjs --env-file=".env" .mastra/output/index.mjs
+```
+
+#### After (v1)
+
+Simply remove the `instrumentation.mjs` file and configure observability in your Mastra instance:
+
+```typescript
+// src/mastra/index.ts
+import {
+  Observability,
+  DefaultExporter,
+  CloudExporter,
+  SensitiveDataFilter,
+} from '@mastra/observability'
+
+export const mastra = new Mastra({
+  observability: new Observability({
+    configs: {
+      default: {
+        serviceName: 'mastra',
+        exporters: [new DefaultExporter(), new CloudExporter()],
+        spanOutputProcessors: [new SensitiveDataFilter()],
+      },
+    },
+  }),
+})
+```
+
+Start your process normally without the `--import` flag:
+
+```bash
+node --env-file=".env" .mastra/output/index.mjs
+```
+
+No separate instrumentation files or special startup flags required.
+
+## Provider Migration Reference
+
+If you were using OTEL-based telemetry with specific providers in 0.x, here's how to configure them in v1:
+
+| Provider                                                  | Exporter          | Guide                                                                      | Reference                                                                           |
+| --------------------------------------------------------- | ----------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| Arize AX, Arize Phoenix                                   | **Arize**         | [Guide](https://mastra.ai/docs/observability/tracing/exporters/arize)      | [Reference](https://mastra.ai/reference/observability/tracing/exporters/arize)      |
+| Braintrust                                                | **Braintrust**    | [Guide](https://mastra.ai/docs/observability/tracing/exporters/braintrust) | [Reference](https://mastra.ai/reference/observability/tracing/exporters/braintrust) |
+| Langfuse                                                  | **Langfuse**      | [Guide](https://mastra.ai/docs/observability/tracing/exporters/langfuse)   | [Reference](https://mastra.ai/reference/observability/tracing/exporters/langfuse)   |
+| LangSmith                                                 | **LangSmith**     | [Guide](https://mastra.ai/docs/observability/tracing/exporters/langsmith)  | [Reference](https://mastra.ai/reference/observability/tracing/exporters/langsmith)  |
+| Dash0, Laminar, New Relic, SigNoz, Traceloop, Custom OTEL | **OpenTelemetry** | [Guide](https://mastra.ai/docs/observability/tracing/exporters/otel)       | [Reference](https://mastra.ai/reference/observability/tracing/exporters/otel)       |
+| LangWatch                                                 | \<coming soon>    | -                                                                          | -                                                                                   |
+
+### Installation
+
+**Dedicated exporters** (Arize, Braintrust, Langfuse, LangSmith):
+
+**npm**:
+
+```bash
+npm install @mastra/[exporter-name]-exporter
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/[exporter-name]-exporter
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/[exporter-name]-exporter
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/[exporter-name]-exporter
+```
+
+**OpenTelemetry exporter** (Dash0, Laminar, New Relic, SigNoz, Traceloop):
+
+**npm**:
+
+```bash
+npm install @mastra/otel-exporter@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/otel-exporter@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/otel-exporter@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/otel-exporter@latest
+```
+
+Plus the required protocol package for your provider (see [OTEL guide](https://mastra.ai/docs/observability/tracing/exporters/otel)).

package/.docs/guides/migrations/upgrade-to-v1/vectors.md

@@ -0,0 +1,87 @@
+# Vectors
+
+Vector store constructors now require an `id` property, and vector store methods have been renamed to follow consistent naming conventions.
+
+## Changed
+
+### Required `id` property for vector store instances
+
+Vector store instances now require an `id` property. This unique identifier is used for tracking and managing vector store instances within Mastra. The `id` should be a descriptive, unique string for each vector store in your application.
+
+To migrate, add an `id` field to your vector store constructor.
+
+```diff
+const vectorStore = new PgVector({
++   id: 'main-vector-store',
+    connectionString: process.env.POSTGRES_CONNECTION_STRING,
+  });
+
+  const chromaStore = new ChromaVector({
++   id: 'chroma-embeddings',
+    url: process.env.CHROMA_URL,
+  });
+
+  const pineconeStore = new PineconeVector({
++   id: 'pinecone-production',
+    apiKey: process.env.PINECONE_API_KEY,
+  });
+```
+
+### `getVectors` to `listVectors`
+
+The `getVectors()` method has been renamed to `listVectors()`. This change aligns with the naming convention used across the API where plural getter methods use the `list` prefix.
+
+To migrate, replace all calls to `getVectors()` with `listVectors()`.
+
+```diff
+const vectorStore = new VectorStore({ ... });
+
+- const vectors = await vectorStore.getVectors({ ... });
++ const vectors = await vectorStore.listVectors({ ... });
+```
+
+### LibSQLVector: `connectionUrl` to `url`
+
+The `connectionUrl` parameter has been renamed to `url` to align with the `@libsql/client` API and match LibSQLStorage.
+
+```diff
+const vectorStore = new LibSQLVector({
+    id: 'my-vector',
+-   connectionUrl: 'file:./db.sqlite',
++   url: 'file:./db.sqlite',
+  });
+```
+
+### OpenSearchVector: `url` to `node`
+
+The `url` parameter has been renamed to `node` to match the OpenSearch `ClientOptions` API. The constructor now accepts all OpenSearch client options including authentication, SSL, and compression.
+
+```diff
+const vectorStore = new OpenSearchVector({
+    id: 'my-vector',
+-   url: 'http://localhost:9200',
++   node: 'http://localhost:9200',
+  });
+```
+
+### PineconeVector: `environment` removed
+
+The `environment` parameter has been removed. Use `controllerHostUrl` instead if you need to specify a custom controller host. The constructor now accepts all Pinecone configuration options.
+
+```diff
+const vectorStore = new PineconeVector({
+    id: 'my-vector',
+    apiKey: process.env.PINECONE_API_KEY,
+-   environment: process.env.PINECONE_ENVIRONMENT,
+  });
+```
+
+If you need a custom controller host:
+
+```ts
+const vectorStore = new PineconeVector({
+  id: 'my-vector',
+  apiKey: process.env.PINECONE_API_KEY,
+  controllerHostUrl: 'https://api.pinecone.io',
+})
+```

package/.docs/guides/migrations/upgrade-to-v1/voice.md

@@ -0,0 +1,30 @@
+# Voice Packages
+
+Voice packages have been renamed from speech to voice with updated class names and API methods.
+
+## Changed
+
+### Voice configuration property names
+
+Voice configuration properties have been renamed for consistency. `speakProvider` is now `output`, `listenProvider` is now `input`, and `realtimeProvider` is now `realtime`. This change provides more intuitive property names.
+
+To migrate, update configuration property names when configuring agents with voice capabilities.
+
+```diff
+const agent = new Agent({
+    voice: {
+-     speakProvider: murfVoice,
+-     listenProvider: deepgramVoice,
+-     realtimeProvider: openaiRealtime,
++     output: murfVoice,
++     input: deepgramVoice,
++     realtime: openaiRealtime,
+    },
+  });
+```
+
+> **Codemod:** You can use Mastra's codemod CLI to update your code automatically:
+>
+> ```bash
+> npx @mastra/codemod@latest v1/voice-property-names .
+> ```