@mastra/mcp-docs-server 0.0.0-studio-deploy-20260404184540 → 0.0.0-studio-cli-20260504022012

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 (281) hide show
  1. package/.docs/docs/agents/adding-voice.md +18 -17
  2. package/.docs/docs/agents/background-tasks.md +242 -0
  3. package/.docs/docs/agents/channels.md +2 -1
  4. package/.docs/docs/agents/overview.md +4 -0
  5. package/.docs/docs/agents/processors.md +177 -5
  6. package/.docs/docs/agents/structured-output.md +66 -1
  7. package/.docs/docs/agents/supervisor-agents.md +65 -0
  8. package/.docs/docs/agents/using-tools.md +73 -0
  9. package/.docs/docs/browser/agent-browser.md +78 -0
  10. package/.docs/docs/browser/browser-viewer.md +144 -0
  11. package/.docs/docs/browser/overview.md +168 -0
  12. package/.docs/docs/browser/stagehand.md +129 -0
  13. package/.docs/docs/deployment/cloud-providers.md +5 -1
  14. package/.docs/docs/deployment/mastra-server.md +4 -4
  15. package/.docs/docs/deployment/monorepo.md +3 -3
  16. package/.docs/docs/deployment/overview.md +11 -8
  17. package/.docs/docs/editor/overview.md +290 -0
  18. package/.docs/docs/editor/prompts.md +134 -0
  19. package/.docs/docs/editor/tools.md +152 -0
  20. package/.docs/docs/evals/custom-scorers.md +63 -3
  21. package/.docs/docs/evals/datasets/overview.md +1 -1
  22. package/.docs/docs/index.md +2 -2
  23. package/.docs/docs/mastra-platform/configuration.md +36 -0
  24. package/.docs/docs/mastra-platform/overview.md +78 -0
  25. package/.docs/docs/mcp/overview.md +17 -0
  26. package/.docs/docs/memory/memory-processors.md +3 -3
  27. package/.docs/docs/memory/message-history.md +8 -2
  28. package/.docs/docs/memory/observational-memory.md +65 -8
  29. package/.docs/docs/memory/storage.md +1 -2
  30. package/.docs/docs/memory/working-memory.md +2 -2
  31. package/.docs/docs/observability/logging.md +1 -1
  32. package/.docs/docs/observability/metrics/overview.md +2 -2
  33. package/.docs/docs/observability/overview.md +1 -1
  34. package/.docs/docs/observability/tracing/bridges/datadog.md +217 -0
  35. package/.docs/docs/observability/tracing/bridges/otel.md +2 -2
  36. package/.docs/docs/observability/tracing/exporters/arthur.md +163 -0
  37. package/.docs/docs/observability/tracing/exporters/cloud.md +135 -63
  38. package/.docs/docs/observability/tracing/exporters/datadog.md +3 -1
  39. package/.docs/docs/observability/tracing/exporters/default.md +5 -5
  40. package/.docs/docs/observability/tracing/exporters/laminar.md +22 -14
  41. package/.docs/docs/observability/tracing/exporters/langfuse.md +50 -33
  42. package/.docs/docs/observability/tracing/overview.md +87 -20
  43. package/.docs/docs/server/custom-adapters.md +5 -5
  44. package/.docs/docs/server/custom-api-routes.md +3 -3
  45. package/.docs/docs/server/middleware.md +46 -42
  46. package/.docs/docs/server/request-context.md +13 -2
  47. package/.docs/docs/server/server-adapters.md +91 -8
  48. package/.docs/docs/streaming/background-task-streaming.md +80 -0
  49. package/.docs/docs/streaming/overview.md +3 -0
  50. package/.docs/docs/studio/deployment.md +24 -6
  51. package/.docs/docs/studio/observability.md +1 -1
  52. package/.docs/docs/studio/overview.md +4 -4
  53. package/.docs/docs/voice/overview.md +74 -5
  54. package/.docs/docs/voice/speech-to-speech.md +45 -1
  55. package/.docs/docs/voice/speech-to-text.md +7 -7
  56. package/.docs/docs/voice/text-to-speech.md +10 -10
  57. package/.docs/docs/workflows/agents-and-tools.md +1 -1
  58. package/.docs/docs/workflows/overview.md +105 -4
  59. package/.docs/docs/workflows/scheduled-workflows.md +181 -0
  60. package/.docs/docs/workspace/filesystem.md +64 -6
  61. package/.docs/docs/workspace/lsp.md +76 -4
  62. package/.docs/docs/workspace/overview.md +27 -8
  63. package/.docs/docs/workspace/sandbox.md +3 -1
  64. package/.docs/docs/workspace/search.md +41 -2
  65. package/.docs/docs/workspace/skills.md +19 -19
  66. package/.docs/guides/agent-frameworks/ai-sdk.md +4 -4
  67. package/.docs/guides/build-your-ui/ai-sdk-ui.md +56 -9
  68. package/.docs/guides/build-your-ui/assistant-ui.md +1 -1
  69. package/.docs/guides/deployment/mastra-platform.md +191 -0
  70. package/.docs/guides/deployment/netlify.md +16 -1
  71. package/.docs/guides/getting-started/nestjs.md +238 -0
  72. package/.docs/guides/getting-started/next-js.md +0 -4
  73. package/.docs/guides/guide/code-review-bot.md +2 -2
  74. package/.docs/guides/guide/dev-assistant.md +4 -4
  75. package/.docs/{docs/mcp → guides/guide}/publishing-mcp-server.md +21 -1
  76. package/.docs/guides/guide/slack-assistant.md +191 -0
  77. package/.docs/guides/migrations/mastra-cloud.md +368 -0
  78. package/.docs/guides/migrations/upgrade-to-v1/tracing.md +1 -1
  79. package/.docs/models/embeddings.md +3 -3
  80. package/.docs/models/gateways/azure-openai.md +74 -35
  81. package/.docs/models/gateways/mastra.md +64 -0
  82. package/.docs/models/gateways/netlify.md +7 -3
  83. package/.docs/models/gateways/openrouter.md +28 -12
  84. package/.docs/models/gateways/vercel.md +16 -1
  85. package/.docs/models/gateways.md +1 -0
  86. package/.docs/models/index.md +43 -8
  87. package/.docs/models/providers/302ai.md +37 -4
  88. package/.docs/models/providers/abliteration-ai.md +71 -0
  89. package/.docs/models/providers/alibaba-cn.md +7 -2
  90. package/.docs/models/providers/alibaba-coding-plan-cn.md +3 -2
  91. package/.docs/models/providers/alibaba-coding-plan.md +3 -2
  92. package/.docs/models/providers/alibaba.md +8 -1
  93. package/.docs/models/providers/anthropic.md +18 -5
  94. package/.docs/models/providers/baseten.md +3 -1
  95. package/.docs/models/providers/berget.md +10 -12
  96. package/.docs/models/providers/chutes.md +4 -2
  97. package/.docs/models/providers/cloudflare-workers-ai.md +14 -48
  98. package/.docs/models/providers/cortecs.md +22 -2
  99. package/.docs/models/providers/deepinfra.md +8 -2
  100. package/.docs/models/providers/deepseek.md +6 -4
  101. package/.docs/models/providers/digitalocean.md +133 -0
  102. package/.docs/models/providers/fireworks-ai.md +6 -1
  103. package/.docs/models/providers/firmware.md +12 -10
  104. package/.docs/models/providers/friendli.md +6 -7
  105. package/.docs/models/providers/google.md +8 -4
  106. package/.docs/models/providers/helicone.md +1 -2
  107. package/.docs/models/providers/hpc-ai.md +73 -0
  108. package/.docs/models/providers/huggingface.md +6 -2
  109. package/.docs/models/providers/inception.md +9 -11
  110. package/.docs/models/providers/kilo.md +359 -339
  111. package/.docs/models/providers/kimi-for-coding.md +2 -1
  112. package/.docs/models/providers/llmgateway.md +67 -77
  113. package/.docs/models/providers/mistral.md +3 -2
  114. package/.docs/models/providers/mixlayer.md +75 -0
  115. package/.docs/models/providers/moonshotai-cn.md +3 -2
  116. package/.docs/models/providers/moonshotai.md +3 -2
  117. package/.docs/models/providers/nano-gpt.md +8 -2
  118. package/.docs/models/providers/neuralwatt.md +84 -0
  119. package/.docs/models/providers/novita-ai.md +19 -4
  120. package/.docs/models/providers/nvidia.md +8 -1
  121. package/.docs/models/providers/ollama-cloud.md +7 -2
  122. package/.docs/models/providers/openai.md +7 -2
  123. package/.docs/models/providers/opencode-go.md +21 -13
  124. package/.docs/models/providers/opencode.md +11 -4
  125. package/.docs/models/providers/ovhcloud.md +6 -8
  126. package/.docs/models/providers/poe.md +10 -15
  127. package/.docs/models/providers/regolo-ai.md +83 -0
  128. package/.docs/models/providers/siliconflow-cn.md +5 -2
  129. package/.docs/models/providers/siliconflow.md +6 -3
  130. package/.docs/models/providers/stepfun.md +8 -7
  131. package/.docs/models/providers/synthetic.md +5 -2
  132. package/.docs/models/providers/tencent-token-plan.md +71 -0
  133. package/.docs/models/providers/tencent-tokenhub.md +71 -0
  134. package/.docs/models/providers/togetherai.md +8 -7
  135. package/.docs/models/providers/vivgrid.md +7 -3
  136. package/.docs/models/providers/vultr.md +7 -6
  137. package/.docs/models/providers/wafer.ai.md +73 -0
  138. package/.docs/models/providers/wandb.md +3 -2
  139. package/.docs/models/providers/xai.md +6 -1
  140. package/.docs/models/providers/xiaomi-token-plan-ams.md +9 -7
  141. package/.docs/models/providers/xiaomi-token-plan-cn.md +9 -7
  142. package/.docs/models/providers/xiaomi-token-plan-sgp.md +9 -7
  143. package/.docs/models/providers/xiaomi.md +4 -2
  144. package/.docs/models/providers/zai-coding-plan.md +11 -19
  145. package/.docs/models/providers/zai.md +2 -1
  146. package/.docs/models/providers/zenmux.md +13 -5
  147. package/.docs/models/providers/zhipuai-coding-plan.md +11 -21
  148. package/.docs/models/providers/zhipuai.md +2 -1
  149. package/.docs/models/providers.md +8 -0
  150. package/.docs/reference/agents/agent.md +1 -1
  151. package/.docs/reference/agents/channels.md +3 -3
  152. package/.docs/reference/agents/generate.md +88 -6
  153. package/.docs/reference/agents/generateLegacy.md +1 -1
  154. package/.docs/reference/ai-sdk/chat-route.md +2 -0
  155. package/.docs/reference/ai-sdk/handle-chat-stream.md +19 -0
  156. package/.docs/reference/ai-sdk/handle-network-stream.md +2 -0
  157. package/.docs/reference/ai-sdk/network-route.md +2 -0
  158. package/.docs/reference/ai-sdk/to-ai-sdk-messages.md +95 -0
  159. package/.docs/reference/ai-sdk/to-ai-sdk-stream.md +15 -0
  160. package/.docs/reference/browser/agent-browser.md +375 -0
  161. package/.docs/reference/browser/browser-viewer.md +228 -0
  162. package/.docs/reference/browser/mastra-browser.md +286 -0
  163. package/.docs/reference/browser/stagehand-browser.md +286 -0
  164. package/.docs/reference/cli/mastra.md +703 -0
  165. package/.docs/reference/client-js/agents.md +166 -0
  166. package/.docs/reference/client-js/mastra-client.md +23 -0
  167. package/.docs/reference/client-js/observability.md +2 -2
  168. package/.docs/reference/client-js/workflows.md +62 -1
  169. package/.docs/reference/configuration.md +67 -1
  170. package/.docs/reference/core/addGateway.md +5 -5
  171. package/.docs/reference/core/getEditor.md +35 -0
  172. package/.docs/reference/core/getGateway.md +5 -5
  173. package/.docs/reference/core/getGatewayById.md +5 -5
  174. package/.docs/reference/core/getMCPServer.md +2 -2
  175. package/.docs/reference/core/getMCPServerById.md +2 -2
  176. package/.docs/reference/core/getScorer.md +3 -3
  177. package/.docs/reference/core/getScorerById.md +3 -3
  178. package/.docs/reference/core/listGateways.md +5 -5
  179. package/.docs/reference/core/listMCPServers.md +2 -2
  180. package/.docs/reference/core/listScorers.md +3 -3
  181. package/.docs/reference/core/mastra-class.md +11 -1
  182. package/.docs/reference/core/mastra-model-gateway.md +5 -5
  183. package/.docs/reference/datasets/create.md +4 -4
  184. package/.docs/reference/datasets/startExperiment.md +28 -2
  185. package/.docs/reference/datasets/update.md +4 -4
  186. package/.docs/reference/deployer/cloudflare.md +14 -1
  187. package/.docs/reference/deployer/netlify.md +50 -2
  188. package/.docs/reference/editor/mastra-editor.md +168 -0
  189. package/.docs/reference/editor/tool-provider.md +85 -0
  190. package/.docs/reference/evals/context-precision.md +3 -3
  191. package/.docs/reference/evals/context-relevance.md +3 -3
  192. package/.docs/reference/evals/create-scorer.md +5 -3
  193. package/.docs/reference/evals/filter-run.md +117 -0
  194. package/.docs/reference/evals/mastra-scorer.md +4 -4
  195. package/.docs/reference/evals/noise-sensitivity.md +6 -6
  196. package/.docs/reference/evals/prompt-alignment.md +12 -12
  197. package/.docs/reference/evals/run-evals.md +6 -6
  198. package/.docs/reference/evals/scorer-utils.md +3 -3
  199. package/.docs/reference/evals/trajectory-accuracy.md +3 -3
  200. package/.docs/reference/harness/harness-class.md +152 -53
  201. package/.docs/reference/index.md +25 -0
  202. package/.docs/reference/logging/pino-logger.md +0 -2
  203. package/.docs/reference/mastra-platform/api.md +108 -0
  204. package/.docs/reference/memory/clone-utilities.md +4 -2
  205. package/.docs/reference/memory/cloneThread.md +4 -2
  206. package/.docs/reference/memory/observational-memory.md +4 -0
  207. package/.docs/reference/observability/metrics/automatic-metrics.md +3 -3
  208. package/.docs/reference/observability/tracing/bridges/datadog.md +211 -0
  209. package/.docs/reference/observability/tracing/bridges/otel.md +3 -3
  210. package/.docs/reference/observability/tracing/configuration.md +18 -11
  211. package/.docs/reference/observability/tracing/exporters/arthur.md +122 -0
  212. package/.docs/reference/observability/tracing/exporters/cloud-exporter.md +102 -21
  213. package/.docs/reference/observability/tracing/exporters/console-exporter.md +8 -8
  214. package/.docs/reference/observability/tracing/exporters/datadog.md +3 -1
  215. package/.docs/reference/observability/tracing/exporters/default-exporter.md +8 -8
  216. package/.docs/reference/observability/tracing/exporters/langfuse.md +25 -32
  217. package/.docs/reference/observability/tracing/exporters/otel.md +3 -3
  218. package/.docs/reference/observability/tracing/instances.md +7 -7
  219. package/.docs/reference/observability/tracing/interfaces.md +23 -6
  220. package/.docs/reference/observability/tracing/span-filtering.md +95 -0
  221. package/.docs/reference/observability/tracing/spans.md +6 -6
  222. package/.docs/reference/processors/prefill-error-handler.md +70 -0
  223. package/.docs/reference/processors/processor-interface.md +400 -40
  224. package/.docs/reference/processors/skill-search-processor.md +20 -1
  225. package/.docs/reference/processors/stream-error-retry-processor.md +54 -0
  226. package/.docs/reference/processors/tool-call-filter.md +23 -0
  227. package/.docs/reference/server/create-route.md +3 -3
  228. package/.docs/reference/server/express-adapter.md +4 -4
  229. package/.docs/reference/server/fastify-adapter.md +4 -4
  230. package/.docs/reference/server/hono-adapter.md +4 -4
  231. package/.docs/reference/server/koa-adapter.md +4 -4
  232. package/.docs/reference/server/mastra-server.md +3 -3
  233. package/.docs/reference/server/nestjs-adapter.md +169 -0
  234. package/.docs/reference/server/register-api-route.md +4 -4
  235. package/.docs/reference/server/routes.md +11 -10
  236. package/.docs/reference/storage/clickhouse.md +300 -0
  237. package/.docs/reference/storage/cloudflare-d1.md +42 -42
  238. package/.docs/reference/storage/composite.md +5 -3
  239. package/.docs/reference/storage/duckdb.md +150 -0
  240. package/.docs/reference/storage/overview.md +1 -1
  241. package/.docs/reference/storage/redis.md +266 -0
  242. package/.docs/reference/streaming/ChunkType.md +143 -3
  243. package/.docs/reference/streaming/agents/MastraModelOutput.md +2 -2
  244. package/.docs/reference/streaming/agents/stream.md +10 -2
  245. package/.docs/reference/streaming/agents/streamUntilIdle.md +94 -0
  246. package/.docs/reference/streaming/workflows/resumeStream.md +2 -0
  247. package/.docs/reference/templates/overview.md +88 -14
  248. package/.docs/reference/tools/create-tool.md +107 -5
  249. package/.docs/reference/tools/mcp-client.md +45 -0
  250. package/.docs/reference/tools/mcp-server.md +1 -3
  251. package/.docs/reference/tools/perplexity.md +155 -0
  252. package/.docs/reference/tools/tavily.md +307 -0
  253. package/.docs/reference/vectors/mongodb.md +0 -2
  254. package/.docs/reference/voice/aws-nova-sonic.md +247 -0
  255. package/.docs/reference/voice/cloudflare.md +3 -3
  256. package/.docs/reference/voice/sarvam.md +29 -23
  257. package/.docs/reference/voice/voice.connect.md +4 -4
  258. package/.docs/reference/voice/voice.listen.md +3 -3
  259. package/.docs/reference/workflows/run-methods/resume.md +24 -0
  260. package/.docs/reference/workflows/run-methods/startAsync.md +1 -1
  261. package/.docs/reference/workflows/step.md +88 -7
  262. package/.docs/reference/workflows/workflow-methods/foreach.md +14 -1
  263. package/.docs/reference/workflows/workflow.md +88 -4
  264. package/.docs/reference/workspace/azure-blob-filesystem.md +219 -0
  265. package/.docs/reference/workspace/docker-sandbox.md +196 -0
  266. package/.docs/reference/workspace/gcs-filesystem.md +1 -0
  267. package/.docs/reference/workspace/google-drive-filesystem.md +185 -0
  268. package/.docs/reference/workspace/modal-sandbox.md +168 -0
  269. package/.docs/reference/workspace/process-manager.md +1 -1
  270. package/.docs/reference/workspace/s3-filesystem.md +80 -5
  271. package/.docs/reference/workspace/vercel.md +1 -1
  272. package/.docs/reference/workspace/workspace-class.md +37 -6
  273. package/CHANGELOG.md +486 -4
  274. package/dist/stdio.js.map +1 -1
  275. package/dist/utils.d.ts +1 -4
  276. package/dist/utils.d.ts.map +1 -1
  277. package/package.json +11 -11
  278. package/.docs/docs/mastra-cloud/deployment.md +0 -77
  279. package/.docs/docs/mastra-cloud/observability.md +0 -38
  280. package/.docs/docs/mastra-cloud/overview.md +0 -23
  281. package/.docs/docs/mastra-cloud/setup.md +0 -42
