@mastra/mcp-docs-server 1.2.8-alpha.9 → 1.2.8

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 (143) hide show
  1. package/.docs/docs/agent-builder/integrations.md +1 -3
  2. package/.docs/docs/agent-builder/overview.md +2 -0
  3. package/.docs/docs/agents/overview.md +17 -13
  4. package/.docs/docs/agents/skills.md +1 -3
  5. package/.docs/docs/agents/structured-output.md +2 -0
  6. package/.docs/docs/agents/using-tools.md +66 -49
  7. package/.docs/docs/browser/agent-browser.md +1 -0
  8. package/.docs/docs/browser/firecrawl.md +129 -0
  9. package/.docs/docs/browser/overview.md +16 -2
  10. package/.docs/docs/capabilities/channels/slack.md +111 -1
  11. package/.docs/docs/deployment/mastra-server.md +35 -0
  12. package/.docs/docs/deployment/monorepo.md +2 -0
  13. package/.docs/docs/deployment/overview.md +6 -0
  14. package/.docs/docs/deployment/sandbox.md +277 -0
  15. package/.docs/docs/editor/overview.md +2 -6
  16. package/.docs/docs/editor/tools.md +2 -6
  17. package/.docs/docs/evals/running-in-ci.md +3 -9
  18. package/.docs/docs/getting-started/build-with-ai.md +2 -6
  19. package/.docs/docs/getting-started/manual-install.md +1 -1
  20. package/.docs/docs/index.md +17 -13
  21. package/.docs/docs/long-running-agents/background-tasks.md +2 -2
  22. package/.docs/docs/long-running-agents/goals.md +3 -1
  23. package/.docs/docs/mastra-platform/database.md +12 -6
  24. package/.docs/docs/mastra-platform/deploy.md +14 -7
  25. package/.docs/docs/mastra-platform/environments.md +5 -4
  26. package/.docs/docs/mastra-platform/observability.md +4 -12
  27. package/.docs/docs/mastra-platform/overview.md +1 -1
  28. package/.docs/docs/mastra-platform/regions.md +73 -0
  29. package/.docs/docs/mastra-platform/workspace.md +111 -0
  30. package/.docs/docs/memory/observational-memory.md +77 -2
  31. package/.docs/docs/memory/overview.md +4 -0
  32. package/.docs/docs/observability/feedback.md +4 -0
  33. package/.docs/docs/observability/integrations/bridges/otel.md +1 -3
  34. package/.docs/docs/observability/integrations/exporters/otel.md +1 -3
  35. package/.docs/docs/server/auth/fga.md +40 -0
  36. package/.docs/docs/server/auth/simple-auth.md +1 -3
  37. package/.docs/docs/studio/overview.md +2 -0
  38. package/.docs/docs/workflows/control-flow.md +1 -3
  39. package/.docs/docs/workspace/filesystem.md +1 -0
  40. package/.docs/docs/workspace/sandbox.md +1 -0
  41. package/.docs/guides/getting-started/quickstart.md +40 -25
  42. package/.docs/guides/index.md +1 -1
  43. package/.docs/guides/migrations/vnext-to-standard-apis.md +1 -3
  44. package/.docs/models/environment-variables.md +2 -0
  45. package/.docs/models/gateways/netlify.md +3 -6
  46. package/.docs/models/gateways/openrouter.md +343 -346
  47. package/.docs/models/gateways/vercel.md +6 -5
  48. package/.docs/models/index.md +1 -1
  49. package/.docs/models/providers/aki-io.md +78 -0
  50. package/.docs/models/providers/alibaba-token-plan-cn.md +22 -21
  51. package/.docs/models/providers/alibaba-token-plan.md +22 -21
  52. package/.docs/models/providers/ambient.md +12 -10
  53. package/.docs/models/providers/baseten.md +2 -1
  54. package/.docs/models/providers/cline-pass.md +82 -0
  55. package/.docs/models/providers/cortecs.md +2 -1
  56. package/.docs/models/providers/crossmodel.md +2 -1
  57. package/.docs/models/providers/deepinfra.md +4 -7
  58. package/.docs/models/providers/deepseek.md +3 -1
  59. package/.docs/models/providers/empiriolabs.md +2 -1
  60. package/.docs/models/providers/google.md +4 -2
  61. package/.docs/models/providers/huggingface.md +2 -1
  62. package/.docs/models/providers/inferx.md +3 -3
  63. package/.docs/models/providers/kenari.md +44 -29
  64. package/.docs/models/providers/kimi-for-coding.md +6 -9
  65. package/.docs/models/providers/llmgateway.md +4 -1
  66. package/.docs/models/providers/moonshotai-cn.md +1 -1
  67. package/.docs/models/providers/moonshotai.md +1 -1
  68. package/.docs/models/providers/nebius.md +3 -1
  69. package/.docs/models/providers/novita-ai.md +3 -1
  70. package/.docs/models/providers/opencode-go.md +4 -3
  71. package/.docs/models/providers/opencode.md +4 -2
  72. package/.docs/models/providers/poolside.md +2 -2
  73. package/.docs/models/providers/togetherai.md +2 -6
  74. package/.docs/models/providers/wandb.md +2 -1
  75. package/.docs/models/providers/zenmux.md +3 -1
  76. package/.docs/models/providers.md +2 -0
  77. package/.docs/reference/agent-controller/session.md +13 -0
  78. package/.docs/reference/agents/agent.md +13 -1
  79. package/.docs/reference/agents/generate.md +18 -0
  80. package/.docs/reference/browser/firecrawl-browser.md +71 -0
  81. package/.docs/reference/cli/create-mastra.md +118 -43
  82. package/.docs/reference/cli/mastra.md +59 -5
  83. package/.docs/reference/code-sdk/mount-agent-controller.md +4 -4
  84. package/.docs/reference/core/getMCPServer.md +1 -3
  85. package/.docs/reference/core/getMCPServerById.md +1 -3
  86. package/.docs/reference/core/getWorkflow.md +1 -3
  87. package/.docs/reference/core/listMCPServers.md +2 -6
  88. package/.docs/reference/datasets/addItem.md +1 -3
  89. package/.docs/reference/datasets/addItems.md +1 -3
  90. package/.docs/reference/datasets/compareExperiments.md +1 -3
  91. package/.docs/reference/datasets/create.md +1 -3
  92. package/.docs/reference/datasets/dataset.md +2 -6
  93. package/.docs/reference/datasets/datasets-manager.md +5 -15
  94. package/.docs/reference/datasets/delete.md +1 -3
  95. package/.docs/reference/datasets/deleteExperiment.md +1 -3
  96. package/.docs/reference/datasets/deleteItem.md +1 -3
  97. package/.docs/reference/datasets/deleteItems.md +1 -3
  98. package/.docs/reference/datasets/get.md +1 -3
  99. package/.docs/reference/datasets/getDetails.md +1 -3
  100. package/.docs/reference/datasets/getExperiment.md +1 -3
  101. package/.docs/reference/datasets/getItem.md +1 -3
  102. package/.docs/reference/datasets/getItemHistory.md +1 -3
  103. package/.docs/reference/datasets/list.md +1 -3
  104. package/.docs/reference/datasets/listExperimentResults.md +1 -3
  105. package/.docs/reference/datasets/listExperiments.md +1 -3
  106. package/.docs/reference/datasets/listItems.md +1 -3
  107. package/.docs/reference/datasets/listVersions.md +1 -3
  108. package/.docs/reference/datasets/startExperiment.md +1 -3
  109. package/.docs/reference/datasets/startExperimentAsync.md +1 -3
  110. package/.docs/reference/datasets/update.md +1 -3
  111. package/.docs/reference/datasets/updateItem.md +1 -3
  112. package/.docs/reference/editor/mastra-editor.md +1 -3
  113. package/.docs/reference/evals/context-recall.md +205 -0
  114. package/.docs/reference/evals/create-scorer.md +3 -9
  115. package/.docs/reference/evals/mastra-scorer.md +1 -3
  116. package/.docs/reference/file-based-agents/tools.md +7 -6
  117. package/.docs/reference/index.md +5 -0
  118. package/.docs/reference/memory/observational-memory.md +21 -0
  119. package/.docs/reference/observability/tracing/exporters/posthog.md +39 -1
  120. package/.docs/reference/observability/tracing/processors/sensitive-data-filter.md +1 -3
  121. package/.docs/reference/processors/token-limiter-processor.md +1 -3
  122. package/.docs/reference/rag/database-config.md +12 -0
  123. package/.docs/reference/streaming/agents/stream.md +2 -0
  124. package/.docs/reference/templates/overview.md +6 -32
  125. package/.docs/reference/tools/create-tool.md +78 -52
  126. package/.docs/reference/tools/mcp-client.md +8 -24
  127. package/.docs/reference/tools/mcp-server.md +143 -44
  128. package/.docs/reference/tools/tavily.md +1 -1
  129. package/.docs/reference/tools/vector-query-tool.md +22 -0
  130. package/.docs/reference/vectors/mongodb.md +2 -0
  131. package/.docs/reference/vectors/turbopuffer.md +4 -0
  132. package/.docs/reference/voice/mistral.md +127 -0
  133. package/.docs/reference/workspace/daytona-sandbox.md +2 -6
  134. package/.docs/reference/workspace/platform-filesystem.md +182 -0
  135. package/.docs/reference/workspace/platform-sandbox.md +200 -0
  136. package/.docs/reference/workspace/railway-sandbox.md +37 -1
  137. package/CHANGELOG.md +71 -0
  138. package/dist/{chunk-GLPCVXXO.js → chunk-HGADBLKG.js} +2 -2
  139. package/dist/{chunk-GLPCVXXO.js.map → chunk-HGADBLKG.js.map} +1 -1
  140. package/dist/index.js +1 -1
  141. package/dist/stdio.js +1 -1
  142. package/dist/tools/docs.d.ts.map +1 -1
  143. package/package.json +8 -8
