@mastra/mcp-docs-server 1.2.14 → 1.2.15-alpha.1

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 (12) hide show
  1. package/.docs/models/gateways/neon.md +6 -6
  2. package/.docs/models/gateways/openrouter.md +2 -1
  3. package/.docs/models/index.md +1 -1
  4. package/.docs/models/providers/anthropic.md +2 -2
  5. package/.docs/models/providers/minimax.md +25 -23
  6. package/.docs/models/providers/openai.md +28 -26
  7. package/.docs/models/providers/perplexity-agent.md +24 -24
  8. package/.docs/models/providers/pioneer.md +27 -1
  9. package/.docs/reference/file-based-agents/schedules.md +232 -0
  10. package/.docs/reference/index.md +1 -0
  11. package/CHANGELOG.md +7 -0
  12. package/package.json +6 -6
package/.docs/models/gateways/neon.md CHANGED
@@ -9,14 +9,14 @@ Learn more in the [Neon documentation](https://neon.com/docs).
9
9
  ## Usage
10
10
 
11
11
  ```typescript
12
- import { Agent } from '@mastra/core/agent'
12
+ import { Agent } from "@mastra/core/agent";
13
13
 
14
14
  const agent = new Agent({
15
- id: 'my-agent',
16
- name: 'My Agent',
17
- instructions: 'You are a helpful assistant',
18
- model: 'neon/claude-haiku-4-5',
19
- })
15
+ id: "my-agent",
16
+ name: "My Agent",
17
+ instructions: "You are a helpful assistant",
18
+ model: "neon/claude-haiku-4-5"
19
+ });
20
20
  ```
21
21
 
22
22
  > **Info:** Mastra uses the OpenAI-compatible `/chat/completions` endpoint. Some provider-specific features may not be available. Check the [Neon documentation](https://neon.com/docs) for details.
package/.docs/models/gateways/openrouter.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  # ![OpenRouter logo](https://models.dev/logos/openrouter.svg)OpenRouter
4
4
 
5
- OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 337 models through Mastra's model router.
5
+ OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 338 models through Mastra's model router.
6
6
 
7
7
  Learn more in the [OpenRouter documentation](https://openrouter.ai/models).
8
8
 
@@ -155,6 +155,7 @@ ANTHROPIC_API_KEY=ant-...
155
155
  | `meta-llama/llama-4-scout` |
156
156
  | `meta-llama/llama-guard-4-12b` |
157
157
  | `meta/muse-spark-1.1` |
158
+ | `meta/muse-spark-1.2` |
158
159
  | `microsoft/phi-4` |
159
160
  | `microsoft/wizardlm-2-8x22b` |
160
161
  | `minimax/minimax-01` |
package/.docs/models/index.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  # Model Providers
4
4
 
5
- Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 5336 models from 168 providers through a single API.
5
+ Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 5361 models from 168 providers through a single API.
6
6
 
7
7
  ## Features
8
8
 
package/.docs/models/providers/anthropic.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  # ![Anthropic logo](https://models.dev/logos/anthropic.svg)Anthropic
4
4
 
5
- Access 15 Anthropic models through Mastra's model router. Authentication is handled automatically using the `ANTHROPIC_API_KEY` environment variable.
5
+ Access 13 Anthropic models through Mastra's model router. Authentication is handled automatically using the `ANTHROPIC_API_KEY` environment variable.
6
6
 
7
7
  Learn more in the [Anthropic documentation](https://docs.anthropic.com/en/docs/about-claude/models).
8
8
 
@@ -123,7 +123,7 @@ const response = await agent.generate("Hello!", {
123
123
 
124
124
  **inferenceGeo** (`"us" | "global" | undefined`)
125
125
 
126
- **fallbacks** (`{ model: string; max_tokens?: number | undefined; thinking?: Record<string, unknown> | undefined; output_config?: Record<string, unknown> | undefined; speed?: "fast" | "standard" | undefined; }[] | undefined`)
126
+ **fallbacks** (`"default" | { model: string; max_tokens?: number | undefined; thinking?: Record<string, unknown> | undefined; output_config?: Record<string, unknown> | undefined; speed?: "fast" | "standard" | undefined; }[] | undefined`)
127
127
 
128
128
  **anthropicBeta** (`string[] | undefined`)
129
129
 
package/.docs/models/providers/minimax.md CHANGED
@@ -11,22 +11,22 @@ MINIMAX_API_KEY=your-api-key
11
11
  ```
12
12
 
13
13
  ```typescript
14
- import { Agent } from '@mastra/core/agent'
14
+ import { Agent } from "@mastra/core/agent";
15
15
 
16
16
  const agent = new Agent({
17
- id: 'my-agent',
18
- name: 'My Agent',
19
- instructions: 'You are a helpful assistant',
20
- model: 'minimax/MiniMax-M2',
21
- })
17
+ id: "my-agent",
18
+ name: "My Agent",
19
+ instructions: "You are a helpful assistant",
20
+ model: "minimax/MiniMax-M2"
21
+ });
22
22
 
23
23
  // Generate a response
24
- const response = await agent.generate('Hello!')
24
+ const response = await agent.generate("Hello!");
25
25
 
26
26
  // Stream a response
27
- const stream = await agent.stream('Tell me a story')
27
+ const stream = await agent.stream("Tell me a story");
28
28
  for await (const chunk of stream) {
29
- console.log(chunk)
29
+ console.log(chunk);
30
30
  }
31
31
  ```
32
32
 
@@ -50,30 +50,32 @@ for await (const chunk of stream) {
50
50
 
51
51
  ```typescript
52
52
  const agent = new Agent({
53
- id: 'custom-agent',
54
- name: 'custom-agent',
53
+ id: "custom-agent",
54
+ name: "custom-agent",
55
55
  model: {
56
- url: 'https://api.minimax.io/anthropic/v1',
57
- id: 'minimax/MiniMax-M2',
56
+ url: "https://api.minimax.io/anthropic/v1",
57
+ id: "minimax/MiniMax-M2",
58
58
  apiKey: process.env.MINIMAX_API_KEY,
59
59
  headers: {
60
- 'X-Custom-Header': 'value',
61
- },
62
- },
63
- })
60
+ "X-Custom-Header": "value"
61
+ }
62
+ }
63
+ });
64
64
  ```
65
65
 
66
66
  ### Dynamic model selection
67
67
 
68
68
  ```typescript
