@mastra/mcp-docs-server 0.13.39 → 1.0.0-beta.0

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

@@ -0,0 +1,270 @@
+---
+title: "Storage | v1 Migration Guide"
+description: "Learn how to migrate storage-related changes when upgrading to v1."
+---
+
+# Storage
+
+Storage APIs have been standardized with consistent pagination and naming patterns across all methods.
+
+## Changed
+
+### Pagination from `offset/limit` to `page/perPage`
+
+All pagination APIs now use `page` and `perPage` instead of `offset` and `limit`. This change provides a more intuitive pagination model that aligns with common web pagination patterns.
+
+To migrate, update all pagination parameters from `offset/limit` to `page/perPage`. Note that `page` is 0-indexed.
+
+```diff
+  storage.listMessages({
+    threadId: 'thread-123',
+-   offset: 0,
+-   limit: 20,
++   page: 0,
++   perPage: 20,
+  });
+```
+
+### `getMessagesPaginated` to `listMessages`
+
+The `getMessagesPaginated()` method has been replaced with `listMessages()`. The new method supports `perPage: false` to fetch all records without pagination. This change aligns with the `list*` naming convention and adds flexibility for fetching all records.
+
+To migrate, rename the method and update pagination parameters. You can now use `perPage: false` to fetch all records.
+
+```diff
+  // Paginated
+- const result = await storage.getMessagesPaginated({
++ const result = await storage.listMessages({
+    threadId: 'thread-123',
+-   offset: 0,
+-   limit: 20,
++   page: 0,
++   perPage: 20,
+  });
+  
+  // Fetch all records (no pagination limit)
++ const allMessages = await storage.listMessages({
++   threadId: 'thread-123',
++   page: 0,
++   perPage: false,
++ });
+```
+
+### `getThreadsByResourceId` to `listThreadsByResourceId`
+
+The `getThreadsByResourceId()` method has been renamed to `listThreadsByResourceId()`. This change aligns with the convention that `list*` methods return collections.
+
+To migrate, rename the method call and update pagination parameters.
+
+```diff
+- const threads = await storage.getThreadsByResourceId({
++ const threads = await storage.listThreadsByResourceId({
+    resourceId: 'res-123',
++   page: 0,
++   perPage: 20,
+  });
+```
+
+### `getWorkflowRuns` to `listWorkflowRuns`
+
+The `getWorkflowRuns()` method has been renamed to `listWorkflowRuns()`. This change aligns with the convention that `list*` methods return collections.
+
+To migrate, rename the method call and update pagination parameters.
+
+```diff
+- const runs = await storage.getWorkflowRuns({
++ const runs = await storage.listWorkflowRuns({
+    fromDate,
+    toDate,
++   page: 0,
++   perPage: 20,
+  });
+```
+
+### `getMessagesById` to `listMessagesById`
+
+The `getMessagesById()` method has been renamed to `listMessagesById()`. This change aligns with the convention that `list*` methods return collections.
+
+To migrate, rename the method call.
+
+```diff
+- const result = await storage.getMessagesById({
++ const result = await storage.listMessagesById({
+    messageIds: ['msg-1', 'msg-2'],
+  });
+```
+
+### Storage `getMessages` and `saveMessages` signatures
+
+The `getMessages()` and `saveMessages()` methods have changed signatures and return types. Format overloads have been removed, and the methods now always work with `MastraDBMessage`. This change simplifies the API by removing format variations.
+
+To migrate, remove format parameters and update code to work with the consistent return type.
+
+```diff
+  // Always returns { messages: MastraDBMessage[] }
+- const v1Messages = await storage.getMessages({ threadId, format: 'v1' });
+- const v2Messages = await storage.getMessages({ threadId, format: 'v2' });
++ const result = await storage.getMessages({ threadId });
++ const messages = result.messages; // MastraDBMessage[]
+  
+  // SaveMessages always uses MastraDBMessage
+- await storage.saveMessages({ messages: v1Messages, format: 'v1' });
+- await storage.saveMessages({ messages: v2Messages, format: 'v2' });
++ const result = await storage.saveMessages({ messages: mastraDBMessages });
++ const saved = result.messages; // MastraDBMessage[]
+```
+
+### Vector store API from positional to named arguments
+
+All vector store methods now use named arguments instead of positional arguments. This change improves code readability and makes method signatures more maintainable.
+
+To migrate, update all vector store method calls to use named arguments.
+
+```diff
+- await vectorDB.createIndex(indexName, 3, 'cosine');
++ await vectorDB.createIndex({
++   indexName: indexName,
++   dimension: 3,
++   metric: 'cosine',
++ });
+
+- await vectorDB.upsert(indexName, [[1, 2, 3]], [{ test: 'data' }]);
++ await vectorDB.upsert({
++   indexName: indexName,
++   vectors: [[1, 2, 3]],
++   metadata: [{ test: 'data' }],
++ });
+
+- await vectorDB.query(indexName, [1, 2, 3], 5);
++ await vectorDB.query({
++   indexName: indexName,
++   queryVector: [1, 2, 3],
++   topK: 5,
++ });
+```
+
+### Vector store method renames
+
+The `updateIndexById` and `deleteIndexById` methods have been renamed to `updateVector` and `deleteVector` respectively. This change provides clearer naming that better describes the operations.
+
+To migrate, rename the methods and use named arguments.
+
+```diff
+- await vectorDB.updateIndexById(indexName, id, update);
+- await vectorDB.deleteIndexById(indexName, id);
++ await vectorDB.updateVector({ indexName, id, update });
++ await vectorDB.deleteVector({ indexName, id });
+```
+
+### PGVector constructor from connection string to object
+
+The PGVector constructor now requires object parameters instead of a connection string. This change provides a more consistent API across all storage adapters.
+
+To migrate, pass the connection string as an object property.
+
+```diff
+- const pgVector = new PgVector(process.env.POSTGRES_CONNECTION_STRING!);
++ const pgVector = new PgVector({
++   connectionString: process.env.POSTGRES_CONNECTION_STRING,
++ });
+```
+
+### PGVector `defineIndex` to `buildIndex`
+
+The `defineIndex()` method has been removed in favor of `buildIndex()`. This change provides clearer naming for the index building operation.
+
+To migrate, rename the method and use named arguments.
+
+```diff
+- await vectorDB.defineIndex(indexName, 'cosine', { type: 'flat' });
++ await vectorDB.buildIndex({
++   indexName: indexName,
++   metric: 'cosine',
++   indexConfig: { type: 'flat' },
++ });
+```
+
+### PostgresStore `schema` to `schemaName`
+
+The `schema` parameter has been renamed to `schemaName` in the PostgresStore constructor. This change provides clearer naming to avoid confusion with database schema concepts.
+
+To migrate, rename the parameter.
+
+```diff
+  const pgStore = new PostgresStore({
+    connectionString: process.env.POSTGRES_CONNECTION_STRING,
+-   schema: customSchema,
++   schemaName: customSchema,
+  });
+```
+
+### Score storage methods to `listScoresBy*` pattern
+
+Score storage APIs have been renamed to follow the `listScoresBy*` pattern. This change provides consistency with the broader API naming conventions.
+
+To migrate, update method names from `getScores` to `listScoresByScorerId` and related variants.
+
+```diff
+- const scores = await storage.getScores({ scorerName: 'helpfulness-scorer' });
++ const scores = await storage.listScoresByScorerId({
++   scorerId: 'helpfulness-scorer',
++ });
++ // Also available: listScoresByRunId, listScoresByEntityId, listScoresBySpan
+```
+
+## Removed
+
+### Non-paginated storage functions
+
+Non-paginated storage functions have been removed in favor of paginated versions. All list operations now use pagination, though you can fetch all records with `perPage: false`. This change provides consistency across the API and prevents accidental loading of large datasets.
+
+To migrate, use paginated methods. For fetching all records, use `perPage: false`.
+
+```diff
+- // Non-paginated direct access
+- const messages = await storage.getMessages({ threadId });
+
++ // Use paginated methods
++ const result = await storage.listMessages({ threadId, page: 0, perPage: 20 });
++ // Or fetch all
++ const allMessages = await storage.listMessages({
++   threadId,
++   page: 0,
++   perPage: false,
++ });
+```
+
+### `getTraces` and `getTracesPaginated`
+
+The `getTraces()` and `getTracesPaginated()` methods have been removed from storage. Traces are now handled through the observability package rather than core storage. This change provides better separation of concerns between core storage and observability features.
+
+To migrate, use observability storage methods instead.
+
+```diff
+- const traces = await storage.getTraces({ traceId: 'trace-123' });
+- const paginated = await storage.getTracesPaginated({ page: 0, perPage: 20 });
+
++ // Use observability API for traces
++ import { initObservability } from '@mastra/observability';
++ const observability = initObservability({ config: { ... } });
++ // Access traces through observability API
+```
+
+### Evals test utilities
+
+Evals domain test utilities have been removed from `@internal/test-utils`. This change reflects the removal of legacy evals functionality.
+
+To migrate, use storage APIs directly for testing instead of specialized evals test utilities.
+
+```diff
+- import { createEvalsTests } from '@internal/test-utils/domains/evals';
+- createEvalsTests({ storage });
+
++ // Use storage APIs directly for testing
+```
+
+### TABLE_EVALS from MSSQL storage
+
+The `TABLE_EVALS` table has been removed from MSSQL storage implementations. This change reflects the removal of legacy evals functionality.
+
+If you were using MSSQL storage with evals, migrate to a different storage adapter or remove evals functionality.

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