@@ -270,6 +270,66 @@ const glutenCheckerScorer = createScorer({...})
270
270
  })
271
271
  ```
272
272
 
273
+ ## Input filtering
274
+
275
+ Agent conversations can contain hundreds of messages with tool calls, data parts, and system metadata. Most scorers only need a subset of this data. The `prepareRun` option transforms the run data before the scorer pipeline executes, reducing noise and keeping scorers focused.
276
+
277
+ ### Declarative filtering with `filterRun()`
278
+
279
+ The [`filterRun()`](https://mastra.ai/reference/evals/filter-run) utility creates a `prepareRun` function from declarative options:
280
+
281
+ ```typescript
282
+ import { createScorer, filterRun } from '@mastra/core/evals'
283
+
284
+ const toolScorer = createScorer({
285
+ id: 'tool-quality',
286
+ description: 'Evaluates tool usage quality',
287
+ type: 'agent',
288
+ prepareRun: filterRun({
289
+ partTypes: ['tool-invocation', 'text'],
290
+ maxRememberedMessages: 20,
291
+ }),
292
+ }).generateScore(({ run }) => {
293
+ // run.input.rememberedMessages has only tool and text messages, max 20
294
+ return 1
295
+ })
296
+ ```
297
+
298
+ Common options include:
299
+
300
+ - `partTypes`: Keep only messages with matching part types (e.g., `'tool-invocation'`, `'text'`, `'reasoning'`)
301
+ - `toolNames`: Keep only messages involving specific tools (e.g., `['write_file', 'execute_command']`)
302
+ - `maxRememberedMessages`: Limit context window size
303
+ - `dropRequestContext`, `dropGroundTruth`, `dropExpectedTrajectory`: Remove unused fields
304
+
305
+ See the [`filterRun()` reference](https://mastra.ai/reference/evals/filter-run) for the full list of options.
306
+
307
+ ### Custom `prepareRun` functions
308
+
309
+ For logic that `filterRun()` doesn't cover, write a `prepareRun` function directly:
310
+
311
+ ```typescript
312
+ import { createScorer } from '@mastra/core/evals'
313
+
314
+ const customScorer = createScorer({
315
+ id: 'recent-output',
316
+ description: 'Scores only the last response',
317
+ type: 'agent',
318
+ prepareRun: (run) => ({
319
+ ...run,
320
+ output: run.output.slice(-1), // Keep only the last message
321
+ requestContext: undefined,
322
+ }),
323
+ })
324
+ .generateScore(({ run }) => {
325
+ return run.output.length > 0 ? 1 : 0
326
+ })
327
+ ```
328
+
329
+ The `prepareRun` function can also be async.
330
+
331
+ > **System messages are always preserved:** `filterRun()` never filters `systemMessages` or `taggedSystemMessages`. These contain agent instructions and are critical context for scoring.
332
+
273
333
  ## Example: Create a custom scorer
274
334
 
275
335
  A custom scorer in Mastra uses `createScorer` with four core components:
@@ -402,7 +462,7 @@ Defines how the LLM should analyze the input and what structured output to retur
402
462
  The analysis step uses a prompt object to:
403
463
 
404
464
  - Provide a clear description of the analysis task
405
- - Define expected output structure with Zod schema (both boolean result and list of gluten sources)
465
+ - Define expected output structure with a Standard JSON Schema (both boolean result and list of gluten sources)
406
466
  - Generate dynamic prompts based on the input content
407
467
 
408
468
  ### Score Generation
@@ -515,5 +575,5 @@ console.log('Reason:', result.reason)
515
575
 
516
576
  **Examples and Resources:**
517
577
 
518
- - [createScorer API Reference](https://mastra.ai/reference/evals/create-scorer) - Complete technical documentation
519
- - [Built-in Scorers Source Code](https://github.com/mastra-ai/mastra/tree/main/packages/evals/src/scorers) - Real implementations for reference
578
+ - [createScorer API Reference](https://mastra.ai/reference/evals/create-scorer): Complete technical documentation
579
+ - [Built-in Scorers Source Code](https://github.com/mastra-ai/mastra/tree/main/packages/evals/src/scorers): Real implementations for reference
@@ -68,7 +68,7 @@ console.log(dataset.id) // auto-generated UUID
68
68
 
69
69
  ### Defining schemas
70
70
 
71
- You can enforce the shape of `input` and `groundTruth` by passing Zod schemas. Mastra converts them to JSON Schema at creation time:
71
+ You can enforce the shape of `input` and `groundTruth` by passing a [Standard JSON Schema](https://standardschema.dev/json-schema) ([Zod](https://zod.dev/), [Valibot](https://valibot.dev/), [ArkType](https://arktype.io/), etc.) when creating the dataset:
72
72
 
73
73
  ```typescript