69
69
  const agent = new Agent({
70
- id: 'dynamic-agent',
71
- name: 'Dynamic Agent',
70
+ id: "dynamic-agent",
71
+ name: "Dynamic Agent",
72
72
  model: ({ requestContext }) => {
73
- const useAdvanced = requestContext.task === 'complex'
74
- return useAdvanced ? 'minimax/MiniMax-M3' : 'minimax/MiniMax-M2'
75
- },
76
- })
73
+ const useAdvanced = requestContext.task === "complex";
74
+ return useAdvanced
75
+ ? "minimax/MiniMax-M3"
76
+ : "minimax/MiniMax-M2";
77
+ }
78
+ });
77
79
  ```
78
80
 
79
81
  ## Direct provider installation
package/.docs/models/providers/openai.md CHANGED
@@ -11,22 +11,22 @@ OPENAI_API_KEY=your-api-key
11
11
  ```
12
12
 
13
13
  ```typescript
14
- import { Agent } from '@mastra/core/agent'
14
+ import { Agent } from "@mastra/core/agent";
15
15
 
16
16
  const agent = new Agent({
17
- id: 'my-agent',
18
- name: 'My Agent',
19
- instructions: 'You are a helpful assistant',
20
- model: 'openai/chatgpt-image-latest',
21
- })
17
+ id: "my-agent",
18
+ name: "My Agent",
19
+ instructions: "You are a helpful assistant",
20
+ model: "openai/chatgpt-image-latest"
21
+ });
22
22
 
23
23
  // Generate a response
24
- const response = await agent.generate('Hello!')
24
+ const response = await agent.generate("Hello!");
25
25
 
26
26
  // Stream a response
27
- const stream = await agent.stream('Tell me a story')
27
+ const stream = await agent.stream("Tell me a story");
28
28
  for await (const chunk of stream) {
29
- console.log(chunk)
29
+ console.log(chunk);
30
30
  }
31
31
  ```
32
32
 
