@mastra/mcp-docs-server 1.1.5 → 1.1.6-alpha.0

package/.docs/reference/workspace/filesystem.md

@@ -0,0 +1,255 @@
+# WorkspaceFilesystem
+
+**Added in:** `@mastra/core@1.1.0`
+
+The `WorkspaceFilesystem` interface defines how workspaces interact with file storage.
+
+## Methods
+
+### `readFile(path, options?)`
+
+Read file contents.
+
+```typescript
+const content = await filesystem.readFile('/docs/guide.md')
+const buffer = await filesystem.readFile('/image.png', { encoding: 'binary' })
+```
+
+**Parameters:**
+
+**path:** (`string`): File path relative to basePath
+
+**options.encoding?:** (`'utf-8' | 'binary'`): Text or binary encoding (Default: `'utf-8'`)
+
+**Returns:** `Promise<string | Buffer>`
+
+### `writeFile(path, content, options?)`
+
+Write file contents.
+
+```typescript
+await filesystem.writeFile('/docs/new.md', '# New Document')
+await filesystem.writeFile('/nested/path/file.md', content, { recursive: true })
+```
+
+**Parameters:**
+
+**path:** (`string`): File path relative to basePath
+
+**content:** (`string | Buffer`): File content
+
+**options.recursive?:** (`boolean`): Create parent directories if they don't exist (Default: `false`)
+
+**options.overwrite?:** (`boolean`): Overwrite existing file (Default: `true`)
+
+### `deleteFile(path, options?)`
+
+Delete a file.
+
+```typescript
+await filesystem.deleteFile('/docs/old.md')
+await filesystem.deleteFile('/docs/maybe.md', { force: true }) // Don't throw if missing
+```
+
+**Parameters:**
+
+**path:** (`string`): File path
+
+**options.force?:** (`boolean`): Don't throw error if file doesn't exist (Default: `false`)
+
+### `appendFile(path, content)`
+
+Append content to a file, creating it if it does not already exist. Parent directories are created automatically.
+
+```typescript
+await filesystem.appendFile('/logs/app.log', 'New log entry\n')
+```
+
+**Parameters:**
+
+**path:** (`string`): File path
+
+**content:** (`string | Buffer`): Content to append
+
+### `copyFile(src, dest, options?)`
+
+Copy a file to a new location.
+
+```typescript
+await filesystem.copyFile('/docs/template.md', '/docs/new-doc.md')
+```
+
+**Parameters:**
+
+**src:** (`string`): Source file path
+
+**dest:** (`string`): Destination file path
+
+**options.overwrite?:** (`boolean`): Overwrite destination if it exists (Default: `true`)
+
+### `moveFile(src, dest, options?)`
+
+Move or rename a file.
+
+```typescript
+await filesystem.moveFile('/docs/draft.md', '/docs/final.md')
+```
+
+**Parameters:**
+
+**src:** (`string`): Source file path
+
+**dest:** (`string`): Destination file path
+
+**options.overwrite?:** (`boolean`): Overwrite destination if it exists (Default: `true`)
+
+### `readdir(path, options?)`
+
+List directory contents.
+
+```typescript
+const entries = await filesystem.readdir('/docs')
+// [{ name: 'guide.md', type: 'file' }, { name: 'api', type: 'directory' }]
+```
+
+**Returns:** `Promise<FileEntry[]>`
+
+```typescript
+interface FileEntry {
+  name: string
+  type: 'file' | 'directory'
+  size?: number
+  isSymlink?: boolean
+  symlinkTarget?: string
+}
+```
+
+### `mkdir(path, options?)`
+
+Create a directory.
+
+```typescript
+await filesystem.mkdir('/docs/api')
+await filesystem.mkdir('/deeply/nested/path', { recursive: true })
+```
+
+**Parameters:**
+
+**path:** (`string`): Directory path
+
+**options.recursive?:** (`boolean`): Create parent directories (Default: `false`)
+
+### `rmdir(path, options?)`
+
+Remove a directory.
+
+```typescript
+await filesystem.rmdir('/docs/old')
+await filesystem.rmdir('/docs/nested', { recursive: true })
+```
+
+**Parameters:**
+
+**path:** (`string`): Directory path
+
+**options.recursive?:** (`boolean`): Remove contents recursively (Default: `false`)
+
+**options.force?:** (`boolean`): Don't throw if directory doesn't exist (Default: `false`)
+
+### `exists(path)`
+
+Check if a path exists.
+
+```typescript
+const exists = await filesystem.exists('/docs/guide.md')
+```
+
+**Returns:** `Promise<boolean>`
+
+### `stat(path)`
+
+Get file or directory metadata.
+
+```typescript
+const stat = await filesystem.stat('/docs/guide.md')
+// { name: 'guide.md', path: '/docs/guide.md', type: 'file', size: 1234, createdAt: Date, modifiedAt: Date }
+```
+
+**Returns:** `Promise<FileStat>`
+
+```typescript
+interface FileStat {
+  name: string // File or directory name (basename only)
+  path: string // Path relative to the filesystem basePath
+  type: 'file' | 'directory'
+  size: number
+  createdAt: Date
+  modifiedAt: Date
+  mimeType?: string
+}
+```
+
+## Optional Methods
+
+### `init()`
+
+Initialize the filesystem. Called by `workspace.init()`.
+
+```typescript
+await filesystem.init?.()
+```
+
+### `destroy()`
+
+Clean up resources. Called by `workspace.destroy()`.
+
+```typescript
+await filesystem.destroy?.()
+```
+
+### `getInfo()`
+
+Get filesystem metadata.
+
+```typescript
+const info = await filesystem.getInfo?.()
+// { id, name, provider, basePath, readOnly, status, storage? }
+```
+
+**Returns:** `Promise<FilesystemInfo>`
+
+```typescript
+interface FilesystemInfo {
+  id: string
+  name: string
+  provider: string
+  basePath?: string
+  readOnly?: boolean
+  status?: string
+  storage?: {
+    totalBytes?: number
+    usedBytes?: number
+    availableBytes?: number
+  }
+}
+```
+
+### `getInstructions(opts?)`
+
+Returns a description of how this filesystem works. Injected into the agent's system message when the workspace is assigned to an agent.
+
+```typescript
+const instructions = filesystem.getInstructions?.()
+// 'Local filesystem at "/workspace". Files at workspace path "/foo" are stored at "/workspace/foo" on disk.'
+```
+
+**Parameters:**
+
+**opts.requestContext?:** (`RequestContext`): Forwarded to the \`instructions\` function if one was provided in the constructor.
+
+**Returns:** `string`
+
+## Related
+
+- [Workspace Class](https://mastra.ai/reference/workspace/workspace-class)
+- [Sandbox Interface](https://mastra.ai/reference/workspace/sandbox)

package/.docs/reference/workspace/gcs-filesystem.md

@@ -0,0 +1,174 @@
+# GCSFilesystem
+
+Stores files in Google Cloud Storage.
+
+> **Info:** For interface details, see [WorkspaceFilesystem Interface](https://mastra.ai/reference/workspace/filesystem).
+
+## Installation
+
+```bash
+npm install @mastra/gcs
+```
+
+## Usage
+
+Add a `GCSFilesystem` to a workspace and assign it to an agent:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Workspace } from '@mastra/core/workspace'
+import { GCSFilesystem } from '@mastra/gcs'
+
+const workspace = new Workspace({
+  filesystem: new GCSFilesystem({
+    bucket: 'my-gcs-bucket',
+    projectId: 'my-project-id',
+    credentials: JSON.parse(process.env.GCS_SERVICE_ACCOUNT_KEY),
+  }),
+})
+
+const agent = new Agent({
+  name: 'file-agent',
+  model: 'anthropic/claude-opus-4-5',
+  workspace,
+})
+```
+
+### Using Application Default Credentials
+
+If running on Google Cloud or with `gcloud` CLI configured, you can omit credentials:
+
+```typescript
+import { GCSFilesystem } from '@mastra/gcs'
+
+const filesystem = new GCSFilesystem({
+  bucket: 'my-gcs-bucket',
+  // Uses Application Default Credentials automatically
+})
+```
+
+[Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/application-default-credentials) automatically discovers credentials in this order:
+
+1. `GOOGLE_APPLICATION_CREDENTIALS` environment variable (path to a service account key file)
+2. Default service account when running on GCP (Compute Engine, Cloud Run, GKE, etc.)
+3. User credentials from `gcloud auth application-default login` (for local development)
+
+### Using a Key File Path
+
+You can also pass a path to a service account key file:
+
+```typescript
+import { GCSFilesystem } from '@mastra/gcs'
+
+const filesystem = new GCSFilesystem({
+  bucket: 'my-gcs-bucket',
+  projectId: 'my-project-id',
+  credentials: '/path/to/service-account-key.json',
+})
+```
+
+## Constructor parameters
+
+**bucket:** (`string`): GCS bucket name
+
+**projectId?:** (`string`): GCS project ID. Required when using service account credentials.
+
+**credentials?:** (`object | string`): Service account key JSON object or path to key file. If not provided, uses Application Default Credentials.
+
+**prefix?:** (`string`): Optional prefix for all keys (acts like a subdirectory)
+
+**id?:** (`string`): Unique identifier for this filesystem instance (Default: `Auto-generated`)
+
+**displayName?:** (`string`): Human-friendly display name for the UI
+
+**icon?:** (`FilesystemIcon`): Icon identifier for the UI
+
+**description?:** (`string`): Short description of this filesystem for the UI
+
+**readOnly?:** (`boolean`): When true, all write operations are blocked (Default: `false`)
+
+**endpoint?:** (`string`): Custom API endpoint URL. Used for local development with emulators.
+
+## Properties
+
+**id:** (`string`): Filesystem instance identifier
+
+**name:** (`string`): Provider name ('GCSFilesystem')
+
+**provider:** (`string`): Provider identifier ('gcs')
+
+**bucket:** (`string`): The GCS bucket name
+
+**readOnly:** (`boolean | undefined`): Whether the filesystem is in read-only mode
+
+## Methods
+
+GCSFilesystem implements the [WorkspaceFilesystem interface](https://mastra.ai/reference/workspace/filesystem), providing all standard filesystem methods:
+
+- `readFile(path, options?)` - Read file contents
+- `writeFile(path, content, options?)` - Write content to a file
+- `appendFile(path, content)` - Append content to a file
+- `deleteFile(path, options?)` - Delete a file
+- `copyFile(src, dest, options?)` - Copy a file
+- `moveFile(src, dest, options?)` - Move or rename a file
+- `mkdir(path, options?)` - Create a directory
+- `rmdir(path, options?)` - Remove a directory
+- `readdir(path, options?)` - List directory contents
+- `exists(path)` - Check if a path exists
+- `stat(path)` - Get file or directory metadata
+
+### `init()`
+
+Initialize the filesystem. Verifies bucket access and credentials.
+
+```typescript
+await filesystem.init()
+```
+
+### `getInfo()`
+
+Returns metadata about this filesystem instance.
+
+```typescript
+const info = filesystem.getInfo()
+// { id: '...', name: 'GCSFilesystem', provider: 'gcs', status: 'ready' }
+```
+
+### `getMountConfig()`
+
+Returns the mount configuration for sandboxes that support mounting this filesystem type.
+
+```typescript
+const config = filesystem.getMountConfig()
+// { type: 'gcs', bucket: 'my-bucket', ... }
+```
+
+## Mounting in E2B Sandboxes
+
+GCSFilesystem can be mounted into E2B sandboxes, making the bucket accessible as a local directory:
+
+```typescript
+import { Workspace } from '@mastra/core/workspace'
+import { GCSFilesystem } from '@mastra/gcs'
+import { E2BSandbox } from '@mastra/e2b'
+
+const workspace = new Workspace({
+  mounts: {
+    '/data': new GCSFilesystem({
+      bucket: 'my-gcs-bucket',
+      projectId: 'my-project-id',
+      credentials: JSON.parse(process.env.GCS_SERVICE_ACCOUNT_KEY),
+    }),
+  },
+  sandbox: new E2BSandbox({ id: 'dev-sandbox' }),
+})
+```
+
+See [E2BSandbox reference](https://mastra.ai/reference/workspace/e2b-sandbox) for more details on mounting.
+
+## Related
+
+- [WorkspaceFilesystem interface](https://mastra.ai/reference/workspace/filesystem)
+- [S3Filesystem reference](https://mastra.ai/reference/workspace/s3-filesystem)
+- [E2BSandbox reference](https://mastra.ai/reference/workspace/e2b-sandbox)
+- [Workspace overview](https://mastra.ai/docs/workspace/overview)