@mastra/mcp-docs-server 1.1.33-alpha.6 → 1.1.33-alpha.7

package/.docs/docs/mastra-platform/configuration.md

@@ -33,4 +33,26 @@ The CLI reads from `.env` and `.env.local` files in your project directory durin
 You can set environment variables like so:
 
 - **Studio**: Environment variables are read from your local `.env` files and bundled into the deploy artifact. To update them, redeploy.
-- **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.
+- **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.
+
+To pin the deploy to a specific env file (instead of relying on the default selection), pass `--env-file`:
+
+```bash
+mastra studio deploy --env-file .env.production --yes
+```
+
+## Multiple environments
+
+A platform project maps to a single deployed instance with one set of env vars. There is no built-in concept of `staging` vs `production` slots within a project. To run the same codebase across multiple environments, create one project per environment and override `.mastra-project.json` per deploy.
+
+```bash
+# Create-and-deploy each environment (first time only)
+mastra studio deploy --project "my-app-staging" --env-file .env.staging --yes
+mastra studio deploy --project "my-app-production" --env-file .env.production --yes
+
+# Subsequent deploys — set MASTRA_PROJECT_ID per environment
+MASTRA_PROJECT_ID="<staging-id>" mastra studio deploy --env-file .env.staging --yes
+MASTRA_PROJECT_ID="<production-id>" mastra studio deploy --env-file .env.production --yes
+```
+
+Each project has its own Studio URL and its own observability data. When using [`CloudExporter`](https://mastra.ai/docs/observability/tracing/exporters/cloud), set `MASTRA_PROJECT_ID` and `MASTRA_CLOUD_ACCESS_TOKEN` per environment so traces route to the matching Studio project.

package/.docs/docs/studio/deployment.md

@@ -75,7 +75,29 @@ This builds your project (compiling `src/mastra/` into `.mastra/output`), packag
 
 If this is your first deploy, the CLI will prompt you to create a new project or select an existing one. The `.mastra-project.json` file is written automatically.
 
-A deploy transitions through **queued → uploading → starting → running** (or **failed** if something goes wrong). If a sandbox is already running for your project, the platform hot-updates it in place with no downtime. Otherwise it creates a fresh sandbox. Your instance URL is assigned per project slug and remains stable across deploys. Environment variables from `.env`, `.env.local`, and `.env.production` are included automatically.
+A deploy transitions through **queued → uploading → starting → running** (or **failed** if something goes wrong). If a sandbox is already running for your project, the platform hot-updates it in place with no downtime. Otherwise it creates a fresh sandbox. Your instance URL is assigned per project slug and remains stable across deploys.
+
+### Env file requirement
+
+The deploy bundles environment variables from a `.env` or `.env.*` file in the project directory. If no env file is present, the deploy errors with `No env file found for deploy.` after the build step. Add at least an empty `.env` file before running the command.
+
+When multiple env files are present, the CLI prompts you to pick one. To select non-interactively, pass `--env-file`:
+
+```bash
+mastra studio deploy --env-file .env.production --yes
+```
+
+This is also how you target multiple environments from a single codebase: maintain one env file per environment (for example `.env.staging`, `.env.production`) and pass the right one to each deploy. Each environment still requires its own Mastra platform project — see [Configuration](https://mastra.ai/docs/mastra-platform/configuration) for the multi-environment pattern.
+
+### Create a new project non-interactively
+
+`mastra studio deploy` can create a project on first run. If `--project <name>` does not match an existing project, the CLI uses the value as the new project name and creates it after confirmation. Combined with `--yes`, this is fully scriptable:
+
+```bash
+mastra studio deploy --project "my-new-project" --yes
+```
+
+Use this from CI or AI coding agents instead of `mastra studio projects create`, which is interactive only.
 
 ## Running a server
 

package/.docs/guides/migrations/mastra-cloud.md

@@ -269,8 +269,34 @@ mastra studio deploy
 
 The CLI builds your project, uploads the artifact, and deploys it. On first deploy, a `.mastra-project.json` file is created to link your local project to the platform. Commit this file to your repository.
 
+The deploy requires a `.env` or `.env.*` file in the project directory. If none exists the CLI errors with `No env file found for deploy.` after the build completes — add at least an empty `.env` before running the command.
+
+To create a new platform project in one non-interactive step (instead of running `mastra studio projects create` separately), pass a name with `--project` and accept defaults with `--yes`:
+
+```bash
+mastra studio deploy --project "my-new-project" --yes
+```
+
 See [Studio deployment](https://mastra.ai/docs/studio/deployment) for details.
 
+### Multiple environments
+
+Mastra platform projects do not have a built-in concept of named environments (for example `staging` vs `production`). To deploy the same codebase to multiple environments, create one project per environment and pair each deploy with the matching env file using `--env-file`.
+
+The pattern below uses one `.env.<env>` file per environment, deploys to a project named `my-app-<env>`, and overrides `.mastra-project.json` per deploy with `MASTRA_ORG_ID` and `MASTRA_PROJECT_ID`:
+
+```bash
+# First deploy of each environment — creates the project
+mastra studio deploy --project "my-app-staging" --env-file .env.staging --yes
+mastra studio deploy --project "my-app-production" --env-file .env.production --yes
+
+# Subsequent deploys (CI/CD) — target the existing project
+MASTRA_PROJECT_ID="<staging-id>" mastra studio deploy --env-file .env.staging --yes
+MASTRA_PROJECT_ID="<production-id>" mastra studio deploy --env-file .env.production --yes
+```
+
+Each environment ends up with its own Studio URL and its own observability data. Send `MASTRA_CLOUD_ACCESS_TOKEN` and `MASTRA_PROJECT_ID` per environment so `CloudExporter` routes traces to the correct project.
+
 ## Deploy Server (optional)
 
 If you need a production API endpoint, deploy a Server:

package/.docs/guides/migrations/upgrade-to-v1/overview.md

@@ -8,6 +8,10 @@ This guide provides a comprehensive overview of breaking changes when upgrading
 
 > **Need help?:** Need help with the migration? Join our [Discord community](https://discord.gg/BTYqqHKUrf) to ask questions.
 
+> **Coming from Mastra Cloud?:** The legacy Mastra Cloud product has been replaced by the [Mastra platform](https://mastra.ai/docs/mastra-platform/overview), which splits hosting into two separate products: **Studio** (visual environment, observability) and **Server** (production API). Old Mastra Cloud access tokens do not work with Mastra platform — you must create new ones with `mastra auth tokens create`.
+>
+> If you upgrade to v1 packages without also migrating your `telemetry:` config to `observability:` and creating a Studio project, observability data will stop flowing. Follow the [Mastra Cloud migration guide](https://mastra.ai/guides/migrations/mastra-cloud) end to end.
+
 ## Migration strategy
 
 ### Update all Mastra packages to `latest` tag

package/.docs/guides/migrations/upgrade-to-v1/tracing.md

@@ -2,6 +2,10 @@
 
 The observability system has been restructured in v1 with a dedicated `@mastra/observability` package. This guide covers two migration paths depending on which version you're upgrading from.
 
+> **Observability data stops flowing on upgrade:** If you upgrade Mastra packages to v1 without migrating your `telemetry:` config to `observability:`, the old config is ignored at runtime. Your service will start cleanly with no error, but **no traces, logs, or metrics will be sent anywhere**. If you were sending data to Mastra Cloud, the dashboard will go empty.
+>
+> Complete this migration in the same change that bumps your Mastra packages, and verify traces appear in [Mastra Studio](https://mastra.ai/docs/studio/observability) before considering the upgrade complete. If you previously hosted on Mastra Cloud, also follow the [Mastra Cloud migration guide](https://mastra.ai/guides/migrations/mastra-cloud) — the new platform requires a new access token and a Studio project before `CloudExporter` can route data to it.
+
 ## Migration paths
 
 ### From OTEL-based Telemetry (0.x)

package/.docs/reference/cli/mastra.md

@@ -199,10 +199,18 @@ Builds and deploys your project to Mastra platform. Requires authentication via
 mastra studio deploy
 ```
 
-The command runs `mastra build`, zips the output, reads environment variables from `.env`, `.env.local`, and `.env.production`, and uploads everything to the platform. After uploading, it polls the deploy status and streams build logs until the deploy reaches a terminal state.
+The command runs `mastra build`, zips the output, reads an env file from the project directory, and uploads everything to the platform. After uploading, it polls the deploy status and streams build logs until the deploy reaches a terminal state.
+
+The CLI requires at least one `.env` or `.env.*` file (excluding `.env.example`) in the project directory and fails with `Error: No env file found for deploy.` if none exists. When multiple env files are present, the CLI prompts you to pick one (defaulting to `.env.production`); pass `--env-file` to choose explicitly. With `--yes` and multiple env files, you must pass `--env-file` or the deploy errors.
 
 Organization and project are resolved in order from: Environment variable flag, `.mastra-project.json` config file, current org from credentials, and lastly interactive prompt. On first deploy, the CLI saves the resolved IDs to `.mastra-project.json` so subsequent deploys skip the prompts.
 
+If `--project <value>` does not match an existing project (by ID or slug), the CLI treats `<value>` as a new project name and creates it after confirmation. Combined with `--yes`, this creates and deploys a new project in one non-interactive command:
+
+```bash
+mastra studio deploy --project "my-new-project" --yes
+```
+
 ### Arguments
 
 #### `[dir]`
@@ -217,7 +225,7 @@ Organization ID. Can also be set via the `MASTRA_ORG_ID` environment variable.
 
 #### `--project`
 
-Project ID or slug. Can also be set via the `MASTRA_PROJECT_ID` environment variable.
+Project ID or slug. Can also be set via the `MASTRA_PROJECT_ID` environment variable. If no project matches, the value is used as the name of a new project to create on deploy.
 
 #### `-y, --yes`
 
@@ -227,6 +235,14 @@ Auto-accept defaults without confirmation prompts.
 
 Path to the project config file. Defaults to `.mastra-project.json`.
 
+#### `--env-file`
+
+Path to the env file to bundle with the deploy (relative to the project directory). Use this to deploy the same project to multiple environments by pointing at different env files (for example `.env.staging`, `.env.production`).
+
+```bash
+mastra studio deploy --env-file .env.staging --yes
+```
+
 #### `--skip-build`
 
 Skip the build step and deploy the existing `.mastra/output` directory.
@@ -271,13 +287,23 @@ Stream logs in real time.
 
 Number of recent log lines to show.
 
+### `mastra studio deploy suggestions`
+
+Shows diagnosis results and suggested fixes for a failed Studio deploy.
+
+```bash
+mastra studio deploy suggestions [deploy-id]
+```
+
+If you omit `deploy-id`, the command uses the latest deploy for the linked project. If a diagnosis does not exist yet, the command starts one and polls until results are ready. If the deploy is healthy, no suggestions are shown.
+
 ### `mastra studio projects`
 
 Lists all projects in the current organization.
 
 ### `mastra studio projects create`
 
-Creates a new project through an interactive prompt.
+Creates a new project through an interactive prompt. This command does not accept a `--name` flag; for non-interactive project creation, use [`mastra studio deploy --project <name> --yes`](#mastra-studio-deploy) instead, which creates the project and deploys to it in one step.
 
 ## `mastra server deploy`
 
@@ -287,6 +313,16 @@ Builds and deploys your project to Server on Mastra platform. Works the same as
 mastra server deploy [dir]
 ```
 
+### `mastra server deploy suggestions`
+
+Shows diagnosis results and suggested fixes for a failed Server deploy.
+
+```bash
+mastra server deploy suggestions [deploy-id]
+```
+
+If you omit `deploy-id`, the command uses the latest deploy for the linked project. If a diagnosis does not exist yet, the command starts one and polls until results are ready. If the deploy is healthy, no suggestions are shown.
+
 ## `mastra server pause`
 
 Pauses the running server instance for the linked project. Organization and project resolution work the same as [`mastra server deploy`](#mastra-server-deploy).

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @mastra/mcp-docs-server
 
+## 1.1.33-alpha.7
+
+### Patch Changes
+
+- Updated dependencies [[`ca28c23`](https://github.com/mastra-ai/mastra/commit/ca28c232a2f18801a6cf20fe053479237b4d4fb0)]:
+  - @mastra/core@1.32.0-alpha.3
+
 ## 1.1.33-alpha.5
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.1.33-alpha.6",
+  "version": "1.1.33-alpha.7",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -29,8 +29,8 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.3.6",
-    "@mastra/core": "1.32.0-alpha.2",
-    "@mastra/mcp": "^1.6.1-alpha.1"
+    "@mastra/mcp": "^1.6.1-alpha.1",
+    "@mastra/core": "1.32.0-alpha.3"
   },
   "devDependencies": {
     "@hono/node-server": "^1.19.11",
@@ -46,9 +46,9 @@
     "tsx": "^4.21.0",
     "typescript": "^6.0.3",
     "vitest": "4.1.5",
-    "@internal/lint": "0.0.90",
     "@internal/types-builder": "0.0.65",
-    "@mastra/core": "1.32.0-alpha.2"
+    "@internal/lint": "0.0.90",
+    "@mastra/core": "1.32.0-alpha.3"
   },
   "homepage": "https://mastra.ai",
   "repository": {