@mastra/mcp-docs-server 1.2.16 → 1.2.17-alpha.11

package/.docs/docs/agents/agent-approval.md

@@ -391,6 +391,8 @@ const agent = new Agent({
 
 When enabled, the agent detects suspended tools from message history on the next user message. It extracts `resumeData` based on the tool's `resumeSchema`, then automatically resumes the tool.
 
+Automatic resumption applies to data-bearing `suspend()` flows. It doesn't approve tools that use `requireApproval`; those tools remain suspended until an explicit approval or decline is submitted through `approveToolCall()`, `declineToolCall()`, `resumeStream({ approved: boolean })`, or an equivalent UI or API action.
+
 The following example shows a complete conversational flow:
 
 ```typescript

package/.docs/docs/agents/code-mode.md

@@ -29,7 +29,7 @@ Each turn adds the full tool response to the agent's context window which can le
 
 With code mode, your tools keep running on the host with full validation, request context, and tracing. Only the model's orchestration code runs in the sandbox. Each `external_*` call is bridged back to the real tool on the host, and the function can reduce or aggregate results before returning one response to the agent.
 
-The function runs in a [Workspace sandbox](https://mastra.ai/docs/workspace/overview). A sandbox is required, because code mode runs model-authored code and the execution boundary must be chosen deliberately. Pass one via `sandbox`, or run the agent in a workspace that provides one. To execute on the host machine, pass `new LocalSandbox()` explicitly. This runs the function as a host `node` process with host privileges, so only use it for trusted or local development.
+The function runs in a [Workspace sandbox](https://mastra.ai/docs/workspace/sandbox). A sandbox is required, because code mode runs model-authored code and the execution boundary must be chosen deliberately. Pass one via `sandbox`, or run the agent in a workspace that provides one. To execute on the host machine, pass `new LocalSandbox()` explicitly. This runs the function as a host `node` process with host privileges, so only use it for trusted or local development.
 
 Transports that bring their own execution boundary are the exception: with [`IsolatedVmCodeModeTransport`](https://mastra.ai/reference/tools/isolated-vm-transport) the program runs in an in-process V8 isolate and no sandbox is needed (see [In-process isolation](#in-process-isolation)).
 
@@ -184,4 +184,4 @@ See [Choosing a transport](https://mastra.ai/reference/tools/quickjs-transport)
 - [IsolatedVmCodeModeTransport reference](https://mastra.ai/reference/tools/isolated-vm-transport)
 - [QuickJsCodeModeTransport reference](https://mastra.ai/reference/tools/quickjs-transport)
 - [Tools](https://mastra.ai/docs/agents/using-tools)
-- [Workspace overview](https://mastra.ai/docs/workspace/overview)
+- [Sandbox](https://mastra.ai/docs/workspace/sandbox)

package/.docs/docs/agents/processors.md

@@ -426,7 +426,7 @@ See the [`ToolSearchProcessor` reference](https://mastra.ai/reference/processors
 
 Handles provider-specific history incompatibilities when agents reuse messages across model providers. It can rewrite the outbound LLM request before the provider call, or recover from known provider API errors and retry.
 
-Add `ProviderHistoryCompat` explicitly when you need provider history compatibility rules, reactive API error recovery, custom compatibility rules, or predictable processor ordering.
+Add `ProviderHistoryCompat` explicitly when you need provider history compatibility rules, reactive API error recovery, custom compatibility rules, or predictable processor ordering. For Azure OpenAI agents that use observational memory, the processor rewrites `<system-reminder>` wrappers in outbound prompts to avoid content moderation refusals. Stored history remains unchanged.
 
 See the [`ProviderHistoryCompat` reference](https://mastra.ai/reference/processors/provider-history-compat) for setup, built-in rules, and custom rule options.
 

package/.docs/docs/agents/skills.md

@@ -4,7 +4,7 @@
 
 Skills are reusable instructions that teach agents how to perform specific tasks. They follow the [Agent Skills specification](https://agentskills.io).
 
-You can attach skills directly to an agent through its `skills` config, or configure them on a [workspace](https://mastra.ai/docs/workspace/overview). Attach them to the agent when the skills belong to that specific agent and you want to define them in code with no workspace required. Use a workspace when you want skills discovered from the filesystem and shared across every agent that uses it. This page covers the agent-level approach, defining skills in code and loading them from files, plus resolving them per request.
+You can attach skills directly to an agent through its `skills` config, or configure them on a [workspace](https://mastra.ai/docs/workspace/skills). Attach them to the agent when the skills belong to that specific agent and you want to define them in code with no workspace required. Use a workspace when you want skills discovered from the filesystem and shared across every agent that uses it. This page covers the agent-level approach, defining skills in code and loading them from files, plus resolving them per request.
 
 ## When to use agent-level skills
 

package/.docs/docs/agents/using-tools.md

@@ -326,7 +326,7 @@ For more phases, including `input`, `inputDelta`, `error`, `approval`, `suspend`
 
 ## Run logic around tool calls
 
-Use `hooks` to run custom logic before and after every tool call an agent makes. Hooks apply to all tool sources: assigned tools, memory tools, toolsets, client tools, agent and workflow tools, and [workspace tools](https://mastra.ai/docs/workspace/overview). Common uses include logging, auditing, input validation, and blocking specific calls.
+Use `hooks` to run custom logic before and after every tool call an agent makes. Hooks apply to all tool sources: assigned tools, memory tools, toolsets, client tools, agent and workflow tools, and [workspace tools](https://mastra.ai/reference/workspace/workspace-class). Common uses include logging, auditing, input validation, and blocking specific calls.
 
 ```typescript
 import { Agent } from '@mastra/core/agent'

package/.docs/docs/capabilities/channels.md

@@ -152,7 +152,7 @@ export const deleteFile = createTool({
 
 When the agent calls this tool, users see a card with the tool name, arguments, and Approve and Deny actions. The tool only executes after approval.
 
-Set `toolDisplay: 'text'` on an adapter to render tool calls as plain text instead of interactive cards. In `'hidden'` mode, `autoResumeSuspendedTools` can resume suspended tools when a later user message arrives on the same thread. This requires memory. Hidden mode only suppresses the approval buttons.
+Set `toolDisplay: 'text'` on an adapter to render tool calls as plain text instead of interactive cards. In `'hidden'` mode, `autoResumeSuspendedTools` can resume data-bearing `suspend()` flows when a later user message arrives on the same thread. This requires memory. Hidden mode only suppresses approval buttons. It doesn't turn a message into consent. Tools that require approval remain suspended until an explicit approval or decline is submitted through a UI or API action.
 
 ## Reply formatting
 
@@ -182,6 +182,39 @@ In group conversations, Mastra prefixes each message with the sender's name and
 [Bob (@U456DEF)]: I have a question too.
 ```
 
+## Per-message Signal metadata
+
+Use `signalMetadata` in a custom Channel handler to attach structured context to one inbound message. The metadata follows the message when it starts an idle run or joins an active run.
+
+The following example attaches registered file IDs before calling the default handler:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { createSlackAdapter } from '@chat-adapter/slack'
+
+export const yourAgent = new Agent({
+  id: 'your-agent',
+  name: 'Your Agent',
+  instructions: 'You are a helpful assistant.',
+  model: 'openai/gpt-5.6-sol',
+  channels: {
+    adapters: {
+      slack: createSlackAdapter(),
+    },
+    handlers: {
+      onDirectMessage: async (thread, message, defaultHandler, ctx) => {
+        ctx.signalMetadata.attachmentIds = ['file-1']
+        await defaultHandler(thread, message)
+      },
+    },
+  },
+})
+```
+
+Add only JSON-serializable, non-sensitive values. Signal metadata may be stored in memory or sent through a shared publish-subscribe transport. It isn't added to the model prompt.
+
+Use `requestContext` for run-scoped configuration, such as credentials for a message that starts a run. Use `signalMetadata` for context that must stay attached to one message, including messages delivered to an active run.
+
 ## Multimodal content
 
 Models like Gemini can process images, video, and audio natively. Combine `inlineMedia` and `inlineLinks` to let users share rich content with your agent across platforms:

package/.docs/docs/datasets/running-experiments.md

@@ -35,6 +35,8 @@ console.log(summary.failedCount) // number of items that failed
 
 You can also run experiments in [Studio](https://mastra.ai/docs/studio/overview). After you've added a dataset item, open it and select **Run Experiment** and configure the target, scorers, and options.
 
+To configure scorers for one item, edit the item and enable **Override dataset scorers**. Select one or more scorers, or leave the selection empty to run no scorers for that item.
+
 After running an experiment, the **Experiments** tab shows all runs for that dataset (with status, counts, and timestamps). Select an experiment to see per-item results, scores, and execution traces.
 
 In the **Experiments** tab, select **Compare** and choose two or more experiments to compare their scores and results side by side.
@@ -149,6 +151,50 @@ for (const item of summary.results) {
 
 Visit the [Scorers overview](https://mastra.ai/docs/evals/overview) for details on available and custom scorers.
 
+## Select scorers per item
+
+Add registered scorer IDs to a dataset item to override the scorers attached to its dataset:
+
+```typescript
+await dataset.addItem({
+  input: 'Translate "hello" to French.',
+  scorerIds: ['accuracy', 'fluency'],
+})
+```
+
+An experiment uses exactly one scorer source for each item, in this order:
+
+1. The experiment's `scorers` option, when provided
+2. The item's `scorerIds` field, when provided
+3. The dataset's `scorerIds` field
+4. No scorers
+
+Mastra doesn't merge these sources. An explicit empty array at the run or item level selects no scorers and prevents fallback to the next source. An empty categorized run-level configuration has the same effect. Duplicate item or dataset IDs run once, in the order of their first occurrence.
+
+The following updates switch between an explicit empty override and dataset inheritance:
+
+```typescript
+// Run no scorers for this item
+await dataset.updateItem({
+  itemId: 'translation-item-id',
+  scorerIds: [],
+})
+
+// Remove the item override and inherit the dataset's scorers
+await dataset.updateItem({
+  itemId: 'translation-item-id',
+  scorerIds: null,
+})
+```
+
+Omitting `scorerIds` from an update preserves its current value. Each item version stores its scorer ID list, including an empty list. Scorer definitions aren't copied into the item version and continue to use their existing registry or Editor behavior.
+
+Mastra resolves each item's scorer IDs before running its target. It checks registered scorers first, then asks the Editor to hydrate a stored scorer. A stale item-level ID produces the `EXPERIMENT_ITEM_SCORER_NOT_FOUND` code for that item. Mastra skips target execution without retrying that item, while the rest of the experiment continues.
+
+A missing ID in the selected run-level or dataset-level source fails experiment setup. Mastra doesn't resolve IDs from lower-priority sources that the precedence rules ignore.
+
+Workflow step scorers are available only through a run-level categorized `scorers` configuration. Item-level IDs apply to the flat agent, workflow, and trajectory scorer dispatch.
+
 ## Control persistence per run
 
 Use `persistence` to skip storage writes for a specific run. Experiment records and score records can be disabled independently:

package/.docs/docs/harness/agent-controller.md

@@ -412,6 +412,6 @@ Subscriptions are isolated by Session. Events from another Session on the same c
 ## Related
 
 - [Agents](https://mastra.ai/docs/agents/overview)
-- [Workspace](https://mastra.ai/docs/workspace/overview)
+- [Workspace](https://mastra.ai/docs/workspace/sandbox)
 - [Observational memory](https://mastra.ai/docs/memory/observational-memory)
 - [Channels](https://mastra.ai/docs/capabilities/channels)

package/.docs/docs/mcp/overview.md

@@ -252,7 +252,7 @@ Use an MCP App when a tool result benefits from interaction, such as a form, cal
 
 ### Define an app resource
 
-Return a short `content` summary for the model and place UI data in `structuredContent`. Link the tool to its app by setting `_meta.ui.resourceUri` to the same `ui://` URI used in `appResources`:
+Return a short `content` summary for the model and place UI data in `structuredContent`. Link the tool to its app by setting `mcp._meta.ui.resourceUri` to the same `ui://` URI used in `appResources`:
 
 ```typescript
 import { MCPServer } from '@mastra/mcp'
@@ -266,16 +266,15 @@ export const calculatorTool = createTool({
     num1: z.number(),
     num2: z.number(),
   }),
+  mcp: {
+    _meta: { ui: { resourceUri: 'ui://calculator/main' } },
+  },
   execute: async ({ num1, num2 }) => ({
     content: [{ type: 'text', text: 'The result is displayed in the calculator app.' }],
     structuredContent: { result: num1 + num2 },
   }),
 })
 
-calculatorTool._meta = {
-  ui: { resourceUri: 'ui://calculator/main' },
-}
-
 export const calculatorMcpServer = new MCPServer({
   id: 'calculator-app-server',
   name: 'Calculator App Server',

package/.docs/docs/server/request-context.md

@@ -56,6 +56,27 @@ await run.resume({
 await weatherTool.execute({ location: 'London' }, { requestContext })
 ```
 
+### Using runtime-only keys
+
+When you provide a type or `requestContextSchema`, the `get`, `set`, `has`, and `delete` methods only accept declared keys. This catches misspelled keys and keeps declared values typed.
+
+Use `getRaw`, `setRaw`, `hasRaw`, and `deleteRaw` for infrastructure or middleware keys that aren't part of the schema. Raw values use the `unknown` type, so narrow them before use.
+
+```typescript
+const requestContext = new RequestContext<{ userId: string }>()
+
+requestContext.set('userId', 'user-123')
+requestContext.setRaw('session.cache', { hits: 0 })
+
+const cache = requestContext.getRaw('session.cache')
+
+if (typeof cache === 'object' && cache !== null && 'hits' in cache) {
+  console.log(cache.hits)
+}
+```
+
+Prefer schema-declared keys for application data. Use the raw methods only when a key must remain outside the request context schema.
+
 ### Setting values based on request headers
 
 You can populate `requestContext` in a runtime server middleware by extracting information from the request. In this example, the `temperature-unit` is set based on the Cloudflare `CF-IPCountry` header to ensure responses match the user's locale.

package/.docs/docs/studio/overview.md

@@ -85,7 +85,7 @@ Run tools on their own to observe behavior and test them before assigning them t
 
 Browse the files in your agent's workspace filesystem using a built-in file browser. Switch between workspace mounts, create directories, and view file contents with syntax highlighting. Writable workspaces allow directory creation and file deletion; read-only workspaces are labeled accordingly. The Skills tab lists all discovered skills with their instructions, references, and metadata. Install community skills from [skills.sh](https://skills.sh) or remove existing ones.
 
-See [workspaces](https://mastra.ai/docs/workspace/overview) for configuration details.
+See [workspaces](https://mastra.ai/docs/workspace/sandbox) for configuration details.
 
 ### Request context