@mastra/mcp-docs-server 1.1.4 → 1.1.5

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

@@ -1,337 +0,0 @@
-# Client SDK
-
-Client SDK changes align with server-side API updates including renamed utilities, updated pagination, and type naming conventions.
-
-## Changed
-
-### `messages` is now identical to `@mastra/core/agent` syntax
-
-The `messages` argument is now the first argument of the `generate`, `stream` and `network` method calls, similar to the NodeJS version in `@mastra/core/agent`.
-
-To migrate, move `messages` to the first argument of the method call:
-
-**Using `@mastra/client-js`:**
-
-```diff
-const agent = client.getAgent('my-agent');
-
--  await agent.generate({
--    messages: [...]
-+  await agent.generate([...], {
-  });
-
--  await agent.stream({
--    messages: [...]
-+  await agent.stream([...], {
-  });
-
--  await agent.network({
--    messages: [...]
-+  await agent.network([...], {
-  });
-```
-
-> **Codemod:** You can use Mastra's codemod CLI to update your code automatically:
->
-> ```bash
-> npx @mastra/codemod@beta v1/client-msg-function-args .
-> ```
-
-### `threadId` and `resourceId` to `memory` option
-
-The `threadId` and `resourceId` options have been removed from agent method calls. Use the `memory` option instead, which provides a cleaner API for memory configuration. This applies to both `@mastra/client-js` and `@mastra/react` packages.
-
-To migrate, move `threadId` and `resourceId` into the `memory` option:
-
-**Using `@mastra/client-js`:**
-
-```diff
-const agent = client.getAgent('my-agent');
-
-  await agent.generate([...], {
--   threadId: 'thread-123',
--   resourceId: 'user-456',
-+   memory: {
-+     thread: 'thread-123',
-+     resource: 'user-456',
-+   },
-  });
-
-+  await agent.stream([...], {
--   threadId: 'thread-123',
--   resourceId: 'user-456',
-+   memory: {
-+     thread: 'thread-123',
-+     resource: 'user-456',
-+   },
-  });
-```
-
-**Using `@mastra/react` `useChat` hook:**
-
-The `useChat` hook internally passes the memory option when you provide a `threadId`. No changes are needed in your component code if you're using the hook's built-in memory handling. However, if you were manually passing options to `sendMessage`, update them accordingly:
-
-```diff
-const { sendMessage } = useChat({ agentId: 'my-agent' });
-
-  await sendMessage({
-    message: 'Hello',
-    mode: 'stream',
--   threadId: 'thread-123',
-+   threadId: 'thread-123', // Still works - internally converted to memory option
-  });
-```
-
-The `memory` option also supports passing thread metadata when creating new threads:
-
-```typescript
-await agent.generate([...], {
-  memory: {
-    thread: {
-      id: 'thread-123',
-      title: 'Support conversation',
-      metadata: { category: 'billing' },
-    },
-    resource: 'user-456',
-  },
-});
-```
-
-### Client SDK types from `Get*` to `List*`
-
-Client SDK types have been renamed from `Get*` to `List*` pattern. This change aligns type names with the method naming convention.
-
-To migrate, update type imports to use the new naming pattern.
-
-```diff
-- import type {
--   GetWorkflowRunsParams,
--   GetWorkflowRunsResponse,
--   GetMemoryThreadParams,
-- } from '@mastra/client-js';
-+ import type {
-+   ListWorkflowRunsParams,
-+   ListWorkflowRunsResponse,
-+   ListMemoryThreadsParams,
-+ } from '@mastra/client-js';
-```
-
-> **Codemod:** You can use Mastra's codemod CLI to update your code automatically:
->
-> ```bash
-> npx @mastra/codemod@latest v1/client-sdk-types .
-> ```
-
-### Pagination parameters from `offset/limit` to `page/perPage`
-
-All client SDK methods that used `offset/limit` now use `page/perPage`. This change provides a more intuitive pagination model aligned with web pagination patterns.
-
-To migrate, update pagination parameters in all client SDK method calls. Example:
-
-```diff
-client.memory.listMessages({
-    threadId: 'thread-123',
--   offset: 0,
--   limit: 20,
-+   page: 0,
-+   perPage: 20,
-  });
-```
-
-> **Codemod:** You can use Mastra's codemod CLI to update your code automatically:
->
-> ```bash
-> npx @mastra/codemod@latest v1/client-offset-limit .
-> ```
-
-### `getMemoryThread` parameter structure
-
-The `getMemoryThread` method parameter structure has been updated. This change provides a more consistent API across memory methods.
-
-To migrate, update the method call with the new parameter structure. Check the updated API documentation for the specific changes.
-
-```diff
-- const thread = await client.getMemoryThread(threadId, agentId);
-+ const thread = await client.getMemoryThread({ threadId, agentId });
-```
-
-> **Codemod:** You can use Mastra's codemod CLI to update your code automatically:
->
-> ```bash
-> npx @mastra/codemod@latest v1/client-get-memory-thread .
-> ```
-
-### Unified `runById` API for workflow runs
-
-The `runById()` method now returns a unified `WorkflowState` object containing both metadata (runId, workflowName, resourceId, createdAt, updatedAt) and processed execution state (status, result, error, payload, steps). This unifies the previously separate `runById()` and `runExecutionResult()` methods.
-
-The method also accepts an options object with optional `fields` and `withNestedWorkflows` parameters for performance optimization.
-
-```diff
-const workflow = client.getWorkflow('my-workflow');
-
-- // Previously: runById returned raw WorkflowRun with snapshot
-- const run = await workflow.runById(runId, requestContext);
-- // Separately: runExecutionResult returned processed execution state
-- const result = await workflow.runExecutionResult(runId);
-
-+ // Now: Single method returns unified WorkflowState
-+ const run = await workflow.runById(runId, {
-+   requestContext,  // Optional request context
-+   fields: ['status', 'result'],  // Optional: request only specific fields
-+   withNestedWorkflows: false,  // Optional: skip nested workflow data for performance
-+ });
-+ // Returns: { runId, workflowName, resourceId, createdAt, updatedAt, status, result, error, payload, steps }
-```
-
-## Removed
-
-### `runExecutionResult` method and `GetWorkflowRunExecutionResultResponse` type
-
-The `runExecutionResult()` method and `GetWorkflowRunExecutionResultResponse` type have been removed from `@mastra/client-js`. The `/execution-result` API endpoints have also been removed.
-
-To migrate, use `runById()` instead, which now returns the same unified `WorkflowState` with both metadata and processed execution state.
-
-```diff
-- import type { GetWorkflowRunExecutionResultResponse } from '@mastra/client-js';
--
-- const workflow = client.getWorkflow('my-workflow');
-- const result = await workflow.runExecutionResult(runId);
-
-+ const workflow = client.getWorkflow('my-workflow');
-+ const result = await workflow.runById(runId);
-+ // Or with options for performance optimization:
-+ const result = await workflow.runById(runId, {
-+   fields: ['status', 'result'],  // Only fetch specific fields
-+   withNestedWorkflows: false,     // Skip expensive nested workflow data
-+ });
-```
-
-### `toAISdkFormat` function
-
-The `toAISdkFormat()` function has been removed from `@mastra/ai-sdk`. This change provides clearer naming for stream conversion utilities.
-
-To migrate, use `toAISdkStream()` instead.
-
-```diff
-- import { toAISdkFormat } from '@mastra/ai-sdk';
-- const stream = toAISdkFormat(agentStream, { from: 'agent' });
-+ import { toAISdkStream } from '@mastra/ai-sdk';
-+ const stream = toAISdkStream(agentStream, { from: 'agent' });
-```
-
-> **Codemod:** You can use Mastra's codemod CLI to update your code automatically:
->
-> ```bash
-> npx @mastra/codemod@latest v1/client-to-ai-sdk-format .
-> ```
-
-### Network memory methods
-
-Network memory methods have been removed from `@mastra/client-js`. The `NetworkMemoryThread` class and all network memory-related methods are no longer available. This change simplifies the memory API by removing specialized network memory functionality.
-
-To migrate, use regular memory APIs instead of network memory.
-
-```diff
-- import { MastraClient } from '@mastra/client-js';
--
-- const client = new MastraClient({ baseUrl: '...' });
-- const networkThread = client.networkMemory.getThread('thread-id');
-- const networkThread = client.memory.networkThread('thread-id', 'network-id');
-- await networkThread.get();
-- await networkThread.getMessages();
-
-+ // Use regular memory thread APIs instead
-+ const client = new MastraClient({ baseUrl: '...' });
-+ const thread = client.memory.getThread('thread-id');
-+ await thread.get();
-+ const messages = await thread.listMessages();
-```
-
-### Watch-related types
-
-Watch-related types have been removed from `@mastra/client-js`. This includes `WorkflowWatchResult`, `WatchEvent`, and related types. This change reflects the removal of the watch API in favor of streaming.
-
-To migrate, use workflow streaming APIs instead of watch.
-
-```diff
-- import type { WorkflowWatchResult, WatchEvent } from '@mastra/client-js';
--
-- const workflow = client.getWorkflow('my-workflow');
-- const run = await workflow.createRun();
-- await run.watch((event: WatchEvent) => {
--   console.log('Event:', event);
-- });
-
-+ const workflow = client.getWorkflow('my-workflow');
-+ const run = await workflow.createRun();
-+ const stream = await run.stream({ inputData: { ... } });
-+ for await (const chunk of stream) {
-+   console.log('Event:', chunk);
-+ }
-```
-
-### Run-related methods cannot be called directly on workflow instance
-
-Run-related methods cannot be called directly on workflow instance. You need to create a run instance first using `createRun()` method.
-
-```diff
-- const result = await workflow.start({ runId: '123', inputData: { ... } });
-+ const run = await workflow.createRun({ runId: '123' });
-+ const result = await run.start({ inputData: { ... } });
-```
-
-```diff
-- const result = await workflow.stream({ runId: '123', inputData: { ... } });
-+ const run = await workflow.createRun({ runId: '123' });
-+ const stream = await run.stream({ inputData: { ... } });
-```
-
-### `streamVNext`, `resumeStreamVNext`, and `observeStreamVNext` methods
-
-The experimental `streamVNext()`, `resumeStreamVNext()`, and `observeStreamVNext()` methods have been removed. These methods are now the standard implementation with updated event structures and return types.
-
-To migrate, use the standard `stream()`, `resumeStream()`, and `observeStream()` methods instead.
-
-```diff
-+ const run = await workflow.createRun({ runId: '123' });
-- const stream = await run.streamVNext({ inputData: { ... } });
-+ const stream = await run.stream({ inputData: { ... } });
-```
-
-### Deprecated stream endpoints
-
-Some stream endpoints are deprecated and will be removed. The `/api/agents/:agentId/stream/vnext` endpoint returns 410 Gone, and `/api/agents/:agentId/stream/ui` is deprecated. This change consolidates on standard streaming endpoints.
-
-To migrate, use the standard stream endpoint or `@mastra/ai-sdk` for UI message transformations.
-
-```diff
-- const response = await fetch('/api/agents/my-agent/stream/vnext', {
--   method: 'POST',
--   body: JSON.stringify({ messages: [...] }),
-- });
-
-+ const response = await fetch('/api/agents/my-agent/stream', {
-+   method: 'POST',
-+   body: JSON.stringify({ messages: [...] }),
-+ });
-+
-+ // Or use @mastra/ai-sdk for UI message transformations
-```
-
-### Network memory API endpoints
-
-Network memory API endpoints have been removed including `/api/memory/network/*`. This change simplifies the memory API surface.
-
-To migrate, use regular memory API endpoints.
-
-```diff
-- const networkThread = await fetch('/api/memory/network/threads/thread-123');
-+ const thread = await fetch('/api/memory/threads/thread-123');
-```
-
-### Eval-related client SDK types
-
-Several eval-related types have been removed from the client SDK including `GetEvalsByAgentIdResponse`, `GetTelemetryResponse`, and `GetTelemetryParams`. This change reflects the removal of legacy evals functionality.
-
-To migrate, use the new scorers API instead of legacy evals.

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

