@mastra/mcp-docs-server 1.2.17-alpha.18 → 1.2.17-alpha.19

package/.docs/docs/deployment/cloud-providers.md

@@ -21,5 +21,6 @@ The following pages show you how to deploy Mastra to specific cloud providers.
 - [Inngest](https://mastra.ai/integrations/deploy/inngest)
 - [Kubernetes](https://mastra.ai/integrations/deploy/kubernetes)
 - [Netlify](https://mastra.ai/integrations/deploy/netlify)
+- [Render](https://mastra.ai/integrations/deploy/render)
 - [Temporal](https://mastra.ai/integrations/deploy/temporal)
 - [Vercel](https://mastra.ai/integrations/deploy/vercel)

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

@@ -52,6 +52,7 @@ Use this option for auto-scaling, minimal infrastructure management, or when you
 - [Inngest](https://mastra.ai/integrations/deploy/inngest)
 - [Kubernetes](https://mastra.ai/integrations/deploy/kubernetes)
 - [Netlify](https://mastra.ai/integrations/deploy/netlify)
+- [Render](https://mastra.ai/integrations/deploy/render)
 - [Temporal](https://mastra.ai/integrations/deploy/temporal)
 - [Vercel](https://mastra.ai/integrations/deploy/vercel)
 

package/.docs/docs/sandbox/overview.md

@@ -111,6 +111,7 @@ Use a remote or container backend when commands need a stronger boundary from th
 - [AgentCore](https://mastra.ai/integrations/sandboxes/agentcore)
 - [Apple Container](https://mastra.ai/integrations/sandboxes/apple-container)
 - [Blaxel](https://mastra.ai/integrations/sandboxes/blaxel)
+- [Cloudflare Sandbox](https://mastra.ai/integrations/sandboxes/cloudflare-sandbox)
 - [Daytona](https://mastra.ai/integrations/sandboxes/daytona)
 - [Docker](https://mastra.ai/integrations/sandboxes/docker)
 - [E2B](https://mastra.ai/integrations/sandboxes/e2b)

package/.docs/integrations/deploy/render.md

@@ -0,0 +1,389 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Render
+
+Deploy Mastra applications on [Render](https://render.com/). Host the Mastra API as a [web service](https://render.com/docs/web-services), or use [Render Workflows](https://render.com/docs/workflows) for long-running tasks with independent retry policies.
+
+Choose the deployment path that fits your application:
+
+- **Mastra API**: Deploy Mastra's [server](https://mastra.ai/docs/server/overview) as a web service with a public endpoint. The [Web Services guide](https://render.com/docs/web-services) explains how to deploy custom code or a supported [server adapter](https://mastra.ai/docs/server/server-adapters).
+- **Mastra workflow**: Run an entire Mastra workflow within one task. Render controls the outer run, while Mastra manages its steps and state. See [Defining Workflow Tasks](https://render.com/docs/workflows-defining) for configuration details.
+- **Distributed agent operations**: Give each operation its own compute plan, timeout, and retry policy. Render Workflows handles the execution queue and provides run observability.
+
+This guide builds an editorial pipeline that reviews a draft from three perspectives in parallel, then passes the feedback to an editor agent. Use the links above if you want to deploy a Mastra API or execute an entire Mastra workflow as one task.
+
+## How Render Workflows integrates with Mastra
+
+Mastra supplies the agents and application logic, while Render Workflows defines the execution boundaries. A typical pipeline has three layers:
+
+1. A parent task coordinates the run.
+2. Child tasks invoke Mastra agents for focused work.
+3. A final task combines the results.
+
+Calling one task from another creates a chained run in a separate instance, with its own compute plan, timeout, and retry policy.
+
+## Setup
+
+Create an empty Mastra project named `render-workflows`:
+
+**npm**:
+
+```bash
+npm create mastra@latest render-workflows -- --empty
+```
+
+**pnpm**:
+
+```bash
+pnpm create mastra render-workflows --empty
+```
+
+**Yarn**:
+
+```bash
+yarn create mastra render-workflows --empty
+```
+
+**Bun**:
+
+```bash
+bunx create-mastra render-workflows --empty
+```
+
+Install two additional dependencies:
+
+**npm**:
+
+```bash
+npm install @renderinc/sdk tsx
+```
+
+**pnpm**:
+
+```bash
+pnpm add @renderinc/sdk tsx
+```
+
+**Yarn**:
+
+```bash
+yarn add @renderinc/sdk tsx
+```
+
+**Bun**:
+
+```bash
+bun add @renderinc/sdk tsx
+```
+
+Add your API key to an `.env` file. This example uses OpenAI, but any supported [model provider](https://mastra.ai/models) works.
+
+```text
+OPENAI_API_KEY=your_openai_api_key
+```
+
+Install the [Render CLI](https://render.com/docs/cli) to run workflow commands from your terminal.
+
+## Distributed agent pipeline
+
+### Create the agents
+
+In `src/mastra`, create an `agents` directory with `reviewer-agent.ts` and `editor-agent.ts`. Define both agents:
+
+```ts
+import { Agent } from '@mastra/core/agent'
+
+export const reviewerAgent = new Agent({
+  id: 'reviewer-agent',
+  name: 'Reviewer Agent',
+  model: 'openai/gpt-5.6-sol',
+  instructions: `
+    Review the supplied draft only from the requested perspective.
+    Identify concrete problems and recommend specific changes.
+    Do not rewrite the full draft.
+  `,
+})
+```
+
+```ts
+import { Agent } from '@mastra/core/agent'
+
+export const editorAgent = new Agent({
+  id: 'editor-agent',
+  name: 'Editor Agent',
+  model: 'openai/gpt-5.6-sol',
+  instructions: `
+    Revise the supplied draft using the reviewers' feedback.
+    Return the complete revised draft and nothing else.
+    Preserve accurate details and do not introduce unsupported claims.
+  `,
+})
+```
+
+### Configure the Mastra instance
+
+Add both agents to the Mastra instance in `src/mastra/index.ts`:
+
+```ts
+import { Mastra } from '@mastra/core/mastra'
+import { editorAgent } from './agents/editor-agent.js'
+import { reviewerAgent } from './agents/reviewer-agent.js'
+
+export const mastra = new Mastra({
+  agents: {
+    editorAgent,
+    reviewerAgent,
+  },
+})
+```
+
+### Create the tasks
+
+In `src`, create a `tasks` directory with `review-task.ts`, `revision-task.ts`, and `editorial-task.ts`.
+
+#### Review task
+
+The reviewer agent handles one area of focus. Its compute plan, five-minute timeout, and retry policy apply only to that analysis. A temporary model-provider failure can trigger another attempt without restarting the other reviewers.
+
+```typescript
+import { task } from '@renderinc/sdk/workflows'
+import { mastra } from '../mastra/index.js'
+
+type Review = {
+  focus: string
+  feedback: string
+}
+
+export const reviewDraft = task(
+  {
+    name: 'review_draft',
+    plan: 'starter',
+    timeoutSeconds: 300,
+    retry: {
+      maxRetries: 2,
+      waitDurationMs: 1_000,
+      backoffScaling: 2,
+    },
+  },
+  async function reviewDraft(draft: string, focus: string): Promise<Review> {
+    const reviewer = mastra.getAgentById('reviewer-agent')
+    const response = await reviewer.generate(`
+      Review this draft for ${focus}.
+      Draft: ${draft}
+    `)
+    if (!response.text) {
+      throw new Error(`The ${focus} review returned no text`)
+    }
+    return {
+      focus,
+      feedback: response.text,
+    }
+  },
+)
+```
+
+#### Revision task
+
+This task combines the feedback and produces a revised draft. It uses a larger compute plan and a longer timeout than each reviewer.
+
+```typescript
+import { task } from '@renderinc/sdk/workflows'
+import { mastra } from '../mastra/index.js'
+
+type Review = {
+  focus: string
+  feedback: string
+}
+
+export const reviseDraft = task(
+  {
+    name: 'revise_draft',
+    plan: 'standard',
+    timeoutSeconds: 600,
+    retry: {
+      maxRetries: 2,
+      waitDurationMs: 1_000,
+      backoffScaling: 2,
+    },
+  },
+  async function reviseDraft(draft: string, reviews: Review[]): Promise<{ draft: string }> {
+    const editor = mastra.getAgentById('editor-agent')
+    const response = await editor.generate(`
+      Revise the draft using the review feedback.
+      Draft: ${draft}
+      Reviews: ${JSON.stringify(reviews, null, 2)}
+    `)
+    if (!response.text) {
+      throw new Error('The editor returned no text')
+    }
+    return {
+      draft: response.text,
+    }
+  },
+)
+```
+
+#### Editorial task
+
+The parent dispatches three reviews in parallel with `Promise.all()`, then sends their combined feedback to the revision step. Retries are disabled at this level because each child defines its own policy. If you enable orchestration retries, ensure that another attempt can't duplicate external side effects or other non-idempotent work.
+
+```typescript
+import { task } from '@renderinc/sdk/workflows'
+import { reviewDraft } from './review-task.js'
+import { reviseDraft } from './revision-task.js'
+
+export const editorialPipeline = task(
+  {
+    name: 'editorial_pipeline',
+    plan: 'starter',
+    timeoutSeconds: 1_200,
+    retry: {
+      maxRetries: 0,
+      waitDurationMs: 1_000,
+      backoffScaling: 2,
+    },
+  },
+  async function editorialPipeline(draft: string): Promise<{ draft: string }> {
+    const focuses = ['technical clarity', 'structure and flow', 'reader usefulness']
+    const reviews = await Promise.all(focuses.map(focus => reviewDraft(draft, focus)))
+    return reviseDraft(draft, reviews)
+  },
+)
+```
+
+### Set up the entry point
+
+Create `src/index.ts` and import the editorial task:
+
+```ts
+import './tasks/editorial-task.js'
+```
+
+In `package.json`, add scripts to build the TypeScript project and run the workflow:
+
+```json
+{
+  "scripts": {
+    "build": "tsc",
+    "dev:workflows": "tsx src/index.ts",
+    "start:workflows": "node dist/index.js"
+  }
+}
+```
+
+Configure `tsconfig.json` for the build:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "rootDir": "src",
+    "outDir": "dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*"]
+}
+```
+
+Build the project. The command compiles the JavaScript files into `dist`.
+
+**npm**:
+
+```bash
+npm run build
+```
+
+**pnpm**:
+
+```bash
+pnpm run build
+```
+
+**Yarn**:
+
+```bash
+yarn build
+```
+
+**Bun**:
+
+```bash
+bun run build
+```
+
+## Run the pipeline
+
+### Locally
+
+Start the local development server with the Render CLI:
+
+```bash
+render workflows dev -- npm run dev:workflows
+```
+
+The server lists the registered tasks:
+
+```bash
+➜ render workflows dev -- npm run dev:workflows
+Workflow server listening on port 8120
+Loaded environment variables from .env
+3 tasks found in npm run dev:workflows
+  • editorial_pipeline
+  • review_draft
+  • revise_draft
+
+To browse and run tasks, open another terminal and run:
+  render workflows tasks list --local
+```
+
+In another terminal, confirm that the tasks are available:
+
+```bash
+render workflows tasks list --local
+```
+
+The command displays each task's name, ID, and creation time. Press `Ctrl+C`, then start the editorial pipeline from the same terminal:
+
+```bash
+render workflows tasks runs start editorial_pipeline \
+  --local \
+  --input='["Render Workflows runs long-running tasks outside the request lifecycle."]'
+```
+
+The development server records the parent run, three parallel reviews, and the final revision.
+
+### Production
+
+Create a workflow service from the current repository:
+
+```bash
+render workflows create \
+  --name mastra-workflows \
+  --repo . \
+  --runtime node \
+  --build-command "npm install && npm run build" \
+  --run-command "npm run start:workflows"
+```
+
+Add `OPENAI_API_KEY`, or the key for your chosen model provider, to the service's environment variables.
+
+After deployment, start a production run. If needed, replace `mastra-workflows/editorial_pipeline` with the task slug shown in the Render Dashboard.
+
+```bash
+render workflows tasks start mastra-workflows/editorial_pipeline \
+  --input='["Render Workflows runs long-running tasks outside the request lifecycle."]'
+```
+
+Open the workflow service in the Render Dashboard to inspect each task run, attempt, result, and log stream.
+
+## Related
+
+- [Render Workflows documentation](https://render.com/docs/workflows)
+- [Defining Render workflow tasks](https://render.com/docs/workflows-defining)
+- [Triggering task runs](https://render.com/docs/workflows-running)
+- [Render Workflows TypeScript SDK](https://render.com/docs/workflows-sdk-typescript)
+- [Render Workflows limits and pricing](https://render.com/docs/workflows-limits)

package/.docs/integrations/sandboxes/cloudflare-sandbox.md

@@ -0,0 +1,118 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Cloudflare Sandbox
+
+`CloudflareSandbox` executes commands and manages files in a remote [Cloudflare Sandbox](https://developers.cloudflare.com/sandbox/) through the [Sandbox Bridge HTTP API](https://developers.cloudflare.com/sandbox/bridge/http-api/).
+
+> **Warning:** Deploy and secure a [Sandbox Bridge Worker](https://developers.cloudflare.com/sandbox/bridge/) before using this provider. The bridge can create and delete sandboxes, execute commands, and write files on behalf of its callers.
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/cloudflare-sandbox
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/cloudflare-sandbox
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/cloudflare-sandbox
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/cloudflare-sandbox
+```
+
+## Usage
+
+Add `CloudflareSandbox` to a workspace and assign it to an agent:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Workspace } from '@mastra/core/workspace'
+import { CloudflareSandbox } from '@mastra/cloudflare-sandbox'
+
+const workspace = new Workspace({
+  sandbox: new CloudflareSandbox({
+    baseUrl: process.env.CLOUDFLARE_SANDBOX_BRIDGE_URL!,
+    apiToken: process.env.CLOUDFLARE_SANDBOX_API_KEY,
+    workingDirectory: '/workspace',
+    commandTimeout: 300_000,
+  }),
+})
+
+export const agent = new Agent({
+  id: 'dev-agent',
+  name: 'Development agent',
+  instructions: 'You are a helpful development assistant.',
+  model: 'anthropic/claude-sonnet-4-6',
+  workspace,
+})
+```
+
+The provider creates a remote sandbox when the workspace starts. Pass `sandboxId` to reconnect to an existing sandbox instead.
+
+## Execute commands
+
+Pass command arguments, environment variables, a working directory, and streaming callbacks through `executeCommand()`. The provider sends the command as an `argv` array, so the bridge handles shell escaping:
+
+```typescript
+const result = await workspace.sandbox?.executeCommand?.('npm', ['test'], {
+  cwd: '/workspace/project',
+  env: {
+    NODE_ENV: 'test',
+  },
+  onStdout: chunk => process.stdout.write(chunk),
+  onStderr: chunk => process.stderr.write(chunk),
+})
+```
+
+## Write files
+
+Relative paths are resolved under `/workspace`. Absolute paths must also resolve within `/workspace`. Each file is sent as its own bridge request, and the bridge caps a single file at 32 MiB.
+
+```typescript
+await workspace.sandbox?.writeFiles?.([
+  { path: 'src/index.ts', content: "console.log('hello')\n" },
+  { path: '/workspace/package.json', content: JSON.stringify({ type: 'module' }) },
+])
+```
+
+## Constructor parameters
+
+**baseUrl** (`string`): URL of the deployed Cloudflare Sandbox Bridge Worker.
+
+**apiToken** (`string`): Bearer token matching the Worker's SANDBOX\_API\_KEY secret.
+
+**sandboxId** (`string`): Existing Cloudflare sandbox ID to reconnect to instead of creating a sandbox.
+
+**id** (`string`): Stable Mastra identifier. Defaults to a generated UUID-based value.
+
+**name** (`string`): Human-readable sandbox name. (Default: `Cloudflare Sandbox`)
+
+**env** (`Record<string, string>`): Environment variables applied to every command.
+
+**workingDirectory** (`string`): Working directory applied to every command.
+
+**commandTimeout** (`number`): Default command timeout in milliseconds. (Default: `300000`)
+
+**instructions** (`string | ((options) => string)`): Custom instructions returned by getInstructions().
+
+## Lifecycle behavior
+
+- `start()`: Reconnects to `sandboxId` or creates a remote sandbox.
+- `stop()`: Detaches the Mastra lifecycle without deleting the remote sandbox because the bridge doesn't expose a suspend operation.
+- `destroy()`: Deletes the remote sandbox.
+
+## Limitations
+
+The provider supports command execution, streamed output, and file writes. It doesn't currently expose the bridge's bucket mounts, sessions, PTY terminals, or workspace persistence routes, and it doesn't support background process management, stdin, snapshots, or port URLs.

package/.docs/integrations.md

@@ -36,6 +36,7 @@
 - [AgentCore](https://mastra.ai/integrations/sandboxes/agentcore)
 - [Apple Container](https://mastra.ai/integrations/sandboxes/apple-container)
 - [Blaxel](https://mastra.ai/integrations/sandboxes/blaxel)
+- [Cloudflare Sandbox](https://mastra.ai/integrations/sandboxes/cloudflare-sandbox)
 - [Daytona](https://mastra.ai/integrations/sandboxes/daytona)
 - [Docker](https://mastra.ai/integrations/sandboxes/docker)
 - [E2B](https://mastra.ai/integrations/sandboxes/e2b)
@@ -90,6 +91,7 @@
 - [Kubernetes](https://mastra.ai/integrations/deploy/kubernetes)
 - [Mastra](https://mastra.ai/docs/mastra-platform/deploy)
 - [Netlify](https://mastra.ai/integrations/deploy/netlify)
+- [Render](https://mastra.ai/integrations/deploy/render)
 - [Temporal](https://mastra.ai/integrations/deploy/temporal)
 - [Vercel](https://mastra.ai/integrations/deploy/vercel)
 

package/.docs/reference/processors/skill-search-processor.md

@@ -41,6 +41,8 @@ const skillSearch = new SkillSearchProcessor({
 
 **options.ttl** (`number`): Time-to-live for thread state in milliseconds. After this duration of inactivity, thread state will be cleaned up. Set to 0 to disable cleanup.
 
+**options.blockingRefresh** (`boolean`): When true, awaits the skills staleness check before the first step of each request so skill changes appear in the same turn. When false, the cached catalog is served and revalidated in the background, so skill changes can lag by one turn plus the staleness cooldown (up to 30 seconds).
+
 ## Returns
 
 **id** (`string`): Processor identifier set to 'skill-search'

package/.docs/reference/tools/mcp-server.md

@@ -104,7 +104,7 @@ By default, `MCPServer` speaks the legacy (2025-era) MCP protocol: sessionful st
 - Tool list, prompt list, resource list, and resource update notifications also reach `2026-07-28` clients through `subscriptions/listen`.
 - Tool log messages honor the caller's per-request `logLevel` opt-in instead of the session-level `logging/setLevel`.
 - Configured `cacheHints` are advertised on cacheable results such as `tools/list`.
-- Tool elicitation (`options.mcp.elicitation.sendRequest()`) works on both eras. On `2026-07-28` requests, it uses the protocol's multi round-trip mechanism. The tool call first returns an `input_required` result. After the client answers, the call retries with the answer attached. The `sendRequest()` promise API is unchanged, but the tool function re-executes from the top on each retry, so keep side effects idempotent (or place them after the last elicitation) and keep the order of `sendRequest()` calls deterministic for a given input.
+- Tool elicitation (`options.mcp.elicitation.sendRequest()`) works on both eras. On `2026-07-28` requests, it uses the protocol's multi round-trip mechanism. The tool call first returns an `input_required` result. After the client answers, the call retries with the answer attached. The `sendRequest()` promise API is unchanged, but the tool function re-executes from the top on each retry, so keep side effects idempotent (or place them after the last elicitation) and keep the order of `sendRequest()` calls deterministic for an input.
 
 ```typescript
 const server = new MCPServer({

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @mastra/mcp-docs-server
 
+## 1.2.17-alpha.19
+
+### Patch Changes
+
+- Updated dependencies [[`6db7a5d`](https://github.com/mastra-ai/mastra/commit/6db7a5dd3dd2b6f7ef75dcd804fcffef5fa83963), [`0cdc5dc`](https://github.com/mastra-ai/mastra/commit/0cdc5dc69024957815da4f51acc4119eb4f447d7)]:
+  - @mastra/core@1.60.0-alpha.12
+
 ## 1.2.17-alpha.18
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.2.17-alpha.18",
+  "version": "1.2.17-alpha.19",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -28,8 +28,8 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.4.3",
-    "@mastra/mcp": "^1.17.0-alpha.2",
-    "@mastra/core": "1.60.0-alpha.11"
+    "@mastra/core": "1.60.0-alpha.12",
+    "@mastra/mcp": "^1.17.0-alpha.2"
   },
   "devDependencies": {
     "@hono/node-server": "^2.0.0",
@@ -45,9 +45,9 @@
     "tsx": "^4.23.1",
     "typescript": "^6.0.3",
     "vitest": "4.1.10",
-    "@mastra/core": "1.60.0-alpha.11",
-    "@internal/types-builder": "0.0.98",
-    "@internal/lint": "0.0.123"
+    "@internal/lint": "0.0.123",
+    "@mastra/core": "1.60.0-alpha.12",
+    "@internal/types-builder": "0.0.98"
   },
   "homepage": "https://mastra.ai",
   "repository": {