@@ -2,9 +2,7 @@
2
2
 
3
3
  # create-mastra
4
4
 
5
- The `create-mastra` command **creates** a new standalone Mastra project. Use this command to scaffold a complete Mastra setup in a dedicated directory. You can run it with additional flags to customize the setup process.
6
-
7
- ## Usage
5
+ Create a standalone Mastra project. By default, `create-mastra` installs a default starter and configures it for your selected model provider.
8
6
 
9
7
  **npm**:
10
8
 
@@ -30,116 +28,193 @@ yarn dlx create-mastra@latest
30
28
  bun x create-mastra@latest
31
29
  ```
32
30
 
33
- `create-mastra` automatically runs in _interactive_ mode, but you can also specify your project name and template with command line arguments.
31
+ ## Creation modes
32
+
33
+ ### Default starter
34
+
35
+ The default starter creates an agent harness with workspace tools, memory, task tracking, web access, recurring schedules, storage, and observability. Select OpenAI, Anthropic, Gemini, or xAI as your model provider.
36
+
37
+ Provide both the project name and provider to create the project without prompts. This example uses Anthropic; you can also pass `openai`, `google`, or `xai`:
34
38
 
35
39
  **npm**:
36
40
 
37
41
  ```bash
38
- npx create-mastra@latest my-mastra-project -- --template coding-agent
42
+ npx create-mastra@latest my-mastra-project --llm anthropic
39
43
  ```
40
44
 
41
45
  **pnpm**:
42
46
 
43
47
  ```bash
