@mastra/mcp-docs-server 1.1.1 → 1.1.2
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/deployment/cloud-providers.md +1 -1
- package/.docs/docs/deployment/overview.md +1 -1
- package/.docs/docs/deployment/studio.md +234 -0
- package/.docs/docs/memory/observational-memory.md +86 -11
- package/.docs/docs/streaming/events.md +23 -0
- package/.docs/docs/workspace/filesystem.md +72 -1
- package/.docs/docs/workspace/overview.md +95 -12
- package/.docs/docs/workspace/sandbox.md +2 -0
- package/.docs/guides/agent-frameworks/ai-sdk.md +6 -2
- package/.docs/guides/deployment/cloudflare.md +99 -0
- package/.docs/models/gateways/openrouter.md +6 -3
- package/.docs/models/index.md +1 -1
- package/.docs/models/providers/baseten.md +2 -1
- package/.docs/models/providers/cerebras.md +2 -1
- package/.docs/models/providers/fireworks-ai.md +2 -1
- package/.docs/models/providers/friendli.md +3 -2
- package/.docs/models/providers/huggingface.md +3 -2
- package/.docs/models/providers/jiekou.md +4 -2
- package/.docs/models/providers/minimax-cn-coding-plan.md +3 -2
- package/.docs/models/providers/minimax-cn.md +3 -2
- package/.docs/models/providers/minimax-coding-plan.md +3 -2
- package/.docs/models/providers/minimax.md +3 -2
- package/.docs/models/providers/nano-gpt.md +12 -4
- package/.docs/models/providers/novita-ai.md +4 -2
- package/.docs/models/providers/ollama-cloud.md +3 -1
- package/.docs/models/providers/openai.md +15 -14
- package/.docs/models/providers/opencode.md +31 -32
- package/.docs/models/providers/stackit.md +78 -0
- package/.docs/models/providers/synthetic.md +1 -1
- package/.docs/models/providers/zai-coding-plan.md +3 -2
- package/.docs/models/providers/zai.md +3 -2
- package/.docs/models/providers/zhipuai-coding-plan.md +3 -2
- package/.docs/models/providers/zhipuai.md +3 -2
- package/.docs/models/providers.md +1 -0
- package/.docs/reference/ai-sdk/with-mastra.md +1 -1
- package/.docs/reference/cli/mastra.md +1 -1
- package/.docs/reference/deployer/cloudflare.md +35 -12
- package/.docs/reference/index.md +3 -0
- package/.docs/reference/memory/observational-memory.md +318 -9
- package/.docs/reference/streaming/workflows/stream.md +1 -0
- package/.docs/reference/workflows/workflow-methods/foreach.md +30 -0
- package/.docs/reference/workspace/e2b-sandbox.md +299 -0
- package/.docs/reference/workspace/gcs-filesystem.md +170 -0
- package/.docs/reference/workspace/s3-filesystem.md +169 -0
- package/CHANGELOG.md +14 -0
- package/package.json +6 -6
- package/.docs/guides/deployment/cloudflare-deployer.md +0 -102
|
@@ -0,0 +1,299 @@
|
|
|
1
|
+
# E2BSandbox
|
|
2
|
+
|
|
3
|
+
Executes commands in isolated [E2B](https://e2b.dev) cloud sandboxes. Provides secure, ephemeral environments with support for mounting cloud storage.
|
|
4
|
+
|
|
5
|
+
> **Info:** For interface details, see [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox).
|
|
6
|
+
|
|
7
|
+
## Installation
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm install @mastra/e2b
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## Usage
|
|
14
|
+
|
|
15
|
+
Add an `E2BSandbox` to a workspace and assign it to an agent:
|
|
16
|
+
|
|
17
|
+
```typescript
|
|
18
|
+
import { Agent } from '@mastra/core/agent';
|
|
19
|
+
import { Workspace } from '@mastra/core/workspace';
|
|
20
|
+
import { E2BSandbox } from '@mastra/e2b';
|
|
21
|
+
|
|
22
|
+
const workspace = new Workspace({
|
|
23
|
+
sandbox: new E2BSandbox({
|
|
24
|
+
id: 'dev-sandbox',
|
|
25
|
+
timeout: 60_000, // 60 second timeout (default: 5 minutes)
|
|
26
|
+
}),
|
|
27
|
+
});
|
|
28
|
+
|
|
29
|
+
const agent = new Agent({
|
|
30
|
+
name: 'dev-agent',
|
|
31
|
+
model: 'anthropic/claude-opus-4-5',
|
|
32
|
+
workspace,
|
|
33
|
+
});
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
## Constructor parameters
|
|
37
|
+
|
|
38
|
+
**apiKey?:** (`string`): E2B API key. Falls back to E2B\_API\_KEY environment variable.
|
|
39
|
+
|
|
40
|
+
**timeout?:** (`number`): Execution timeout in milliseconds (Default: `300000 (5 minutes)`)
|
|
41
|
+
|
|
42
|
+
**template?:** (`string | TemplateBuilder | function`): Sandbox template specification. Can be a template ID string, a TemplateBuilder, or a function that customizes the default template.
|
|
43
|
+
|
|
44
|
+
**env?:** (`Record<string, string>`): Environment variables to set in the sandbox
|
|
45
|
+
|
|
46
|
+
**runtimes?:** (`SandboxRuntime[]`): Supported runtimes (Default: `['node', 'python', 'bash']`)
|
|
47
|
+
|
|
48
|
+
**id?:** (`string`): Unique identifier for this sandbox instance (Default: `Auto-generated`)
|
|
49
|
+
|
|
50
|
+
**domain?:** (`string`): Domain for self-hosted E2B. Falls back to E2B\_DOMAIN env var.
|
|
51
|
+
|
|
52
|
+
**apiUrl?:** (`string`): API URL for self-hosted E2B. Falls back to E2B\_API\_URL env var.
|
|
53
|
+
|
|
54
|
+
**accessToken?:** (`string`): Access token for authentication. Falls back to E2B\_ACCESS\_TOKEN env var.
|
|
55
|
+
|
|
56
|
+
## Properties
|
|
57
|
+
|
|
58
|
+
**id:** (`string`): Sandbox instance identifier
|
|
59
|
+
|
|
60
|
+
**name:** (`string`): Provider name ('E2BSandbox')
|
|
61
|
+
|
|
62
|
+
**provider:** (`string`): Provider identifier ('e2b')
|
|
63
|
+
|
|
64
|
+
**status:** (`ProviderStatus`): 'pending' | 'initializing' | 'ready' | 'error'
|
|
65
|
+
|
|
66
|
+
**supportsMounting:** (`boolean`): Always true - E2B sandboxes support mounting cloud filesystems
|
|
67
|
+
|
|
68
|
+
## Methods
|
|
69
|
+
|
|
70
|
+
### `start()`
|
|
71
|
+
|
|
72
|
+
Initialize and start the sandbox. Creates the E2B sandbox instance and mounts any configured filesystems.
|
|
73
|
+
|
|
74
|
+
```typescript
|
|
75
|
+
await sandbox.start();
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
Called automatically on first command execution or by `workspace.init()`.
|
|
79
|
+
|
|
80
|
+
### `stop()`
|
|
81
|
+
|
|
82
|
+
Stop the sandbox and release resources.
|
|
83
|
+
|
|
84
|
+
```typescript
|
|
85
|
+
await sandbox.stop();
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
### `destroy()`
|
|
89
|
+
|
|
90
|
+
Clean up sandbox resources completely.
|
|
91
|
+
|
|
92
|
+
```typescript
|
|
93
|
+
await sandbox.destroy();
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
### `executeCommand(command, args?, options?)`
|
|
97
|
+
|
|
98
|
+
Execute a shell command in the sandbox.
|
|
99
|
+
|
|
100
|
+
```typescript
|
|
101
|
+
const result = await sandbox.executeCommand('ls', ['-la']);
|
|
102
|
+
const npmResult = await sandbox.executeCommand('npm', ['install', 'lodash'], {
|
|
103
|
+
timeout: 60000,
|
|
104
|
+
cwd: '/app',
|
|
105
|
+
});
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
**Parameters:**
|
|
109
|
+
|
|
110
|
+
**command:** (`string`): Command to execute
|
|
111
|
+
|
|
112
|
+
**args?:** (`string[]`): Command arguments
|
|
113
|
+
|
|
114
|
+
**options.timeout?:** (`number`): Execution timeout in milliseconds
|
|
115
|
+
|
|
116
|
+
**options.cwd?:** (`string`): Working directory for the command
|
|
117
|
+
|
|
118
|
+
**options.env?:** (`Record<string, string>`): Additional environment variables
|
|
119
|
+
|
|
120
|
+
**options.onStdout?:** (`(data: string) => void`): Callback for stdout streaming
|
|
121
|
+
|
|
122
|
+
**options.onStderr?:** (`(data: string) => void`): Callback for stderr streaming
|
|
123
|
+
|
|
124
|
+
### `canMount(filesystem)`
|
|
125
|
+
|
|
126
|
+
Check if a filesystem can be mounted into this sandbox.
|
|
127
|
+
|
|
128
|
+
```typescript
|
|
129
|
+
const canMount = sandbox.canMount(s3Filesystem);
|
|
130
|
+
// true for S3Filesystem and GCSFilesystem
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
### `mount(filesystem, mountPath)`
|
|
134
|
+
|
|
135
|
+
Mount a filesystem into the sandbox at the specified path.
|
|
136
|
+
|
|
137
|
+
```typescript
|
|
138
|
+
await sandbox.mount(s3Filesystem, '/mnt/data');
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
### `unmount(mountPath)`
|
|
142
|
+
|
|
143
|
+
Unmount a previously mounted filesystem.
|
|
144
|
+
|
|
145
|
+
```typescript
|
|
146
|
+
await sandbox.unmount('/mnt/data');
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
### `getMounts()`
|
|
150
|
+
|
|
151
|
+
Get a list of currently mounted filesystems.
|
|
152
|
+
|
|
153
|
+
```typescript
|
|
154
|
+
const mounts = await sandbox.getMounts();
|
|
155
|
+
// [{ path: '/mnt/data', filesystem: 's3' }]
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
### `getInfo()`
|
|
159
|
+
|
|
160
|
+
Get sandbox status and resource information.
|
|
161
|
+
|
|
162
|
+
```typescript
|
|
163
|
+
const info = await sandbox.getInfo();
|
|
164
|
+
// { id: '...', name: 'E2BSandbox', provider: 'e2b', status: 'ready', supportsMounting: true }
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
## Mounting Cloud Storage
|
|
168
|
+
|
|
169
|
+
E2B sandboxes can mount S3 or GCS filesystems, making cloud storage accessible as local directories inside the sandbox. This is useful for:
|
|
170
|
+
|
|
171
|
+
- Processing large datasets stored in cloud buckets
|
|
172
|
+
- Writing output files directly to cloud storage
|
|
173
|
+
- Sharing data between sandbox sessions
|
|
174
|
+
|
|
175
|
+
### Using the mounts config
|
|
176
|
+
|
|
177
|
+
The simplest way to mount filesystems is through the workspace `mounts` config:
|
|
178
|
+
|
|
179
|
+
```typescript
|
|
180
|
+
import { Workspace } from '@mastra/core/workspace';
|
|
181
|
+
import { S3Filesystem } from '@mastra/s3';
|
|
182
|
+
import { GCSFilesystem } from '@mastra/gcs';
|
|
183
|
+
import { E2BSandbox } from '@mastra/e2b';
|
|
184
|
+
|
|
185
|
+
const workspace = new Workspace({
|
|
186
|
+
mounts: {
|
|
187
|
+
'/s3-data': new S3Filesystem({
|
|
188
|
+
bucket: 'my-s3-bucket',
|
|
189
|
+
region: 'us-east-1',
|
|
190
|
+
accessKeyId: process.env.AWS_ACCESS_KEY_ID,
|
|
191
|
+
secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
|
|
192
|
+
}),
|
|
193
|
+
'/gcs-data': new GCSFilesystem({
|
|
194
|
+
bucket: 'my-gcs-bucket',
|
|
195
|
+
projectId: 'my-project',
|
|
196
|
+
credentials: JSON.parse(process.env.GCS_SERVICE_ACCOUNT_KEY),
|
|
197
|
+
}),
|
|
198
|
+
},
|
|
199
|
+
sandbox: new E2BSandbox({ id: 'dev-sandbox' }),
|
|
200
|
+
});
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
When the sandbox starts, the filesystems are automatically mounted at the specified paths. Code running in the sandbox can then access files at `/s3-data` and `/gcs-data` as if they were local directories.
|
|
204
|
+
|
|
205
|
+
### How mounting works
|
|
206
|
+
|
|
207
|
+
E2B sandboxes use FUSE (Filesystem in Userspace) to mount cloud storage:
|
|
208
|
+
|
|
209
|
+
- **S3/R2**: Mounted via [s3fs-fuse](https://github.com/s3fs-fuse/s3fs-fuse)
|
|
210
|
+
- **GCS**: Mounted via [gcsfuse](https://github.com/GoogleCloudPlatform/gcsfuse)
|
|
211
|
+
|
|
212
|
+
The E2B sandbox automatically installs the required FUSE tools when mounting is used. For best performance, pre-build a custom template with the tools installed.
|
|
213
|
+
|
|
214
|
+
## Custom Templates
|
|
215
|
+
|
|
216
|
+
By default, when no template is specified, E2BSandbox automatically builds a template with `s3fs` installed for S3 mounting support. This template is cached and reused across sandbox instances.
|
|
217
|
+
|
|
218
|
+
For GCS mounting, `gcsfuse` is automatically installed at mount time if not already present. For additional tools or faster cold starts, use custom templates.
|
|
219
|
+
|
|
220
|
+
### Using an existing template
|
|
221
|
+
|
|
222
|
+
If you have a pre-built template, pass its ID:
|
|
223
|
+
|
|
224
|
+
```typescript
|
|
225
|
+
const workspace = new Workspace({
|
|
226
|
+
sandbox: new E2BSandbox({
|
|
227
|
+
id: 'dev-sandbox',
|
|
228
|
+
template: 'my-custom-template',
|
|
229
|
+
}),
|
|
230
|
+
});
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
### Customizing the default template
|
|
234
|
+
|
|
235
|
+
Pass a function to customize the default mountable template. The function receives a `TemplateBuilder` and should return the modified template:
|
|
236
|
+
|
|
237
|
+
```typescript
|
|
238
|
+
const workspace = new Workspace({
|
|
239
|
+
sandbox: new E2BSandbox({
|
|
240
|
+
template: (base) => base
|
|
241
|
+
.aptInstall(['ffmpeg', 'imagemagick', 'poppler-utils'])
|
|
242
|
+
.pipInstall(['pandas', 'numpy'])
|
|
243
|
+
.npmInstall(['sharp']),
|
|
244
|
+
}),
|
|
245
|
+
});
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
The template builder supports method chaining with operations like:
|
|
249
|
+
|
|
250
|
+
- `aptInstall(packages)` - Install system packages
|
|
251
|
+
- `pipInstall(packages)` - Install Python packages
|
|
252
|
+
- `npmInstall(packages)` - Install Node.js packages
|
|
253
|
+
- `runCmd(command)` - Run shell commands
|
|
254
|
+
- `setEnvs(vars)` - Set environment variables
|
|
255
|
+
- `copy(src, dest)` - Copy files into the template
|
|
256
|
+
|
|
257
|
+
See [E2B's template documentation](https://e2b.dev/docs/template/defining-template) for the full list of available methods.
|
|
258
|
+
|
|
259
|
+
### Pre-building templates
|
|
260
|
+
|
|
261
|
+
The default template is built on first use and cached. For faster cold starts or to include GCS support, you can pre-build a template:
|
|
262
|
+
|
|
263
|
+
```typescript
|
|
264
|
+
import { createDefaultMountableTemplate } from '@mastra/e2b';
|
|
265
|
+
import { Template } from 'e2b';
|
|
266
|
+
|
|
267
|
+
// Get the default mountable template (includes s3fs)
|
|
268
|
+
const { template, id } = createDefaultMountableTemplate();
|
|
269
|
+
|
|
270
|
+
// Build and save to E2B
|
|
271
|
+
const result = await Template.build(template, id);
|
|
272
|
+
console.log('Template ID:', result.templateId);
|
|
273
|
+
|
|
274
|
+
// Use this ID in your E2BSandbox config for instant startup
|
|
275
|
+
const sandbox = new E2BSandbox({
|
|
276
|
+
template: result.templateId,
|
|
277
|
+
});
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
For faster GCS cold starts, pre-install `gcsfuse` in a custom template:
|
|
281
|
+
|
|
282
|
+
```typescript
|
|
283
|
+
const workspace = new Workspace({
|
|
284
|
+
sandbox: new E2BSandbox({
|
|
285
|
+
id: 'dev-sandbox',
|
|
286
|
+
template: (base) => base.aptInstall(['gcsfuse']),
|
|
287
|
+
}),
|
|
288
|
+
});
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
This is optional—`gcsfuse` is installed automatically at mount time if not present.
|
|
292
|
+
|
|
293
|
+
## Related
|
|
294
|
+
|
|
295
|
+
- [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox)
|
|
296
|
+
- [LocalSandbox reference](https://mastra.ai/reference/workspace/local-sandbox)
|
|
297
|
+
- [S3Filesystem reference](https://mastra.ai/reference/workspace/s3-filesystem)
|
|
298
|
+
- [GCSFilesystem reference](https://mastra.ai/reference/workspace/gcs-filesystem)
|
|
299
|
+
- [Workspace overview](https://mastra.ai/docs/workspace/overview)
|
|
@@ -0,0 +1,170 @@
|
|
|
1
|
+
# GCSFilesystem
|
|
2
|
+
|
|
3
|
+
Stores files in Google Cloud Storage.
|
|
4
|
+
|
|
5
|
+
> **Info:** For interface details, see [WorkspaceFilesystem Interface](https://mastra.ai/reference/workspace/filesystem).
|
|
6
|
+
|
|
7
|
+
## Installation
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm install @mastra/gcs
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## Usage
|
|
14
|
+
|
|
15
|
+
Add a `GCSFilesystem` to a workspace and assign it to an agent:
|
|
16
|
+
|
|
17
|
+
```typescript
|
|
18
|
+
import { Agent } from '@mastra/core/agent';
|
|
19
|
+
import { Workspace } from '@mastra/core/workspace';
|
|
20
|
+
import { GCSFilesystem } from '@mastra/gcs';
|
|
21
|
+
|
|
22
|
+
const workspace = new Workspace({
|
|
23
|
+
filesystem: new GCSFilesystem({
|
|
24
|
+
bucket: 'my-gcs-bucket',
|
|
25
|
+
projectId: 'my-project-id',
|
|
26
|
+
credentials: JSON.parse(process.env.GCS_SERVICE_ACCOUNT_KEY),
|
|
27
|
+
}),
|
|
28
|
+
});
|
|
29
|
+
|
|
30
|
+
const agent = new Agent({
|
|
31
|
+
name: 'file-agent',
|
|
32
|
+
model: 'anthropic/claude-opus-4-5',
|
|
33
|
+
workspace,
|
|
34
|
+
});
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
### Using Application Default Credentials
|
|
38
|
+
|
|
39
|
+
If running on Google Cloud or with `gcloud` CLI configured, you can omit credentials:
|
|
40
|
+
|
|
41
|
+
```typescript
|
|
42
|
+
import { GCSFilesystem } from '@mastra/gcs';
|
|
43
|
+
|
|
44
|
+
const filesystem = new GCSFilesystem({
|
|
45
|
+
bucket: 'my-gcs-bucket',
|
|
46
|
+
// Uses Application Default Credentials automatically
|
|
47
|
+
});
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
[Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/application-default-credentials) automatically discovers credentials in this order:
|
|
51
|
+
|
|
52
|
+
1. `GOOGLE_APPLICATION_CREDENTIALS` environment variable (path to a service account key file)
|
|
53
|
+
2. Default service account when running on GCP (Compute Engine, Cloud Run, GKE, etc.)
|
|
54
|
+
3. User credentials from `gcloud auth application-default login` (for local development)
|
|
55
|
+
|
|
56
|
+
### Using a Key File Path
|
|
57
|
+
|
|
58
|
+
You can also pass a path to a service account key file:
|
|
59
|
+
|
|
60
|
+
```typescript
|
|
61
|
+
import { GCSFilesystem } from '@mastra/gcs';
|
|
62
|
+
|
|
63
|
+
const filesystem = new GCSFilesystem({
|
|
64
|
+
bucket: 'my-gcs-bucket',
|
|
65
|
+
projectId: 'my-project-id',
|
|
66
|
+
credentials: '/path/to/service-account-key.json',
|
|
67
|
+
});
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
## Constructor parameters
|
|
71
|
+
|
|
72
|
+
**bucket:** (`string`): GCS bucket name
|
|
73
|
+
|
|
74
|
+
**projectId?:** (`string`): GCS project ID. Required when using service account credentials.
|
|
75
|
+
|
|
76
|
+
**credentials?:** (`object | string`): Service account key JSON object or path to key file. If not provided, uses Application Default Credentials.
|
|
77
|
+
|
|
78
|
+
**prefix?:** (`string`): Optional prefix for all keys (acts like a subdirectory)
|
|
79
|
+
|
|
80
|
+
**id?:** (`string`): Unique identifier for this filesystem instance (Default: `Auto-generated`)
|
|
81
|
+
|
|
82
|
+
**displayName?:** (`string`): Human-friendly display name for the UI
|
|
83
|
+
|
|
84
|
+
**readOnly?:** (`boolean`): When true, all write operations are blocked (Default: `false`)
|
|
85
|
+
|
|
86
|
+
**endpoint?:** (`string`): Custom API endpoint URL. Used for local development with emulators.
|
|
87
|
+
|
|
88
|
+
## Properties
|
|
89
|
+
|
|
90
|
+
**id:** (`string`): Filesystem instance identifier
|
|
91
|
+
|
|
92
|
+
**name:** (`string`): Provider name ('GCSFilesystem')
|
|
93
|
+
|
|
94
|
+
**provider:** (`string`): Provider identifier ('gcs')
|
|
95
|
+
|
|
96
|
+
**bucket:** (`string`): The GCS bucket name
|
|
97
|
+
|
|
98
|
+
**readOnly:** (`boolean | undefined`): Whether the filesystem is in read-only mode
|
|
99
|
+
|
|
100
|
+
## Methods
|
|
101
|
+
|
|
102
|
+
GCSFilesystem implements the [WorkspaceFilesystem interface](https://mastra.ai/reference/workspace/filesystem), providing all standard filesystem methods:
|
|
103
|
+
|
|
104
|
+
- `readFile(path, options?)` - Read file contents
|
|
105
|
+
- `writeFile(path, content, options?)` - Write content to a file
|
|
106
|
+
- `appendFile(path, content)` - Append content to a file
|
|
107
|
+
- `deleteFile(path, options?)` - Delete a file
|
|
108
|
+
- `copyFile(src, dest, options?)` - Copy a file
|
|
109
|
+
- `moveFile(src, dest, options?)` - Move or rename a file
|
|
110
|
+
- `mkdir(path, options?)` - Create a directory
|
|
111
|
+
- `rmdir(path, options?)` - Remove a directory
|
|
112
|
+
- `readdir(path, options?)` - List directory contents
|
|
113
|
+
- `exists(path)` - Check if a path exists
|
|
114
|
+
- `stat(path)` - Get file or directory metadata
|
|
115
|
+
|
|
116
|
+
### `init()`
|
|
117
|
+
|
|
118
|
+
Initialize the filesystem. Verifies bucket access and credentials.
|
|
119
|
+
|
|
120
|
+
```typescript
|
|
121
|
+
await filesystem.init();
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
### `getInfo()`
|
|
125
|
+
|
|
126
|
+
Returns metadata about this filesystem instance.
|
|
127
|
+
|
|
128
|
+
```typescript
|
|
129
|
+
const info = filesystem.getInfo();
|
|
130
|
+
// { id: '...', name: 'GCSFilesystem', provider: 'gcs', status: 'ready' }
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
### `getMountConfig()`
|
|
134
|
+
|
|
135
|
+
Returns the mount configuration for sandboxes that support mounting this filesystem type.
|
|
136
|
+
|
|
137
|
+
```typescript
|
|
138
|
+
const config = filesystem.getMountConfig();
|
|
139
|
+
// { type: 'gcs', bucket: 'my-bucket', ... }
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
## Mounting in E2B Sandboxes
|
|
143
|
+
|
|
144
|
+
GCSFilesystem can be mounted into E2B sandboxes, making the bucket accessible as a local directory:
|
|
145
|
+
|
|
146
|
+
```typescript
|
|
147
|
+
import { Workspace } from '@mastra/core/workspace';
|
|
148
|
+
import { GCSFilesystem } from '@mastra/gcs';
|
|
149
|
+
import { E2BSandbox } from '@mastra/e2b';
|
|
150
|
+
|
|
151
|
+
const workspace = new Workspace({
|
|
152
|
+
mounts: {
|
|
153
|
+
'/data': new GCSFilesystem({
|
|
154
|
+
bucket: 'my-gcs-bucket',
|
|
155
|
+
projectId: 'my-project-id',
|
|
156
|
+
credentials: JSON.parse(process.env.GCS_SERVICE_ACCOUNT_KEY),
|
|
157
|
+
}),
|
|
158
|
+
},
|
|
159
|
+
sandbox: new E2BSandbox({ id: 'dev-sandbox' }),
|
|
160
|
+
});
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
See [E2BSandbox reference](https://mastra.ai/reference/workspace/e2b-sandbox) for more details on mounting.
|
|
164
|
+
|
|
165
|
+
## Related
|
|
166
|
+
|
|
167
|
+
- [WorkspaceFilesystem interface](https://mastra.ai/reference/workspace/filesystem)
|
|
168
|
+
- [S3Filesystem reference](https://mastra.ai/reference/workspace/s3-filesystem)
|
|
169
|
+
- [E2BSandbox reference](https://mastra.ai/reference/workspace/e2b-sandbox)
|
|
170
|
+
- [Workspace overview](https://mastra.ai/docs/workspace/overview)
|
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
# S3Filesystem
|
|
2
|
+
|
|
3
|
+
Stores files in Amazon S3 or S3-compatible storage services like Cloudflare R2, MinIO, and DigitalOcean Spaces.
|
|
4
|
+
|
|
5
|
+
> **Info:** For interface details, see [WorkspaceFilesystem Interface](https://mastra.ai/reference/workspace/filesystem).
|
|
6
|
+
|
|
7
|
+
## Installation
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm install @mastra/s3
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## Usage
|
|
14
|
+
|
|
15
|
+
Add an `S3Filesystem` to a workspace and assign it to an agent:
|
|
16
|
+
|
|
17
|
+
```typescript
|
|
18
|
+
import { Agent } from '@mastra/core/agent';
|
|
19
|
+
import { Workspace } from '@mastra/core/workspace';
|
|
20
|
+
import { S3Filesystem } from '@mastra/s3';
|
|
21
|
+
|
|
22
|
+
const workspace = new Workspace({
|
|
23
|
+
filesystem: new S3Filesystem({
|
|
24
|
+
bucket: 'my-bucket',
|
|
25
|
+
region: 'us-east-1',
|
|
26
|
+
accessKeyId: process.env.AWS_ACCESS_KEY_ID,
|
|
27
|
+
secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
|
|
28
|
+
}),
|
|
29
|
+
});
|
|
30
|
+
|
|
31
|
+
const agent = new Agent({
|
|
32
|
+
name: 'file-agent',
|
|
33
|
+
model: 'anthropic/claude-opus-4-5',
|
|
34
|
+
workspace,
|
|
35
|
+
});
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
### Cloudflare R2
|
|
39
|
+
|
|
40
|
+
```typescript
|
|
41
|
+
import { S3Filesystem } from '@mastra/s3';
|
|
42
|
+
|
|
43
|
+
const filesystem = new S3Filesystem({
|
|
44
|
+
bucket: 'my-r2-bucket',
|
|
45
|
+
region: 'auto',
|
|
46
|
+
endpoint: `https://${process.env.R2_ACCOUNT_ID}.r2.cloudflarestorage.com`,
|
|
47
|
+
accessKeyId: process.env.R2_ACCESS_KEY_ID,
|
|
48
|
+
secretAccessKey: process.env.R2_SECRET_ACCESS_KEY,
|
|
49
|
+
});
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
### MinIO
|
|
53
|
+
|
|
54
|
+
```typescript
|
|
55
|
+
import { S3Filesystem } from '@mastra/s3';
|
|
56
|
+
|
|
57
|
+
const filesystem = new S3Filesystem({
|
|
58
|
+
bucket: 'my-bucket',
|
|
59
|
+
region: 'us-east-1',
|
|
60
|
+
endpoint: 'http://localhost:9000',
|
|
61
|
+
accessKeyId: 'minioadmin',
|
|
62
|
+
secretAccessKey: 'minioadmin',
|
|
63
|
+
});
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
## Constructor parameters
|
|
67
|
+
|
|
68
|
+
**bucket:** (`string`): S3 bucket name
|
|
69
|
+
|
|
70
|
+
**region:** (`string`): AWS region (use 'auto' for R2)
|
|
71
|
+
|
|
72
|
+
**accessKeyId?:** (`string`): AWS access key ID. Optional for public buckets (read-only access).
|
|
73
|
+
|
|
74
|
+
**secretAccessKey?:** (`string`): AWS secret access key. Optional for public buckets (read-only access).
|
|
75
|
+
|
|
76
|
+
**endpoint?:** (`string`): Custom endpoint URL for S3-compatible storage (R2, MinIO, etc.)
|
|
77
|
+
|
|
78
|
+
**prefix?:** (`string`): Optional prefix for all keys (acts like a subdirectory)
|
|
79
|
+
|
|
80
|
+
**id?:** (`string`): Unique identifier for this filesystem instance (Default: `Auto-generated`)
|
|
81
|
+
|
|
82
|
+
**displayName?:** (`string`): Human-friendly display name for the UI
|
|
83
|
+
|
|
84
|
+
**readOnly?:** (`boolean`): When true, all write operations are blocked (Default: `false`)
|
|
85
|
+
|
|
86
|
+
## Properties
|
|
87
|
+
|
|
88
|
+
**id:** (`string`): Filesystem instance identifier
|
|
89
|
+
|
|
90
|
+
**name:** (`string`): Provider name ('S3Filesystem')
|
|
91
|
+
|
|
92
|
+
**provider:** (`string`): Provider identifier ('s3')
|
|
93
|
+
|
|
94
|
+
**bucket:** (`string`): The S3 bucket name
|
|
95
|
+
|
|
96
|
+
**readOnly:** (`boolean | undefined`): Whether the filesystem is in read-only mode
|
|
97
|
+
|
|
98
|
+
## Methods
|
|
99
|
+
|
|
100
|
+
S3Filesystem implements the [WorkspaceFilesystem interface](https://mastra.ai/reference/workspace/filesystem), providing all standard filesystem methods:
|
|
101
|
+
|
|
102
|
+
- `readFile(path, options?)` - Read file contents
|
|
103
|
+
- `writeFile(path, content, options?)` - Write content to a file
|
|
104
|
+
- `appendFile(path, content)` - Append content to a file
|
|
105
|
+
- `deleteFile(path, options?)` - Delete a file
|
|
106
|
+
- `copyFile(src, dest, options?)` - Copy a file
|
|
107
|
+
- `moveFile(src, dest, options?)` - Move or rename a file
|
|
108
|
+
- `mkdir(path, options?)` - Create a directory
|
|
109
|
+
- `rmdir(path, options?)` - Remove a directory
|
|
110
|
+
- `readdir(path, options?)` - List directory contents
|
|
111
|
+
- `exists(path)` - Check if a path exists
|
|
112
|
+
- `stat(path)` - Get file or directory metadata
|
|
113
|
+
|
|
114
|
+
### `init()`
|
|
115
|
+
|
|
116
|
+
Initialize the filesystem. Verifies bucket access and credentials.
|
|
117
|
+
|
|
118
|
+
```typescript
|
|
119
|
+
await filesystem.init();
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
### `getInfo()`
|
|
123
|
+
|
|
124
|
+
Returns metadata about this filesystem instance.
|
|
125
|
+
|
|
126
|
+
```typescript
|
|
127
|
+
const info = filesystem.getInfo();
|
|
128
|
+
// { id: '...', name: 'S3Filesystem', provider: 's3', status: 'ready' }
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
### `getMountConfig()`
|
|
132
|
+
|
|
133
|
+
Returns the mount configuration for sandboxes that support mounting this filesystem type.
|
|
134
|
+
|
|
135
|
+
```typescript
|
|
136
|
+
const config = filesystem.getMountConfig();
|
|
137
|
+
// { type: 's3', bucket: 'my-bucket', region: 'us-east-1', ... }
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
## Mounting in E2B Sandboxes
|
|
141
|
+
|
|
142
|
+
S3Filesystem can be mounted into E2B sandboxes, making the bucket accessible as a local directory:
|
|
143
|
+
|
|
144
|
+
```typescript
|
|
145
|
+
import { Workspace } from '@mastra/core/workspace';
|
|
146
|
+
import { S3Filesystem } from '@mastra/s3';
|
|
147
|
+
import { E2BSandbox } from '@mastra/e2b';
|
|
148
|
+
|
|
149
|
+
const workspace = new Workspace({
|
|
150
|
+
mounts: {
|
|
151
|
+
'/data': new S3Filesystem({
|
|
152
|
+
bucket: 'my-bucket',
|
|
153
|
+
region: 'us-east-1',
|
|
154
|
+
accessKeyId: process.env.AWS_ACCESS_KEY_ID,
|
|
155
|
+
secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
|
|
156
|
+
}),
|
|
157
|
+
},
|
|
158
|
+
sandbox: new E2BSandbox({ id: 'dev-sandbox' }),
|
|
159
|
+
});
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
See [E2BSandbox reference](https://mastra.ai/reference/workspace/e2b-sandbox) for more details on mounting.
|
|
163
|
+
|
|
164
|
+
## Related
|
|
165
|
+
|
|
166
|
+
- [WorkspaceFilesystem interface](https://mastra.ai/reference/workspace/filesystem)
|
|
167
|
+
- [GCSFilesystem reference](https://mastra.ai/reference/workspace/gcs-filesystem)
|
|
168
|
+
- [E2BSandbox reference](https://mastra.ai/reference/workspace/e2b-sandbox)
|
|
169
|
+
- [Workspace overview](https://mastra.ai/docs/workspace/overview)
|
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,19 @@
|
|
|
1
1
|
# @mastra/mcp-docs-server
|
|
2
2
|
|
|
3
|
+
## 1.1.2
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- Updated dependencies [[`7ef618f`](https://github.com/mastra-ai/mastra/commit/7ef618f3c49c27e2f6b27d7f564c557c0734325b), [`b373564`](https://github.com/mastra-ai/mastra/commit/b37356491d43b4d53067f10cb669abaf2502f218), [`927c2af`](https://github.com/mastra-ai/mastra/commit/927c2af9792286c122e04409efce0f3c804f777f), [`b896b41`](https://github.com/mastra-ai/mastra/commit/b896b41343de7fcc14442fb40fe82d189e65bbe2), [`6415277`](https://github.com/mastra-ai/mastra/commit/6415277a438faa00db2af850ead5dee25f40c428), [`0831bbb`](https://github.com/mastra-ai/mastra/commit/0831bbb5bc750c18e9b22b45f18687c964b70828), [`63f7eda`](https://github.com/mastra-ai/mastra/commit/63f7eda605eb3e0c8c35ee3912ffe7c999c69f69), [`a5b67a3`](https://github.com/mastra-ai/mastra/commit/a5b67a3589a74415feb663a55d1858324a2afde9), [`877b02c`](https://github.com/mastra-ai/mastra/commit/877b02cdbb15e199184c7f2b8f217be8d3ebada7), [`7567222`](https://github.com/mastra-ai/mastra/commit/7567222b1366f0d39980594792dd9d5060bfe2ab), [`af71458`](https://github.com/mastra-ai/mastra/commit/af71458e3b566f09c11d0e5a0a836dc818e7a24a), [`eb36bd8`](https://github.com/mastra-ai/mastra/commit/eb36bd8c52fcd6ec9674ac3b7a6412405b5983e1), [`3cbf121`](https://github.com/mastra-ai/mastra/commit/3cbf121f55418141924754a83102aade89835947)]:
|
|
8
|
+
- @mastra/core@1.4.0
|
|
9
|
+
|
|
10
|
+
## 1.1.2-alpha.0
|
|
11
|
+
|
|
12
|
+
### Patch Changes
|
|
13
|
+
|
|
14
|
+
- Updated dependencies [[`7ef618f`](https://github.com/mastra-ai/mastra/commit/7ef618f3c49c27e2f6b27d7f564c557c0734325b), [`b373564`](https://github.com/mastra-ai/mastra/commit/b37356491d43b4d53067f10cb669abaf2502f218), [`927c2af`](https://github.com/mastra-ai/mastra/commit/927c2af9792286c122e04409efce0f3c804f777f), [`b896b41`](https://github.com/mastra-ai/mastra/commit/b896b41343de7fcc14442fb40fe82d189e65bbe2), [`6415277`](https://github.com/mastra-ai/mastra/commit/6415277a438faa00db2af850ead5dee25f40c428), [`0831bbb`](https://github.com/mastra-ai/mastra/commit/0831bbb5bc750c18e9b22b45f18687c964b70828), [`63f7eda`](https://github.com/mastra-ai/mastra/commit/63f7eda605eb3e0c8c35ee3912ffe7c999c69f69), [`a5b67a3`](https://github.com/mastra-ai/mastra/commit/a5b67a3589a74415feb663a55d1858324a2afde9), [`877b02c`](https://github.com/mastra-ai/mastra/commit/877b02cdbb15e199184c7f2b8f217be8d3ebada7), [`7567222`](https://github.com/mastra-ai/mastra/commit/7567222b1366f0d39980594792dd9d5060bfe2ab), [`af71458`](https://github.com/mastra-ai/mastra/commit/af71458e3b566f09c11d0e5a0a836dc818e7a24a), [`eb36bd8`](https://github.com/mastra-ai/mastra/commit/eb36bd8c52fcd6ec9674ac3b7a6412405b5983e1), [`3cbf121`](https://github.com/mastra-ai/mastra/commit/3cbf121f55418141924754a83102aade89835947)]:
|
|
15
|
+
- @mastra/core@1.4.0-alpha.0
|
|
16
|
+
|
|
3
17
|
## 1.1.1
|
|
4
18
|
|
|
5
19
|
### Patch Changes
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mastra/mcp-docs-server",
|
|
3
|
-
"version": "1.1.
|
|
3
|
+
"version": "1.1.2",
|
|
4
4
|
"description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -29,8 +29,8 @@
|
|
|
29
29
|
"jsdom": "^26.1.0",
|
|
30
30
|
"local-pkg": "^1.1.2",
|
|
31
31
|
"zod": "^3.25.76",
|
|
32
|
-
"@mastra/
|
|
33
|
-
"@mastra/
|
|
32
|
+
"@mastra/mcp": "^1.0.1",
|
|
33
|
+
"@mastra/core": "1.4.0"
|
|
34
34
|
},
|
|
35
35
|
"devDependencies": {
|
|
36
36
|
"@hono/node-server": "^1.19.9",
|
|
@@ -46,9 +46,9 @@
|
|
|
46
46
|
"tsx": "^4.21.0",
|
|
47
47
|
"typescript": "^5.9.3",
|
|
48
48
|
"vitest": "4.0.16",
|
|
49
|
-
"@internal/lint": "0.0.
|
|
50
|
-
"@internal/types-builder": "0.0.
|
|
51
|
-
"@mastra/core": "1.
|
|
49
|
+
"@internal/lint": "0.0.59",
|
|
50
|
+
"@internal/types-builder": "0.0.34",
|
|
51
|
+
"@mastra/core": "1.4.0"
|
|
52
52
|
},
|
|
53
53
|
"homepage": "https://mastra.ai",
|
|
54
54
|
"repository": {
|