@@ -78,29 +78,31 @@ for await (const chunk of stream) {
78
78
 
79
79
  ```typescript
80
80
  const agent = new Agent({
81
- id: 'custom-agent',
82
- name: 'custom-agent',
81
+ id: "custom-agent",
82
+ name: "custom-agent",
83
83
  model: {
84
- id: 'openai/chatgpt-image-latest',
84
+ id: "openai/chatgpt-image-latest",
85
85
  apiKey: process.env.OPENAI_API_KEY,
86
86
  headers: {
87
- 'X-Custom-Header': 'value',
88
- },
89
- },
90
- })
87
+ "X-Custom-Header": "value"
88
+ }
89
+ }
90
+ });
91
91
  ```
92
92
 
93
93
  ### Dynamic model selection
94
94
 
95
95
  ```typescript
96
96
  const agent = new Agent({
97
- id: 'dynamic-agent',
98
- name: 'Dynamic Agent',
97
+ id: "dynamic-agent",
98
+ name: "Dynamic Agent",
99
99
  model: ({ requestContext }) => {
100
- const useAdvanced = requestContext.task === 'complex'
101
- return useAdvanced ? 'openai/text-embedding-ada-002' : 'openai/chatgpt-image-latest'
102
- },
103
- })
100
+ const useAdvanced = requestContext.task === "complex";
101
+ return useAdvanced
102
+ ? "openai/text-embedding-ada-002"
103
+ : "openai/chatgpt-image-latest";
104
+ }
105
+ });
104
106
  ```
105
107
 
106
108
  ## Provider Options
@@ -108,13 +110,13 @@ const agent = new Agent({
108
110
  OpenAI supports the following provider-specific options via the `providerOptions` parameter:
109
111
 
110
112
  ```typescript
111
- const response = await agent.generate('Hello!', {
113
+ const response = await agent.generate("Hello!", {
112
114
  providerOptions: {
113
115
  openai: {
114
116
  // See available options in the table below
115
- },
116
- },
117
- })
117
+ }
118
+ }
119
+ });
118
120
  ```
119
121
 
120
122
  ### Available Options
package/.docs/models/providers/perplexity-agent.md CHANGED
@@ -11,22 +11,22 @@ PERPLEXITY_API_KEY=your-api-key
11
11
  ```
12
12
 
13
13
  ```typescript
14
- import { Agent } from '@mastra/core/agent'
14
+ import { Agent } from "@mastra/core/agent";
15
15
 
16
16
  const agent = new Agent({
17
- id: 'my-agent',
18
- name: 'My Agent',
19
- instructions: 'You are a helpful assistant',
20
- model: 'perplexity-agent/anthropic/claude-haiku-4-5',
21
- })
17
+ id: "my-agent",
18
+ name: "My Agent",
19
+ instructions: "You are a helpful assistant",
20
+ model: "perplexity-agent/anthropic/claude-haiku-4-5"
21
+ });
22
22
 
23
23
  // Generate a response
24
- const response = await agent.generate('Hello!')
24
+ const response = await agent.generate("Hello!");
25
25
 
26
26
  // Stream a response
27
- const stream = await agent.stream('Tell me a story')
27
+ const stream = await agent.stream("Tell me a story");
28
28
  for await (const chunk of stream) {
29
- console.log(chunk)
29
+ console.log(chunk);
30
30
  }
31
31
  ```
32
32
 
@@ -63,32 +63,32 @@ for await (const chunk of stream) {
63
63
 
64
64
  ```typescript
65
65
  const agent = new Agent({
66
- id: 'custom-agent',
67
- name: 'custom-agent',
66
+ id: "custom-agent",
67
+ name: "custom-agent",
68
68
  model: {
69
- url: 'https://api.perplexity.ai/v1',
70
- id: 'perplexity-agent/anthropic/claude-haiku-4-5',
69
+ url: "https://api.perplexity.ai/v1",
70
+ id: "perplexity-agent/anthropic/claude-haiku-4-5",
71
71
  apiKey: process.env.PERPLEXITY_API_KEY,
72
72
  headers: {
73
- 'X-Custom-Header': 'value',
74
- },
75
- },
76
- })
73
+ "X-Custom-Header": "value"
74
+ }
75
+ }
76
+ });
77
77
  ```
78
78
 
79
79
  ### Dynamic model selection
80
80
 
81
81
  ```typescript