44
- pnpm dlx create-mastra@latest my-mastra-project -- --template coding-agent
48
+ pnpm dlx create-mastra@latest my-mastra-project --llm anthropic
45
49
  ```
46
50
 
47
51
  **Yarn**:
48
52
 
49
53
  ```bash
50
- yarn dlx create-mastra@latest my-mastra-project -- --template coding-agent
54
+ yarn dlx create-mastra@latest my-mastra-project --llm anthropic
51
55
  ```
52
56
 
53
57
  **Bun**:
54
58
 
55
59
  ```bash
56
- bun x create-mastra@latest my-mastra-project -- --template coding-agent
60
+ bun x create-mastra@latest my-mastra-project --llm anthropic
61
+ ```
62
+
63
+ Omit `--llm` to select the provider and optionally enter its API key interactively. The interactive setup also offers to connect your project to the Mastra platform. If enabled, the command opens the browser authentication flow, creates a platform project with the same name as the local project, and writes `MASTRA_PLATFORM_ACCESS_TOKEN` and `MASTRA_PROJECT_ID` to `.env`.
64
+
65
+ ### Template
66
+
67
+ Use a template slug or a public GitHub URL:
68
+
69
+ **npm**:
70
+
71
+ ```bash
72
+ npx create-mastra@latest my-mastra-project --template agent-harness
73
+ ```
74
+
75
+ **pnpm**:
76
+
77
+ ```bash
78
+ pnpm dlx create-mastra@latest my-mastra-project --template agent-harness
79
+ ```
80
+
81
+ **Yarn**:
82
+
83
+ ```bash
84
+ yarn dlx create-mastra@latest my-mastra-project --template agent-harness
85
+ ```
86
+
87
+ **Bun**:
88
+
89
+ ```bash
90
+ bun x create-mastra@latest my-mastra-project --template agent-harness
91
+ ```
92
+
93
+ **npm**:
94
+
95
+ ```bash
96
+ npx create-mastra@latest my-mastra-project --template https://github.com/mastra-ai/template-agent-harness
97
+ ```
98
+
99
+ **pnpm**:
100
+
101
+ ```bash
102
+ pnpm dlx create-mastra@latest my-mastra-project --template https://github.com/mastra-ai/template-agent-harness
57
103
  ```
58
104
 
59
- Check out the [full list](https://mastra.ai/api/templates.json) of templates and use the `slug` as input to the `--template` CLI flag.
105
+ **Yarn**:
60
106
 
61
- You can also use any GitHub repo as a template (it has to be a valid Mastra project):
107
+ ```bash
108
+ yarn dlx create-mastra@latest my-mastra-project --template https://github.com/mastra-ai/template-agent-harness
109
+ ```
110
+
111
+ **Bun**:
62
112
 
63
113
  ```bash
64
- npx create-mastra@latest my-mastra-project -- --template mastra-ai/template-coding-agent
114
+ bun x create-mastra@latest my-mastra-project --template https://github.com/mastra-ai/template-agent-harness
65
115
  ```
66
116
 
67
- You can install Mastra skills for specific agents during project creation:
117
+ Leave the template value blank to select a template interactively:
68
118
 
69
119
  **npm**:
70
120
 
71
121
  ```bash
72
- npx create-mastra@latest my-project -- --default --skills claude-code,cursor
122
+ npx create-mastra@latest my-mastra-project --template
73
123
  ```
74
124
 
75
125
  **pnpm**:
76
126
 
77
127
  ```bash
