@mastra/mcp-docs-server 1.1.26-alpha.6 → 1.1.26
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.
- package/.docs/docs/agents/structured-output.md +22 -0
- package/.docs/docs/agents/supervisor-agents.md +18 -0
- package/.docs/docs/editor/overview.md +69 -0
- package/.docs/docs/memory/observational-memory.md +4 -0
- package/.docs/docs/memory/storage.md +1 -0
- package/.docs/docs/observability/tracing/exporters/langfuse.md +31 -0
- package/.docs/guides/deployment/netlify.md +16 -1
- package/.docs/guides/getting-started/next-js.md +0 -4
- package/.docs/guides/migrations/mastra-cloud.md +128 -3
- package/.docs/models/gateways/netlify.md +2 -2
- package/.docs/models/gateways/openrouter.md +3 -1
- package/.docs/models/gateways/vercel.md +4 -1
- package/.docs/models/index.md +36 -1
- package/.docs/models/providers/302ai.md +32 -1
- package/.docs/models/providers/alibaba-cn.md +2 -1
- package/.docs/models/providers/anthropic.md +2 -1
- package/.docs/models/providers/berget.md +9 -12
- package/.docs/models/providers/cloudflare-workers-ai.md +2 -1
- package/.docs/models/providers/cortecs.md +4 -1
- package/.docs/models/providers/deepinfra.md +4 -1
- package/.docs/models/providers/digitalocean.md +116 -0
- package/.docs/models/providers/fireworks-ai.md +2 -1
- package/.docs/models/providers/firmware.md +2 -3
- package/.docs/models/providers/helicone.md +1 -2
- package/.docs/models/providers/huggingface.md +2 -1
- package/.docs/models/providers/kilo.md +2 -1
- package/.docs/models/providers/kimi-for-coding.md +2 -1
- package/.docs/models/providers/llmgateway.md +59 -77
- package/.docs/models/providers/moonshotai-cn.md +3 -2
- package/.docs/models/providers/moonshotai.md +3 -2
- package/.docs/models/providers/nano-gpt.md +8 -1
- package/.docs/models/providers/nvidia.md +2 -1
- package/.docs/models/providers/ollama-cloud.md +2 -1
- package/.docs/models/providers/openai.md +1 -2
- package/.docs/models/providers/opencode-go.md +2 -1
- package/.docs/models/providers/opencode.md +5 -1
- package/.docs/models/providers/ovhcloud.md +4 -7
- package/.docs/models/providers/poe.md +2 -1
- package/.docs/models/providers/tencent-token-plan.md +71 -0
- package/.docs/models/providers/tencent-tokenhub.md +71 -0
- package/.docs/models/providers/wafer.ai.md +72 -0
- package/.docs/models/providers/zenmux.md +3 -1
- package/.docs/models/providers.md +4 -0
- package/.docs/reference/agents/generate.md +8 -0
- package/.docs/reference/client-js/workflows.md +12 -0
- package/.docs/reference/core/mastra-class.md +9 -1
- package/.docs/reference/deployer/cloudflare.md +14 -1
- package/.docs/reference/deployer/netlify.md +50 -2
- package/.docs/reference/harness/harness-class.md +72 -49
- package/.docs/reference/index.md +3 -0
- package/.docs/reference/observability/tracing/exporters/langfuse.md +2 -0
- package/.docs/reference/processors/prefill-error-handler.md +5 -5
- package/.docs/reference/storage/cloudflare-d1.md +42 -42
- package/.docs/reference/storage/redis.md +266 -0
- package/.docs/reference/streaming/agents/stream.md +8 -0
- package/.docs/reference/streaming/workflows/resumeStream.md +2 -0
- package/.docs/reference/tools/tavily.md +307 -0
- package/.docs/reference/workflows/run-methods/resume.md +24 -0
- package/.docs/reference/workflows/workflow-methods/foreach.md +14 -1
- package/.docs/reference/workspace/docker-sandbox.md +196 -0
- package/CHANGELOG.md +78 -0
- package/package.json +10 -10
|
@@ -0,0 +1,307 @@
|
|
|
1
|
+
# Tavily tools
|
|
2
|
+
|
|
3
|
+
**Added in:** `@mastra/tavily@0.1.0-alpha.0`
|
|
4
|
+
|
|
5
|
+
The `@mastra/tavily` package wraps the [Tavily](https://app.tavily.com) API as Mastra-compatible tools. It exposes factory functions for search, extract, crawl, and map — each returning a tool created with [`createTool()`](https://mastra.ai/reference/tools/create-tool) that includes full Zod input/output schemas.
|
|
6
|
+
|
|
7
|
+
## Installation
|
|
8
|
+
|
|
9
|
+
**npm**:
|
|
10
|
+
|
|
11
|
+
```sh
|
|
12
|
+
npm install @mastra/tavily @tavily/core zod
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
**pnpm**:
|
|
16
|
+
|
|
17
|
+
```sh
|
|
18
|
+
pnpm add @mastra/tavily @tavily/core zod
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
**Yarn**:
|
|
22
|
+
|
|
23
|
+
```sh
|
|
24
|
+
yarn add @mastra/tavily @tavily/core zod
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
**Bun**:
|
|
28
|
+
|
|
29
|
+
```sh
|
|
30
|
+
bun add @mastra/tavily @tavily/core zod
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
## Quick start
|
|
34
|
+
|
|
35
|
+
Use `createTavilyTools()` to get all four tools with shared configuration:
|
|
36
|
+
|
|
37
|
+
```typescript
|
|
38
|
+
import { createTavilyTools } from '@mastra/tavily'
|
|
39
|
+
|
|
40
|
+
const tools = createTavilyTools()
|
|
41
|
+
// Or pass an explicit API key:
|
|
42
|
+
// const tools = createTavilyTools({ apiKey: 'tvly-...' })
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Each tool can also be created individually:
|
|
46
|
+
|
|
47
|
+
```typescript
|
|
48
|
+
import { createTavilySearchTool, createTavilyExtractTool } from '@mastra/tavily'
|
|
49
|
+
|
|
50
|
+
const searchTool = createTavilySearchTool()
|
|
51
|
+
const extractTool = createTavilyExtractTool({ apiKey: 'tvly-...' })
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
By default, all tools read `TAVILY_API_KEY` from the environment. You can pass `{ apiKey }` explicitly to override.
|
|
55
|
+
|
|
56
|
+
## Configuration
|
|
57
|
+
|
|
58
|
+
All factory functions accept `TavilyClientOptions` from `@tavily/core`:
|
|
59
|
+
|
|
60
|
+
**apiKey** (`string`): Tavily API key. Falls back to the \`TAVILY\_API\_KEY\` environment variable.
|
|
61
|
+
|
|
62
|
+
**clientSource** (`string`): Attribution string sent with each request. (Default: `'mastra'`)
|
|
63
|
+
|
|
64
|
+
**apiBaseURL** (`string`): Base URL for the Tavily API.
|
|
65
|
+
|
|
66
|
+
**proxies** (`object`): Proxy configuration passed to the underlying HTTP client.
|
|
67
|
+
|
|
68
|
+
**projectId** (`string`): Tavily project ID for request scoping.
|
|
69
|
+
|
|
70
|
+
## `createTavilyTools()`
|
|
71
|
+
|
|
72
|
+
Returns an object containing all four tools with a shared configuration.
|
|
73
|
+
|
|
74
|
+
```typescript
|
|
75
|
+
import { createTavilyTools } from '@mastra/tavily'
|
|
76
|
+
|
|
77
|
+
const tools = createTavilyTools({ apiKey: 'tvly-...' })
|
|
78
|
+
// tools.tavilySearch, tools.tavilyExtract, tools.tavilyCrawl, tools.tavilyMap
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
**Returns:** `{ tavilySearch, tavilyExtract, tavilyCrawl, tavilyMap }`
|
|
82
|
+
|
|
83
|
+
## `createTavilySearchTool()`
|
|
84
|
+
|
|
85
|
+
Creates a tool that searches the web using Tavily. Returns relevant results with content snippets, optional AI-generated answers, and images.
|
|
86
|
+
|
|
87
|
+
**Tool ID:** `tavily-search`
|
|
88
|
+
|
|
89
|
+
```typescript
|
|
90
|
+
import { createTavilySearchTool } from '@mastra/tavily'
|
|
91
|
+
|
|
92
|
+
const searchTool = createTavilySearchTool()
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
### Input
|
|
96
|
+
|
|
97
|
+
**query** (`string`): The search query.
|
|
98
|
+
|
|
99
|
+
**searchDepth** (`'basic' | 'advanced' | 'fast' | 'ultra-fast'`): Search depth. Use 'basic' for standard results, 'advanced' for more thorough results, or 'fast'/'ultra-fast' for low latency.
|
|
100
|
+
|
|
101
|
+
**maxResults** (`number`): Maximum number of results to return (1-20).
|
|
102
|
+
|
|
103
|
+
**includeAnswer** (`boolean | 'basic' | 'advanced'`): Include an AI-generated answer summary.
|
|
104
|
+
|
|
105
|
+
**includeImages** (`boolean`): Include query-related images in the response.
|
|
106
|
+
|
|
107
|
+
**includeImageDescriptions** (`boolean`): Include descriptions for returned images.
|
|
108
|
+
|
|
109
|
+
**includeRawContent** (`false | 'markdown' | 'text'`): Include cleaned HTML content of each result. Pass false to disable, or 'markdown'/'text' for format.
|
|
110
|
+
|
|
111
|
+
**includeDomains** (`string[]`): Restrict results to these domains.
|
|
112
|
+
|
|
113
|
+
**excludeDomains** (`string[]`): Exclude results from these domains.
|
|
114
|
+
|
|
115
|
+
**timeRange** (`'day' | 'week' | 'month' | 'year'`): Filter results by recency.
|
|
116
|
+
|
|
117
|
+
### Output
|
|
118
|
+
|
|
119
|
+
**query** (`string`): The original search query.
|
|
120
|
+
|
|
121
|
+
**answer** (`string`): AI-generated answer summary.
|
|
122
|
+
|
|
123
|
+
**images** (`{ url: string; description?: string }[]`): Related images.
|
|
124
|
+
|
|
125
|
+
**results** (`SearchResult[]`): Array of search results.
|
|
126
|
+
|
|
127
|
+
**results.title** (`string`): Result title.
|
|
128
|
+
|
|
129
|
+
**results.url** (`string`): Result URL.
|
|
130
|
+
|
|
131
|
+
**results.content** (`string`): Content snippet.
|
|
132
|
+
|
|
133
|
+
**results.score** (`number`): Relevance score.
|
|
134
|
+
|
|
135
|
+
**results.rawContent** (`string`): Full-page content (when requested).
|
|
136
|
+
|
|
137
|
+
**responseTime** (`number`): Server response time in seconds.
|
|
138
|
+
|
|
139
|
+
## `createTavilyExtractTool()`
|
|
140
|
+
|
|
141
|
+
Creates a tool that extracts content from one or more URLs. Returns raw page content in markdown or text format with up to 20 URLs per request.
|
|
142
|
+
|
|
143
|
+
**Tool ID:** `tavily-extract`
|
|
144
|
+
|
|
145
|
+
```typescript
|
|
146
|
+
import { createTavilyExtractTool } from '@mastra/tavily'
|
|
147
|
+
|
|
148
|
+
const extractTool = createTavilyExtractTool()
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
### Input
|
|
152
|
+
|
|
153
|
+
**urls** (`string[]`): URLs to extract content from (1-20).
|
|
154
|
+
|
|
155
|
+
**extractDepth** (`'basic' | 'advanced'`): Extraction depth. Use 'advanced' to retrieve tables and embedded content.
|
|
156
|
+
|
|
157
|
+
**query** (`string`): User intent for reranking extracted content chunks by relevance.
|
|
158
|
+
|
|
159
|
+
**includeImages** (`boolean`): Include images extracted from the pages.
|
|
160
|
+
|
|
161
|
+
**format** (`'markdown' | 'text'`): Output format for extracted content. (Default: `'markdown'`)
|
|
162
|
+
|
|
163
|
+
### Output
|
|
164
|
+
|
|
165
|
+
**results** (`ExtractResult[]`): Successfully extracted pages.
|
|
166
|
+
|
|
167
|
+
**results.url** (`string`): Page URL.
|
|
168
|
+
|
|
169
|
+
**results.rawContent** (`string`): Extracted page content.
|
|
170
|
+
|
|
171
|
+
**results.images** (`string[]`): Extracted image URLs.
|
|
172
|
+
|
|
173
|
+
**failedResults** (`FailedResult[]`): URLs that failed extraction.
|
|
174
|
+
|
|
175
|
+
**failedResults.url** (`string`): Failed URL.
|
|
176
|
+
|
|
177
|
+
**failedResults.error** (`string`): Error message.
|
|
178
|
+
|
|
179
|
+
**responseTime** (`number`): Server response time in seconds.
|
|
180
|
+
|
|
181
|
+
## `createTavilyCrawlTool()`
|
|
182
|
+
|
|
183
|
+
Creates a tool that crawls a website starting from a URL. Extracts content from discovered pages with configurable depth, breadth, and domain constraints.
|
|
184
|
+
|
|
185
|
+
**Tool ID:** `tavily-crawl`
|
|
186
|
+
|
|
187
|
+
```typescript
|
|
188
|
+
import { createTavilyCrawlTool } from '@mastra/tavily'
|
|
189
|
+
|
|
190
|
+
const crawlTool = createTavilyCrawlTool()
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
### Input
|
|
194
|
+
|
|
195
|
+
**url** (`string`): The root URL to begin the crawl.
|
|
196
|
+
|
|
197
|
+
**maxDepth** (`number`): Maximum depth of the crawl from the base URL.
|
|
198
|
+
|
|
199
|
+
**maxBreadth** (`number`): Maximum number of links to follow per page.
|
|
200
|
+
|
|
201
|
+
**limit** (`number`): Total number of pages the crawler processes before stopping.
|
|
202
|
+
|
|
203
|
+
**instructions** (`string`): Natural language instructions for the crawler.
|
|
204
|
+
|
|
205
|
+
**selectPaths** (`string[]`): Regex patterns to select specific URL paths.
|
|
206
|
+
|
|
207
|
+
**selectDomains** (`string[]`): Regex patterns to restrict to specific domains.
|
|
208
|
+
|
|
209
|
+
**excludePaths** (`string[]`): Regex patterns to exclude specific URL paths.
|
|
210
|
+
|
|
211
|
+
**excludeDomains** (`string[]`): Regex patterns to exclude specific domains.
|
|
212
|
+
|
|
213
|
+
**allowExternal** (`boolean`): Whether to follow links to external domains.
|
|
214
|
+
|
|
215
|
+
**extractDepth** (`'basic' | 'advanced'`): Extraction depth. Use 'advanced' to retrieve tables and embedded content.
|
|
216
|
+
|
|
217
|
+
**includeImages** (`boolean`): Include images from crawled pages.
|
|
218
|
+
|
|
219
|
+
**format** (`'markdown' | 'text'`): Output format for extracted content. (Default: `'markdown'`)
|
|
220
|
+
|
|
221
|
+
### Output
|
|
222
|
+
|
|
223
|
+
**baseUrl** (`string`): The root URL that was crawled.
|
|
224
|
+
|
|
225
|
+
**results** (`CrawlResult[]`): Content extracted from discovered pages.
|
|
226
|
+
|
|
227
|
+
**results.url** (`string`): Page URL.
|
|
228
|
+
|
|
229
|
+
**results.rawContent** (`string`): Extracted page content.
|
|
230
|
+
|
|
231
|
+
**results.images** (`string[]`): Image URLs found on the page.
|
|
232
|
+
|
|
233
|
+
**responseTime** (`number`): Server response time in seconds.
|
|
234
|
+
|
|
235
|
+
## `createTavilyMapTool()`
|
|
236
|
+
|
|
237
|
+
Creates a tool that maps a website's structure starting from a URL. Discovers and returns a list of URLs without extracting page content. Use this to understand site structure before targeted extraction.
|
|
238
|
+
|
|
239
|
+
**Tool ID:** `tavily-map`
|
|
240
|
+
|
|
241
|
+
```typescript
|
|
242
|
+
import { createTavilyMapTool } from '@mastra/tavily'
|
|
243
|
+
|
|
244
|
+
const mapTool = createTavilyMapTool()
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
### Input
|
|
248
|
+
|
|
249
|
+
**url** (`string`): The root URL to begin mapping.
|
|
250
|
+
|
|
251
|
+
**maxDepth** (`number`): Maximum depth of the mapping from the base URL.
|
|
252
|
+
|
|
253
|
+
**maxBreadth** (`number`): Maximum number of links to follow per page.
|
|
254
|
+
|
|
255
|
+
**limit** (`number`): Total number of links the mapper processes before stopping.
|
|
256
|
+
|
|
257
|
+
**instructions** (`string`): Natural language instructions for the mapper.
|
|
258
|
+
|
|
259
|
+
**selectPaths** (`string[]`): Regex patterns to select specific URL paths.
|
|
260
|
+
|
|
261
|
+
**selectDomains** (`string[]`): Regex patterns to restrict to specific domains.
|
|
262
|
+
|
|
263
|
+
**excludePaths** (`string[]`): Regex patterns to exclude specific URL paths.
|
|
264
|
+
|
|
265
|
+
**excludeDomains** (`string[]`): Regex patterns to exclude specific domains.
|
|
266
|
+
|
|
267
|
+
**allowExternal** (`boolean`): Whether to include external domain links.
|
|
268
|
+
|
|
269
|
+
### Output
|
|
270
|
+
|
|
271
|
+
**baseUrl** (`string`): The root URL that was mapped.
|
|
272
|
+
|
|
273
|
+
**results** (`string[]`): Discovered URLs.
|
|
274
|
+
|
|
275
|
+
**responseTime** (`number`): Server response time in seconds.
|
|
276
|
+
|
|
277
|
+
## Agent example
|
|
278
|
+
|
|
279
|
+
The following example demonstrates a research agent that combines search and extract:
|
|
280
|
+
|
|
281
|
+
```typescript
|
|
282
|
+
import { Agent } from '@mastra/core/agent'
|
|
283
|
+
import { createTavilySearchTool, createTavilyExtractTool } from '@mastra/tavily'
|
|
284
|
+
|
|
285
|
+
const agent = new Agent({
|
|
286
|
+
id: 'web-search-agent',
|
|
287
|
+
name: 'Web Search Agent',
|
|
288
|
+
model: 'anthropic/claude-sonnet-4-6',
|
|
289
|
+
instructions:
|
|
290
|
+
'You are a web search assistant. Use search tool to find relevant pages, then use extract tool to get full content from the best results.',
|
|
291
|
+
tools: {
|
|
292
|
+
search: createTavilySearchTool(),
|
|
293
|
+
extract: createTavilyExtractTool(),
|
|
294
|
+
},
|
|
295
|
+
})
|
|
296
|
+
```
|
|
297
|
+
|
|
298
|
+
## Environment variables
|
|
299
|
+
|
|
300
|
+
| Variable | Description |
|
|
301
|
+
| ---------------- | ------------------------------------------------------------------------------------------- |
|
|
302
|
+
| `TAVILY_API_KEY` | Your Tavily API key. Used as the default when `apiKey` is not passed to a factory function. |
|
|
303
|
+
|
|
304
|
+
## Related
|
|
305
|
+
|
|
306
|
+
- [`createTool()`](https://mastra.ai/reference/tools/create-tool)
|
|
307
|
+
- [Tavily API documentation](https://docs.tavily.com)
|
|
@@ -26,6 +26,8 @@ if (result.status === 'suspended') {
|
|
|
26
26
|
|
|
27
27
|
**retryCount** (`number`): Optional retry count for nested workflow execution
|
|
28
28
|
|
|
29
|
+
**forEachIndex** (`number`): Target a specific iteration of a suspended \`.foreach()\` step. Pass the zero-based index of the iteration you want to resume; other iterations remain suspended. Omit this field to resume all suspended iterations of the step with the same \`resumeData\`.
|
|
30
|
+
|
|
29
31
|
**tracingContext** (`TracingContext`): Tracing context for creating child spans and adding metadata. Automatically injected when using Mastra's tracing system.
|
|
30
32
|
|
|
31
33
|
**tracingContext.currentSpan** (`Span`): Current span for creating child spans and adding metadata. Use this to create custom child spans or update span attributes during execution.
|
|
@@ -67,6 +69,28 @@ if (result.status === 'suspended') {
|
|
|
67
69
|
|
|
68
70
|
> **Note:** When exactly one step is suspended, you can omit the `step` parameter and the workflow will automatically resume that step. For workflows with multiple suspended steps, you must explicitly specify which step to resume.
|
|
69
71
|
|
|
72
|
+
### Resuming a single [`.foreach()`](https://mastra.ai/reference/workflows/workflow-methods/foreach) iteration
|
|
73
|
+
|
|
74
|
+
When a [`.foreach()`](https://mastra.ai/reference/workflows/workflow-methods/foreach) step suspends across multiple iterations, use `forEachIndex` (zero-based) to resume one iteration at a time with different `resumeData`. Iterations not targeted by `forEachIndex` remain suspended until resumed.
|
|
75
|
+
|
|
76
|
+
```typescript
|
|
77
|
+
// Resume only the second iteration (index 1) with its own data
|
|
78
|
+
await run.resume({
|
|
79
|
+
step: 'approve',
|
|
80
|
+
resumeData: { ok: true },
|
|
81
|
+
forEachIndex: 1,
|
|
82
|
+
})
|
|
83
|
+
|
|
84
|
+
// Later, resume the first iteration with different data
|
|
85
|
+
await run.resume({
|
|
86
|
+
step: 'approve',
|
|
87
|
+
resumeData: { ok: false },
|
|
88
|
+
forEachIndex: 0,
|
|
89
|
+
})
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
If `forEachIndex` is omitted, every suspended iteration of the step is resumed with the same `resumeData`.
|
|
93
|
+
|
|
70
94
|
## Related
|
|
71
95
|
|
|
72
96
|
- [Workflows overview](https://mastra.ai/docs/workflows/overview)
|
|
@@ -113,6 +113,19 @@ Each progress event payload contains:
|
|
|
113
113
|
|
|
114
114
|
**iterationOutput** (`Record<string, any>`): Output of the iteration (present when iterationStatus is 'success')
|
|
115
115
|
|
|
116
|
+
### Resuming a single iteration
|
|
117
|
+
|
|
118
|
+
When a step inside `.foreach()` suspends, each iteration suspends independently. Pass `forEachIndex` to [`run.resume()`](https://mastra.ai/reference/workflows/run-methods/resume) to resume one iteration at a time with its own `resumeData`. Omitting `forEachIndex` resumes every suspended iteration with the same data.
|
|
119
|
+
|
|
120
|
+
```typescript
|
|
121
|
+
await run.resume({
|
|
122
|
+
step: 'approve',
|
|
123
|
+
resumeData: { ok: true },
|
|
124
|
+
forEachIndex: 1,
|
|
125
|
+
})
|
|
126
|
+
```
|
|
127
|
+
|
|
116
128
|
## Related
|
|
117
129
|
|
|
118
|
-
- [Looping with foreach](https://mastra.ai/docs/workflows/control-flow)
|
|
130
|
+
- [Looping with foreach](https://mastra.ai/docs/workflows/control-flow)
|
|
131
|
+
- [run.resume()](https://mastra.ai/reference/workflows/run-methods/resume)
|
|
@@ -0,0 +1,196 @@
|
|
|
1
|
+
# DockerSandbox
|
|
2
|
+
|
|
3
|
+
Executes commands inside Docker containers on the local machine. Uses long-lived containers with `docker exec` for command execution. Targets local development, CI/CD, air-gapped deployments, and cost-sensitive scenarios where cloud sandboxes are unnecessary.
|
|
4
|
+
|
|
5
|
+
> **Info:** For interface details, see [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox).
|
|
6
|
+
|
|
7
|
+
## Installation
|
|
8
|
+
|
|
9
|
+
**npm**:
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
npm install @mastra/docker
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
**pnpm**:
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
pnpm add @mastra/docker
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
**Yarn**:
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
yarn add @mastra/docker
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
**Bun**:
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
bun add @mastra/docker
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Requires [Docker Engine](https://docs.docker.com/engine/install/) running on the host machine.
|
|
34
|
+
|
|
35
|
+
## Usage
|
|
36
|
+
|
|
37
|
+
Add a `DockerSandbox` to a workspace and assign it to an agent:
|
|
38
|
+
|
|
39
|
+
```typescript
|
|
40
|
+
import { Agent } from '@mastra/core/agent'
|
|
41
|
+
import { Workspace } from '@mastra/core/workspace'
|
|
42
|
+
import { DockerSandbox } from '@mastra/docker'
|
|
43
|
+
|
|
44
|
+
const workspace = new Workspace({
|
|
45
|
+
sandbox: new DockerSandbox({
|
|
46
|
+
image: 'node:22-slim',
|
|
47
|
+
}),
|
|
48
|
+
})
|
|
49
|
+
|
|
50
|
+
const agent = new Agent({
|
|
51
|
+
name: 'dev-agent',
|
|
52
|
+
model: 'anthropic/claude-opus-4-6',
|
|
53
|
+
workspace,
|
|
54
|
+
})
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
## Constructor parameters
|
|
58
|
+
|
|
59
|
+
**id** (`string`): Unique identifier for this sandbox instance. Used for container naming and reconnection via labels. (Default: `Auto-generated`)
|
|
60
|
+
|
|
61
|
+
**image** (`string`): Docker image to use for the container. (Default: `'node:22-slim'`)
|
|
62
|
+
|
|
63
|
+
**command** (`string[]`): Container entrypoint command. Must keep the container alive for exec-based command execution. (Default: `['sleep', 'infinity']`)
|
|
64
|
+
|
|
65
|
+
**env** (`Record<string, string>`): Environment variables to set in the container.
|
|
66
|
+
|
|
67
|
+
**volumes** (`Record<string, string>`): Host-to-container bind mounts. Keys are host paths, values are container paths.
|
|
68
|
+
|
|
69
|
+
**network** (`string`): Docker network to join.
|
|
70
|
+
|
|
71
|
+
**privileged** (`boolean`): Run in privileged mode. (Default: `false`)
|
|
72
|
+
|
|
73
|
+
**workingDir** (`string`): Working directory inside the container. (Default: `'/workspace'`)
|
|
74
|
+
|
|
75
|
+
**labels** (`Record<string, string>`): Additional container labels. Mastra labels (mastra.sandbox, mastra.sandbox.id) are always included.
|
|
76
|
+
|
|
77
|
+
**timeout** (`number`): Default command timeout in milliseconds. (Default: `300000 (5 minutes)`)
|
|
78
|
+
|
|
79
|
+
**dockerOptions** (`Docker.DockerOptions`): Pass-through dockerode connection options for custom socket paths, remote hosts, or TLS certificates.
|
|
80
|
+
|
|
81
|
+
**instructions** (`string | function`): Custom instructions that override the default instructions returned by getInstructions(). Pass an empty string to suppress instructions.
|
|
82
|
+
|
|
83
|
+
## Properties
|
|
84
|
+
|
|
85
|
+
**id** (`string`): Sandbox instance identifier.
|
|
86
|
+
|
|
87
|
+
**name** (`string`): Provider name ('DockerSandbox').
|
|
88
|
+
|
|
89
|
+
**provider** (`string`): Provider identifier ('docker').
|
|
90
|
+
|
|
91
|
+
**status** (`ProviderStatus`): 'pending' | 'starting' | 'running' | 'stopping' | 'stopped' | 'destroying' | 'destroyed' | 'error'
|
|
92
|
+
|
|
93
|
+
**container** (`Container`): The underlying dockerode Container instance. Throws SandboxNotReadyError if the sandbox has not been started.
|
|
94
|
+
|
|
95
|
+
**processes** (`DockerProcessManager`): Background process manager. See \[SandboxProcessManager reference]\(/reference/workspace/process-manager).
|
|
96
|
+
|
|
97
|
+
## Background processes
|
|
98
|
+
|
|
99
|
+
`DockerSandbox` includes a built-in process manager for spawning and managing background processes. Processes run inside the container using `docker exec`.
|
|
100
|
+
|
|
101
|
+
```typescript
|
|
102
|
+
const sandbox = new DockerSandbox({ id: 'dev-sandbox' })
|
|
103
|
+
await sandbox._start()
|
|
104
|
+
|
|
105
|
+
// Spawn a background process
|
|
106
|
+
const handle = await sandbox.processes.spawn('node server.js', {
|
|
107
|
+
env: { PORT: '3000' },
|
|
108
|
+
onStdout: data => console.log(data),
|
|
109
|
+
})
|
|
110
|
+
|
|
111
|
+
// Interact with the process
|
|
112
|
+
console.log(handle.stdout)
|
|
113
|
+
await handle.sendStdin('input\n')
|
|
114
|
+
await handle.kill()
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
See [`SandboxProcessManager` reference](https://mastra.ai/reference/workspace/process-manager) for the full API.
|
|
118
|
+
|
|
119
|
+
## Environment variables
|
|
120
|
+
|
|
121
|
+
Set environment variables at the container level with `env`. Per-command environment variables can also be passed when spawning processes:
|
|
122
|
+
|
|
123
|
+
```typescript
|
|
124
|
+
const sandbox = new DockerSandbox({
|
|
125
|
+
image: 'node:22-slim',
|
|
126
|
+
env: {
|
|
127
|
+
NODE_ENV: 'production',
|
|
128
|
+
DATABASE_URL: 'postgres://localhost:5432/mydb',
|
|
129
|
+
},
|
|
130
|
+
})
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
## Bind mounts
|
|
134
|
+
|
|
135
|
+
Mount host directories into the container using the `volumes` option:
|
|
136
|
+
|
|
137
|
+
```typescript
|
|
138
|
+
const sandbox = new DockerSandbox({
|
|
139
|
+
image: 'node:22-slim',
|
|
140
|
+
volumes: {
|
|
141
|
+
'/my/project': '/workspace/project',
|
|
142
|
+
'/shared/data': '/data',
|
|
143
|
+
},
|
|
144
|
+
})
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
Bind mounts are applied at container creation time. The host paths must exist before the sandbox starts.
|
|
148
|
+
|
|
149
|
+
## Reconnection
|
|
150
|
+
|
|
151
|
+
`DockerSandbox` can reconnect to existing containers by matching labels. When `start()` is called, it checks for a container with the `mastra.sandbox.id` label matching the sandbox ID. If found:
|
|
152
|
+
|
|
153
|
+
- A running container is reused directly.
|
|
154
|
+
- A stopped container is restarted.
|
|
155
|
+
|
|
156
|
+
```typescript
|
|
157
|
+
// First run — creates a new container
|
|
158
|
+
const sandbox = new DockerSandbox({ id: 'persistent-sandbox' })
|
|
159
|
+
await sandbox._start()
|
|
160
|
+
|
|
161
|
+
// Later — reconnects to the existing container
|
|
162
|
+
const sandbox2 = new DockerSandbox({ id: 'persistent-sandbox' })
|
|
163
|
+
await sandbox2._start()
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
## Docker connection options
|
|
167
|
+
|
|
168
|
+
Connect to remote Docker hosts or use custom socket paths via `dockerOptions`:
|
|
169
|
+
|
|
170
|
+
```typescript
|
|
171
|
+
// Remote Docker host
|
|
172
|
+
const sandbox = new DockerSandbox({
|
|
173
|
+
dockerOptions: {
|
|
174
|
+
host: '192.168.1.100',
|
|
175
|
+
port: 2376,
|
|
176
|
+
ca: fs.readFileSync('ca.pem'),
|
|
177
|
+
cert: fs.readFileSync('cert.pem'),
|
|
178
|
+
key: fs.readFileSync('key.pem'),
|
|
179
|
+
},
|
|
180
|
+
})
|
|
181
|
+
|
|
182
|
+
// Custom socket path
|
|
183
|
+
const sandbox = new DockerSandbox({
|
|
184
|
+
dockerOptions: {
|
|
185
|
+
socketPath: '/var/run/docker.sock',
|
|
186
|
+
},
|
|
187
|
+
})
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
## Related
|
|
191
|
+
|
|
192
|
+
- [SandboxProcessManager reference](https://mastra.ai/reference/workspace/process-manager)
|
|
193
|
+
- [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox)
|
|
194
|
+
- [LocalSandbox reference](https://mastra.ai/reference/workspace/local-sandbox)
|
|
195
|
+
- [E2BSandbox reference](https://mastra.ai/reference/workspace/e2b-sandbox)
|
|
196
|
+
- [Workspace overview](https://mastra.ai/docs/workspace/overview)
|
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,83 @@
|
|
|
1
1
|
# @mastra/mcp-docs-server
|
|
2
2
|
|
|
3
|
+
## 1.1.26
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- Updated dependencies [[`20f59b8`](https://github.com/mastra-ai/mastra/commit/20f59b876cf91199efbc49a0e36b391240708f08), [`aba393e`](https://github.com/mastra-ai/mastra/commit/aba393e2da7390c69b80e516a4f153cda6f09376), [`3d83d06`](https://github.com/mastra-ai/mastra/commit/3d83d06f776f00fb5f4163dddd32a030c5c20844), [`e2687a7`](https://github.com/mastra-ai/mastra/commit/e2687a7408790c384563816a9a28ed06735684c9), [`fdd54cf`](https://github.com/mastra-ai/mastra/commit/fdd54cf612a9af876e9fdd85e534454f6e7dd518), [`6315317`](https://github.com/mastra-ai/mastra/commit/63153175fe9a7b224e5be7c209bbebc01dd9b0d5), [`a371ac5`](https://github.com/mastra-ai/mastra/commit/a371ac534aa1bb368a1acf9d8b313378dfdc787e), [`0474c2b`](https://github.com/mastra-ai/mastra/commit/0474c2b2e7c7e1ad8691dca031284841391ff1ef), [`0a5fa1d`](https://github.com/mastra-ai/mastra/commit/0a5fa1d3cb0583889d06687155f26fd7d2edc76c), [`7e0e63e`](https://github.com/mastra-ai/mastra/commit/7e0e63e2e485e84442351f4c7a79a424c83539dc), [`ea43e64`](https://github.com/mastra-ai/mastra/commit/ea43e646dd95d507694b6112b0bf1df22ad552b2), [`f607106`](https://github.com/mastra-ai/mastra/commit/f607106854c6416c4a07d4082604b9f66d047221), [`30456b6`](https://github.com/mastra-ai/mastra/commit/30456b6b08c8fd17e109dd093b73d93b65e83bc5), [`9d11a8c`](https://github.com/mastra-ai/mastra/commit/9d11a8c1c8924eb975a245a5884d40ca1b7e0491), [`9d3b24b`](https://github.com/mastra-ai/mastra/commit/9d3b24b19407ae9c09586cf7766d38dc4dff4a69), [`7020c06`](https://github.com/mastra-ai/mastra/commit/7020c0690b199d9da337f0e805f16948e557922e), [`00d1b16`](https://github.com/mastra-ai/mastra/commit/00d1b16b401199cb294fa23f43336547db4dca9b), [`47cee3e`](https://github.com/mastra-ai/mastra/commit/47cee3e137fe39109cf7fffd2a8cf47b76dc702e), [`62919a6`](https://github.com/mastra-ai/mastra/commit/62919a6ee0fbf3779ad21a97b1ec6696515d5104), [`d246696`](https://github.com/mastra-ai/mastra/commit/d246696139a3144a5b21b042d41c532688e957e1), [`354f9ce`](https://github.com/mastra-ai/mastra/commit/354f9ce1ca6af2074b6a196a23f8ec30012dccca), [`16e34ca`](https://github.com/mastra-ai/mastra/commit/16e34caa98b9a114b17a6125e4e3fd87f169d0d0), [`7020c06`](https://github.com/mastra-ai/mastra/commit/7020c0690b199d9da337f0e805f16948e557922e), [`8786a61`](https://github.com/mastra-ai/mastra/commit/8786a61fa54ba265f85eeff9985ca39863d18bb6), [`9467ea8`](https://github.com/mastra-ai/mastra/commit/9467ea87695749a53dfc041576410ebf9ee7bb67), [`7338d94`](https://github.com/mastra-ai/mastra/commit/7338d949380cf68b095342e8e42610dc51d557c1), [`c80dc16`](https://github.com/mastra-ai/mastra/commit/c80dc16e113e6cc159f510ffde501ad4711b2189), [`af8a57e`](https://github.com/mastra-ai/mastra/commit/af8a57ed9ba9685ad8601d5b71ae3706da6222f9), [`d63ffdb`](https://github.com/mastra-ai/mastra/commit/d63ffdbb2c11e76fe5ea45faab44bc15460f010c), [`47cee3e`](https://github.com/mastra-ai/mastra/commit/47cee3e137fe39109cf7fffd2a8cf47b76dc702e), [`1bd5104`](https://github.com/mastra-ai/mastra/commit/1bd51048b6da93507276d6623e3fd96a9e1a8944), [`e9837b5`](https://github.com/mastra-ai/mastra/commit/e9837b53699e18711b09e0ca010a4106376f2653), [`c65aec3`](https://github.com/mastra-ai/mastra/commit/c65aec356cc037ee7c4b30ccea946807d4c4f443), [`8f1b280`](https://github.com/mastra-ai/mastra/commit/8f1b280b7fe6999ec654f160cb69c1a8719e7a57), [`92dcf02`](https://github.com/mastra-ai/mastra/commit/92dcf029294210ac91b090900c1a0555a425c57a), [`0fd90a2`](https://github.com/mastra-ai/mastra/commit/0fd90a215caf5fca8099c15a67ca03e4427747a3), [`8fb2405`](https://github.com/mastra-ai/mastra/commit/8fb2405138f2d208b7962ad03f121ca25bcc28c5), [`12df98c`](https://github.com/mastra-ai/mastra/commit/12df98c4904643d9481f5c78f3bed443725b4c96)]:
|
|
8
|
+
- @mastra/core@1.26.0
|
|
9
|
+
- @mastra/mcp@1.5.1
|
|
10
|
+
|
|
11
|
+
## 1.1.26-alpha.24
|
|
12
|
+
|
|
13
|
+
### Patch Changes
|
|
14
|
+
|
|
15
|
+
- Updated dependencies:
|
|
16
|
+
- @mastra/core@1.26.0-alpha.13
|
|
17
|
+
|
|
18
|
+
## 1.1.26-alpha.23
|
|
19
|
+
|
|
20
|
+
### Patch Changes
|
|
21
|
+
|
|
22
|
+
- Updated dependencies [[`a371ac5`](https://github.com/mastra-ai/mastra/commit/a371ac534aa1bb368a1acf9d8b313378dfdc787e), [`47cee3e`](https://github.com/mastra-ai/mastra/commit/47cee3e137fe39109cf7fffd2a8cf47b76dc702e), [`c80dc16`](https://github.com/mastra-ai/mastra/commit/c80dc16e113e6cc159f510ffde501ad4711b2189), [`47cee3e`](https://github.com/mastra-ai/mastra/commit/47cee3e137fe39109cf7fffd2a8cf47b76dc702e)]:
|
|
23
|
+
- @mastra/core@1.26.0-alpha.12
|
|
24
|
+
|
|
25
|
+
## 1.1.26-alpha.21
|
|
26
|
+
|
|
27
|
+
### Patch Changes
|
|
28
|
+
|
|
29
|
+
- Updated dependencies [[`20f59b8`](https://github.com/mastra-ai/mastra/commit/20f59b876cf91199efbc49a0e36b391240708f08), [`e2687a7`](https://github.com/mastra-ai/mastra/commit/e2687a7408790c384563816a9a28ed06735684c9), [`8f1b280`](https://github.com/mastra-ai/mastra/commit/8f1b280b7fe6999ec654f160cb69c1a8719e7a57), [`12df98c`](https://github.com/mastra-ai/mastra/commit/12df98c4904643d9481f5c78f3bed443725b4c96)]:
|
|
30
|
+
- @mastra/core@1.26.0-alpha.11
|
|
31
|
+
|
|
32
|
+
## 1.1.26-alpha.19
|
|
33
|
+
|
|
34
|
+
### Patch Changes
|
|
35
|
+
|
|
36
|
+
- Updated dependencies [[`aba393e`](https://github.com/mastra-ai/mastra/commit/aba393e2da7390c69b80e516a4f153cda6f09376), [`0a5fa1d`](https://github.com/mastra-ai/mastra/commit/0a5fa1d3cb0583889d06687155f26fd7d2edc76c), [`ea43e64`](https://github.com/mastra-ai/mastra/commit/ea43e646dd95d507694b6112b0bf1df22ad552b2), [`00d1b16`](https://github.com/mastra-ai/mastra/commit/00d1b16b401199cb294fa23f43336547db4dca9b), [`af8a57e`](https://github.com/mastra-ai/mastra/commit/af8a57ed9ba9685ad8601d5b71ae3706da6222f9)]:
|
|
37
|
+
- @mastra/core@1.26.0-alpha.10
|
|
38
|
+
|
|
39
|
+
## 1.1.26-alpha.17
|
|
40
|
+
|
|
41
|
+
### Patch Changes
|
|
42
|
+
|
|
43
|
+
- Updated dependencies [[`16e34ca`](https://github.com/mastra-ai/mastra/commit/16e34caa98b9a114b17a6125e4e3fd87f169d0d0)]:
|
|
44
|
+
- @mastra/core@1.26.0-alpha.9
|
|
45
|
+
|
|
46
|
+
## 1.1.26-alpha.16
|
|
47
|
+
|
|
48
|
+
### Patch Changes
|
|
49
|
+
|
|
50
|
+
- Updated dependencies [[`1bd5104`](https://github.com/mastra-ai/mastra/commit/1bd51048b6da93507276d6623e3fd96a9e1a8944)]:
|
|
51
|
+
- @mastra/core@1.26.0-alpha.8
|
|
52
|
+
|
|
53
|
+
## 1.1.26-alpha.14
|
|
54
|
+
|
|
55
|
+
### Patch Changes
|
|
56
|
+
|
|
57
|
+
- Updated dependencies [[`8786a61`](https://github.com/mastra-ai/mastra/commit/8786a61fa54ba265f85eeff9985ca39863d18bb6), [`8fb2405`](https://github.com/mastra-ai/mastra/commit/8fb2405138f2d208b7962ad03f121ca25bcc28c5)]:
|
|
58
|
+
- @mastra/core@1.26.0-alpha.7
|
|
59
|
+
|
|
60
|
+
## 1.1.26-alpha.12
|
|
61
|
+
|
|
62
|
+
### Patch Changes
|
|
63
|
+
|
|
64
|
+
- Updated dependencies [[`6315317`](https://github.com/mastra-ai/mastra/commit/63153175fe9a7b224e5be7c209bbebc01dd9b0d5), [`9d3b24b`](https://github.com/mastra-ai/mastra/commit/9d3b24b19407ae9c09586cf7766d38dc4dff4a69)]:
|
|
65
|
+
- @mastra/core@1.26.0-alpha.6
|
|
66
|
+
|
|
67
|
+
## 1.1.26-alpha.9
|
|
68
|
+
|
|
69
|
+
### Patch Changes
|
|
70
|
+
|
|
71
|
+
- Updated dependencies [[`92dcf02`](https://github.com/mastra-ai/mastra/commit/92dcf029294210ac91b090900c1a0555a425c57a)]:
|
|
72
|
+
- @mastra/core@1.26.0-alpha.5
|
|
73
|
+
|
|
74
|
+
## 1.1.26-alpha.7
|
|
75
|
+
|
|
76
|
+
### Patch Changes
|
|
77
|
+
|
|
78
|
+
- Updated dependencies [[`0474c2b`](https://github.com/mastra-ai/mastra/commit/0474c2b2e7c7e1ad8691dca031284841391ff1ef), [`f607106`](https://github.com/mastra-ai/mastra/commit/f607106854c6416c4a07d4082604b9f66d047221), [`62919a6`](https://github.com/mastra-ai/mastra/commit/62919a6ee0fbf3779ad21a97b1ec6696515d5104), [`0fd90a2`](https://github.com/mastra-ai/mastra/commit/0fd90a215caf5fca8099c15a67ca03e4427747a3)]:
|
|
79
|
+
- @mastra/core@1.26.0-alpha.4
|
|
80
|
+
|
|
3
81
|
## 1.1.26-alpha.5
|
|
4
82
|
|
|
5
83
|
### Patch Changes
|