@@ -0,0 +1,115 @@
+---
+title: "Tools | v1 Migration Guide"
+description: "Learn how to migrate tool-related changes when upgrading to v1."
+---
+
+# 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' };
++   },
+  });
+```
+
+:::note
+For MCP-specific tool context changes, see the [MCP migration guide]/guides/v1/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 };
+    },
+  });
+```
+
+:::tip[Codemod]
+
+You can use Mastra's codemod CLI to update your imports automatically:
+
+```shell
+npx @mastra/codemod v1/runtime-context .
+```
+
+:::

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

@@ -0,0 +1,280 @@
+---
+title: "Tracing | v1 Migration Guide"
+description: "Migration guide for updating from otel-telemetry or AI tracing to the new observability system."
+---
+
+# 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 - quick start):**
+
+```typescript
+import { Mastra } from '@mastra/core';
+import { Observability } from '@mastra/observability';
+
+export const mastra = new Mastra({
+  observability: new Observability({
+    default: { enabled: true },
+  }),
+});
+```
+
+This minimal configuration automatically includes the `DefaultExporter`, `CloudExporter`, and `SensitiveDataFilter` processor. See the [observability tracing documentation]/docs/v1/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:
+
+```bash
+npm install @mastra/otel-exporter @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 `default: { enabled: true }` for quick setup, or `configs:` for custom configuration
+4. Export types change from string literals (`'otlp'`) to exporter class instances (`new OtelExporter()`)
+
+See the [exporters documentation]/docs/v1/observability/tracing/overview#exporters) for all available exporters.
+
+### From AI Tracing
+
+If you already upgraded to AI tracing (the intermediate system), you only need to wrap your configuration and install the new package.
+
+**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 } from '@mastra/observability';
+
+export const mastra = new Mastra({
+  observability: new Observability({
+    default: { enabled: true },
+  }),
+});
+```
+
+Key changes:
+1. Install `@mastra/observability` package
+2. Import `Observability` from `@mastra/observability`
+3. Wrap configuration with `new Observability()`
+
+## 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:
+
+```bash
+npm install @mastra/observability
+```
+
+```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 instead of a plain object.
+
+To migrate, wrap your configuration object with `new Observability()`.
+
+```diff
++ import { Observability } from '@mastra/observability';
+
+  export const mastra = new Mastra({
+-   observability: {
++   observability: new Observability({
+      default: { enabled: true },
+-   },
++   }),
+  });
+```
+
+### 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]/docs/v1/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]/docs/v1/observability/tracing/overview#exporters) 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 } from '@mastra/observability';
+
+export const mastra = new Mastra({
+  observability: new Observability({
+    default: { enabled: true },
+  }),
+});
+```
+
+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]/docs/v1/observability/tracing/exporters/arize) | [Reference]/reference/v1/observability/tracing/exporters/arize) |
+| Braintrust | **Braintrust** | [Guide]/docs/v1/observability/tracing/exporters/braintrust) | [Reference]/reference/v1/observability/tracing/exporters/braintrust) |
+| Langfuse | **Langfuse** | [Guide]/docs/v1/observability/tracing/exporters/langfuse) | [Reference]/reference/v1/observability/tracing/exporters/langfuse) |
+| LangSmith | **LangSmith** | [Guide]/docs/v1/observability/tracing/exporters/langsmith) | [Reference]/reference/v1/observability/tracing/exporters/langsmith) |
+| Dash0, Laminar, New Relic, SigNoz, Traceloop, Custom OTEL | **OpenTelemetry** | [Guide]/docs/v1/observability/tracing/exporters/otel) | [Reference]/reference/v1/observability/tracing/exporters/otel) |
+| LangWatch | \<coming soon\> | - | - |
+
+### Installation
+
+**Dedicated exporters** (Arize, Braintrust, Langfuse, LangSmith):
+```bash
+npm install @mastra/[exporter-name]-exporter
+```
+
+**OpenTelemetry exporter** (Dash0, Laminar, New Relic, SigNoz, Traceloop):
+```bash
+npm install @mastra/otel-exporter
+```
+
+Plus the required protocol package for your provider (see [OTEL guide]/docs/v1/observability/tracing/exporters/otel#installation)).

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

@@ -0,0 +1,23 @@
+---
+title: "Vectors | v1 Migration Guide"
+description: "Learn how to migrate vector-related changes when upgrading to v1."
+---
+
+# Vectors
+
+Vector store methods have been renamed to follow consistent naming conventions.
+
+## Changed
+
+### `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({ ... });
+```