74
74
  import { z } from 'zod'
@@ -4,7 +4,7 @@ Build AI agents your users actually depend on. Mastra is a TypeScript framework
4
4
 
5
5
  ## Quickstart
6
6
 
7
- Run this command to create a new project you can test immediately in [Studio](https://mastra.ai/docs/studio/overview):
7
+ Run this command to create a new project:
8
8
 
9
9
  **npm**:
10
10
 
@@ -30,7 +30,7 @@ yarn create mastra
30
30
  bunx create-mastra
31
31
  ```
32
32
 
33
- See the [quickstart guide](https://mastra.ai/guides/getting-started/quickstart) for a full walkthrough.
33
+ You can open [Studio](https://mastra.ai/docs/studio/overview) immediately, which is an interactive UI for your Mastra project. See the [quickstart guide](https://mastra.ai/guides/getting-started/quickstart) for a full walkthrough.
34
34
 
35
35
  ## Integrate with your framework
36
36
 
@@ -0,0 +1,36 @@
1
+ # Configuration
2
+
3
+ When you deploy to the Mastra platform, the CLI generates a `.mastra-project.json` config file and reads environment variables from your local `.env` files.
4
+
5
+ This page explains both mechanisms and how they differ between Studio and Server deployments.
6
+
7
+ ## Project config
8
+
9
+ The `.mastra-project.json` file is auto-generated on your first Studio or Server deploy. It links your local project to a platform project.
10
+
11
+ Commit it to your version control so that subsequent deploys (including from CI) target the correct project.
12
+
13
+ Your file will look something like this:
14
+
15
+ ```json
16
+ {
17
+ "projectId": "06daaac4-89b1-40f0-9e3f-0993e039a627",
18
+ "projectName": "my-project",
19
+ "organizationId": "org_01KNA5YSP52SX4M6YVSXC2MAHP"
20
+ }
21
+ ```
22
+
23
+ | Field | Description |
24
+ | -------------- | ---------------------------------------------------------------------------------------------------- |
25
+ | projectId | UUID for the project. Assigned when the project is created. |
26
+ | projectName | Human-readable project name. Used as a display label in the dashboard and CLI output. |
27
+ | organizationId | The organization that owns the project. All deploys, API keys, and resources are scoped to this org. |
28
+
29
+ ## Environment variables
30
+
31
+ The CLI reads from `.env` and `.env.local` files in your project directory during deploy. Variables from `.env.local` override those in `.env`.
32
+
33
+ You can set environment variables like so:
34
+
35
+ - **Studio**: Environment variables are read from your local `.env` files and bundled into the deploy artifact. To update them, redeploy.
36
+ - **Server**: On the first deploy, the CLI automatically seeds environment variables from your local `.env` files. After that, manage them per-project through the dashboard or API.
@@ -0,0 +1,78 @@
1
+ # Mastra platform
2
+
3
+ The [Mastra platform](https://projects.mastra.ai) provides two products for deploying and managing AI applications built with the Mastra framework:
4
+
5
+ - **Studio**: A hosted visual environment for testing agents, running workflows, and inspecting traces
6
+ - **Server**: A production deployment target that runs your Mastra application as an API server
7
+
8
+ ## Quickstart
9
+
10
+ Before you begin, ensure you have Node.js 22.13.0 or later installed.
11
+
12
+ 1. Follow the [get started guide](https://mastra.ai/docs) to create your first Mastra project.
13
+
14
+ 2. Install the `mastra` CLI globally:
15
+
16
+ **npm**:
17
+
18
+ ```bash
19
+ npm install -g mastra
20
+ ```
21
+
22
+ **pnpm**:
23
+
24
+ ```bash
25
+ pnpm add -g mastra
26
+ ```
27
+
28
+ **Yarn**:
29
+
30
+ ```bash
31
+ yarn global add mastra
32
+ ```
33
+
34
+ **Bun**:
35
+
36
+ ```bash
37
+ bun add --global mastra
38
+ ```
39
+
40
+ 3. Deploy Studio with a single command:
41
+
42
+ ```bash
43
+ mastra studio deploy
44
+ ```
45
+
46
+ On a successful deploy, the CLI will output the URL of your deployed Studio instance.
47
+
48
+ 4. Deploy Server with a single command:
49
+
50
+ ```bash
51
+ mastra server deploy
52
+ ```
53
+
54
+ On a successful deploy, the CLI will output the URL of your deployed Server instance.
55
+
56
+ You have now successfully deployed both Studio and Server instances of your Mastra application. The CLI created a `.mastra-project.json` file in your project directory.
57
+
58
+ This file links your local project to a platform project. It's auto-generated on your first deploy and contains the `projectId`, `projectName`, and `organizationId`. Commit this file to your repository so CI/CD knows which project to deploy to.
59
+
60
+ ## Key Concepts
61
+
62
+ **Projects** are the shared parent entity across all products. A single project can have a Studio deployment and a Server deployment. Projects belong to an **Organization**, which is the multi-tenant container for your team.
63
+
64
+ Your Mastra application is built from three building blocks:
65
+
66
+ - [Agents](https://mastra.ai/docs/agents/overview): AI agents that can use tools, follow instructions, and maintain context
67
+ - [Tools](https://mastra.ai/docs/agents/using-tools): Callable functions and integrations available to your agents
68
+ - [Workflows](https://mastra.ai/docs/workflows/overview): Multi-step orchestration pipelines that coordinate agents and tools
69
+
70
+ ## Going to production
71
+
72
+ Develop your project locally with [`mastra dev`](https://mastra.ai/reference/cli/mastra) and open [Studio](https://mastra.ai/docs/studio/overview) to test your agents, workflows, and tools in a visual environment.
73
+
74
+ Once you're ready to deploy your application to production, use [`mastra studio deploy`](https://mastra.ai/reference/cli/mastra) and [`mastra server deploy`](https://mastra.ai/reference/cli/mastra) to push your application to the cloud.
75
+
76
+ Follow the [Studio deployment guide](https://mastra.ai/docs/studio/deployment) and [Server deployment guide](https://mastra.ai/guides/deployment/mastra-platform) for step-by-step instructions.
77
+
78
+ If you host your Mastra application on your own infrastructure, you can still send observability data to Studio using the [CloudExporter](https://mastra.ai/docs/observability/tracing/exporters/cloud).
@@ -89,6 +89,23 @@ export const testAgent = new Agent({
89
89
 
90
90
  > **Info:** Visit [Agent Class](https://mastra.ai/reference/agents/agent) for a full list of configuration options.
91
91
 
92
+ ## Tool approval
93
+
94
+ You can require human approval before MCP tools are executed by setting `requireToolApproval` on a server definition. This integrates with the existing [human-in-the-loop](https://mastra.ai/docs/workflows/human-in-the-loop) approval flow.
95
+
96
+ ```typescript
97
+ export const mcp = new MCPClient({
98
+ servers: {
99
+ github: {
100
+ url: new URL('http://localhost:3000/mcp'),
101
+ requireToolApproval: true,
102
+ },
103
+ },
104
+ })
105
+ ```
106
+
107
+ You can also pass a function to decide dynamically per-call. See the [MCPClient reference](https://mastra.ai/reference/tools/mcp-client) for the full API.
108
+
92
109
  ## Configuring `MCPServer`
93
110
 
94
111
  To expose agents, tools, and workflows from your Mastra application to external systems over HTTP(S) use the `MCPServer` class. This makes them accessible to any system or agent that supports the protocol.
@@ -307,8 +307,8 @@ Both scenarios are safe - guardrails prevent inappropriate content from being pe
307
307
 
308
308
  ## Related documentation
309
309
 
310
- - [Processors](https://mastra.ai/docs/agents/processors) - General processor concepts and custom processor creation
311
- - [Guardrails](https://mastra.ai/docs/agents/guardrails) - Security and validation processors
312
- - [Memory Overview](https://mastra.ai/docs/memory/overview) - Memory types and configuration
310
+ - [Processors](https://mastra.ai/docs/agents/processors): General processor concepts and custom processor creation
311
+ - [Guardrails](https://mastra.ai/docs/agents/guardrails): Security and validation processors
312
+ - [Memory Overview](https://mastra.ai/docs/memory/overview): Memory types and configuration
313
313
 
314
314
  When creating custom processors avoid mutating the input `messages` array or its objects directly.
@@ -6,6 +6,12 @@ You can also retrieve message history to display past conversations in your UI.
6
6
 
7
7
  > **Info:** Each message belongs to a thread (the conversation) and a resource (the user or entity it's associated with). See [Threads and resources](https://mastra.ai/docs/memory/storage) for more detail.
8
8
 
9
+ > **Warning:** When you use memory with a client application, send **only the new message** from the client instead of the full conversation history.
10
+ >
11
+ > Sending the full history is redundant because Mastra loads messages from storage, and it can cause message ordering bugs when client-side timestamps conflict with stored timestamps.
12
+ >
13
+ > For an AI SDK example, see [Using Mastra Memory](https://mastra.ai/guides/build-your-ui/ai-sdk-ui).
14
+
9
15
  ## Getting started
10
16
 
11
17
  Install the Mastra memory module along with a [storage adapter](https://mastra.ai/docs/memory/storage) for your database. The examples below use `@mastra/libsql`, which stores data locally in a `mastra.db` file.
@@ -100,8 +106,8 @@ await agent.stream('Hello', {
100
106
 
101
107
  You can use this history in two ways:
102
108
 
103
- - **Automatic inclusion** - Mastra automatically fetches and includes recent messages in the context window. By default, it includes the last 10 messages, keeping agents grounded in the conversation. You can adjust this number with `lastMessages`, but in most cases you don't need to think about it.
104
- - [**Manual querying**](#querying) - For more control, use the `recall()` function to query threads and messages directly. This lets you choose exactly which memories are included in the context window, or fetch messages to render conversation history in your UI.
109
+ - **Automatic inclusion**: Mastra automatically fetches and includes recent messages in the context window. By default, it includes the last 10 messages, keeping agents grounded in the conversation. You can adjust this number with `lastMessages`, but in most cases you don't need to think about it.
110
+ - [**Manual querying**](#querying): For more control, use the `recall()` function to query threads and messages directly. This lets you choose exactly which memories are included in the context window, or fetch messages to render conversation history in your UI.
105
111
 
106
112
  > **Tip:** When memory is enabled, [Studio](https://mastra.ai/docs/studio/overview) uses message history to display past conversations in the chat sidebar.
107
113
 
@@ -38,8 +38,45 @@ const memory = new Memory({
38
38
 
39
39
  See [configuration options](https://mastra.ai/reference/memory/observational-memory) for full API details.
40
40
 
41
+ > **Warning:** When you use OM with a client application, send **only the new message** from the client instead of the full conversation history.
42
+ >
43
+ > Observational memory still relies on stored conversation history. Sending the full history is redundant and can cause message ordering bugs when client-side timestamps conflict with stored timestamps.
44
+ >
45
+ > For an AI SDK example, see [Using Mastra Memory](https://mastra.ai/guides/build-your-ui/ai-sdk-ui).
46
+
41
47
  > **Note:** OM currently only supports `@mastra/pg`, `@mastra/libsql`, and `@mastra/mongodb` storage adapters. It uses background agents for managing memory. When using `observationalMemory: true`, the default model is `google/gemini-2.5-flash`. When passing a config object, a `model` must be explicitly set.
42
48
 
49
+ ## Temporal gap markers
50
+
51
+ Temporal gap markers insert a short reminder before a new user message when enough time has passed since the previous message in the thread. They help the agent and the UI see that the conversation resumed after a meaningful pause.
52
+
53
+ Temporal gap markers are off by default. Enable them with `temporalMarkers: true` in the `observationalMemory` config:
54
+
55
+ ```typescript
56
+ import { Memory } from '@mastra/memory'
57
+ import { Agent } from '@mastra/core/agent'
58
+
59
+ export const agent = new Agent({
60
+ name: 'my-agent',
61
+ instructions: 'You are a helpful assistant.',
62
+ model: 'openai/gpt-5-mini',
63
+ memory: new Memory({
64
+ options: {
65
+ observationalMemory: {
66
+ model: 'google/gemini-2.5-flash',
67
+ temporalMarkers: true,
68
+ },
69
+ },
70
+ }),
71
+ })
72
+ ```
73
+
74
+ Mastra inserts a temporal gap marker when the gap is at least 10 minutes. The marker is stored in memory and also emitted as a transient reminder event, so clients can render it as a lightweight timeline hint.
75
+
76
+ The observer also sees these markers when it processes the thread, so the observations it writes can anchor memories to when they happened (for example, "User asked about deployment after a 2-day gap").
77
+
78
+ See [the API reference](https://mastra.ai/reference/memory/observational-memory) for the full configuration shape.
79
+
43
80
  ## Benefits
44
81
 
45
82
  - **Prompt caching**: OM's context is stable and observations append over time rather than being dynamically retrieved each turn. This keeps the prompt prefix cacheable, which reduces costs.
@@ -157,7 +194,7 @@ With retrieval mode enabled, OM:
157
194
  - Registers a `recall` tool the agent can call to:
158
195
 
159
196
  - Page through the raw messages behind any observation group range
160
- - Search by semantic similarity (`mode: "search"` with a `query` string) requires `vector: true`
197
+ - Search by semantic similarity (`mode: "search"` with a `query` string); requires `vector: true`
161
198
  - List all threads (`mode: "threads"`), browse other threads (`threadId`), and search across all threads (default `scope: 'resource'`)
162
199
  - When `scope: 'thread'`: restrict browsing and search to the current thread only
163
200
 
@@ -327,13 +364,33 @@ Reflection works similarly — the Reflector runs in the background when observa
327
364
 
328
365
  ### Settings
329
366
 
330
- | Setting | Default | What it controls |
331
- | ------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
332
- | `observation.bufferTokens` | `0.2` | How often to buffer. `0.2` means every 20% of `messageTokens` — with the default 30k threshold, that's roughly every 6k tokens. Can also be an absolute token count (e.g. `5000`). |
333
- | `observation.bufferActivation` | `0.8` | How aggressively to clear the message window on activation. `0.8` means remove enough messages to keep only 20% of `messageTokens` remaining. Lower values keep more message history. |
334
- | `observation.blockAfter` | `1.2` | Safety threshold as a multiplier of `messageTokens`. At `1.2`, synchronous observation is forced at 36k tokens (1.2 × 30k). Only matters if buffering can't keep up. |
335
- | `reflection.bufferActivation` | `0.5` | When to start background reflection. `0.5` means reflection begins when observations reach 50% of the `observationTokens` threshold. |
336
- | `reflection.blockAfter` | `1.2` | Safety threshold for reflection, same logic as observation. |
367
+ | Setting | Default | What it controls |
368
+ | ------------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
369
+ | `observation.bufferTokens` | `0.2` | How often to buffer. `0.2` means every 20% of `messageTokens` — with the default 30k threshold, that's roughly every 6k tokens. Can also be an absolute token count (e.g. `5000`). |
370
+ | `observation.bufferActivation` | `0.8` | How aggressively to clear the message window on activation. `0.8` means remove enough messages to keep only 20% of `messageTokens` remaining. Lower values keep more message history. |
371
+ | `observation.blockAfter` | `1.2` | Safety threshold as a multiplier of `messageTokens`. At `1.2`, synchronous observation is forced at 36k tokens (1.2 × 30k). Only matters if buffering can't keep up. |
372
+ | `activateAfterIdle` | none | Forces buffered observations and buffered reflections to activate after a period of inactivity, even if their token thresholds have not been reached yet. Accepts milliseconds or duration strings like `300_000`, `"5m"`, or `"1hr"`. Set this to your prompt cache TTL if you want activation to happen before the next cold prompt. |
373
+ | `activateOnProviderChange` | `false` | Forces buffered observations and reflections to activate when the next step uses a different `provider/model` than the one that produced the latest assistant step. Use this when switching providers or models would invalidate prompt cache reuse. |
374
+ | `reflection.bufferActivation` | `0.5` | When to start background reflection. `0.5` means reflection begins when observations reach 50% of the `observationTokens` threshold. |
375
+ | `reflection.blockAfter` | `1.2` | Safety threshold for reflection, same logic as observation. |
376
+
377
+ If you're relying on prompt caching, set `activateAfterIdle` to match your cache TTL. That way, once a thread has been idle long enough for the cache to expire, the next request can activate buffered observations or reflections first and send a smaller compressed context window.
378
+
379
+ ```typescript
380
+ const memory = new Memory({
381
+ options: {
382
+ observationalMemory: {
383
+ model: 'google/gemini-2.5-flash',
384
+ activateAfterIdle: '5m',
385
+ activateOnProviderChange: true,
386
+ },
387
+ },
388
+ })
389
+ ```
390
+
391
+ With a 5-minute prompt cache TTL, this activates buffered context after 5 minutes of inactivity so the next uncached prompt uses observations and reflections instead of a larger raw message window. If you prefer, `300_000` works the same way.
392
+
393
+ Changing model or providers mid-thread will invalidate the prompt cache. If your agent can switch between providers or models mid-thread, `activateOnProviderChange: true` forces buffered context to activate before the new provider runs. That avoids sending a large raw window to a provider that cannot reuse the previous prompt cache.
337
394
 
338
395
  ### Disabling
339
396
 
@@ -34,6 +34,7 @@ Each provider page includes installation instructions, configuration parameters,
34
34
  - [PostgreSQL](https://mastra.ai/reference/storage/postgresql)
35
35
  - [MongoDB](https://mastra.ai/reference/storage/mongodb)
36
36
  - [Upstash](https://mastra.ai/reference/storage/upstash)
37
+ - [Redis](https://mastra.ai/reference/storage/redis)
37
38
  - [Cloudflare D1](https://mastra.ai/reference/storage/cloudflare-d1)
38
39
  - [Cloudflare KV & Durable Objects](https://mastra.ai/reference/storage/cloudflare)
39
40
  - [Convex](https://mastra.ai/reference/storage/convex)
@@ -118,8 +119,6 @@ export const agent = new Agent({
118
119
  })
119
120
  ```
120
121
 
121
- > **Warning:** Agent-level storage isn't supported when using [Mastra Cloud Store](https://mastra.ai/docs/mastra-cloud/deployment). If you use Mastra Cloud Store, configure storage on the Mastra instance instead. This limitation doesn't apply if you bring your own database.
122
-
123
122
  ## Threads and resources
124
123
 
125
124
  Mastra organizes conversations using two identifiers:
@@ -208,7 +208,7 @@ const paragraphMemory = new Memory({
208
208
 
209
209
  ## Structured working memory
210
210
 
211
- Working memory can also be defined using a structured schema instead of a Markdown template. This allows you to specify the exact fields and types that should be tracked, using a [Zod](https://zod.dev/) schema. When using a schema, the agent will see and update working memory as a JSON object matching your schema.
211
+ Working memory can also be defined using a structured schema instead of a Markdown template. This allows you to specify the exact fields and types that should be tracked, using a [Standard JSON Schema](https://standardschema.dev/json-schema) ([Zod](https://zod.dev/), [Valibot](https://valibot.dev/), [ArkType](https://arktype.io/), etc.). When using a schema, the agent will see and update working memory as a JSON object matching your schema.
212
212
 
213
213
  **Important:** You must specify either `template` or `schema`, but not both.
214
214
 
@@ -397,4 +397,4 @@ const response = await agent.generate('What do you know about me?', {
397
397
 
398
398
  - [Working memory with template](https://github.com/mastra-ai/mastra/tree/main/examples/memory-with-template)
399
399
  - [Working memory with schema](https://github.com/mastra-ai/mastra/tree/main/examples/memory-with-schema)
400
- - [Per-resource working memory](https://github.com/mastra-ai/mastra/tree/main/examples/memory-per-resource-example) - Complete example showing resource-scoped memory persistence
400
+ - [Per-resource working memory](https://github.com/mastra-ai/mastra/tree/main/examples/memory-per-resource-example): Complete example showing resource-scoped memory persistence
@@ -2,7 +2,7 @@
2
2
 
3
3
  Mastra's logging system captures function execution, input data, and output responses in a structured format.
4
4
 
5
- When deploying to Mastra Cloud, logs are shown on the [Logs](https://mastra.ai/docs/mastra-cloud/observability) page. In self-hosted or custom environments, logs can be directed to files or external services depending on the configured transports.
5
+ When deploying to the Mastra platform, logs are shown in the dashboard. In self-hosted or custom environments, logs can be directed to files or external services depending on the configured transports.
6
6
 
7
7
  ## Configuring logs with `PinoLogger`
8
8
 
@@ -8,9 +8,9 @@ Three categories of metrics are emitted automatically:
8
8
  - **Token usage metrics**: Input and output token counts broken down by type (text, cache, audio, image, reasoning).
9
9
  - **Cost estimation**: Estimated cost per model call based on an embedded pricing registry.
10
10
 
11
- > **Note:** Metrics require a separate OLAP store for observability. Relational databases like PostgreSQL, LibSQL, etc. are not supported for metrics. In-memory storage resets on restart.
11
+ > **Note:** Metrics require an OLAP-capable store for observability. Relational databases like PostgreSQL, LibSQL, etc. are not supported for metrics. In-memory storage resets on restart.
12
12
  >
13
- > For local development, you can use [DuckDB](https://mastra.ai/reference/vectors/duckdb). We don't recommend using in-memory/DuckDB for production, ClickHouse support is coming soon for scalable metrics storage.
13
+ > For local development, use [DuckDB](https://duckdb.org/) through `@mastra/duckdb`. For production, use [ClickHouse](https://clickhouse.com/) through `@mastra/clickhouse`.
14
14
 
15
15
  ## When to use metrics
16
16
 
@@ -83,7 +83,7 @@ export const mastra = new Mastra({
83
83
  serviceName: 'mastra',
84
84
  exporters: [
85
85
  new DefaultExporter(), // Persists traces to storage for Mastra Studio
86
- new CloudExporter(), // Sends traces to Mastra Cloud (if MASTRA_CLOUD_ACCESS_TOKEN is set)
86
+ new CloudExporter(), // Sends observability data to hosted Mastra Studio (if MASTRA_CLOUD_ACCESS_TOKEN is set)
87
87
  ],
88
88
  spanOutputProcessors: [
89
89
  new SensitiveDataFilter(), // Redacts sensitive data like passwords, tokens, keys