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

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

@@ -1,202 +0,0 @@
-# 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`)
-
-### `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;
-  modifiedAt?: Date;
-}
-```
-
-### `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');
-// { type: 'file', size: 1234, modifiedAt: Date, createdAt: Date, path: '/docs/guide.md' }
-```
-
-**Returns:** `Promise<FileStat>`
-
-```typescript
-interface FileStat {
-  type: 'file' | 'directory';
-  size: number;
-  modifiedAt: Date;
-  createdAt: Date;
-  path: 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()`
-
-Get a description of how this filesystem works. Used in tool descriptions to help agents understand path semantics.
-
-```typescript
-const instructions = filesystem.getInstructions?.();
-// 'Local filesystem at "/workspace". Files at workspace path "/foo" are stored at "/workspace/foo" on disk.'
-```
-
-**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

@@ -1,170 +0,0 @@
-# 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
-
-**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)

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

@@ -1,327 +0,0 @@
-# LocalFilesystem
-
-**Added in:** `@mastra/core@1.1.0`
-
-Stores files in a directory on the local filesystem.
-
-> **Info:** For interface details, see [WorkspaceFilesystem Interface](https://mastra.ai/reference/workspace/filesystem).
-
-## Usage
-
-Add a `LocalFilesystem` to a workspace and assign it to an agent. The agent can then read, write, and manage files as part of its tasks:
-
-```typescript
-import { Agent } from '@mastra/core/agent';
-import { Workspace, LocalFilesystem } from '@mastra/core/workspace';
-
-const workspace = new Workspace({
-  filesystem: new LocalFilesystem({
-    basePath: './workspace',
-  }),
-});
-
-const agent = new Agent({
-  id: 'file-agent',
-  model: 'openai/gpt-4o',
-  workspace,
-});
-
-// The agent now has filesystem tools available
-const response = await agent.generate('List all files in the workspace');
-```
-
-## Constructor parameters
-
-**basePath:** (`string`): Base directory path on disk. All file paths are resolved relative to this directory.
-
-**id?:** (`string`): Unique identifier for this filesystem instance (Default: `Auto-generated`)
-
-**contained?:** (`boolean`): When true, all file operations are restricted to stay within basePath. Prevents path traversal attacks and symlink escapes. See \[containment]\(/docs/workspace/filesystem#containment). (Default: `true`)
-
-**allowedPaths?:** (`string[]`): Additional absolute paths that are allowed beyond basePath. Useful with \`contained: true\` to grant access to specific directories without disabling containment entirely. Paths are resolved to absolute paths. (Default: `[]`)
-
-**readOnly?:** (`boolean`): When true, all write operations are blocked. Read operations are still allowed. (Default: `false`)
-
-## Properties
-
-**id:** (`string`): Filesystem instance identifier
-
-**name:** (`string`): Provider name ('LocalFilesystem')
-
-**provider:** (`string`): Provider identifier ('local')
-
-**basePath:** (`string`): The absolute base path on disk
-
-**readOnly:** (`boolean | undefined`): Whether the filesystem is in read-only mode
-
-**allowedPaths:** (`readonly string[]`): Current set of additional allowed paths (absolute, resolved). These paths are permitted beyond basePath when containment is enabled.
-
-## Methods
-
-### `init()`
-
-Initialize the filesystem. Creates the base directory if it doesn't exist.
-
-```typescript
-await filesystem.init();
-```
-
-Called by `workspace.init()`.
-
-### Lazy initialization
-
-LocalFilesystem initializes on first operation if not already initialized, creating the base directory automatically. Calling `init()` explicitly is optional but can be useful to pre-create directories before the first operation.
-
-### `destroy()`
-
-Clean up filesystem resources.
-
-```typescript
-await filesystem.destroy();
-```
-
-Called by `workspace.destroy()`.
-
-### `setAllowedPaths(pathsOrUpdater)`
-
-Update the allowed paths at runtime. Accepts a new paths array (replaces current) or an updater callback that receives the current paths and returns the new set.
-
-```typescript
-// Set directly
-filesystem.setAllowedPaths(['/home/user/.config']);
-
-// Update with callback
-filesystem.setAllowedPaths(prev => [...prev, '/home/user/documents']);
-
-// Clear all allowed paths
-filesystem.setAllowedPaths([]);
-```
-
-**Parameters:**
-
-**pathsOrUpdater:** (`string[] | ((current: readonly string[]) => string[])`): New allowed paths array or updater function receiving current paths
-
-### `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'`)
-
-### `writeFile(path, content, options?)`
-
-Write content to a file.
-
-```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`)
-
-### `appendFile(path, content)`
-
-Append content to an existing file.
-
-```typescript
-await filesystem.appendFile('/logs/app.log', 'New log entry\n');
-```
-
-**Parameters:**
-
-**path:** (`string`): File path relative to basePath
-
-**content:** (`string | Buffer`): Content to append
-
-### `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`)
-
-### `copyFile(src, dest, options?)`
-
-Copy a file to a new location.
-
-```typescript
-await filesystem.copyFile('/docs/template.md', '/docs/new-doc.md');
-await filesystem.copyFile('/src/config.json', '/backup/config.json', { overwrite: false });
-```
-
-**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');
-await filesystem.moveFile('/temp/upload.txt', '/files/document.txt');
-```
-
-**Parameters:**
-
-**src:** (`string`): Source file path
-
-**dest:** (`string`): Destination file path
-
-**options.overwrite?:** (`boolean`): Overwrite destination if it exists (Default: `true`)
-
-### `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`)
-
-### `readdir(path, options?)`
-
-List directory contents.
-
-```typescript
-const entries = await filesystem.readdir('/docs');
-// [{ name: 'guide.md', type: 'file' }, { name: 'api', type: 'directory' }]
-```
-
-### `exists(path)`
-
-Check if a path exists.
-
-```typescript
-const exists = await filesystem.exists('/docs/guide.md');
-```
-
-### `stat(path)`
-
-Get file or directory metadata.
-
-```typescript
-const stat = await filesystem.stat('/docs/guide.md');
-// { type: 'file', size: 1234, modifiedAt: Date, createdAt: Date, path: '/docs/guide.md' }
-```
-
-### `getInfo()`
-
-Returns metadata about this filesystem instance.
-
-```typescript
-const info = filesystem.getInfo();
-// { id: '...', name: 'LocalFilesystem', provider: 'local', basePath: '/workspace', readOnly: false }
-```
-
-### `getInstructions()`
-
-Returns a description of how paths work in this filesystem. Used in tool descriptions.
-
-```typescript
-const instructions = filesystem.getInstructions();
-// 'Local filesystem at "/workspace". Files at workspace path "/foo" are stored at "/workspace/foo" on disk.'
-```
-
-## Path resolution
-
-### How basePath works
-
-The `basePath` option sets the root directory for all file operations. File paths passed to methods like `readFile()` are resolved relative to this base:
-
-- Leading slashes are stripped: `/docs/guide.md` → `docs/guide.md`
-- The path is normalized and joined with basePath
-- Result: `./workspace` + `docs/guide.md` → `./workspace/docs/guide.md`
-
-```typescript
-const filesystem = new LocalFilesystem({
-  basePath: './workspace',
-});
-
-// These all resolve to ./workspace/docs/guide.md
-await filesystem.readFile('/docs/guide.md');
-await filesystem.readFile('docs/guide.md');
-```
-
-### Relative paths and execution context
-
-When you use a relative path for `basePath`, it resolves from `process.cwd()`. In Mastra projects, cwd varies depending on how you run your code:
-
-| Context        | Working directory         | `./workspace` resolves to       |
-| -------------- | ------------------------- | ------------------------------- |
-| `mastra dev`   | `./src/mastra/public/`    | `./src/mastra/public/workspace` |
-| `mastra start` | `./.mastra/output/`       | `./.mastra/output/workspace`    |
-| Direct script  | Where you ran the command | Relative to that location       |
-
-This can cause confusion when the same relative path resolves to different locations.
-
-### Recommended: Use absolute paths
-
-For consistent paths across all execution contexts, use an environment variable with an absolute path:
-
-```typescript
-import { LocalFilesystem } from '@mastra/core/workspace';
-
-const filesystem = new LocalFilesystem({
-  basePath: process.env.WORKSPACE_PATH!,
-});
-```
-
-Set `WORKSPACE_PATH` in your environment to an absolute path like `/home/user/my-project/workspace`. This ensures the workspace path is consistent regardless of how you run your code.
-
-## Related
-
-- [WorkspaceFilesystem interface](https://mastra.ai/reference/workspace/filesystem)
-- [Workspace class](https://mastra.ai/reference/workspace/workspace-class)
-- [Workspace overview](https://mastra.ai/docs/workspace/overview)