@mastra/mcp-docs-server 1.1.8 → 1.1.9-alpha.1

package/.docs/reference/client-js/agents.md

@@ -2,7 +2,7 @@
 
 The Agents API provides methods to interact with Mastra AI agents, including generating responses, streaming interactions, and managing agent tools.
 
-## Getting All Agents
+## Getting all agents
 
 Retrieve a list of all available agents:
 
@@ -12,7 +12,7 @@ const agents = await mastraClient.listAgents()
 
 Returns a record of agent IDs to their serialized agent configurations.
 
-## Working with a Specific Agent
+## Working with a specific agent
 
 Get an instance of a specific agent by its ID:
 
@@ -26,9 +26,9 @@ export const myAgent = new Agent({
 const agent = mastraClient.getAgent('my-agent')
 ```
 
-## Agent Methods
+## Agent methods
 
-### details()
+### `details()`
 
 Retrieve detailed information about an agent:
 
@@ -36,7 +36,7 @@ Retrieve detailed information about an agent:
 const details = await agent.details()
 ```
 
-### generate()
+### `generate()`
 
 Generate a response from the agent:
 
@@ -69,7 +69,7 @@ const response = await agent.generate('Hello, how are you?', {
 })
 ```
 
-### stream()
+### `stream()`
 
 Stream responses from the agent for real-time interactions:
 
@@ -151,7 +151,7 @@ for await (const part of uiMessageStream) {
 }
 ```
 
-### getTool()
+### `getTool()`
 
 Retrieve information about a specific tool available to the agent:
 
@@ -159,7 +159,7 @@ Retrieve information about a specific tool available to the agent:
 const tool = await agent.getTool('tool-id')
 ```
 
-### executeTool()
+### `executeTool()`
 
 Execute a specific tool for the agent:
 
@@ -169,7 +169,7 @@ const result = await agent.executeTool('tool-id', {
 })
 ```
 
-### network()
+### `network()`
 
 Stream responses from an agent network for multi-agent interactions:
 
@@ -183,7 +183,7 @@ response.processDataStream({
 })
 ```
 
-### approveToolCall()
+### `approveToolCall()`
 
 Approve a pending tool call that requires human confirmation:
 
@@ -200,7 +200,7 @@ response.processDataStream({
 })
 ```
 
-### declineToolCall()
+### `declineToolCall()`
 
 Decline a pending tool call that requires human confirmation:
 
@@ -217,7 +217,7 @@ response.processDataStream({
 })
 ```
 
-### approveToolCallGenerate()
+### `approveToolCallGenerate()`
 
 Approve a pending tool call when using `generate()` (non-streaming). Returns the complete response:
 
@@ -236,7 +236,7 @@ if (output.finishReason === 'suspended') {
 }
 ```
 
-### declineToolCallGenerate()
+### `declineToolCallGenerate()`
 
 Decline a pending tool call when using `generate()` (non-streaming). Returns the complete response:
 
@@ -255,7 +255,7 @@ if (output.finishReason === 'suspended') {
 }
 ```
 
-## Client Tools
+## Client tools
 
 Client-side tools allow you to execute custom functions on the client side when the agent requests them.
 
@@ -306,11 +306,11 @@ response.processDataStream({
 })
 ```
 
-## Stored Agents
+## Stored agents
 
 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()
+### `listStoredAgents()`
 
 Retrieve a paginated list of all stored agents:
 
@@ -333,7 +333,7 @@ const result = await mastraClient.listStoredAgents({
 })
 ```
 
-### createStoredAgent()
+### `createStoredAgent()`
 
 Create a new stored agent:
 
@@ -380,7 +380,7 @@ const agent = await mastraClient.createStoredAgent({
 })
 ```
 
-### getStoredAgent()
+### `getStoredAgent()`
 
 Get an instance of a specific stored agent:
 
@@ -388,9 +388,9 @@ Get an instance of a specific stored agent:
 const storedAgent = mastraClient.getStoredAgent('my-agent')
 ```
 
-## Stored Agent Methods
+## Stored agent methods
 
-### details()
+### `details()`
 
 Retrieve the stored agent configuration:
 
@@ -401,7 +401,7 @@ console.log(details.instructions)
 console.log(details.model)
 ```
 
-### update()
+### `update()`
 
 Update specific fields of a stored agent. All fields are optional:
 
@@ -427,7 +427,7 @@ await storedAgent.update({
 })
 ```
 
-### delete()
+### `delete()`
 
 Delete a stored agent:
 

package/.docs/reference/client-js/error-handling.md

@@ -1,8 +1,8 @@
-# Error Handling
+# Error handling
 
 The Mastra Client SDK includes built-in retry mechanism and error handling capabilities.
 
-## Error Handling
+## Error handling
 
 All API methods can throw errors that you can catch and handle:
 

package/.docs/reference/client-js/logs.md

@@ -2,7 +2,7 @@
 
 The Logs API provides methods to access and query system logs and debugging information in Mastra.
 
-## Getting Logs
+## Getting logs
 
 Retrieve system logs with optional filtering:
 
@@ -12,7 +12,7 @@ const logs = await mastraClient.listLogs({
 })
 ```
 
-## Getting Logs for a Specific Run
+## Getting logs for a specific run
 
 Retrieve logs for a specific execution run:
 

package/.docs/reference/client-js/mastra-client.md

@@ -1,6 +1,6 @@
-# Mastra Client SDK
+# Mastra client SDK
 
-The Mastra Client SDK provides a simple and type-safe interface for interacting with your [Mastra Server](https://mastra.ai/docs/deployment/mastra-server) from your client environment.
+The Mastra Client SDK provides a type-safe interface for interacting with your [Mastra Server](https://mastra.ai/docs/deployment/mastra-server) from your client environment.
 
 ## Usage example
 

package/.docs/reference/client-js/memory.md

@@ -2,7 +2,7 @@
 
 The Memory API provides methods to manage conversation threads and message history in Mastra.
 
-## Get All Threads
+## Get all threads
 
 Retrieve all memory threads for a specific resource:
 
@@ -15,7 +15,7 @@ const threads = await mastraClient.getMemoryThreads({
 
 When `agentId` is omitted and storage is configured on the server, threads will be retrieved using storage directly. This is useful when multiple agents share the same threads (e.g., in workflows with multiple agent steps).
 
-## Create a New Thread
+## Create a new thread
 
 Create a new memory thread:
 
@@ -28,7 +28,7 @@ const thread = await mastraClient.createMemoryThread({
 })
 ```
 
-## Working with a Specific Thread
+## Working with a specific thread
 
 Get an instance of a specific memory thread:
 
@@ -36,7 +36,7 @@ Get an instance of a specific memory thread:
 const thread = mastraClient.getMemoryThread({ threadId: 'thread-id', agentId: 'agent-id' })
 ```
 
-## Thread Methods
+## Thread methods
 
 ### Get Thread Details
 
@@ -105,7 +105,7 @@ The clone response includes:
 - `thread`: The newly created cloned thread with clone metadata
 - `clonedMessages`: Array of the cloned messages with new IDs
 
-## Message Operations
+## Message operations
 
 ### Save Messages
 
@@ -168,7 +168,7 @@ const result = await thread.deleteMessages(['message-1', 'message-2', 'message-3
 // Returns: { success: true, message: "Message deleted successfully" }
 ```
 
-## Working Memory
+## Working memory
 
 Working memory allows agents to maintain persistent information about users across interactions. It can be scoped to either a specific thread or across all threads for a resource (user).
 

package/.docs/reference/client-js/observability.md

@@ -2,7 +2,7 @@
 
 The Observability API provides methods to retrieve traces, monitor your application's performance, and score traces for evaluation. This helps you understand how your AI agents and workflows are performing.
 
-## Getting a Specific Trace
+## Getting a specific trace
 
 Retrieve a specific trace by its ID, including all its spans and details:
 
@@ -10,7 +10,7 @@ Retrieve a specific trace by its ID, including all its spans and details:
 const trace = await mastraClient.getTrace('trace-id-123')
 ```
 
-## Getting Traces with Filtering
+## Getting traces with filtering
 
 Retrieve a paginated list of trace root spans with optional filtering:
 
@@ -39,7 +39,7 @@ console.log(`Total pages: ${traces.pagination.totalPages}`)
 const completeTrace = await mastraClient.getTrace(traces.spans[0].traceId)
 ```
 
-## Scoring Traces
+## Scoring traces
 
 Score specific traces using registered scorers for evaluation:
 
@@ -53,7 +53,7 @@ const result = await mastraClient.score({
 })
 ```
 
-## Getting Scores by Span
+## Getting scores by span
 
 Retrieve scores for a specific span within a trace:
 

package/.docs/reference/client-js/telemetry.md

@@ -2,7 +2,7 @@
 
 The Telemetry API provides methods to retrieve and analyze traces from your Mastra application. This helps you monitor and debug your application's behavior and performance.
 
-## Getting Traces
+## Getting traces
 
 Retrieve traces with optional filtering and pagination:
 

package/.docs/reference/client-js/tools.md

@@ -2,7 +2,7 @@
 
 The Tools API provides methods to interact with and execute tools available in the Mastra platform.
 
-## Getting All Tools
+## Getting all tools
 
 Retrieve a list of all available tools:
 
@@ -10,7 +10,7 @@ Retrieve a list of all available tools:
 const tools = await mastraClient.listTools()
 ```
 
-## Working with a Specific Tool
+## Working with a specific tool
 
 Get an instance of a specific tool:
 
@@ -18,7 +18,7 @@ Get an instance of a specific tool:
 const tool = mastraClient.getTool('tool-id')
 ```
 
-## Tool Methods
+## Tool methods
 
 ### Get Tool Details
 

package/.docs/reference/client-js/vectors.md

@@ -2,7 +2,7 @@
 
 The Vectors API provides methods to work with vector embeddings for semantic search and similarity matching in Mastra.
 
-## Working with Vectors
+## Working with vectors
 
 Get an instance of a vector store:
 
@@ -10,7 +10,7 @@ Get an instance of a vector store:
 const vector = mastraClient.getVector('vector-name')
 ```
 
-## Vector Methods
+## Vector methods
 
 ### Get Vector Index Details
 

package/.docs/reference/client-js/workflows.md

@@ -2,7 +2,7 @@
 
 The Workflows API provides methods to interact with and execute automated workflows in Mastra.
 
-## Getting All Workflows
+## Getting all workflows
 
 Retrieve a list of all available workflows:
 
@@ -10,7 +10,7 @@ Retrieve a list of all available workflows:
 const workflows = await mastraClient.listWorkflows()
 ```
 
-## Working with a Specific Workflow
+## Working with a specific workflow
 
 Get an instance of a specific workflow by its ID:
 
@@ -24,9 +24,9 @@ export const testWorkflow = createWorkflow({
 const workflow = mastraClient.getWorkflow('city-workflow')
 ```
 
-## Workflow Methods
+## Workflow methods
 
-### details()
+### `details()`
 
 Retrieve detailed information about a workflow:
 
@@ -34,7 +34,7 @@ Retrieve detailed information about a workflow:
 const details = await workflow.details()
 ```
 
-### createRun()
+### `createRun()`
 
 Create a new workflow run instance:
 
@@ -53,7 +53,7 @@ const run = await workflow.createRun({
 
 The `resourceId` parameter associates the workflow run with a specific resource (e.g., user ID, tenant ID). This value is persisted with the run and can be used for filtering and querying runs later.
 
-### startAsync()
+### `startAsync()`
 
 Start a workflow run and await the full result:
 
@@ -95,7 +95,7 @@ const result = await run.startAsync({
 })
 ```
 
-### start()
+### `start()`
 
 Start a workflow run without waiting for completion:
 
@@ -114,7 +114,7 @@ const result = await workflow.runById(run.runId)
 
 This is useful for long-running workflows where you want to start execution and check results later.
 
-### resumeAsync()
+### `resumeAsync()`
 
 Resume a suspended workflow step and await the full result:
 
@@ -127,7 +127,7 @@ const result = await run.resumeAsync({
 })
 ```
 
-### resume()
+### `resume()`
 
 Resume a suspended workflow step without waiting for completion:
 
@@ -140,7 +140,7 @@ await run.resume({
 })
 ```
 
-### cancel()
+### `cancel()`
 
 Cancel a running workflow:
 
@@ -155,7 +155,7 @@ This method stops any running steps and prevents subsequent steps from executing
 
 See the [Run.cancel()](https://mastra.ai/reference/workflows/run-methods/cancel) reference for detailed information about how cancellation works and how to write steps that respond to cancellation.
 
-### stream()
+### `stream()`
 
 Stream workflow execution for real-time updates:
 
@@ -173,7 +173,7 @@ for await (const chunk of stream) {
 }
 ```
 
-### runById()
+### `runById()`
 
 Get the execution result for a workflow run:
 

package/.docs/reference/configuration.md

@@ -59,7 +59,7 @@ export const mastra = new Mastra({
 
 Event handlers for the internal pub/sub system. Maps event topics to handler functions that are called when events are published to those topics.
 
-> **Warning:** This is used internally by Mastra's workflow engine. Most users will not need to configure this option.
+> **Warning:** This is used internally by Mastra's workflow engine. Most users won't need to configure this option.
 
 ```typescript
 import { Mastra } from '@mastra/core'
@@ -94,19 +94,39 @@ export const mastra = new Mastra({
 
 ### idGenerator
 
-**Type:** `() => string`\
+**Type:** `(context?: IdGeneratorContext) => string`\
 **Default:** `crypto.randomUUID()`
 
-Custom ID generator function for creating unique identifiers.
+Custom ID generator function for creating unique identifiers. Mastra passes optional context so you can generate IDs based on what's being created.
 
-> **Warning:** This is used internally by Mastra for creating IDs for workflow runs, agent conversations, and other resources. Most users will not need to configure this option.
+`IdGeneratorContext` includes:
+
+- `idType`: `'thread' | 'message' | 'run' | 'step' | 'generic'`
+- `source?`: `'agent' | 'workflow' | 'memory'`
+- `entityId?`: ID of the requesting agent/workflow/memory entity
+- `threadId?`: Thread ID when relevant (for example, when creating message IDs)
+- `resourceId?`: Resource ID when relevant (for example, user-scoped threads)
+- `role?`: Message role when creating a message ID
+- `stepType?`: Workflow step type when creating a step ID
+
+> **Warning:** This is used internally by Mastra for creating IDs for workflow runs, agent conversations, and other resources. Most users won't need to configure this option.
 
 ```typescript
 import { Mastra } from '@mastra/core'
 import { nanoid } from 'nanoid'
 
 export const mastra = new Mastra({
-  idGenerator: () => nanoid(),
+  idGenerator: context => {
+    if (context?.idType === 'message' && context?.threadId) {
+      return `msg-${context.threadId}-${nanoid(8)}`
+    }
+
+    if (context?.idType === 'run' && context?.source && context?.entityId) {
+      return `${context.source}-run-${context.entityId}-${nanoid(6)}`
+    }
+
+    return nanoid()
+  },
 })
 ```
 
@@ -243,7 +263,7 @@ export const mastra = new Mastra({
 
 Pub/sub system for event-driven communication between components. Used internally by Mastra for workflow event processing and component communication.
 
-> **Warning:** This is used internally by Mastra. Most users will not need to configure this option.
+> **Warning:** This is used internally by Mastra. Most users won't need to configure this option.
 
 ```typescript
 import { Mastra } from '@mastra/core'
@@ -693,6 +713,42 @@ export const mastra = new Mastra({
 })
 ```
 
+### server.onValidationError
+
+**Type:** `(error: ZodError, context: 'query' | 'body' | 'path') => { status: number; body: unknown } | undefined`
+
+Custom handler called when a request fails Zod schema validation. Use this to customize validation error responses, change the status code, or format errors to match your API standards.
+
+Return a `{ status, body }` object to override the default `400` response, or `undefined` to fall through to the default behavior. This hook is supported by all server adapters (Hono, Express, Fastify, Koa).
+
+The `context` parameter indicates which part of the request failed validation:
+
+- `'query'` — query parameters
+- `'body'` — request body
+- `'path'` — path parameters
+
+```typescript
+import { Mastra } from '@mastra/core'
+
+export const mastra = new Mastra({
+  server: {
+    onValidationError: (error, context) => ({
+      status: 422,
+      body: {
+        ok: false,
+        errors: error.issues.map(i => ({
+          path: i.path.join('.'),
+          message: i.message,
+        })),
+        source: context,
+      },
+    }),
+  },
+})
+```
+
+You can also set `onValidationError` on individual routes created with `createRoute()`. A route-level hook takes precedence over the server-level hook.
+
 ### server.port
 
 **Type:** `number`\

package/.docs/reference/core/getDeployer.md

@@ -10,7 +10,7 @@ mastra.getDeployer()
 
 ## Parameters
 
-This method does not accept any parameters.
+This method doesn't accept any parameters.
 
 ## Returns
 

package/.docs/reference/core/getGatewayById.md

@@ -18,7 +18,7 @@ const gateway = mastra.getGatewayById('my-custom-gateway')
 console.log(gateway.name) // 'My Custom Gateway'
 ```
 
-## Use Cases
+## Use cases
 
 - Gateway versioning: Different versions with unique IDs (`'gateway-v1'`, `'gateway-v2'`)
 - Finding gateways when registration keys are unknown

package/.docs/reference/core/getLogger.md

@@ -10,7 +10,7 @@ mastra.getLogger()
 
 ## Parameters
 
-This method does not accept any parameters.
+This method doesn't accept any parameters.
 
 ## Returns
 

package/.docs/reference/core/getMCPServer.md

@@ -36,12 +36,12 @@ const serverById = mastra.getMCPServerById('my-mcp-server')
 
 **server** (`MCPServerBase | undefined`): The MCP server instance with the specified registry key, or undefined if not found.
 
-## Related Methods
+## Related methods
 
 - [Mastra.getMCPServerById()](https://mastra.ai/reference/core/getMCPServerById) - Retrieve an MCP server by its intrinsic `id` property
 - [Mastra.listMCPServers()](https://mastra.ai/reference/core/listMCPServers) - List all registered MCP servers
 
-## See Also
+## See also
 
 - [MCP overview](https://mastra.ai/docs/mcp/overview)
 - [MCP server reference](https://mastra.ai/reference/tools/mcp-server)

package/.docs/reference/core/getMCPServerById.md

@@ -44,12 +44,12 @@ const serverByKey = mastra.getMCPServer('customKey')
 - If multiple servers have the same `id` but different versions, you must provide the `version` parameter to disambiguate
 - If no `version` is provided and multiple versions exist, the method returns the first match
 
-## Related Methods
+## Related methods
 
 - [Mastra.getMCPServer()](https://mastra.ai/reference/core/getMCPServer) - Retrieve an MCP server by its registry key
 - [Mastra.listMCPServers()](https://mastra.ai/reference/core/listMCPServers) - List all registered MCP servers
 
-## See Also
+## See also
 
 - [MCP overview](https://mastra.ai/docs/mcp/overview)
 - [MCP server reference](https://mastra.ai/reference/tools/mcp-server)

package/.docs/reference/core/getMemory.md

@@ -22,7 +22,7 @@ const thread = await memory.createThread({
 
 **memory** (`TMemory[TMemoryKey]`): The memory instance with the specified key. Throws an error if the memory is not found.
 
-## Example: Registering and Retrieving Memory
+## Example: Registering and retrieving memory
 
 ```typescript
 import { Mastra } from '@mastra/core'

package/.docs/reference/core/getScorer.md

@@ -1,8 +1,8 @@
 # getScorer()
 
-The `getScorer()` method retrieves a specific scorer that was registered with the Mastra instance using its registration key. This method provides type-safe access to scorers and throws an error if the requested scorer is not found.
+The `getScorer()` method retrieves a specific scorer that was registered with the Mastra instance using its registration key. This method provides type-safe access to scorers and throws an error if the requested scorer isn't found.
 
-## Usage Example
+## Usage example
 
 ```typescript
 import { mastra } from './mastra'
@@ -30,11 +30,11 @@ await weatherAgent.generate('What is the weather in Rome', {
 
 **scorer** (`MastraScorer`): The MastraScorer instance associated with the provided key.
 
-## Error Handling
+## Error handling
 
 This method throws a `MastraError` if:
 
-- The scorer with the specified key is not found
+- The scorer with the specified key isn't found
 - No scorers are registered with the Mastra instance
 
 ```typescript

package/.docs/reference/core/getScorerById.md

@@ -2,7 +2,7 @@
 
 The `getScorerById()` method retrieves a scorer by searching for its `id` property (or `name` property as a fallback) rather than the registration key. This is useful when you know the scorer's id but not necessarily how it was registered in the Mastra instance.
 
-## Usage Example
+## Usage example
 
 ```typescript
 import { mastra } from './mastra'
@@ -30,7 +30,7 @@ await weatherAgent.generate('What is the weather in Rome', {
 
 **scorer** (`MastraScorer`): The MastraScorer instance that has the matching id (or name) property.
 
-## Error Handling
+## Error handling
 
 This method throws a `MastraError` if: