@mastra/mcp-docs-server 1.1.35-alpha.3 → 1.1.35-alpha.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (18) hide show
  1. package/.docs/docs/agents/processors.md +26 -2
  2. package/.docs/docs/memory/observational-memory.md +2 -1
  3. package/.docs/docs/memory/overview.md +2 -1
  4. package/.docs/models/index.md +1 -1
  5. package/.docs/models/providers/kiro.md +110 -0
  6. package/.docs/models/providers/llmgateway.md +1 -1
  7. package/.docs/models/providers/opencode-go.md +2 -4
  8. package/.docs/models/providers/qiniu-ai.md +2 -2
  9. package/.docs/models/providers/xiaomi.md +2 -2
  10. package/.docs/models/providers/zenmux.md +1 -1
  11. package/.docs/models/providers.md +1 -0
  12. package/.docs/reference/harness/harness-class.md +2 -0
  13. package/.docs/reference/index.md +1 -0
  14. package/.docs/reference/processors/processor-interface.md +74 -12
  15. package/.docs/reference/processors/provider-history-compat.md +132 -0
  16. package/.docs/reference/tools/mcp-client.md +47 -0
  17. package/CHANGELOG.md +14 -0
  18. package/package.json +6 -6
package/.docs/docs/agents/processors.md CHANGED
@@ -211,6 +211,22 @@ The method receives the current `stepNumber`, `model`, `tools`, `toolChoice`, `m
211
211
 
212
212
  See the [`Processor` reference](https://mastra.ai/reference/processors/processor-interface) for all available arguments and return types.
213
213
 
214
+ ### Rewrite the LLM request before the provider call
215
+
216
+ Use `processLLMRequest()` when you need to rewrite the final prompt that Mastra sends to the model. This hook runs after Mastra converts the `MessageList` into the provider-facing prompt format (`LanguageModelV2Prompt`) and immediately before the provider call.
217
+
218
+ Use the message-based hooks for conversation changes:
219
+
220
+ - `processInput()`: Change the conversation once before the agentic loop starts.
221
+ - `processInputStep()`: Change messages or step configuration before each LLM call.
222
+ - `processLLMRequest()`: Change only the outbound prompt for the current provider call.
223
+
224
+ Changes returned from `processLLMRequest()` are transient. They don't persist back to `MessageList`, memory, UI history, or future provider calls. This makes the hook a good fit for provider compatibility rewrites, role/content normalization, or other model-specific prompt changes that shouldn't alter stored conversation history.
225
+
226
+ The method receives `prompt`, `model`, `stepNumber`, `steps`, `state`, and the shared processor context. Calling `abort()` from `processLLMRequest()` emits the normal tripwire response and stops the call.
227
+
228
+ See the [`Processor` reference](https://mastra.ai/reference/processors/processor-interface) for all available arguments and return types.
229
+
214
230
  ### Use the `prepareStep()` callback
215
231
 
216
232
  The `prepareStep()` callback on `generate()` or `stream()` is a shorthand for `processInputStep()`. Internally, Mastra wraps it in a processor that calls your function at each step. It accepts the same arguments and return type as `processInputStep()`, but doesn't require creating a class:
@@ -317,7 +333,7 @@ For more on retry behavior, see [Retry mechanism](#retry-mechanism) in Advanced
317
333
 
318
334
  ### Persist data across chunks and steps
319
335
 
320
- Output methods receive a `state` object that persists for the lifetime of one request. State is keyed by the processor's `id`, so each processor sees only its own data, and it is shared between `processOutputStream`, `processOutputStep`, and `processOutputResult`. A new state object is created for every new `agent.generate()` or `agent.stream()` call.
336
+ Output methods receive a `state` object that persists for the lifetime of one request. State is keyed by the processor's `id`, so each processor sees only its own data, and it's shared between `processOutputStream`, `processOutputStep`, and `processOutputResult`. A new state object is created for every new `agent.generate()` or `agent.stream()` call.
321
337
 
322
338
  ```typescript
323
339
  import type { Processor } from '@mastra/core/processors'
@@ -383,6 +399,14 @@ Enables dynamic tool discovery for agents with large tool libraries. Instead of
383
399
 
384
400
  See the [`ToolSearchProcessor` reference](https://mastra.ai/reference/processors/tool-search-processor) for configuration options and usage examples.
385
401
 
402
+ ### `ProviderHistoryCompat`
403
+
404
+ 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.
405
+
406
+ Add `ProviderHistoryCompat` explicitly when you need provider history compatibility rules, reactive API error recovery, custom compatibility rules, or predictable processor ordering.
407
+
408
+ See the [`ProviderHistoryCompat` reference](https://mastra.ai/reference/processors/provider-history-compat) for setup, built-in rules, and custom rule options.
409
+
386
410
  ## Advanced patterns
387
411
 
388
412
  ### Ensure a final response with `maxSteps`
@@ -494,7 +518,7 @@ for await (const chunk of stream.fullStream) {
494
518
 
495
519
  Custom chunk types must use the `data-` prefix (e.g., `data-moderation-update`, `data-status`).
496
520
 
497
- By default, `processOutputStream()` skips `data-*` chunks so it does not accidentally operate on tool telemetry or other processors' output. To inspect, modify, or block these chunks in a processor, set `processDataParts = true` on that processor:
521
+ By default, `processOutputStream()` skips `data-*` chunks so it doesn't accidentally operate on tool telemetry or other processors' output. To inspect, modify, or block these chunks in a processor, set `processDataParts = true` on that processor:
498
522
 
499
523
  ```typescript
500
524
  class ModerationCollector implements Processor {
package/.docs/docs/memory/observational-memory.md CHANGED
@@ -458,4 +458,5 @@ In practical terms, OM replaces both working memory and message history, and has
458
458
  - [Observational Memory Reference](https://mastra.ai/reference/memory/observational-memory)
459
459
  - [Memory Overview](https://mastra.ai/docs/memory/overview)
460
460
  - [Message History](https://mastra.ai/docs/memory/message-history)
461
- - [Memory Processors](https://mastra.ai/docs/memory/memory-processors)
461
+ - [Memory Processors](https://mastra.ai/docs/memory/memory-processors)
462
+ - [Mastra Code](https://code.mastra.ai/): A coding agent using Observational Memory
package/.docs/docs/memory/overview.md CHANGED
@@ -237,4 +237,5 @@ export const memoryAgent = new Agent({
237
237
 
238
238
  - [`Memory` reference](https://mastra.ai/reference/memory/memory-class)
239
239
  - [Tracing](https://mastra.ai/docs/observability/tracing/overview)
240
- - [Request Context](https://mastra.ai/docs/server/request-context)
240
+ - [Request Context](https://mastra.ai/docs/server/request-context)
241
+ - [Mastra Code](https://code.mastra.ai/): A coding agent using Mastra's memory system
package/.docs/models/index.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Model Providers
2
2
 
3
- Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 3879 models from 107 providers through a single API.
3
+ Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 3889 models from 108 providers through a single API.
4
4
 
5
5
  ## Features
6
6
 
package/.docs/models/providers/kiro.md ADDED
@@ -0,0 +1,110 @@
1
+ # ![Kiro logo](https://models.dev/logos/kiro.svg)Kiro
2
+
3
+ Access 12 Kiro models through Mastra's model router. Authentication is handled automatically using the `KIRO_API_KEY` environment variable.
4
+
5
+ Learn more in the [Kiro documentation](https://kiro.dev).
6
+
7
+ ```bash
8
+ KIRO_API_KEY=your-api-key
9
+ ```
10
+
11
+ ```typescript
12
+ import { Agent } from "@mastra/core/agent";
13
+
14
+ const agent = new Agent({
15
+ id: "my-agent",
16
+ name: "My Agent",
17
+ instructions: "You are a helpful assistant",
18
+ model: "kiro/auto"
19
+ });
20
+
21
+ // Generate a response
22
+ const response = await agent.generate("Hello!");
23
+
24
+ // Stream a response
25
+ const stream = await agent.stream("Tell me a story");
26
+ for await (const chunk of stream) {
27
+ console.log(chunk);
28
+ }
29
+ ```
30
+
31
+ > **Info:** Mastra uses the OpenAI-compatible `/chat/completions` endpoint. Some provider-specific features may not be available. Check the [Kiro documentation](https://kiro.dev) for details.
32
+
33
+ ## Models
34
+
35
+ | Model | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
36
+ | ------------------------ | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
37
+ | `kiro/auto` | 1.0M | | | | | | — | — |
38
+ | `kiro/claude-haiku-4.5` | 200K | | | | | | — | — |
39
+ | `kiro/claude-opus-4.5` | 200K | | | | | | — | — |
40
+ | `kiro/claude-opus-4.6` | 1.0M | | | | | | — | — |
41
+ | `kiro/claude-opus-4.7` | 1.0M | | | | | | — | — |
42
+ | `kiro/claude-sonnet-4` | 200K | | | | | | — | — |
43
+ | `kiro/claude-sonnet-4.5` | 200K | | | | | | — | — |
44
+ | `kiro/claude-sonnet-4.6` | 1.0M | | | | | | — | — |
45
+ | `kiro/deepseek-3.2` | 164K | | | | | | — | — |
46
+ | `kiro/minimax-m2.1` | 196K | | | | | | — | — |
47
+ | `kiro/minimax-m2.5` | 196K | | | | | | — | — |
48
+ | `kiro/qwen3-coder-next` | 256K | | | | | | — | — |
49
+
50
+ ## Advanced configuration
51
+
52
+ ### Custom headers
53
+
54
+ ```typescript
55
+ const agent = new Agent({
56
+ id: "custom-agent",
57
+ name: "custom-agent",
58
+ model: {
59
+ url: "https://q.us-east-1.amazonaws.com",
60
+ id: "kiro/auto",
61
+ apiKey: process.env.KIRO_API_KEY,
62
+ headers: {
63
+ "X-Custom-Header": "value"
64
+ }
65
+ }
66
+ });
67
+ ```
68
+
69
+ ### Dynamic model selection
70
+
71
+ ```typescript
72
+ const agent = new Agent({
73
+ id: "dynamic-agent",
74
+ name: "Dynamic Agent",
75
+ model: ({ requestContext }) => {
76
+ const useAdvanced = requestContext.task === "complex";
77
+ return useAdvanced
78
+ ? "kiro/qwen3-coder-next"
79
+ : "kiro/auto";
80
+ }
81
+ });
82
+ ```
83
+
84
+ ## Direct provider installation
85
+
86
+ This provider can also be installed directly as a standalone package, which can be used instead of the Mastra model router string. View the [package documentation](https://www.npmjs.com/package/kiro-acp-ai-provider) for more details.
87
+
88
+ **npm**:
89
+
90
+ ```bash
91
+ npm install kiro-acp-ai-provider
92
+ ```
93
+
94
+ **pnpm**:
95
+
96
+ ```bash
97
+ pnpm add kiro-acp-ai-provider
98
+ ```
99
+
100
+ **Yarn**:
101
+
102
+ ```bash
103
+ yarn add kiro-acp-ai-provider
104
+ ```
105
+
106
+ **Bun**:
107
+
108
+ ```bash
109
+ bun add kiro-acp-ai-provider
110
+ ```
package/.docs/models/providers/llmgateway.md CHANGED
@@ -153,7 +153,7 @@ for await (const chunk of stream) {
153
153
  | `llmgateway/llama-4-maverick-17b-instruct` | 8K | | | | | | $0.24 | $0.97 |
154
154
  | `llmgateway/llama-4-scout` | 33K | | | | | | $0.18 | $0.59 |
155
155
  | `llmgateway/llama-4-scout-17b-instruct` | 8K | | | | | | $0.17 | $0.66 |
156
- | `llmgateway/mimo-v2-flash` | 256K | | | | | | $0.10 | $0.30 |
156
+ | `llmgateway/mimo-v2-flash` | 262K | | | | | | $0.10 | $0.30 |
157
157
  | `llmgateway/minimax-m2` | 197K | | | | | | $0.30 | $1 |
158
158
  | `llmgateway/minimax-m2.1` | 205K | | | | | | $0.30 | $1 |
159
159
  | `llmgateway/minimax-m2.1-lightning` | 197K | | | | | | $0.12 | $0.48 |
package/.docs/models/providers/opencode-go.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # ![OpenCode Go logo](https://models.dev/logos/opencode-go.svg)OpenCode Go
2
2
 
3
- Access 14 OpenCode Go models through Mastra's model router. Authentication is handled automatically using the `OPENCODE_API_KEY` environment variable.
3
+ Access 12 OpenCode Go models through Mastra's model router. Authentication is handled automatically using the `OPENCODE_API_KEY` environment variable.
4
4
 
5
5
  Learn more in the [OpenCode Go documentation](https://opencode.ai/docs/zen).
6
6
 
@@ -39,9 +39,7 @@ for await (const chunk of stream) {
39
39
  | `opencode-go/glm-5` | 203K | | | | | | $1 | $3 |
40
40
  | `opencode-go/glm-5.1` | 203K | | | | | | $1 | $4 |
41
41
  | `opencode-go/kimi-k2.5` | 262K | | | | | | $0.60 | $3 |
42
- | `opencode-go/kimi-k2.6` | 262K | | | | | | $0.32 | $1 |
43
- | `opencode-go/mimo-v2-omni` | 262K | | | | | | $0.40 | $2 |
44
- | `opencode-go/mimo-v2-pro` | 1.0M | | | | | | $1 | $3 |
42
+ | `opencode-go/kimi-k2.6` | 262K | | | | | | $0.95 | $4 |
45
43
  | `opencode-go/mimo-v2.5` | 1.0M | | | | | | $0.40 | $2 |
46
44
  | `opencode-go/mimo-v2.5-pro` | 1.0M | | | | | | $1 | $3 |
47
45
  | `opencode-go/minimax-m2.5` | 205K | | | | | | $0.30 | $1 |
package/.docs/models/providers/qiniu-ai.md CHANGED
@@ -81,7 +81,7 @@ for await (const chunk of stream) {
81
81
  | `qiniu-ai/kling-v2-6` | 100.0M | | | | | | — | — |
82
82
  | `qiniu-ai/meituan/longcat-flash-chat` | 131K | | | | | | — | — |
83
83
  | `qiniu-ai/meituan/longcat-flash-lite` | 256K | | | | | | — | — |
84
- | `qiniu-ai/mimo-v2-flash` | 256K | | | | | | — | — |
84
+ | `qiniu-ai/mimo-v2-flash` | 256K | | | | | | $0.10 | $0.30 |
85
85
  | `qiniu-ai/MiniMax-M1` | 1.0M | | | | | | — | — |
86
86
  | `qiniu-ai/minimax/minimax-m2` | 200K | | | | | | — | — |
87
87
  | `qiniu-ai/minimax/minimax-m2.1` | 205K | | | | | | — | — |
@@ -120,7 +120,7 @@ for await (const chunk of stream) {
120
120
  | `qiniu-ai/x-ai/grok-4.1-fast-non-reasoning` | 2.0M | | | | | | — | — |
121
121
  | `qiniu-ai/x-ai/grok-4.1-fast-reasoning` | 20.0M | | | | | | — | — |
122
122
  | `qiniu-ai/x-ai/grok-code-fast-1` | 256K | | | | | | — | — |
123
- | `qiniu-ai/xiaomi/mimo-v2-flash` | 256K | | | | | | — | — |
123
+ | `qiniu-ai/xiaomi/mimo-v2-flash` | 256K | | | | | | $0.10 | $0.30 |
124
124
  | `qiniu-ai/z-ai/autoglm-phone-9b` | 13K | | | | | | — | — |
125
125
  | `qiniu-ai/z-ai/glm-4.6` | 200K | | | | | | — | — |
126
126
  | `qiniu-ai/z-ai/glm-4.7` | 200K | | | | | | — | — |
package/.docs/models/providers/xiaomi.md CHANGED
@@ -34,8 +34,8 @@ for await (const chunk of stream) {
34
34
 
35
35
  | Model | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
36
36
  | ---------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
37
- | `xiaomi/mimo-v2-flash` | 256K | | | | | | $0.10 | $0.30 |
38
- | `xiaomi/mimo-v2-omni` | 256K | | | | | | $0.40 | $2 |
37
+ | `xiaomi/mimo-v2-flash` | 262K | | | | | | $0.10 | $0.30 |
38
+ | `xiaomi/mimo-v2-omni` | 262K | | | | | | $0.40 | $2 |
39
39
  | `xiaomi/mimo-v2-pro` | 1.0M | | | | | | $1 | $3 |
40
40
  | `xiaomi/mimo-v2.5` | 1.0M | | | | | | $0.40 | $2 |
41
41
  | `xiaomi/mimo-v2.5-pro` | 1.0M | | | | | | $1 | $3 |
package/.docs/models/providers/zenmux.md CHANGED
@@ -114,7 +114,7 @@ for await (const chunk of stream) {
114
114
  | `zenmux/x-ai/grok-code-fast-1` | 256K | | | | | | $0.20 | $2 |
115
115
  | `zenmux/xiaomi/mimo-v2-flash` | 262K | | | | | | $0.10 | $0.30 |
116
116
  | `zenmux/xiaomi/mimo-v2-omni` | 265K | | | | | | $0.40 | $2 |
117
- | `zenmux/xiaomi/mimo-v2-pro` | 1.0M | | | | | | $2 | $5 |
117
+ | `zenmux/xiaomi/mimo-v2-pro` | 1.0M | | | | | | $1 | $3 |
118
118
  | `zenmux/xiaomi/mimo-v2.5` | 1.0M | | | | | | $0.40 | $2 |
119
119
  | `zenmux/xiaomi/mimo-v2.5-pro` | 1.0M | | | | | | $1 | $3 |
120
120
  | `zenmux/z-ai/glm-4.5` | 128K | | | | | | $0.35 | $2 |
package/.docs/models/providers.md CHANGED
@@ -45,6 +45,7 @@ Direct access to individual AI model providers. Each provider offers unique mode
45
45
  - [Jiekou.AI](https://mastra.ai/models/providers/jiekou)
46
46
  - [Kilo Gateway](https://mastra.ai/models/providers/kilo)
47
47
  - [Kimi For Coding](https://mastra.ai/models/providers/kimi-for-coding)
48
+ - [Kiro](https://mastra.ai/models/providers/kiro)
48
49
  - [KUAE Cloud Coding Plan](https://mastra.ai/models/providers/kuae-cloud-coding-plan)
49
50
  - [Llama](https://mastra.ai/models/providers/llama)
50
51
  - [LLM Gateway](https://mastra.ai/models/providers/llmgateway)
package/.docs/reference/harness/harness-class.md CHANGED
@@ -3,6 +3,8 @@
3
3
  **Added in:** `@mastra/core@1.5.0`
4
4
 
5
5
  > **Warning:** The `Harness` class is in alpha stage and subject to change. It won't follow semantic versioning guarantees until it graduates from experimental status. Use with caution and expect breaking changes in minor versions.
6
+ >
7
+ > [Mastra Code](https://code.mastra.ai/) is the flagship implementation of the `Harness` class, showcasing how it can be used to build a powerful terminal-based coding agent with multi-model support, persistent conversations, and built-in tools.
6
8
 
7
9
  The `Harness` class orchestrates multiple agent modes, shared state, memory, and storage. It provides a control layer that a TUI or other UI can drive to manage threads, switch models and modes, send messages, handle tool approvals, and track events.
8
10
 
package/.docs/reference/index.md CHANGED
@@ -168,6 +168,7 @@ The Reference section provides documentation of Mastra's API, including paramete
168
168
  - [PrefillErrorHandler](https://mastra.ai/reference/processors/prefill-error-handler)
169
169
  - [Processor Interface](https://mastra.ai/reference/processors/processor-interface)
170
170
  - [PromptInjectionDetector](https://mastra.ai/reference/processors/prompt-injection-detector)
171
+ - [ProviderHistoryCompat](https://mastra.ai/reference/processors/provider-history-compat)
171
172
  - [RegexFilterProcessor](https://mastra.ai/reference/processors/regex-filter-processor)
172
173
  - [SemanticRecall](https://mastra.ai/reference/processors/semantic-recall-processor)
173
174
  - [SkillSearchProcessor](https://mastra.ai/reference/processors/skill-search-processor)
package/.docs/reference/processors/processor-interface.md CHANGED
@@ -4,7 +4,7 @@ The `Processor` interface defines the contract for all processors in Mastra. Pro
4
4
 
5
5
  ## When processor methods run
6
6
 
7
- The six processor methods run at different points in the agent execution lifecycle:
7
+ The seven processor methods run at different points in the agent execution lifecycle:
8
8
 
9
9
  ```text
10
10
  ┌─────────────────────────────────────────────────────────────────┐
@@ -26,6 +26,11 @@ The six processor methods run at different points in the agent execution lifecyc
26
26
  │ │ └──────────┬──────────┘ │ │
27
27
  │ │ │ │ │
28
28
  │ │ ▼ │ │
29
+ │ │ ┌─────────────────────┐ │ │
30
+ │ │ │ processLLMRequest │ ← Runs before provider call │ │
31
+ │ │ └──────────┬──────────┘ │ │
32
+ │ │ │ │ │
33
+ │ │ ▼ │ │
29
34
  │ │ LLM Execution ──── API Error? ──┐ │ │
30
35
  │ │ │ │ │ │
31
36
  │ │ │ ┌───────────────────┐ │ │
@@ -59,14 +64,15 @@ The six processor methods run at different points in the agent execution lifecyc
59
64
  └─────────────────────────────────────────────────────────────────┘
60
65
  ```
61
66
 
62
- | Method | When it runs | Use case |
63
- | --------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------- |
64
- | `processInput` | Once at the start, before the agentic loop | Validate/transform initial user input, add context |
65
- | `processInputStep` | At each step of the agentic loop, before each LLM call | Transform messages between steps, handle tool results |
66
- | `processAPIError` | When an LLM API call fails | Inspect API rejections, optionally mutate state/messages, and request a retry |
67
- | `processOutputStream` | On each streaming chunk during LLM response | Filter/modify streaming content, detect patterns in real-time |
68
- | `processOutputStep` | After each LLM response, before tool execution | Validate output quality, implement guardrails with retry |
69
- | `processOutputResult` | Once after generation completes | Post-process final response, log results |
67
+ | Method | When it runs | Use case |
68
+ | --------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
69
+ | `processInput` | Once at the start, before the agentic loop | Validate/transform initial user input, add context |
70
+ | `processInputStep` | At each step of the agentic loop, before each LLM call | Transform messages between steps, handle tool results |
71
+ | `processLLMRequest` | After LLM request conversion, before the provider call | Rewrite the outbound `LanguageModelV2Prompt` for the current call without persisting changes |
72
+ | `processAPIError` | When an LLM API call fails | Inspect API rejections, optionally mutate state/messages, and request a retry |
73
+ | `processOutputStream` | On each streaming chunk during LLM response | Filter/modify streaming content, detect patterns in real-time |
74
+ | `processOutputStep` | After each LLM response, before tool execution | Validate output quality, implement guardrails with retry |
75
+ | `processOutputResult` | Once after generation completes | Post-process final response, log results |
70
76
 
71
77
  ## Interface definition
72
78
 
@@ -97,6 +103,10 @@ interface Processor<TId extends string = string, TTripwireMetadata = unknown> {
97
103
  | void
98
104
  | undefined
99
105
 
106
+ processLLMRequest?(
107
+ args: ProcessLLMRequestArgs<TTripwireMetadata>,
108
+ ): Promise<ProcessLLMRequestResult> | ProcessLLMRequestResult
109
+
100
110
  processAPIError?(
101
111
  args: ProcessAPIErrorArgs<TTripwireMetadata>,
102
112
  ): Promise<ProcessAPIErrorResult | void> | ProcessAPIErrorResult | void
@@ -243,9 +253,10 @@ processInputStep?<TTripwireMetadata = unknown>(
243
253
  1. `processInput` (once at start)
244
254
  2. `processInputStep` from inputProcessors (at each step, before LLM call)
245
255
  3. `prepareStep` callback (runs as part of the processInputStep pipeline, after inputProcessors)
246
- 4. LLM execution
247
- 5. Tool execution (if needed)
248
- 6. Repeat from step 2 if tools were called
256
+ 4. `processLLMRequest` from inputProcessors (after prompt conversion, before the provider call)
257
+ 5. LLM execution
258
+ 6. Tool execution (if needed)
259
+ 7. Repeat from step 2 if tools were called
249
260
 
250
261
  #### `ProcessInputStepArgs`
251
262
 
@@ -339,6 +350,57 @@ System messages are **reset to their original values** at the start of each step
339
350
 
340
351
  ***
341
352
 
353
+ ### `processLLMRequest`
354
+
355
+ Processes the final LLM request after Mastra converts the `MessageList` into `LanguageModelV2Prompt` and before the provider call. Use this method for transient, model-aware rewrites that should affect only the current outbound request.
356
+
357
+ Returned prompt changes are forwarded to the model for the current call only. They are not persisted back to `MessageList`, memory, UI history, or later provider calls.
358
+
359
+ ```typescript
360
+ processLLMRequest?(
361
+ args: ProcessLLMRequestArgs,
362
+ ): Promise<ProcessLLMRequestResult> | ProcessLLMRequestResult;
363
+ ```
364
+
365
+ #### `ProcessLLMRequestArgs`
366
+
367
+ **prompt** (`LanguageModelV2Prompt`): The LLM request prompt that will be sent to the provider for this call.
368
+
369
+ **model** (`MastraLanguageModel`): The resolved model that will receive the prompt. Use this to scope provider-specific rewrites.
370
+
371
+ **stepNumber** (`number`): Current step number (0-indexed). Step 0 is the initial LLM call.
372
+
373
+ **steps** (`StepResult[]`): Results from previous steps, including text, toolCalls, and toolResults.
374
+
375
+ **state** (`Record<string, unknown>`): Per-processor state that persists across all method calls within this request.
376
+
377
+ **abort** (`(reason?: string, options?: { retry?: boolean; metadata?: unknown }) => never`): Function to abort processing. Throws a TripWire error that stops execution and emits a \`tripwire\` chunk.
378
+
379
+ **retryCount** (`number`): Current retry attempt count from \`ProcessorContext\`. Starts at \`0\`; use to cap processor-triggered retries.
380
+
381
+ **requestContext** (`RequestContext`): Request-scoped context with execution metadata.
382
+
383
+ **tracingContext** (`TracingContext`): Tracing context for observability.
384
+
385
+ **writer** (`ProcessorStreamWriter`): Stream writer for emitting custom data chunks during streaming. Use \`writer.custom()\` to send transient UI signals.
386
+
387
+ **abortSignal** (`AbortSignal`): Signal for cancelling the operation.
388
+
389
+ #### Return value
390
+
391
+ `processLLMRequest` returns `ProcessLLMRequestResult`, which is `{ prompt?: LanguageModelV2Prompt } | undefined | void`.
392
+
393
+ - Return `{ prompt }` to replace the outbound prompt for the current provider call.
394
+ - Return `undefined` or `void` to forward the original prompt unchanged.
395
+
396
+ #### Use cases
397
+
398
+ - Removing or reshaping provider-specific prompt parts before a model call
399
+ - Normalizing roles or content to match a provider's input requirements
400
+ - Adapting tool result formats when switching providers mid-loop
401
+
402
+ ***
403
+
342
404
  ### `processAPIError`
343
405
 
344
406
  Handles LLM API rejection errors before they surface as final errors. This runs when the API call fails with a non-retryable error (such as a 400 or 422 status code). Unlike `processOutputStep` which runs after successful responses, this runs when the API rejects the request.
package/.docs/reference/processors/provider-history-compat.md ADDED
@@ -0,0 +1,132 @@
1
+ # ProviderHistoryCompat
2
+
3
+ The `ProviderHistoryCompat` processor handles provider-specific history incompatibilities. It can rewrite the outbound language model prompt before a provider call, or react to API errors and retry with repaired message history.
4
+
5
+ Use it when an agent may switch between model providers, reuse message history across providers, or call a provider that rejects fields emitted by another provider.
6
+
7
+ ## Usage example
8
+
9
+ Add `ProviderHistoryCompat` to `inputProcessors` when you want all built-in compatibility rules available for an agent:
10
+
11
+ ```typescript
12
+ import { Agent } from '@mastra/core/agent'
13
+ import { ProviderHistoryCompat } from '@mastra/core/processors'
14
+
15
+ export const agent = new Agent({
16
+ name: 'my-agent',
17
+ instructions: 'You are a helpful assistant.',
18
+ model: 'anthropic/claude-sonnet-4-5',
19
+ inputProcessors: [new ProviderHistoryCompat()],
20
+ })
21
+ ```
22
+
23
+ Mastra agents don't add this processor automatically. Add it explicitly when you need provider history compatibility rules, reactive API error recovery, custom rules, or predictable processor ordering.
24
+
25
+ ## Constructor parameters
26
+
27
+ **opts** (`{ additionalRules?: CompatRule[] }`): Configuration options for provider history compatibility rules.
28
+
29
+ **opts.additionalRules** (`CompatRule[]`): Custom compatibility rules to run after the built-in rules. Rules can rewrite the outbound prompt or repair persisted messages after matching an API error.
30
+
31
+ ## Properties
32
+
33
+ **id** (`'provider-history-compat'`): Processor identifier.
34
+
35
+ **name** (`'Provider History Compat'`): Processor display name.
36
+
37
+ **processLLMRequest** (`(args: ProcessLLMRequestArgs) => ProcessLLMRequestResult`): Runs preemptive compatibility rules against the converted LanguageModelV2Prompt immediately before the provider call. Returned prompt changes are transient and are not persisted to memory or message history.
38
+
39
+ **processAPIError** (`(args: ProcessAPIErrorArgs) => Promise<ProcessAPIErrorResult | void>`): Runs reactive compatibility rules when a provider rejects the request. Matching rules can mutate the message list and return retry: true on the first retry attempt.
40
+
41
+ ## Built-in rules
42
+
43
+ `ProviderHistoryCompat` includes these built-in compatibility rules:
44
+
45
+ | Rule | Provider | Timing | Behavior |
46
+ | ------------------------------------------- | --------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
47
+ | `anthropic-tool-id-format` | Anthropic | Reactive API error recovery | Rewrites tool call IDs that contain characters outside `[a-zA-Z0-9_-]` and retries the request. |
48
+ | `cerebras-strip-reasoning-content` | Cerebras | Preemptive prompt rewrite | Removes assistant `reasoning` parts from the outbound prompt so they're not serialized as unsupported `reasoning_content` fields. |
49
+ | `anthropic-strip-foreign-reasoning-content` | Anthropic | Preemptive prompt rewrite | Removes non-Anthropic assistant `reasoning` parts from the outbound prompt. Anthropic-native thinking history is preserved. |
50
+
51
+ Preemptive rules run through `processLLMRequest` after Mastra converts messages to the model prompt format and before the prompt is sent to the provider. These rewrites affect only the current provider call.
52
+
53
+ Reactive rules run through `processAPIError` after a provider rejection. They can update the persisted `messageList` and request a retry.
54
+
55
+ ## `CompatRule`
56
+
57
+ A `CompatRule` defines one provider history compatibility fix:
58
+
59
+ ```typescript
60
+ import type { CompatRule } from '@mastra/core/processors'
61
+
62
+ const removeUnsupportedPromptParts: CompatRule = {
63
+ name: 'remove-unsupported-prompt-parts',
64
+ applyToPrompt({ prompt, model }) {
65
+ // Return a modified LanguageModelV2Prompt, or undefined to leave it unchanged.
66
+ return undefined
67
+ },
68
+ }
69
+ ```
70
+
71
+ **name** (`string`): Human-readable rule identifier for logs and debugging.
72
+
73
+ **errorPatterns** (`RegExp[]`): Patterns matched against provider API error messages and response bodies. Required for reactive rules that implement fix.
74
+
75
+ **fix** (`(messages: MastraDBMessage[]) => boolean`): Reactive fix that mutates persisted database messages after a matching API error. Return true when the rule changed messages and the request should retry.
76
+
77
+ **applyToPrompt** (`(args: { prompt: LanguageModelV2Prompt; model: unknown }) => LanguageModelV2Prompt | undefined`): Preemptive fix that rewrites the outbound prompt for the current provider call. Return undefined when no prompt change is needed.
78
+
79
+ ## Custom rules
80
+
81
+ Pass custom rules through `additionalRules`. Custom rules run after the built-in rules:
82
+
83
+ ```typescript
84
+ import { Agent } from '@mastra/core/agent'
85
+ import { ProviderHistoryCompat, type CompatRule } from '@mastra/core/processors'
86
+
87
+ const stripUnsupportedAssistantMetadata: CompatRule = {
88
+ name: 'strip-unsupported-assistant-metadata',
89
+ applyToPrompt({ prompt, model }) {
90
+ if (typeof model !== 'string' || !model.startsWith('example-provider/')) {
91
+ return undefined
92
+ }
93
+
94
+ let changed = false
95
+ const nextPrompt = prompt.map(message => {
96
+ if (message.role !== 'assistant' || typeof message.content === 'string') {
97
+ return message
98
+ }
99
+
100
+ const nextContent = message.content.map(part => {
101
+ if (!('providerOptions' in part)) return part
102
+ changed = true
103
+ const { providerOptions: _providerOptions, ...rest } = part
104
+ return rest
105
+ })
106
+
107
+ return { ...message, content: nextContent }
108
+ })
109
+
110
+ return changed ? nextPrompt : undefined
111
+ },
112
+ }
113
+
114
+ export const agent = new Agent({
115
+ name: 'custom-provider-agent',
116
+ instructions: 'You are a helpful assistant.',
117
+ model: 'example-provider/model',
118
+ inputProcessors: [
119
+ new ProviderHistoryCompat({
120
+ additionalRules: [stripUnsupportedAssistantMetadata],
121
+ }),
122
+ ],
123
+ })
124
+ ```
125
+
126
+ Use `applyToPrompt` for provider-specific rewrites that shouldn't be saved to memory. Use `fix` with `errorPatterns` when the provider rejects persisted message history and the repaired history should be reused on future turns.
127
+
128
+ ## Related
129
+
130
+ - [Processor interface](https://mastra.ai/reference/processors/processor-interface)
131
+ - [Processors](https://mastra.ai/docs/agents/processors)
132
+ - [PrefillErrorHandler](https://mastra.ai/reference/processors/prefill-error-handler)
package/.docs/reference/tools/mcp-client.md CHANGED
@@ -987,6 +987,53 @@ await agent.generate('Hello!', {
987
987
  })
988
988
  ```
989
989
 
990
+ ## Handling auth failures inside custom fetch
991
+
992
+ A custom `fetch` should not `throw` when authentication is unavailable. The Streamable HTTP transport in the MCP SDK opens a long-lived `GET /mcp` "standalone listener" stream in the background to receive server-pushed notifications. Errors on that stream are retried with exponential backoff, and a thrown `fetch` or a cleanly-closed stream can produce an indefinite reconnect loop at roughly one attempt per second.
993
+
994
+ Return a synthetic `Response` instead. The [MCP Streamable HTTP specification](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports) defines `405 Method Not Allowed` as the signal a server returns when it does not offer the GET SSE stream, and the SDK honors it as a terminal status that stops the listener cleanly. Use this to disable the listener when your server does not push notifications.
995
+
996
+ The following pattern waits for an auth token on POST requests, attaches it to outgoing headers, and short-circuits the GET listener with a synthetic 405:
997
+
998
+ ```typescript
999
+ async function waitForToken(timeoutMs = 5000): Promise<string | null> {
1000
+ // Replace with your token lookup. Return null if no token is available.
1001
+ return getAuthToken({ timeoutMs })
1002
+ }
1003
+
1004
+ const mcpClient = new MCPClient({
1005
+ servers: {
1006
+ apiServer: {
1007
+ url: new URL('https://api.example.com/mcp'),
1008
+ fetch: async (url, init) => {
1009
+ const method = (init?.method || 'GET').toUpperCase()
1010
+
1011
+ // The SDK opens a background GET stream for server-pushed notifications.
1012
+ // If your server does not use it, short-circuit with 405 to stop reconnect attempts.
1013
+ if (method === 'GET') {
1014
+ return new Response(null, { status: 405, statusText: 'Method Not Allowed' })
1015
+ }
1016
+
1017
+ // POST: wait for the token, then forward the request with an Authorization header.
1018
+ const token = await waitForToken()
1019
+ if (!token) {
1020
+ // Forward the request without a token and let the server reject it.
1021
+ // The SDK surfaces non-2xx POST responses as errors to the caller of
1022
+ // tools/list, tools/call, etc., which is the desired behavior here.
1023
+ return fetch(url, init)
1024
+ }
1025
+
1026
+ const headers = new Headers(init?.headers)
1027
+ headers.set('authorization', `Bearer ${token}`)
1028
+ return fetch(url, { ...init, headers })
1029
+ },
1030
+ },
1031
+ },
1032
+ })
1033
+ ```
1034
+
1035
+ Return `405` for the GET listener only when your server does not push notifications back to the client. If your server uses the standalone GET stream, attach the auth token on `GET` requests as well and let the request through.
1036
+
990
1037
  ## Using SSE request headers
991
1038
 
992
1039
  When using the legacy SSE MCP transport, you must configure both `requestInit` and `eventSourceInit` due to a bug in the MCP SDK. Alternatively, you can use a custom `fetch` function which will be automatically used for both POST requests and SSE connections:
package/CHANGELOG.md CHANGED
@@ -1,5 +1,19 @@
1
1
  # @mastra/mcp-docs-server
2
2
 
3
+ ## 1.1.35-alpha.6
4
+
5
+ ### Patch Changes
6
+
7
+ - Updated dependencies [[`d1fdbd0`](https://github.com/mastra-ai/mastra/commit/d1fdbd012add5623cb7e6b7f882b605ab358bbb4), [`d91ebe2`](https://github.com/mastra-ai/mastra/commit/d91ebe28ee065d8f2ed6df741c3c07f58d359529)]:
8
+ - @mastra/core@1.33.0-alpha.2
9
+
10
+ ## 1.1.35-alpha.4
11
+
12
+ ### Patch Changes
13
+
14
+ - Updated dependencies [[`dccd8f1`](https://github.com/mastra-ai/mastra/commit/dccd8f1f8b8f1ad203b77556207e5529567c616d)]:
15
+ - @mastra/core@1.33.0-alpha.1
16
+
3
17
  ## 1.1.35-alpha.1
4
18
 
5
19
  ### Patch Changes
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mastra/mcp-docs-server",
3
- "version": "1.1.35-alpha.3",
3
+ "version": "1.1.35-alpha.6",
4
4
  "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -29,8 +29,8 @@
29
29
  "jsdom": "^26.1.0",
30
30
  "local-pkg": "^1.1.2",
31
31
  "zod": "^4.3.6",
32
- "@mastra/core": "1.33.0-alpha.0",
33
- "@mastra/mcp": "^1.7.0"
32
+ "@mastra/mcp": "^1.7.0",
33
+ "@mastra/core": "1.33.0-alpha.2"
34
34
  },
35
35
  "devDependencies": {
36
36
  "@hono/node-server": "^1.19.11",
@@ -46,9 +46,9 @@
46
46
  "tsx": "^4.21.0",
47
47
  "typescript": "^6.0.3",
48
48
  "vitest": "4.1.5",
49
- "@internal/types-builder": "0.0.67",
50
- "@mastra/core": "1.33.0-alpha.0",
51
- "@internal/lint": "0.0.92"
49
+ "@internal/lint": "0.0.92",
50
+ "@mastra/core": "1.33.0-alpha.2",
51
+ "@internal/types-builder": "0.0.67"
52
52
  },
53
53
  "homepage": "https://mastra.ai",
54
54
  "repository": {