@@ -1,37 +0,0 @@
-# Deployment
-
-The `CloudflareDeployer` configuration has been updated to use standard `wrangler.json` property names.
-
-## Changed
-
-### CloudflareDeployer uses standard wrangler.json property names
-
-The `CloudflareDeployer` constructor now accepts standard `wrangler.json` property names instead of custom camelCase variants. This change aligns the deployer with Cloudflare's official configuration format and provides access to all wrangler configuration options.
-
-Deprecated fields are automatically migrated at runtime with console warnings, but you should update your code to use the new field names.
-
-```diff
-const deployer = new CloudflareDeployer({
--   projectName: 'my-worker',
-+   name: 'my-worker',
--   d1Databases: [
-+   d1_databases: [
-      {
-        binding: 'DB',
-        database_name: 'my-db',
-        database_id: 'xxx',
-      },
-    ],
--   kvNamespaces: [
-+   kv_namespaces: [
-      {
-        binding: 'KV',
-        id: 'yyy',
-      },
-    ],
-  });
-```
-
-The `workerNamespace` field has been removed as it is no longer used.
-
-For all available configuration options, see the [Wrangler configuration documentation](https://developers.cloudflare.com/workers/wrangler/configuration/).

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

@@ -1,239 +0,0 @@
-# Evals & Scorers
-
-The evaluation API has been consolidated on the new scorers system with updated naming conventions and configuration requirements.
-
-## Changed
-
-### `getScorers` to `listScorers`
-
-The `getScorers()` method has been renamed to `listScorers()`. 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 `getScorers()` with `listScorers()`.
-
-```diff
-- const scorers = mastra.getScorers();
-+ const scorers = mastra.listScorers();
-```
-
-> **Codemod:** You can use Mastra's codemod CLI to update your code automatically:
->
-> ```bash
-> npx @mastra/codemod@latest v1/mastra-plural-apis .
-> ```
-
-### `runExperiment` to `runEvals`
-
-The `runExperiment()` function has been renamed to `runEvals()`. This change provides clearer naming that better describes the evaluation functionality.
-
-To migrate, update function calls from `runExperiment` to `runEvals`.
-
-```diff
-- import { createScorer, runExperiment } from '@mastra/core/evals';
-+ import { createScorer, runEvals } from '@mastra/core/evals';
-  import { myAgent } from './agents/my-agent';
-
-  const scorer = createScorer({
-    id: 'helpfulness-scorer',
-    // ...
-  });
-
-- const result = await runExperiment({ target: myAgent, scorers: [scorer], data: inputs });
-+ const result = await runEvals({ target: myAgent, scorers: [scorer], data: inputs });
-```
-
-> **Codemod:** You can use Mastra's codemod CLI to update your code automatically:
->
-> ```bash
-> npx @mastra/codemod@latest v1/evals-run-experiment .
-> ```
-
-### `getScorerByName` to `getScorerById`
-
-The `getScorerByName()` method has been renamed to `getScorerById()`. Scorers now require an `id` field instead of `name`. This change aligns with the broader API pattern of using `id` for entity identification.
-
-To migrate, update method calls and scorer configuration to use `id` instead of `name`.
-
-```diff
-const scorer = createScorer({
--   name: 'helpfulness-scorer',
-+   id: 'helpfulness-scorer',
-    // ...
-  });
-
-- const scorer = mastra.getScorerByName('helpfulness-scorer');
-+ const scorer = mastra.getScorerById('helpfulness-scorer');
-```
-
-> **Codemod:** You can use Mastra's codemod CLI to update your code automatically:
->
-> ```bash
-> npx @mastra/codemod@latest v1/evals-scorer-by-name .
-> ```
-
-### Scorer configuration from `name` to `id`
-
-Scorers now require an `id` field instead of `name`. The `name` field is now optional. This change provides consistency with other Mastra entities.
-
-To migrate, update scorer definitions to use `id` as the required field.
-
-```diff
-const scorer = createScorer({
--   name: 'helpfulness-scorer',
-+   id: 'helpfulness-scorer',
-+   name: 'Helpfulness Scorer', // optional
-    // ...
-  });
-```
-
-### Storage score APIs to `listScoresBy*` pattern
-
-Score storage APIs have been renamed to follow the `listScoresBy*` pattern. This change aligns with the broader storage API naming conventions.
-
-To migrate, update score query methods to use the new naming pattern.
-
-```diff
-- const scores = await storage.getScores({ scorerName: 'helpfulness-scorer' });
-+ const scores = await storage.listScoresByScorerId({
-+   scorerId: 'helpfulness-scorer',
-+ });
-
-// Also available:
-// - listScoresByRunId
-// - listScoresByEntityId
-// - listScoresBySpan
-```
-
-### Prebuilt scorer imports to `scorers/prebuilt` path
-
-Prebuilt scorer imports have been consolidated under a single `@mastra/evals/scorers/prebuilt` path instead of separate `scorers/llm` and `scorers/code` paths. This change simplifies imports and provides a clearer organization of prebuilt scorers.
-
-To migrate, update import statements to use the new `scorers/prebuilt` path.
-
-```diff
-// LLM-based scorers
-- import { createHallucinationScorer } from '@mastra/evals/scorers/llm';
-- import { createFaithfulnessScorer } from '@mastra/evals/scorers/llm';
-+ import { createHallucinationScorer } from '@mastra/evals/scorers/prebuilt';
-+ import { createFaithfulnessScorer } from '@mastra/evals/scorers/prebuilt';
-
-  // Code-based scorers
-- import { createContentSimilarityScorer } from '@mastra/evals/scorers/code';
-- import { createCompletenessScorer } from '@mastra/evals/scorers/code';
-+ import { createContentSimilarityScorer } from '@mastra/evals/scorers/prebuilt';
-+ import { createCompletenessScorer } from '@mastra/evals/scorers/prebuilt';
-```
-
-> **Codemod:** You can use Mastra's codemod CLI to update your code automatically:
->
-> ```bash
-> npx @mastra/codemod@latest v1/evals-prebuilt-imports .
-> ```
-
-### Scorer message types from `UIMessage` to `MastraDBMessage`
-
-Scorer input and output types now use `MastraDBMessage[]` instead of `UIMessage`. This change aligns scorers with the database-persisted message format for consistency across the framework.
-
-To migrate, update scorer implementations to use `MastraDBMessage` types and access message content through the nested `content` structure.
-
-```diff
-import type {
-    ScorerRunInputForAgent,
-    ScorerRunOutputForAgent
-  } from '@mastra/core/evals';
-
-- // ScorerRunInputForAgent uses UIMessage[]
-- const inputMessages: UIMessage[] = run.input.inputMessages;
-+ // ScorerRunInputForAgent now uses MastraDBMessage[]
-+ import type { MastraDBMessage } from '@mastra/core/agent';
-+ const inputMessages: MastraDBMessage[] = run.input.inputMessages;
-```
-
-### Message content structure to nested format
-
-Tool invocations and text content are now accessed through a nested `content` object structure instead of being flat properties on the message. This change provides better type safety and aligns with the database message format.
-
-To migrate, access tool invocations via `message.content.toolInvocations` and text via `message.content.content` or use the `getTextContentFromMastraDBMessage()` helper.
-
-```diff
-+ import { getTextContentFromMastraDBMessage } from '@mastra/evals';
-+
-  const run = await scorer.run(testRun);
-
-  // Accessing text content
-- const text = message.content;
-+ const text = getTextContentFromMastraDBMessage(message);
-+ // or directly: message.content.content
-
-  // Accessing tool invocations
-- const toolCalls = message.toolInvocations;
-+ const toolCalls = message.content.toolInvocations;
-```
-
-## Removed
-
-### Legacy evals code
-
-Legacy evals code has been removed from `@mastra/core`. This includes legacy evaluation metrics, scorer/judge modules, and hook-based automatic evaluation code. This change simplifies the codebase by removing outdated evaluation approaches.
-
-To migrate, use the new evals/scorers API in `@mastra/core/evals` or `@mastra/evals`.
-
-```diff
-- // Legacy evals APIs
-+ import { createScorer, runEvals } from '@mastra/core/evals';
-+
-+ const scorer = createScorer({
-+   id: 'my-scorer',
-+   // Use new scorer API
-+ });
-```
-
-### Agent `TMetrics` generic parameter
-
-The `TMetrics` generic parameter has been removed from `AgentConfig` and the `Agent` constructor. Metrics/scorers are now configured using the scorers API instead of being part of the Agent type system. This change simplifies the Agent type signature.
-
-To migrate, remove the `TMetrics` generic parameter and configure scorers using the scorers API.
-
-```diff
-- const agent = new Agent<AgentId, Tools, Metrics>({
-+ const agent = new Agent<AgentId, Tools>({
-    // ...
-  });
-```
-
-### Evals-related type exports
-
-Several evals-related type exports have been removed including `DeprecatedOutputOptions`, `Metric`, and processor option types. These types are now internal or have been replaced by the new scorers API. This change reduces API surface area.
-
-To migrate, remove references to these removed types and use the new scorers API.
-
-```diff
-- import type {
--   DeprecatedOutputOptions,
--   Metric,
--   LanguageDetectorOptions,
--   ModerationOptions,
-- } from '@mastra/core';
-+ // Use new scorers API types
-+ import type { Scorer } from '@mastra/core/evals';
-```
-
-### `createUIMessage` test helper
-
-The `createUIMessage()` test helper has been removed and replaced with `createTestMessage()`. The new helper creates `MastraDBMessage` objects with the nested content structure and supports optional tool invocations. This change aligns test utilities with the new message format.
-
-To migrate, replace `createUIMessage()` calls with `createTestMessage()` and update to use `MastraDBMessage` types.
-
-```diff
-- import { createUIMessage } from '@mastra/evals';
-+ import { createTestMessage } from '@mastra/evals';
-
-  // Creating test messages
-- const message = createUIMessage({
--   id: 'test-1',
-+ const message = createTestMessage({
-+   id: 'test-1', // optional, defaults to 'test-message'
-    role: 'user',
-    content: 'Hello',
-    toolInvocations: [], // optional
-  });
-```