82
82
  const agent = new Agent({
83
- id: 'dynamic-agent',
84
- name: 'Dynamic Agent',
83
+ id: "dynamic-agent",
84
+ name: "Dynamic Agent",
85
85
  model: ({ requestContext }) => {
86
- const useAdvanced = requestContext.task === 'complex'
86
+ const useAdvanced = requestContext.task === "complex";
87
87
  return useAdvanced
88
- ? 'perplexity-agent/xai/grok-4-1-fast-non-reasoning'
89
- : 'perplexity-agent/anthropic/claude-haiku-4-5'
90
- },
91
- })
88
+ ? "perplexity-agent/xai/grok-4-1-fast-non-reasoning"
89
+ : "perplexity-agent/anthropic/claude-haiku-4-5";
90
+ }
91
+ });
92
92
  ```
93
93
 
94
94
  ## Direct provider installation
package/.docs/models/providers/pioneer.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  # ![Pioneer logo](https://models.dev/logos/pioneer.svg)Pioneer
4
4
 
5
- Access 76 Pioneer models through Mastra's model router. Authentication is handled automatically using the `PIONEER_API_KEY` environment variable.
5
+ Access 102 Pioneer models through Mastra's model router. Authentication is handled automatically using the `PIONEER_API_KEY` environment variable.
6
6
 
7
7
  Learn more in the [Pioneer documentation](https://agent.pioneer.ai/llms.txt).
8
8
 
@@ -36,16 +36,23 @@ for await (const chunk of stream) {
36
36
 
37
37
  | Model | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
38
38
  | ------------------------------------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
39
+ | `pioneer/claude-3-7-sonnet-latest` | 1.0M | | | | | | $3 | $15 |
40
+ | `pioneer/claude-fable-5` | 1.0M | | | | | | $11 | $55 |
39
41
  | `pioneer/claude-haiku-4-5` | 200K | | | | | | $1 | $5 |
40
42
  | `pioneer/claude-opus-4-1` | 200K | | | | | | $15 | $75 |
41
43
  | `pioneer/claude-opus-4-5` | 200K | | | | | | $5 | $25 |
42
44
  | `pioneer/claude-opus-4-6` | 1.0M | | | | | | $5 | $25 |
43
45
  | `pioneer/claude-opus-4-7` | 1.0M | | | | | | $5 | $25 |
44
46
  | `pioneer/claude-opus-4-8` | 1.0M | | | | | | $5 | $25 |
47
+ | `pioneer/claude-opus-5` | 1.0M | | | | | | $5 | $25 |
45
48
  | `pioneer/claude-sonnet-4-5` | 1.0M | | | | | | $3 | $15 |
46
49
  | `pioneer/claude-sonnet-4-6` | 1.0M | | | | | | $3 | $15 |
50
+ | `pioneer/claude-sonnet-5` | 1.0M | | | | | | $2 | $10 |
51
+ | `pioneer/deepseek-ai/DeepSeek-V3` | 164K | | | | | | $0.27 | $1 |
52
+ | `pioneer/deepseek-ai/DeepSeek-V3.1` | 164K | | | | | | $0.56 | $2 |
47
53
  | `pioneer/deepseek-ai/DeepSeek-V4-Flash` | 1.0M | | | | | | $0.10 | $0.20 |
48
54
  | `pioneer/deepseek-ai/DeepSeek-V4-Pro` | 1.0M | | | | | | $0.43 | $0.87 |
55
+ | `pioneer/devstral-2` | 256K | | | | | | $0.40 | $2 |
49
56
  | `pioneer/fastino/gliguard-LLMGuardrails-300M` | 8K | | | | | | $0.15 | $0.15 |
50
57
  | `pioneer/fastino/gliner2-base-v1` | 8K | | | | | | $0.15 | $0.15 |
51
58
  | `pioneer/fastino/gliner2-large-v1` | 8K | | | | | | $0.15 | $0.15 |
@@ -53,8 +60,11 @@ for await (const chunk of stream) {
53
60
  | `pioneer/fastino/gliner2-multi-v1` | 8K | | | | | | $0.15 | $0.15 |
54
61
  | `pioneer/fastino/gliner2-privacy-filter-PII-multi` | 8K | | | | | | $0.15 | $0.15 |
55
62
  | `pioneer/gemini-3-flash` | 1.0M | | | | | | $0.50 | $3 |
63
+ | `pioneer/gemini-3.1-flash-lite` | 1.0M | | | | | | $0.25 | $2 |
56
64
  | `pioneer/gemini-3.1-pro` | 1.0M | | | | | | $2 | $12 |
57
65
  | `pioneer/gemini-3.5-flash` | 1.0M | | | | | | $2 | $9 |
66
+ | `pioneer/gemini-3.5-flash-lite` | 1.0M | | | | | | $0.30 | $3 |
67
+ | `pioneer/gemini-3.6-flash` | 1.0M | | | | | | $2 | $8 |
58
68
  | `pioneer/google/diffusiongemma-26B-A4B-it` | 262K | | | | | | $0.50 | $0.50 |
59
69
  | `pioneer/google/gemma-3-4b-pt` | 33K | | | | | | $0.15 | $0.15 |
60
70
  | `pioneer/google/gemma-4-12B-it` | 33K | | | | | | $0.25 | $0.25 |
@@ -74,27 +84,43 @@ for await (const chunk of stream) {
74
84
  | `pioneer/gpt-5.4-mini` | 400K | | | | | | $0.75 | $5 |
75
85
  | `pioneer/gpt-5.4-nano` | 1.0M | | | | | | $0.20 | $1 |
76
86
  | `pioneer/gpt-5.5` | 1.1M | | | | | | $5 | $30 |
87
+ | `pioneer/gpt-5.6-luna` | 1.1M | | | | | | $1 | $6 |
88
+ | `pioneer/gpt-5.6-sol` | 1.1M | | | | | | $5 | $30 |
89
+ | `pioneer/gpt-5.6-terra` | 1.1M | | | | | | $3 | $15 |
90
+ | `pioneer/grok-4.5` | 500K | | | | | | $2 | $6 |
77
91
  | `pioneer/HuggingFaceTB/SmolLM3-3B-Base` | 33K | | | | | | $0.15 | $0.15 |
78
92
  | `pioneer/LiquidAI/LFM2-24B-A2B` | 33K | | | | | | $0.03 | $0.12 |
79
93
  | `pioneer/meta-llama/Llama-3.1-8B-Instruct` | 131K | | | | | | $0.20 | $0.20 |
94
+ | `pioneer/meta-llama/Llama-3.2-1B` | 131K | | | | | | $0.10 | $0.10 |
80
95
  | `pioneer/meta-llama/Llama-3.2-1B-Instruct` | 131K | | | | | | $0.10 | $0.20 |
96
+ | `pioneer/meta-llama/Llama-3.2-3B` | 131K | | | | | | $0.10 | $0.10 |
81
97
  | `pioneer/meta-llama/Llama-3.2-3B-Instruct` | 131K | | | | | | $0.10 | $0.34 |
82
98
  | `pioneer/meta-llama/Llama-3.3-70B-Instruct` | 131K | | | | | | $0.90 | $0.90 |
99
+ | `pioneer/meta/muse-spark-1.1` | 1.0M | | | | | | $1 | $4 |
83
100
  | `pioneer/MiniMaxAI/MiniMax-M2.7` | 205K | | | | | | $0.28 | $1 |
84
101
  | `pioneer/MiniMaxAI/MiniMax-M3` | 1.0M | | | | | | $0.30 | $1 |
102
+ | `pioneer/mistral-large-3` | 256K | | | | | | $0.50 | $2 |
85
103
  | `pioneer/mistral-medium-3.5` | 262K | | | | | | $2 | $8 |
104
+ | `pioneer/mistralai/Codestral-22B-v0.1` | 128K | | | | | | $0.30 | $0.90 |
105
+ | `pioneer/mistralai/Magistral-Small-2506` | 128K | | | | | | $0.50 | $2 |
106
+ | `pioneer/mistralai/Ministral-8B-Instruct-2410` | 128K | | | | | | $0.15 | $0.15 |
86
107
  | `pioneer/mistralai/Mistral-7B-Instruct-v0.3` | 33K | | | | | | $0.20 | $0.20 |
87
108
  | `pioneer/mistralai/Mistral-Nemo-Instruct-2407` | 131K | | | | | | $0.02 | $0.03 |
88
109
  | `pioneer/mistralai/Mistral-Small-4-119B-2603` | 262K | | | | | | $0.15 | $0.60 |
110
+ | `pioneer/mistralai/Pixtral-12B-2409` | 128K | | | | | | $0.15 | $0.15 |
89
111
  | `pioneer/moonshotai/Kimi-K2.6` | 262K | | | | | | $0.95 | $4 |
90
112
  | `pioneer/moonshotai/Kimi-K2.7-Code` | 262K | | | | | | $0.95 | $4 |
113
+ | `pioneer/moonshotai/Kimi-K3` | 1.0M | | | | | | $3 | $15 |
91
114
  | `pioneer/nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-BF16` | 262K | | | | | | $0.05 | $0.20 |
92
115
  | `pioneer/nvidia/NVIDIA-Nemotron-3-Super-120B-A12B-FP8` | 1.0M | | | | | | $0.09 | $0.45 |
93
116
  | `pioneer/nvidia/NVIDIA-Nemotron-3-Ultra-550B-A55B-BF16` | 1.0M | | | | | | $0.50 | $3 |
94
117
  | `pioneer/openai/gpt-oss-120b` | 131K | | | | | | $0.15 | $0.60 |
95
118
  | `pioneer/openai/gpt-oss-20b` | 131K | | | | | | $0.07 | $0.30 |
96
119
  | `pioneer/pioneer/auto` | 1.0M | | | | | | — | — |
120
+ | `pioneer/poolside/laguna-s-2.1` | 1.0M | | | | | | $0.10 | $0.20 |
121
+ | `pioneer/Qwen/Qwen2.5-Coder-0.5B` | 33K | | | | | | $0.10 | $0.10 |
97
122
  | `pioneer/Qwen/Qwen3-1.7B-Base` | 33K | | | | | | $0.10 | $0.10 |
123
+ | `pioneer/Qwen/Qwen3-235B-A22B-Instruct-2507` | 262K | | | | | | $1 | $1 |
98
124
  | `pioneer/Qwen/Qwen3-32B` | 131K | | | | | | $0.90 | $0.90 |
99
125
  | `pioneer/Qwen/Qwen3-4B-Base` | 33K | | | | | | $0.15 | $0.15 |
100
126
  | `pioneer/Qwen/Qwen3-4B-Instruct-2507` | 262K | | | | | | $0.20 | $0.20 |
package/.docs/reference/file-based-agents/schedules.md ADDED
@@ -0,0 +1,232 @@
1
+ > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
2
+
3
+ # Schedules
4
+
5
+ A file-based agent discovers **schedules** from its `schedules/` directory. Each file declares one recurring task: a cron expression plus what the agent should do when it fires. Mastra registers them into schedule storage at startup, so a scheduled agent needs no runtime registration code.
6
+
7
+ Use this page for the file-based convention. To create schedules at runtime instead, see [Schedules](https://mastra.ai/reference/schedules/overview).
8
+
9
+ `defineSchedule` is re-exported from `@mastra/core/agent` so file-based agents need one import path. `@mastra/core/schedules` exports it too.
10
+
11
+ ## Quickstart
12
+
13
+ Add a file under the agent's `schedules/` directory:
14
+
15
+ ```typescript
16
+ import { defineSchedule } from '@mastra/core/agent'
17
+
18
+ export default defineSchedule({
19
+ cron: '*/5 * * * *',
20
+ prompt: 'Check system health and report any failures.',
21
+ })
22
+ ```
23
+
24
+ Every five minutes, Mastra runs the `support` agent with that prompt.
25
+
26
+ ## Schedule identity
27
+
28
+ A schedule's id is its path relative to `schedules/` with the extension stripped, so nested directories are a way to group related schedules:
29
+
30
+ ```text
31
+ src/mastra/agents/
32
+ └── support/
33
+ ├── config.ts
34
+ ├── instructions.md
35
+ └── schedules/
36
+ ├── heartbeat.ts # id: heartbeat
37
+ ├── cleanup.md # id: cleanup
38
+ └── billing/
39
+ └── sweep.ts # id: billing/sweep
40
+ ```
41
+
42
+ That id is stable across builds, which is what lets Mastra tell an edited schedule from a new one. Renaming or moving a file is treated as deleting one schedule and creating another.
43
+
44
+ `heartbeat.ts` and `heartbeat.md` resolve to the same id, so declaring both is a build error.
45
+
46
+ ## Execution modes
47
+
48
+ A schedule sets exactly one execution mode. Setting both, or neither, fails the build.
49
+
50
+ ### Prompt mode
51
+
52
+ `prompt` runs the owning agent with a fixed message. This is fire-and-forget: nothing waits for the result.
53
+
54
+ ```typescript
55
+ import { defineSchedule } from '@mastra/core/agent'
56
+
57
+ export default defineSchedule({
58
+ cron: '0 9 * * 1',
59
+ timezone: 'America/New_York',
60
+ prompt: 'Summarize last week and post the digest.',
61
+ })
62
+ ```
63
+
64
+ ### Handler mode
65
+
66
+ `handler` computes the fire's parameters when the schedule triggers. Use it when the prompt depends on current state, when some fires should be skipped, or when the run needs channel delivery context.
67
+
68
+ ```typescript
69
+ import { defineSchedule } from '@mastra/core/agent'
70
+
71
+ export default defineSchedule({
72
+ cron: '0 3 * * *',
73
+ handler: async ({ mastra, agentId }) => {
74
+ const overdue = await findOverdueInvoices()
75
+
76
+ // Returning null skips this fire; nothing runs and the trigger is
77
+ // recorded with outcome 'skipped'.
78
+ if (overdue.length === 0) return null
79
+
80
+ return {
81
+ prompt: `Chase these overdue invoices: ${overdue.join(', ')}`,
82
+ threadId: 'billing-ops',
83
+ resourceId: agentId,
84
+ }
85
+ },
86
+ })
87
+ ```
88
+
89
+ The handler's return value is merged over the schedule's stored fields. Returning `undefined` applies no overrides, so the fire falls back to those stored fields. Since a handler-mode schedule can't declare a `prompt`, that fire then fails for a missing prompt. Return a `prompt` to run, or `null` to skip.
90
+
91
+ Handlers are functions, so they can't be persisted on the stored schedule row. Mastra resolves them in-process when the schedule fires. A handler-mode schedule that supplies no prompt (and declares none) fails that fire with a reason rather than sending the agent an empty message.
92
+
93
+ That in-process lookup means the process running the scheduler must have the owning agent registered. A normal deployment boots a single entry and gets that for free. Standalone workers need the same entry as your server. Boot one from a trimmed entry and it has no handler to call, so its fires fail rather than run.
94
+
95
+ ### Markdown schedules
96
+
97
+ A `.md` schedule uses frontmatter for the cron and the document body as the prompt. This is prompt mode with more room to write:
98
+
99
+ ```markdown
100
+ ---
101
+ cron: '0 3 * * *'
102
+ timezone: 'UTC'
103
+ name: 'nightly cleanup'
104
+ ---
105
+
106
+ Review tickets untouched for 30 days.
107
+
108
+ Close the ones that are clearly resolved and summarize the rest.
109
+ ```
110
+
111
+ Always quote the cron. A leading `*` is a YAML alias, so `cron: */5 * * * *` is a parse error while `cron: "*/5 * * * *"` is fine.
112
+
113
+ Frontmatter accepts every option below except `handler`, which needs a function and so needs a `.ts` or `.js` schedule module. `prompt` isn't settable either, because the body is the prompt. Unknown frontmatter fields fail the build rather than being silently ignored, so a typo like `ifIdel` is caught at build time.
114
+
115
+ ## Options
116
+
117
+ **cron** (`string`): Standard five-field cron expression. Required. The scheduler evaluates schedules on a tick loop, so the effective granularity is one minute. Sub-minute fields are not supported.
118
+
119
+ **prompt** (`string`): Message the agent runs on each fire. Set this or handler, not both.
120
+
121
+ **handler** (`(ctx) => ScheduleOverrides | null | undefined`): Computes the fire at trigger time. Return overrides to apply, or null to skip this fire. Returning nothing applies no overrides, which fails the fire because handler mode has no stored prompt. Set this or prompt, not both.
122
+
123
+ **timezone** (`string`): IANA timezone the cron is evaluated in (e.g. America/New\_York). Defaults to the host process timezone, which varies by deployment, so set this explicitly for anything time-of-day sensitive. DST transitions are handled by the timezone rules, so 0 9 \* \* \* stays 9am local across the shift.
124
+
125
+ **name** (`string`): Free-form label shown in Studio and filterable via mastra.schedules.list({ name }).
126
+
127
+ **threadId** (`string`): Sends the fire as a signal into an existing thread instead of starting a fresh run. Requires resourceId.
128
+
129
+ **resourceId** (`string`): Owner of the target thread. Required when threadId is set.
130
+
131
+ **signalType** (`'user' | 'state' | 'reactive' | 'notification' | 'user-message' | 'system-reminder'`): Signal category for the fire. Threaded schedules only. (Default: `'notification'`)
132
+
133
+ **tagName** (`string`): XML tag the signal renders as, so a fire reaches the agent as \<schedule>…\</schedule>. (Default: `'schedule'`)
134
+
135
+ **attributes** (`Record<string, string | number | boolean | null>`): Attributes rendered onto the signal XML tag.
136
+
137
+ **providerOptions** (`Record<string, unknown>`): Provider options merged into the schedule signal payload on every fire. Must be JSON-safe.
138
+
139
+ **ifActive** (`ScheduleIfActive`): What to do when the target thread is already streaming: deliver, persist, or discard. Threaded schedules only.
140
+
141
+ **ifIdle** (`ScheduleIfIdle`): What to do when the target thread is idle: wake, persist, or discard. Threaded schedules only.
142
+
143
+ **status** (`'active' | 'paused'`): Status the row is created with. Applies on first create only, because the sync never patches status so that pausing through the API survives a redeploy. Changing this value in code later has no effect on an existing schedule. (Default: `'active'`)
144
+
145
+ **metadata** (`Record<string, unknown>`): Arbitrary JSON-safe data stored alongside the schedule row.
146
+
147
+ ## Testing a schedule in development
148
+
149
+ Schedules fire on their cron cadence, which is impractical while iterating. Fire one on demand by id instead:
150
+
151
+ ```bash
152
+ # List schedules to find the id
153
+ curl http://localhost:4111/api/schedules
154
+
155
+ # Fire one now, out-of-band from its cron
156
+ curl -X POST http://localhost:4111/api/schedules/<scheduleId>/run
157
+ ```
158
+
159
+ This records a trigger with `triggerKind: "manual"` and doesn't advance `nextFireAt`, so the regular cadence is unaffected. Studio lists the same schedules and their trigger history.
160
+
161
+ Stored ids are namespaced and URL-encoded. `billing/sweep` on the `support` agent becomes `fsa_support__billing%2Fsweep`, so copy the id from the list response rather than assembling it by hand.
162
+
163
+ ## Registration and lifecycle
164
+
165
+ Mastra syncs declared schedules into schedule storage when it starts, and again whenever an agent is registered afterward. Declaring a schedule is enough to start the scheduler, with no `scheduler: { enabled: true }` needed.
166
+
167
+ The sync compares each declared schedule against its stored row and writes only what changed:
168
+
169
+ - A new schedule file creates a row.
170
+ - Editing `cron` or `timezone` patches the row and recomputes the next fire time, so an edited schedule never fires on its old cadence.
171
+ - Deleting or renaming a schedule file deletes its row.
172
+ - Pausing a schedule through the API survives a redeploy. The sync deliberately leaves `status` alone.
173
+
174
+ The sync only removes rows belonging to agents registered in the current process, so a process holding a subset of your agents never deletes the others' schedules. When an agent is removed from the project entirely, its leftover rows are cleaned up on their next fire, when the scheduler finds no agent to run.
175
+
176
+ Schedules created at runtime through `mastra.schedules.create(...)` live in a separate namespace and are never touched by this sync.
177
+
178
+ ## Limits
179
+
180
+ **Root agents only.** Schedules must be declared on a top-level agent. A `schedules/` directory under `subagents/` is a build error, because subagents are wired into their parent rather than registered on the Mastra instance, so the scheduler could never resolve one as a target. Give the parent the schedule and let it delegate.
181
+
182
+ **Storage required.** Schedules are persisted rows, so the instance needs [storage](https://mastra.ai/reference/file-based-agents/storage) configured. Rows in an in-memory store don't survive a restart.
183
+
184
+ **Hosting.** The scheduler runs as a background worker inside the Mastra process, so it needs a host that keeps that process alive. Long-running Node servers and containers work. Environments that freeze or recycle the process between requests, which includes most serverless function platforms, will miss fires. Use the platform's own cron to call the run endpoint there instead.
185
+
186
+ **Code-defined agents.** An agent directory whose `config.ts` exports `new Agent({...})` is used verbatim, so its `schedules/` directory is ignored with a warning. Use `mastra.schedules.create(...)` for those.
187
+
188
+ ## Example
189
+
190
+ A support agent with two schedules: a fixed weekly digest, and a nightly sweep that only runs when there's something to do.
191
+
192
+ ```text
193
+ src/mastra/agents/
194
+ └── support/
195
+ ├── config.ts
196
+ ├── instructions.md
197
+ └── schedules/
198
+ ├── weekly-digest.md
199
+ └── billing/
200
+ └── sweep.ts
201
+ ```
202
+
203
+ ```typescript
204
+ import { agentConfig } from '@mastra/core/agent'
205
+
206
+ export default agentConfig({
207
+ model: 'openai/gpt-5.6-sol',
208
+ })
209
+ ```
210
+
211
+ ```markdown
212
+ ---
213
+ cron: '0 9 * * 1'
214
+ timezone: 'America/New_York'
215
+ ---
216
+
217
+ Summarize the past week's tickets and post the digest to the team channel.
218
+ ```
219
+
220
+ ```typescript
221
+ import { defineSchedule } from '@mastra/core/agent'
222
+
223
+ export default defineSchedule({
224
+ cron: '0 3 * * *',
225
+ timezone: 'America/New_York',
226
+ handler: async () => {
227
+ const overdue = await findOverdueInvoices()
228
+ if (overdue.length === 0) return null
229
+ return { prompt: `Draft reminders for ${overdue.length} overdue invoices.` }
230
+ },
231
+ })
232
+ ```
package/.docs/reference/index.md CHANGED
@@ -189,6 +189,7 @@ The Reference section provides documentation of Mastra's API, including paramete
189
189
  - [Memory](https://mastra.ai/reference/file-based-agents/memory)
190
190
  - [Observability](https://mastra.ai/reference/file-based-agents/observability)
191
191
  - [Processors](https://mastra.ai/reference/file-based-agents/processors)
192
+ - [Schedules](https://mastra.ai/reference/file-based-agents/schedules)
192
193
  - [Scorers](https://mastra.ai/reference/file-based-agents/scorers)
193
194
  - [Server](https://mastra.ai/reference/file-based-agents/server)
194
195
  - [Skills](https://mastra.ai/reference/file-based-agents/skills)
package/CHANGELOG.md CHANGED
@@ -1,5 +1,12 @@
1
1
  # @mastra/mcp-docs-server
2
2
 
3
+ ## 1.2.15-alpha.0
4
+
5
+ ### Patch Changes
6
+
7
+ - Updated dependencies [[`45a9147`](https://github.com/mastra-ai/mastra/commit/45a914741f578754d79d8b7de7b4e4f304d8e14a), [`990611b`](https://github.com/mastra-ai/mastra/commit/990611ba76eb876d86c9c594371ae5f02f94b432), [`ed5d606`](https://github.com/mastra-ai/mastra/commit/ed5d606739c5e3fbdfa9f272df7809aa5ab43b1d)]:
8
+ - @mastra/core@1.58.0-alpha.0
9
+
3
10
  ## 1.2.14
4
11
 
5
12
  ### Patch Changes
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mastra/mcp-docs-server",
3
- "version": "1.2.14",
3
+ "version": "1.2.15-alpha.1",
4
4
  "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -28,8 +28,8 @@
28
28
  "jsdom": "^26.1.0",
29
29
  "local-pkg": "^1.1.2",
30
30
  "zod": "^4.4.3",
31
- "@mastra/core": "1.57.0",
32
- "@mastra/mcp": "^1.15.1"
31
+ "@mastra/mcp": "^1.15.1",
32
+ "@mastra/core": "1.58.0-alpha.0"
33
33
  },
34
34
  "devDependencies": {
35
35
  "@hono/node-server": "^1.19.14",
@@ -45,9 +45,9 @@
45
45
  "tsx": "^4.23.1",
46
46
  "typescript": "^6.0.3",
47
47
  "vitest": "4.1.10",
48
- "@internal/lint": "0.0.121",
49
- "@mastra/core": "1.57.0",
50
- "@internal/types-builder": "0.0.96"
48
+ "@internal/types-builder": "0.0.96",
49
+ "@mastra/core": "1.58.0-alpha.0",
50
+ "@internal/lint": "0.0.121"
51
51
  },
52
52
  "homepage": "https://mastra.ai",
53
53
  "repository": {