78
- pnpm dlx create-mastra@latest my-project -- --default --skills claude-code,cursor
128
+ pnpm dlx create-mastra@latest my-mastra-project --template
79
129
  ```
80
130
 
81
131
  **Yarn**:
82
132
 
83
133
  ```bash
84
- yarn dlx create-mastra@latest my-project -- --default --skills claude-code,cursor
134
+ yarn dlx create-mastra@latest my-mastra-project --template
85
135
  ```
86
136
 
87
137
  **Bun**:
88
138
 
89
139
  ```bash
90
- bun x create-mastra@latest my-project -- --default --skills claude-code,cursor
140
+ bun x create-mastra@latest my-mastra-project --template
91
141
  ```
92
142
 
93
- ## CLI flags
143
+ Template authors own their dependencies, models, environment variables, and source code. `create-mastra` doesn't apply `--llm` or `--llm-api-key`.
94
144
 
95
- Instead of an interactive prompt you can also define these CLI flags.
145
+ ### Empty scaffold
96
146
 
97
- **--version** (`boolean`): Output the version number
147
+ Use `--empty` to create a provider-free project without agents, examples, model SDKs, or environment files:
98
148
 
99
- **--project-name** (`string`): Project name that will be used in package.json and as the project directory name
149
+ **npm**:
100
150
 
101
- **--default** (`boolean`): Quickstart with defaults (src, OpenAI, no examples)
151
+ ```bash
152
+ npx create-mastra@latest my-empty-project --empty
153
+ ```
102
154
 
103
- **--components** (`string`): Comma-separated list of components (agents, tools, workflows, scorers)
155
+ **pnpm**:
104
156
 
105
- **--llm** (`string`): Default model provider (openai, anthropic, groq, google, or cerebras)
157
+ ```bash
158
+ pnpm dlx create-mastra@latest my-empty-project --empty
159
+ ```
106
160
 
107
- **--llm-api-key** (`string`): API key for the model provider
161
+ **Yarn**:
108
162
 
109
- **--example** (`boolean`): Include example code
163
+ ```bash
164
+ yarn dlx create-mastra@latest my-empty-project --empty
165
+ ```
166
+
167
+ **Bun**:
110
168
 
111
- **--no-example** (`boolean`): Do not include example code
169
+ ```bash
170
+ bun x create-mastra@latest my-empty-project --empty
171
+ ```
112
172
 
113
- **--template** (`string`): Create project from a template (use template name, public GitHub URL, or leave blank to select from list)
173
+ ## Automatic setup
114
174
 
115
- **--timeout** (`number`): Configurable timeout for package installation, defaults to 60000 ms
175
+ After installing dependencies, the command:
116
176
 
117
- **--dir** (`string`): Target directory for Mastra source code (default: src/)
177
+ 1. Detects supported coding assistants on `PATH` and installs Mastra skills. If none are detected, it installs universal skills.
178
+ 2. Creates an initial Git commit when the current directory and generated project aren't already inside Git repositories.
118
179
 
119
- **--mcp** (`string`): MCP Server for code editor (cursor, cursor-global, windsurf, vscode)
180
+ Use `--no-skills` or `--no-git` to skip these steps. Skills and Git setup failures produce warnings but don't remove a successfully created project.
120
181
 
121
- **--skills** (`string`): Comma-separated list of agents to install Mastra skills for (e.g., claude-code,cursor,windsurf)
182
+ ## Conflicts and validation
122
183
 
123
- **--observability** (`boolean`): Enable Observability on the Mastra platform during project creation. This opens browser login when needed, prompts for an organization, provisions a platform project, and configures the observability exporters.
184
+ - `--empty` and `--template` can't be used together.
185
+ - `--llm` and `--llm-api-key` are only valid for the default starter project.
186
+ - The project name must be a safe, lowercase, single directory name and the target must not already exist.
124
187
 
125
- **--no-observability** (`boolean`): Skip the Observability prompt during project creation.
188
+ Invalid input is rejected before templates are fetched or files are created.
126
189
 
127
- **--observability-project** (`string`): Set the platform project name to use when Mastra Observability is enabled.
190
+ ## Arguments and flags
128
191
 
129
- **--help** (`boolean`): Display help for command
192
+ **\[project-name]** (`string`): Project directory and package name. When omitted, the command prompts for it.
130
193
 
131
- ## Telemetry
194
+ **--empty** (`boolean`): Create a minimal, provider-free Mastra project.
132
195
 
133
- By default, Mastra collects anonymous information about your project like your OS, Mastra version or Node.js version. You can read the [source code](https://github.com/mastra-ai/mastra/blob/main/packages/cli/src/analytics/index.ts) to check what's collected.
196
+ **-l, --llm \<provider>** (`string`): Managed agent-harness provider: openai, anthropic, google, or xai.
134
197
 
135
- You can opt out of the CLI analytics by setting an environment variable:
198
+ **-k, --llm-api-key \<key>** (`string`): Write the selected provider API key to the generated .env file.
136
199
 
137
- ```bash
138
- MASTRA_TELEMETRY_DISABLED=1
139
- ```
200
+ **--no-skills** (`boolean`): Skip automatic Mastra skills installation.
201
+
202
+ **--no-git** (`boolean`): Skip automatic Git initialization and the initial commit.
203
+
204
+ **-t, --template \[template]** (`string`): Use a template slug or public GitHub URL. Omit the value to select interactively.
205
+
206
+ **--timeout \<milliseconds>** (`number`): Positive integer timeout for dependency installation. Defaults to 60000.
207
+
208
+ **--version** (`boolean`): Print the create-mastra version.
209
+
210
+ **--help** (`boolean`): Display command help.
211
+
212
+ ## Telemetry
213
+
214
+ Mastra collects anonymous CLI usage information, such as the operating system, Mastra version, and Node.js version. You can review the [analytics source](https://github.com/mastra-ai/mastra/blob/main/packages/cli/src/analytics/index.ts).
140
215
 
141
- You can also set this while using other `mastra` commands:
216
+ Set `MASTRA_TELEMETRY_DISABLED=1` to opt out:
142
217
 
143
218
  ```bash
