@mastra/mcp-docs-server 1.2.8-alpha.0 → 1.2.8-alpha.17

package/.docs/docs/capabilities/channels/slack.md

@@ -53,7 +53,7 @@ export const yourAgent = new Agent({
 
 ## Create a Slack app
 
-To connect your agent, create a Slack app in the workspace where you want it to run. The Slack app controls how your agent appears in Slack, what it can do, and which events it receives.
+To connect your agent, create a Slack app in the workspace where you want it to run. The Slack app controls your agent's display in Slack, its capabilities, and the events it receives.
 
 This guide uses a [manifest](https://docs.slack.dev/app-manifests/configuring-apps-with-app-manifests/#creating_manifests): a configuration file that creates the Slack app settings for you. This is the fastest path when you are adding your agent to your own workspace. It doesn't cover the platform OAuth flow where other workspaces install your agent.
 
@@ -63,7 +63,59 @@ Create the Slack app from a manifest:
 2. Select **Create an app**.
 3. Select **From a manifest**.
 4. Choose the workspace where the agent should run.
-5. Paste this manifest, then select **Create**:
+5. Paste this manifest, then select **Create**. Slack accepts JSON or YAML, so use whichever tab matches the format shown in the app creation modal:
+
+**JSON**:
+
+```json
+{
+  "display_information": {
+    "name": "mastra-agent"
+  },
+  "features": {
+    "app_home": {
+      "home_tab_enabled": false,
+      "messages_tab_enabled": true,
+      "messages_tab_read_only_enabled": false
+    },
+    "bot_user": {
+      "display_name": "mastra-agent",
+      "always_online": true
+    }
+  },
+  "oauth_config": {
+    "scopes": {
+      "bot": [
+        "im:write",
+        "app_mentions:read",
+        "channels:history",
+        "channels:read",
+        "chat:write",
+        "users:read",
+        "im:read",
+        "im:history"
+      ]
+    },
+    "pkce_enabled": false
+  },
+  "settings": {
+    "event_subscriptions": {
+      "request_url": "https://<YOUR-PUBLIC-URL>/api/agents/<YOUR-AGENT-ID>/channels/slack/webhook",
+      "bot_events": ["app_mention", "message.channels", "message.im"]
+    },
+    "interactivity": {
+      "is_enabled": true,
+      "request_url": "https://<YOUR-PUBLIC-URL>/api/agents/<YOUR-AGENT-ID>/channels/slack/webhook"
+    },
+    "org_deploy_enabled": false,
+    "socket_mode_enabled": false,
+    "token_rotation_enabled": false,
+    "is_mcp_enabled": false
+  }
+}
+```
+
+**YAML**:
 
 ```yaml
 display_information:
@@ -109,7 +161,7 @@ This manifest configures:
 - `display_information.name` and `features.bot_user.display_name`: Set your agent's name in Slack. You can update it at any time; remember to reinstall the app after changing names or permissions.
 - `app_home.messages_tab_enabled` and `app_home.messages_tab_read_only_enabled`: Enable direct messages from the Slack app's **Messages** tab.
 - `always_online`: Shows the Slack bot user as always available.
-- `oauth_config.scopes.bot`: Grants the bot permission to post messages, read channel messages where it is present, read mentions, read and write direct messages, and look up users.
+- `oauth_config.scopes.bot`: Grants the bot permission to post messages, read channel messages where it's present, read mentions, read and write direct messages, and look up users.
 - `event_subscriptions`: Tells Slack which message events to send to the webhook.
 - `interactivity`: Enables interactive cards and tells Slack where to send card actions.
 
@@ -211,12 +263,70 @@ Mention the bot in the channel:
 
 The agent responds in the thread. Response content depends on the model, instructions, memory, and tools configured on the agent.
 
+## Authentication
+
+The Slack adapter has no built-in user allowlist. Once the app is installed, anyone in the workspace can talk to the agent by sending it a direct message or mentioning it in a channel where it's a member. Slack verifies each request with the signing secret, and Mastra runs the agent for every valid message the webhook receives.
+
+The main mechanism for controlling access is channel membership. The bot only receives events from direct messages and from channels it has been invited to, so the set of channels the bot belongs to defines who can reach it. Keep the bot out of channels where it shouldn't respond, and remove it from a channel to cut off access.
+
+For finer control, gate on the sender's identity. Every request carries the sender's Slack user ID in the channel [request context](#request-context), so you can allow or deny specific users in an input processor or tool before the agent acts.
+
+### Server authentication
+
+The Slack webhook route is exempt from Mastra's [server authentication](https://mastra.ai/docs/server/auth). Slack can't send a bearer token, so Mastra registers the channel webhook as a public route and verifies each request with the Slack signing secret instead. This holds even when you enable a provider like [`MastraAuthSimple`](https://mastra.ai/docs/server/auth/simple-auth): the rest of your API stays protected, but the webhook route relies on the signing secret rather than your server auth. Keep `SLACK_SIGNING_SECRET` set so the adapter can reject requests that Slack didn't sign.
+
+### External channels
+
+Shared channels ([Slack Connect](https://slack.com/connect)) let people from other workspaces join a conversation. If a workspace member adds the bot to a shared channel, everyone in that channel can talk to the agent, including external members outside your organization. Anyone who can reach the agent can also reach the tools and data it has access to.
+
+Treat adding the bot to a shared or external channel as granting those participants access to the agent. Before you do, confirm the agent's tools and data are safe to expose to outside members, and gate on the sender's user ID when you need to restrict who the agent responds to.
+
+## Request context
+
+On every message, Mastra places a channel context object on the [request context](https://mastra.ai/docs/server/request-context) under the `channel` key. It carries the sender's Slack display name and user ID, the bot's own identity, and details about where the message came from. Read it from an input processor or a tool to identify the user or branch on the conversation type:
+
+```typescript
+import { createTool } from '@mastra/core/tools'
+import type { ChannelContext } from '@mastra/core/channels'
+import { z } from 'zod'
+
+export const whoami = createTool({
+  id: 'whoami',
+  description: 'Return the Slack identity of the current user',
+  inputSchema: z.object({}),
+  execute: async (_input, context) => {
+    const channel = context?.requestContext?.get('channel') as ChannelContext | undefined
+
+    return {
+      platform: channel?.platform,
+      userId: channel?.userId,
+      userName: channel?.userName,
+      isDM: channel?.isDM,
+    }
+  },
+})
+```
+
+The channel context includes:
+
+- `botMention`, `botUserId`, and `botUserName`: The bot's own identity on Slack.
+- `channelId` and `threadId`: The Slack channel and thread the message arrived on.
+- `isDM`: Whether the message is a direct message.
+- `platform`: The platform identifier, `slack` for this adapter.
+- `userId` and `userName`: The sender's Slack user ID and display name.
+
+Mastra also turns this context into a short system message. The agent learns the platform and its own identity, plus whether the conversation is a direct message or a public channel. See [thread context](https://mastra.ai/docs/capabilities/channels/overview) in the channels overview for how to change that behavior.
+
 ## Production deployment
 
 When you deploy the Mastra server, update both request URLs in the Slack app settings to the production webhook URL. The tunnel URL used for local development is temporary and changes when the tunnel restarts.
 
 Channels on serverless platforms may need `waitUntil` and shared pub/sub configuration so background responses and thread leases work across short-lived instances. See [serverless deployment](https://mastra.ai/docs/capabilities/channels/overview) in the channels overview.
 
+### Idle servers
+
+Platform servers scale down to idle when they aren't receiving traffic, and that's fine for Slack. The next event, such as a mention or direct message, wakes the server by delivering its webhook request, and the server resumes handling requests. The first response after the server has been idle can take a little longer while it starts up, which is expected. Slack expects a `200` acknowledgement within 3 seconds and retries the event up to three times when delivery fails or times out, so a very slow cold start may take a retry before the agent responds. Subsequent messages respond at normal speed while the server stays warm.
+
 ## Related
 
 - [Channels overview](https://mastra.ai/docs/capabilities/channels/overview)

package/.docs/docs/deployment/mastra-server.md

@@ -61,6 +61,41 @@ Read the [`mastra start`](https://mastra.ai/reference/cli/mastra) reference for
 
 ## Build configuration
 
+### Build-time configuration
+
+Mastra reads the `bundler`, `deployer`, and `server` options while it builds your application. Keep those options as direct properties of the object passed to `new Mastra()` so the build can extract them.
+
+The following entry-file shape works:
+
+```typescript
+import { Mastra } from '@mastra/core/mastra'
+
+export const mastra = new Mastra({
+  bundler: {
+    externals: ['sharp'],
+  },
+  server: {
+    port: 4111,
+  },
+})
+```
+
+The value of each option can come from a variable, import, or function call. The option itself must remain a direct property. Do not hide build-time options behind a factory call or an object spread:
+
+```typescript
+const options = {
+  bundler: {
+    externals: ['sharp'],
+  },
+}
+
+// These patterns prevent Mastra from extracting `bundler` during the build.
+export const mastra = new Mastra(createMastraOptions())
+export const otherMastra = new Mastra({ ...options })
+```
+
+When Mastra can't extract an option, it uses the default build behavior for that option. See the [configuration reference](https://mastra.ai/reference/configuration) for the available `bundler`, `deployer`, and `server` settings.
+
 ### Public folder
 
 If a `public` folder exists in your Mastra directory (`src/mastra/public`), its contents are copied to the output directory during build. These files are served as static assets by the server.

package/.docs/docs/deployment/monorepo.md

@@ -97,6 +97,8 @@ export const mastra = new Mastra({
 })
 ```
 
+Keep `bundler` as a direct property in the object passed to `new Mastra()`. See [build-time configuration](https://mastra.ai/docs/deployment/mastra-server) for the supported entry-file shape.
+
 ## Environment variables
 
 Store `.env` files in the Mastra application directory (e.g., `apps/api/.env`), not the monorepo root.

package/.docs/docs/deployment/overview.md

@@ -51,6 +51,12 @@ Use this option for auto-scaling, minimal infrastructure management, or when you
 - [Netlify](https://mastra.ai/guides/deployment/netlify)
 - [Vercel](https://mastra.ai/guides/deployment/vercel)
 
+### Sandbox
+
+Deploy a Mastra server into an ephemeral workspace sandbox (such as Vercel Sandbox or E2B) and get a live public URL in seconds.
+
+Use this option for instant previews, deploys from your CI pipeline, verifying agent-built apps, or running untrusted per-user instances. Read the [sandbox deployment guide](https://mastra.ai/docs/deployment/sandbox).
+
 ### Web Framework
 
 When Mastra is integrated with a web framework, it deploys alongside your application using the framework's standard deployment process. The guides below cover framework-specific configuration requirements for deployment.

package/.docs/docs/deployment/sandbox.md

@@ -0,0 +1,277 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Deploy to a sandbox
+
+`@mastra/deployer-sandbox` deploys a full Mastra server, including Studio, into an ephemeral workspace sandbox and returns a live public URL. Repeat deployments can finish faster because the deployer skips dependency installation.
+
+Use sandbox deployments for:
+
+- Agent-built apps: An agent generates a Mastra project and deploys it to verify the result.
+- Continuous integration (CI): Spin up a real server for checks, then tear it down.
+- Instant previews: Share a working agent with your team before merging.
+- Multi-tenant untrusted code: Run per-user Mastra instances isolated from your infrastructure.
+
+Sandboxes have provider-enforced runtime caps and expire. For production hosting, see the [deployment overview](https://mastra.ai/docs/deployment/overview).
+
+## Supported sandboxes
+
+The deployer works with any workspace sandbox that supports networking (public port URLs):
+
+- [Vercel Sandbox](https://mastra.ai/reference/workspace/vercel-sandbox) (`@mastra/vercel`)
+- [E2B](https://mastra.ai/reference/workspace/e2b-sandbox) (`@mastra/e2b`)
+- [Daytona](https://mastra.ai/reference/workspace/daytona-sandbox) (`@mastra/daytona`)
+
+Provider authors can add support by implementing the optional `networking` capability on [`WorkspaceSandbox`](https://mastra.ai/reference/workspace/sandbox).
+
+## Quickstart
+
+Install the deployer and a sandbox provider of your choice. This example uses Vercel Sandbox:
+
+**npm**:
+
+```bash
+npm install @mastra/deployer-sandbox @mastra/vercel
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/deployer-sandbox @mastra/vercel
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/deployer-sandbox @mastra/vercel
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/deployer-sandbox @mastra/vercel
+```
+
+Configure the deployer in your `src/mastra/index.ts` file. The `sandboxName` identifies the deployment, so subsequent deployments with the same name reuse the existing sandbox.
+
+```typescript
+import { Mastra } from '@mastra/core/mastra'
+import { SandboxDeployer } from '@mastra/deployer-sandbox'
+import { VercelSandbox } from '@mastra/vercel'
+
+export const mastra = new Mastra({
+  deployer: new SandboxDeployer({
+    sandbox: new VercelSandbox({
+      sandboxName: 'my-preview',
+      timeout: 3_600_000, // 1 hour
+      ports: [4111],
+    }),
+  }),
+})
+```
+
+Build and deploy in one command:
+
+```bash
+mastra build
+```
+
+When a `SandboxDeployer()` is configured, `mastra build` bundles your project and deploys it into the sandbox. The deploy prints the API and Studio URLs and writes a `sandbox-deployment.json` manifest into `.mastra/output`:
+
+```text
+API:    https://<sandbox-id>-4111.vercel.run/api
+Studio: https://<sandbox-id>-4111.vercel.run
+```
+
+The manifest includes `expiresAt` when the sandbox provider reports an expiration time. Redeploys to the same sandbox skip the dependency install when the install inputs (`package.json`, bundled lockfiles, and the install command) are unchanged.
+
+### Using E2B
+
+For E2B, the `id` identifies the deployment, so subsequent deployments with the same value reconnect to the existing sandbox, whether it's running or paused.
+
+```typescript
+import { SandboxDeployer } from '@mastra/deployer-sandbox'
+import { E2BSandbox } from '@mastra/e2b'
+
+const deployer = new SandboxDeployer({
+  sandbox: new E2BSandbox({
+    id: 'my-preview',
+    template: 'base',
+    timeout: 3_600_000, // 1 hour
+  }),
+})
+```
+
+Pass `template: 'base'` unless you need filesystem mounts; without it, the provider builds a custom Filesystem in Userspace (FUSE) template on first use. E2B pauses instead of stopping: `stop()` snapshots the whole virtual machine (VM), including memory and running processes. When a paused sandbox wakes, the Mastra server resumes where it left off, and there's no relaunch step like on Vercel.
+
+### Using Daytona
+
+For Daytona, the `id` identifies the deployment, so subsequent deployments with the same value reconnect to the existing sandbox. Set `public: true` to make the preview URL accessible without a token.
+
+```typescript
+import { SandboxDeployer } from '@mastra/deployer-sandbox'
+import { DaytonaSandbox } from '@mastra/daytona'
+
+const deployer = new SandboxDeployer({
+  sandbox: new DaytonaSandbox({
+    id: 'my-preview',
+    public: true,
+    autoStopInterval: 30, // minutes
+  }),
+})
+```
+
+Stopping a Daytona sandbox persists its filesystem but not running processes, so waking works like Vercel: the resolver relaunches the server on `wake: true`.
+
+## Deploying programmatically
+
+`deployToSandbox()` deploys a prebuilt output directory without the bundler. Unlike `SandboxDeployer()`, it doesn't include Studio unless you pass `studio: true`. Use it in CI or from agent code:
+
+```typescript
+import { deployToSandbox } from '@mastra/deployer-sandbox'
+import { VercelSandbox } from '@mastra/vercel'
+
+const deployment = await deployToSandbox({
+  sandbox: new VercelSandbox({ sandboxName: 'ci-smoke', ports: [4111] }),
+  dir: '.mastra/output',
+})
+
+console.info(deployment.url) // https://<sandbox-id>-4111.vercel.run
+await deployment.logs() // tail the server log
+await deployment.stop() // stop the sandbox (resumable)
+await deployment.destroy() // permanently delete the sandbox
+```
+
+## Lifecycle
+
+### Managing a deployment
+
+Use the server-only `getDeployment()` export from `@mastra/deployer-sandbox/client` to retrieve an existing deployment. It identifies the sandbox through provider-specific configuration, such as a Vercel `sandboxName` or an E2B or Daytona `id`. The lookup isn't tied to the process that created the deployment, so you can use it from another server-side service or in CI.
+
+```typescript
+import { getDeployment } from '@mastra/deployer-sandbox/client'
+import { VercelSandbox } from '@mastra/vercel'
+
+const deployment = await getDeployment({
+  sandbox: new VercelSandbox({ sandboxName: 'my-preview', ports: [4111] }),
+  port: 4111,
+})
+
+console.info(deployment.status, deployment.url)
+await deployment.logs() // tail the server log
+await deployment.stop() // stop the sandbox (resumable)
+await deployment.destroy() // permanently delete the sandbox
+```
+
+Pass `wake: true` to resume a stopped sandbox before returning. The server is relaunched only if it isn't healthy after the resume. Provider tooling works too, for example `vercel sandbox ls`, `vercel sandbox stop`, and `vercel sandbox rm`.
+
+### Expiry and URLs
+
+Sandboxes expire according to the provider's runtime limits. When the provider reports an expiration time, the deploy logs it and `deployment.expiresAt` exposes it programmatically.
+
+Sandbox URLs can change when a sandbox stops and resumes. Treat the URL as plumbing and the sandbox identity (for example, the `sandboxName`) as the stable handle. The routing tiers below deal with URL rotation.
+
+## Routing tiers
+
+### Tier 1: Direct URL
+
+Use the printed URL directly for development, demos, and CI where a fresh URL per deploy is acceptable.
+
+### Tier 2: Resolve at runtime
+
+`getDeployment()` resolves the current URL at runtime, so consumers never hold a stale URL. Any server that knows the sandbox name can resolve it, including one in a different codebase than the Mastra project:
+
+```typescript
+import { getDeployment } from '@mastra/deployer-sandbox/client'
+import { VercelSandbox } from '@mastra/vercel'
+
+const deployment = await getDeployment({
+  sandbox: new VercelSandbox({ sandboxName: 'my-preview', ports: [4111] }),
+  wake: true,
+})
+
+console.info(deployment.url, deployment.status)
+```
+
+With `wake: false` (the default) the sandbox isn't started and you get `{ url, status }` to act on. Resolving the URL, `stop()`, and `destroy()` attach to the existing sandbox by name without resuming it, so lifecycle operations on a stopped sandbox never wake it or start billing. With `wake: true` the sandbox resumes and the server is relaunched if it isn't answering. Whether a relaunch is needed depends on the provider: Vercel and Daytona restore the filesystem but not running processes, while E2B resumes the whole VM including the server process.
+
+> **Warning:** `@mastra/deployer-sandbox/client` is server-only. Resolving a sandbox uses provider credentials that must never reach the browser. The module throws if imported in a browser context.
+
+### Tier 3: Stable URL for end users
+
+Give end users a stable URL on your own domain and forward to the sandbox server-side, using either a route handler proxy or an Edge Config alias.
+
+The example below shows a Vercel & Next.js setup, but the concept applies to any server-side framework or provider that can forward requests.
+
+- **Route handler proxy.** `createSandboxHandler()` caches the sandbox URL and re-resolves after a connection-level failure, which covers URL rotation and cold wakes:
+
+  ```typescript
+  import { createSandboxHandler, getDeployment } from '@mastra/deployer-sandbox/client'
+  import { VercelSandbox } from '@mastra/vercel'
+
+  const handler = createSandboxHandler({
+    resolve: async () => {
+      const deployment = await getDeployment({
+        sandbox: new VercelSandbox({ sandboxName: 'my-preview', ports: [4111] }),
+        wake: true,
+      })
+      return deployment.url!
+    },
+  })
+
+  export { handler as GET, handler as POST }
+  ```
+
+- **Edge Config alias.** Set the `alias` option on the deployer to keep a [Vercel Edge Config](https://vercel.com/docs/edge-config) item pointed at the current URL on every deploy:
+
+  ```typescript
+  const deployer = new SandboxDeployer({
+    sandbox: new VercelSandbox({ sandboxName: 'my-preview', ports: [4111] }),
+    alias: { edgeConfigId: 'ecfg_...', key: 'my-preview', token: process.env.VERCEL_TOKEN! },
+  })
+  ```
+
+  Then rewrite requests in Next.js middleware with `createSandboxProxy()`:
+
+  ```typescript
+  import { createSandboxProxy } from '@mastra/deployer-sandbox/client'
+
+  export const middleware = createSandboxProxy({ key: 'my-preview' })
+  export const config = { matcher: '/api/:path*' }
+  ```
+
+## CI example
+
+Deploy a preview on every pull request:
+
+```yaml
+name: Sandbox preview
+on: pull_request
+
+jobs:
+  preview:
+    runs-on: ubuntu-latest
+    env:
+      VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
+      VERCEL_TEAM_ID: ${{ secrets.VERCEL_TEAM_ID }}
+      VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: npm ci
+      - run: npx mastra build
+      - run: curl --fail "$(jq -r .url .mastra/output/sandbox-deployment.json)/api"
+```
+
+## Security
+
+- The sandbox URL is public. Anyone with the URL can reach your Mastra server, including Studio. Enable [server auth](https://mastra.ai/docs/server/auth) for anything beyond throwaway previews.
+- Environment variables from your `.env` files are injected into the remote sandbox VM so the server can run. The deploy logs a warning when this happens. Don't deploy secrets you wouldn't put on a shared preview server.
+- To restrict access to Tier 3 traffic, pass a `secret` to `createSandboxHandler()` or `createSandboxProxy()`. The helpers attach it as the `x-mastra-sandbox-secret` header on forwarded requests. Configure [server auth](https://mastra.ai/docs/server/auth) to require that header, and direct hits to the sandbox URL get rejected while traffic through your domain works.
+
+## Related
+
+- [Deployment overview](https://mastra.ai/docs/deployment/overview)
+- [Server authentication](https://mastra.ai/docs/server/auth)
+- [`WorkspaceSandbox` reference](https://mastra.ai/reference/workspace/sandbox)

package/.docs/docs/editor/overview.md

@@ -57,9 +57,7 @@ import { Mastra } from '@mastra/core'
 import { MastraEditor } from '@mastra/editor'
 
 export const mastra = new Mastra({
-  agents: {
-    /* your existing agents */
-  },
+  agents: {/* your existing agents */},
   editor: new MastraEditor(),
 })
 ```
@@ -84,9 +82,7 @@ import { Mastra } from '@mastra/core'
 import { MastraEditor } from '@mastra/editor'
 
 export const mastra = new Mastra({
-  agents: {
-    /* your existing agents */
-  },
+  agents: {/* your existing agents */},
   editor: new MastraEditor({
     source: 'code',
   }),

package/.docs/docs/editor/tools.md

@@ -62,9 +62,7 @@ Integration providers connect external tool platforms to the editor. Once regist
    import { ComposioToolProvider } from '@mastra/editor/composio'
 
    export const mastra = new Mastra({
-     agents: {
-       /* your agents */
-     },
+     agents: {/* your agents */},
      editor: new MastraEditor({
        toolProviders: {
          composio: new ComposioToolProvider({
@@ -91,9 +89,7 @@ Integration providers connect external tool platforms to the editor. Once regist
    import { ArcadeToolProvider } from '@mastra/editor/arcade'
 
    export const mastra = new Mastra({
-     agents: {
-       /* your agents */
-     },
+     agents: {/* your agents */},
      editor: new MastraEditor({
        toolProviders: {
          arcade: new ArcadeToolProvider({