144
- MASTRA_TELEMETRY_DISABLED=1 npx create-mastra@latest
219
+ MASTRA_TELEMETRY_DISABLED=1 npx create-mastra@latest my-project --empty
145
220
  ```
@@ -101,6 +101,18 @@ mastra dev
101
101
 
102
102
  These are forwarded to the Mastra model router and will work with any `"openai/..."` or `"anthropic/..."` model selections.
103
103
 
104
+ ## `mastra factory dev`
105
+
106
+ Starts a development server for [Agent Builder](https://mastra.ai/docs/agent-builder/overview) development. It uses the same dev runtime and flags as [`mastra dev`](#mastra-dev) and writes to the same `.mastra/output` directory.
107
+
108
+ ```bash
109
+ npx mastra factory dev
110
+ ```
111
+
112
+ Both commands share the same dev lock, so `mastra dev` and `mastra factory dev` can't run simultaneously in the same project. If one is already running, the other exits with a duplicate development server error.
113
+
114
+ Use `mastra factory dev` when developing Agent Builder features. It accepts the same flags as [`mastra dev`](#mastra-dev), including `--https`, `--inspect`, `--inspect-brk`, `--custom-args`, and `--request-context-presets`.
115
+
104
116
  ## `mastra build`
105
117
 
106
118
  The `mastra build` command bundles your Mastra project into a production-ready Hono server. [Hono](https://hono.dev/) is a lightweight, type-safe web framework that makes it straightforward to deploy Mastra agents as HTTP endpoints with middleware support.
@@ -361,7 +373,7 @@ File to write. Defaults to `.env`.
361
373
 
362
374
  Manages databases attached to a project on Mastra platform. Databases are provisioned from a managed provider (for example Turso or Neon) and inject their connection env vars into deploys automatically.
363
375
 
364
- A database is either **environment-scoped** (its env vars only go to one environment) or **shared** (project-scoped: its env vars go to all environments). Pass the environment argument to work with environment-scoped databases; omit it for shared databases.
376
+ A database is either **environment-scoped** (its env vars only go to one environment) or **shared** (project-scoped: its env vars go to all environments). Environment-scoped is the default for `mastra env db create` — pass an environment argument, or let the CLI pick or prompt for one. Pass `--shared` on create to attach a shared database instead. For other subcommands (`list`, `delete`, `keys`), pass the environment argument to work with environment-scoped databases and omit it for shared databases.
365
377
 
366
378
  Creating and deleting databases requires the `admin` role in the organization.
367
379
 
@@ -382,11 +394,15 @@ Emit machine-readable JSON.
382
394
 
383
395
  Provisions a managed database, attaches it, and polls until it's ready. Provisioning errors are printed with the provider's error detail.
384
396
 
385
- With an environment argument, the database is scoped to that environment: only it receives the database's connection env vars, and the provider region is derived from the environment's region. Without one, the database is shared by all environments.
397
+ By default the database is scoped to a single environment: pass an environment argument to pick it, or omit the argument to have the CLI pick for you. When the project has one environment, that environment is used. When it has several, the CLI prompts you to select one interactively; in non-interactive contexts (CI, `--json`) an environment argument is required. Pass `--shared` to attach a project-scoped database that's shared by every environment instead.
398
+
399
+ Environment-scoped databases inherit their provider region from the environment. Shared databases accept `--region`.
386
400
 
387
401
  ```bash
388
- mastra env db create <env> --kind turso
389
- mastra env db create --kind neon --name my-app-db --region aws-us-east-1
402
+ mastra env db create --kind turso # picks or prompts for an environment
403
+ mastra env db create staging --kind turso # scoped to the "staging" environment
404
+ mastra env db create --kind turso --shared # shared by all environments
405
+ mastra env db create --kind neon --name my-app-db --region aws-us-east-1 --shared
390
406
  ```
391
407
 
392
408
  #### `--kind`
@@ -401,13 +417,17 @@ Database name. Defaults to a name derived from the project slug (for example `my
401
417
 
402
418
  Provider region ID for shared databases. Ignored for environment-scoped databases.
403
419
 
420
+ #### `--shared`
421
+
422
+ Attach as a project-scoped database that's shared by every environment. Cannot be combined with an environment argument.
423
+
404
424
  #### `--no-wait`
405
425
 
406
426
  Return immediately after the attach is queued instead of polling until the database is ready. Check progress later with `mastra env db show`.
407
427
 
408
428
  #### `--json`
409
429
 
410
- Emit machine-readable JSON.
430
+ Emit machine-readable JSON. In this mode, an environment argument or `--shared` is required when the project has more than one environment (no interactive prompt).
411
431
 
412
432
  ### `mastra env db show`
413
433
 
@@ -796,6 +816,40 @@ Use the [`list`](#list) command to get the correct ID.
796
816
 
797
817
  List all available scorer templates. Use the ID for the `add` command.
798
818
 
819
+ ## `mastra create`
820
+
821
+ Create a standalone Mastra project with the same project-creation flow as [`create-mastra`](https://mastra.ai/reference/cli/create-mastra).
822
+
823
+ **npm**:
824
+
825
+ ```bash
826
+ npx mastra@latest create
827
+ ```
828
+
829
+ **pnpm**:
830
+
831
+ ```bash
832
+ pnpm dlx mastra@latest create
833
+ ```
834
+
835
+ **Yarn**:
836
+
837
+ ```bash
838
+ yarn dlx mastra@latest create
839
+ ```
840
+
841
+ **Bun**:
842
+
843
+ ```bash
844
+ bun x mastra@latest create
845
+ ```
846
+
847
+ Providing both the project name and `--llm` skips the interactive setup prompts. Use `--template [template]` for an arbitrary template or `--empty` for a minimal provider-free scaffold.
848
+
849
+ The command installs Mastra skills for detected coding assistants and initializes Git when appropriate. Use `--no-skills` or `--no-git` to opt out.
850
+
851
+ See the [`create-mastra` reference](https://mastra.ai/reference/cli/create-mastra) for mode behavior, conflicts, validation, and complete flag descriptions.
852
+
799
853
  ## `mastra init`
800
854
 
801
855
  The `mastra init` command initializes Mastra in an existing project. Use this command to scaffold the necessary folders and configuration without generating a new project from scratch.
@@ -4,7 +4,7 @@
4
4
 
5
5
  > **Beta:** The `@mastra/code-sdk` package is experimental and subject to breaking changes in minor versions.
6
6
 
7
- The `mountAgentControllerOnMastra()` function builds the Mastra Code agent controller the coding agent behind the [`mastracode`](https://www.npmjs.com/package/mastracode) CLI, with its modes, tools, memory, and thread management and registers it on a server-owned [Mastra](https://mastra.ai/reference/core/mastra-class) instance. Use it to serve the Mastra Code agent to your own UI (web app, editor, bot): each client creates or resumes its own isolated session through the returned [`AgentController`](https://mastra.ai/reference/agent-controller/agent-controller-class).
7
+ The `mountAgentControllerOnMastra()` function builds the Mastra Code agent controller (the coding agent behind the [`mastracode`](https://www.npmjs.com/package/mastracode) CLI, with its modes, tools, memory, and thread management) and registers it on a server-owned [Mastra](https://mastra.ai/reference/core/mastra-class) instance. Use it to serve the Mastra Code agent to your own UI (web app, editor, bot): each client creates or resumes its own isolated session through the returned [`AgentController`](https://mastra.ai/reference/agent-controller/agent-controller-class).
8
8
 
9
9
  To construct the `Mastra` instance yourself (for example in a deployable entry file), use `prepareAgentControllerMount()` from the same package, which returns the constructor args plus a `finalize()` callback.
10
10
 
@@ -27,9 +27,7 @@ Pass an existing `mastra` to mount the controller onto a Mastra instance that al
27
27
  import { Mastra } from '@mastra/core/mastra'
28
28
  import { mountAgentControllerOnMastra } from '@mastra/code-sdk'
29
29
 
30
- const mastra = new Mastra({
31
- /* ... */
32
- })
30
+ const mastra = new Mastra({/* ... */})
33
31
 
34
32
  const { controller } = await mountAgentControllerOnMastra({ mastra })
35
33
  ```
@@ -50,6 +48,8 @@ const { controller } = await mountAgentControllerOnMastra({ mastra })
50
48
 
51
49
  **postToolObserver** (`(context: ToolAfterHookContext) => void | Promise<void>`): Observes completed tool calls without replacing the tool or changing hook-manager behavior. Observer errors are logged and do not fail successful tool calls.
52
50
 
51
+ **inputProcessors** (`InputProcessor[]`): Stateless input processors prepended before Mastra Code's mandatory safety and compatibility processors. Custom processors extend the pipeline but can't replace the built-in processors.
52
+
53
53
  **disabledTools** (`string[]`): Tools removed from the dynamic tool set before exposure to the model.
54
54
 
55
55
  **storage** (`StorageConfig`): Custom storage config instead of the auto-detected default.
@@ -12,9 +12,7 @@ const myServer = new MCPServer({
12
12
  id: 'my-mcp-server',
13
13
  name: 'My Server',
14
14
  version: '1.0.0',
15
- tools: {
16
- /* ... */
17
- },
15
+ tools: {/* ... */},
18
16
  })
19
17
 
20
18
  export const mastra = new Mastra({
@@ -12,9 +12,7 @@ const myServer = new MCPServer({
12
12
  id: 'my-mcp-server',
13
13
  name: 'My Server',
14
14
  version: '1.0.0',
15
- tools: {
16
- /* ... */
17
- },
15
+ tools: {/* ... */},
18
16
  })
19
17
 
20
18
  export const mastra = new Mastra({
@@ -13,9 +13,7 @@ const run = await workflow.createRun()
13
13
 
14
14
  // TypeScript will properly infer the input schema type
15
15
  await run.startAsync({
16
- inputData: {
17
- /* properly typed */
18
- },
16
+ inputData: {/* properly typed */},
19
17
  })
20
18
  ```
21
19
 
@@ -12,18 +12,14 @@ const server1 = new MCPServer({
12
12
  id: 'server-one',
13
13
  name: 'Server One',
14
14
  version: '1.0.0',
15
- tools: {
16
- /* ... */
17
- },
15
+ tools: {/* ... */},
18
16
  })
19
17
 
20
18
  const server2 = new MCPServer({
21
19
  id: 'server-two',
22
20
  name: 'Server Two',
23
21
  version: '1.0.0',
24
- tools: {
25
- /* ... */
26
- },
22
+ tools: {/* ... */},
27
23
  })
28
24
 
29
25
  export const mastra = new Mastra({
@@ -11,9 +11,7 @@ Adds a single item to the dataset. Each item has an input, optional ground truth
11
11
  ```typescript
12
12
  import { Mastra } from '@mastra/core'
13
13
 
14
- const mastra = new Mastra({
15
- /* storage config */
16
- })
14
+ const mastra = new Mastra({/* storage config */})
17
15
 
18
16
  const dataset = await mastra.datasets.get({ id: 'dataset-id' })
19
17
 
@@ -11,9 +11,7 @@ Adds multiple items to the dataset in a single bulk operation.
11
11
  ```typescript
12
12
  import { Mastra } from '@mastra/core'
13
13
 
14
- const mastra = new Mastra({
15
- /* storage config */
16
- })
14
+ const mastra = new Mastra({/* storage config */})
17
15
 
18
16
  const dataset = await mastra.datasets.get({ id: 'dataset-id' })
19
17
 
@@ -11,9 +11,7 @@ Compares two or more experiments, producing per-item and per-scorer comparisons.
11
11
  ```typescript
12
12
  import { Mastra } from '@mastra/core'
13
13
 
14
- const mastra = new Mastra({
15
- /* storage config */
16
- })
14
+ const mastra = new Mastra({/* storage config */})
17
15
 
18
16
  const comparison = await mastra.datasets.compareExperiments({
19
17
  experimentIds: ['exp-baseline', 'exp-new'],
@@ -12,9 +12,7 @@ Creates a new dataset. Use Standard JSON Schema (Zod, Valibot, ArkType, etc.) fo
12
12
  import { Mastra } from '@mastra/core'
13
13
  import { z } from 'zod'
14
14
 
15
- const mastra = new Mastra({
16
- /* storage config */
17
- })
15
+ const mastra = new Mastra({/* storage config */})
18
16
 
19
17
  // Create with metadata
20
18
  const dataset = await mastra.datasets.create({
@@ -13,9 +13,7 @@ The `Dataset` class provides methods for item CRUD, versioning, and experiment m
13
13
  ```typescript
14
14
  import { Mastra } from '@mastra/core'
15
15
 
16
- const mastra = new Mastra({
17
- /* storage config */
18
- })
16
+ const mastra = new Mastra({/* storage config */})
19
17
 
20
18
  const dataset = await mastra.datasets.create({
21
19
  name: 'QA pairs',
@@ -44,9 +42,7 @@ console.log(`${summary.succeededCount}/${summary.totalItems} succeeded`)
44
42
  ```typescript
45
43
  import { Mastra } from '@mastra/core'
46
44
 
47
- const mastra = new Mastra({
48
- /* storage config */
49
- })
45
+ const mastra = new Mastra({/* storage config */})
50
46
 
51
47
  const dataset = await mastra.datasets.get({ id: 'dataset-id' })
52
48
 
@@ -13,9 +13,7 @@ The `DatasetsManager` class provides the public API for managing datasets, inclu
13
13
  ```typescript
14
14
  import { Mastra } from '@mastra/core'
15
15
 
16
- const mastra = new Mastra({
17
- /* storage config */
18
- })
16
+ const mastra = new Mastra({/* storage config */})
19
17
 
20
18
  // Create a dataset
21
19
  const dataset = await mastra.datasets.create({
@@ -32,9 +30,7 @@ const { datasets } = await mastra.datasets.list()
32
30
  ```typescript
33
31
  import { Mastra } from '@mastra/core'
34
32
 
35
- const mastra = new Mastra({
36
- /* storage config */
37
- })
33
+ const mastra = new Mastra({/* storage config */})
38
34
 
39
35
  // Get by ID
40
36
  const dataset = await mastra.datasets.get({ id: 'dataset-id' })
@@ -50,9 +46,7 @@ Retrieves a specific experiment (run) by ID. Unlike `dataset.getExperiment()`, t
50
46
  ```typescript
51
47
  import { Mastra } from '@mastra/core'
52
48
 
53
- const mastra = new Mastra({
54
- /* storage config */
55
- })
49
+ const mastra = new Mastra({/* storage config */})
56
50
 
57
51
  // Get experiment directly without knowing the dataset
58
52
  const experiment = await mastra.datasets.getExperiment({
@@ -68,9 +62,7 @@ console.log(`Status: ${experiment.status}`)
68
62
  ```typescript
69
63
  import { Mastra } from '@mastra/core'
70
64
 
71
- const mastra = new Mastra({
72
- /* storage config */
73
- })
65
+ const mastra = new Mastra({/* storage config */})
74
66
 
75
67
  const comparison = await mastra.datasets.compareExperiments({
76
68
  experimentIds: ['exp-1', 'exp-2'],
@@ -83,9 +75,7 @@ const comparison = await mastra.datasets.compareExperiments({
83
75
  `DatasetsManager` isn't instantiated directly. Access it from a `Mastra` instance:
84
76
 
85
77
  ```typescript
86
- const mastra = new Mastra({
87
- /* storage config */
88
- })
78
+ const mastra = new Mastra({/* storage config */})
89
79
  const datasetsManager = mastra.datasets
90
80
  ```
91
81
 
@@ -11,9 +11,7 @@ Deletes a dataset by ID, including all items, versions, and experiments.
11
11
  ```typescript
12
12
  import { Mastra } from '@mastra/core'
13
13
 
14
- const mastra = new Mastra({
15
- /* storage config */
16
- })
14
+ const mastra = new Mastra({/* storage config */})
17
15
 
18
16
  await mastra.datasets.delete({ id: 'dataset-id' })
19
17
  ```
@@ -11,9 +11,7 @@ Deletes an experiment (run) by ID, including all associated results.
11
11
  ```typescript
12
12
  import { Mastra } from '@mastra/core'
13
13
 
14
- const mastra = new Mastra({
15
- /* storage config */
16
- })
14
+ const mastra = new Mastra({/* storage config */})
17
15
 
18
16
  const dataset = await mastra.datasets.get({ id: 'dataset-id' })
19
17
 
@@ -11,9 +11,7 @@ Deletes a single item from the dataset by ID.
11
11
  ```typescript
12
12
  import { Mastra } from '@mastra/core'
13
13
 
14
- const mastra = new Mastra({
15
- /* storage config */
16
- })
14
+ const mastra = new Mastra({/* storage config */})
17
15
 
18
16
  const dataset = await mastra.datasets.get({ id: 'dataset-id' })
19
17
 
@@ -11,9 +11,7 @@ Deletes multiple items from the dataset in a single bulk operation.
11
11
  ```typescript
12
12
  import { Mastra } from '@mastra/core'
13
13
 
14
- const mastra = new Mastra({
15
- /* storage config */
16
- })
14
+ const mastra = new Mastra({/* storage config */})
17
15
 
18
16
  const dataset = await mastra.datasets.get({ id: 'dataset-id' })
19
17
 
@@ -11,9 +11,7 @@ Retrieves an existing dataset by ID. Throws a `MastraError` if the dataset doesn
11
11
  ```typescript
12
12
  import { Mastra } from '@mastra/core'
13
13
 
14
- const mastra = new Mastra({
15
- /* storage config */
16
- })
14
+ const mastra = new Mastra({/* storage config */})
17
15
 
18
16
  const dataset = await mastra.datasets.get({ id: 'dataset-id' })
19
17
 
@@ -11,9 +11,7 @@ Retrieves the full dataset record from storage, including metadata, schemas, and
11
11
  ```typescript
12
12
  import { Mastra } from '@mastra/core'
13
13
 
14
- const mastra = new Mastra({
15
- /* storage config */
16
- })
14
+ const mastra = new Mastra({/* storage config */})
17
15
 
18
16
  const dataset = await mastra.datasets.get({ id: 'dataset-id' })
19
17
 
@@ -11,9 +11,7 @@ Retrieves a specific experiment (run) by its ID.
11
11
  ```typescript
12
12
  import { Mastra } from '@mastra/core'
13
13
 
14
- const mastra = new Mastra({
15
- /* storage config */
16
- })
14
+ const mastra = new Mastra({/* storage config */})
17
15
 
18
16
  const dataset = await mastra.datasets.get({ id: 'dataset-id' })
19
17