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

package/.docs/reference/workspace/workspace-class.md

@@ -1,226 +0,0 @@
-# Workspace Class
-
-**Added in:** `@mastra/core@1.1.0`
-
-The `Workspace` class combines a filesystem and sandbox to provide agents with file storage and command execution capabilities. It also supports BM25 and vector search for indexed content.
-
-## Usage Example
-
-```typescript
-import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace';
-
-const workspace = new Workspace({
-  id: 'my-workspace',
-  name: 'My Workspace',
-  filesystem: new LocalFilesystem({
-    basePath: './workspace',
-  }),
-  sandbox: new LocalSandbox({
-    workingDirectory: './workspace',
-  }),
-  bm25: true,
-  autoIndexPaths: ['/docs'],
-});
-```
-
-## Constructor parameters
-
-**id?:** (`string`): Unique identifier for the workspace (Default: `Auto-generated`)
-
-**name?:** (`string`): Human-readable name (Default: `workspace-{id}`)
-
-**filesystem?:** (`WorkspaceFilesystem`): Filesystem provider instance (e.g., LocalFilesystem)
-
-**sandbox?:** (`WorkspaceSandbox`): Sandbox provider instance (e.g., LocalSandbox)
-
-**bm25?:** (`boolean | BM25Config`): Enable BM25 keyword search. Pass true for defaults or a config object. (Default: `undefined`)
-
-**vectorStore?:** (`MastraVector`): Vector store for semantic search
-
-**embedder?:** (`(text: string) => Promise<number[]>`): Embedder function for generating vectors. Required when vectorStore is provided.
-
-**autoIndexPaths?:** (`string[]`): Paths to auto-index on init()
-
-**skills?:** (`string[] | ((context: SkillsContext) => string[] | Promise<string[]>)`): Paths where SKILL.md files are located. This can be a static array or an async function that resolves paths dynamically.
-
-**tools?:** (`WorkspaceToolsConfig`): Per-tool configuration for enabling tools and setting safety options
-
-**operationTimeout?:** (`number`): Timeout for operations in milliseconds
-
-## Tool configuration
-
-The `tools` option accepts a `WorkspaceToolsConfig` object that controls which workspace tools are enabled and their safety settings.
-
-```typescript
-import { WORKSPACE_TOOLS } from '@mastra/core/workspace';
-
-tools: {
-  // Global defaults (apply to all tools)
-  enabled: true,
-  requireApproval: false,
-
-  // Per-tool overrides using WORKSPACE_TOOLS constants
-  [WORKSPACE_TOOLS.FILESYSTEM.WRITE_FILE]: {
-    requireApproval: true,
-  },
-}
-```
-
-The config object has two parts:
-
-- **Global defaults** (`enabled`, `requireApproval`) - Apply to all tools unless overridden
-- **Per-tool overrides** - Use `WORKSPACE_TOOLS` constants as keys to configure individual tools
-
-See [workspace overview](https://mastra.ai/docs/workspace/overview) for more examples.
-
-### Per-tool options
-
-Each tool can be configured with these options:
-
-**enabled?:** (`boolean`): Whether the tool is available to agents (Default: `true`)
-
-**requireApproval?:** (`boolean`): Whether the tool requires user approval before execution (Default: `false`)
-
-**requireReadBeforeWrite?:** (`boolean`): For write tools: require reading the file first to prevent overwrites (Default: `false`)
-
-## Properties
-
-**id:** (`string`): Workspace identifier
-
-**name:** (`string`): Workspace name
-
-**status:** (`WorkspaceStatus`): 'pending' | 'initializing' | 'ready' | 'error' | 'destroying' | 'destroyed'
-
-**filesystem:** (`WorkspaceFilesystem | undefined`): The filesystem provider
-
-**sandbox:** (`WorkspaceSandbox | undefined`): The sandbox provider
-
-**skills:** (`WorkspaceSkills | undefined`): Skills interface for accessing SKILL.md files
-
-**canBM25:** (`boolean`): Whether BM25 search is available
-
-**canVector:** (`boolean`): Whether vector search is available
-
-**canHybrid:** (`boolean`): Whether hybrid search is available
-
-## Methods
-
-### Lifecycle
-
-#### `init()`
-
-Initialize the workspace and prepare resources.
-
-```typescript
-await workspace.init();
-```
-
-Calling `init()` is optional in most cases:
-
-- **Sandbox**: Auto-starts on first `executeCommand()` call. Use `init()` to avoid first-command latency.
-- **Filesystem**: Creates the base directory and runs any provider-specific setup. Some providers auto-create the directory on first operation.
-- **Search**: Required only if using `autoIndexPaths` for auto-indexing.
-
-Initialization performs:
-
-- Starts the filesystem provider (creates base directory if needed)
-- Starts the sandbox provider (creates working directory, sets up isolation if configured)
-- Indexes files from `autoIndexPaths` for search
-
-#### `destroy()`
-
-Destroy the workspace and clean up resources.
-
-```typescript
-await workspace.destroy();
-```
-
-### Search operations
-
-#### `index(path, content, options?)`
-
-Index content for search.
-
-```typescript
-await workspace.index('/docs/guide.md', 'Guide content...');
-```
-
-#### `search(query, options?)`
-
-Search indexed content.
-
-```typescript
-const results = await workspace.search('password reset', {
-  topK: 10,
-  mode: 'hybrid',
-});
-```
-
-### Utility
-
-#### `getInfo()`
-
-Get workspace information.
-
-```typescript
-const info = await workspace.getInfo();
-// { id, name, status, createdAt, lastAccessedAt, filesystem?, sandbox? }
-```
-
-#### `getPathContext()`
-
-Get information about filesystem and sandbox paths, including instructions for agents.
-
-```typescript
-const context = workspace.getPathContext();
-// { filesystem?, sandbox?, instructions }
-```
-
-The `instructions` field contains provider-generated descriptions combined from the filesystem and sandbox. These instructions are included in tool descriptions to help agents understand the execution context.
-
-#### `getToolsConfig()`
-
-Get the tools configuration.
-
-```typescript
-const config = workspace.getToolsConfig();
-```
-
-## Agent tools
-
-A workspace provides tools to agents based on what is configured.
-
-### Filesystem tools
-
-Added when a filesystem is configured:
-
-| Tool                          | Description                                                                                                         |
-| ----------------------------- | ------------------------------------------------------------------------------------------------------------------- |
-| `mastra_workspace_read_file`  | Read file contents. Supports optional line range for reading specific portions of large files.                      |
-| `mastra_workspace_write_file` | Create or overwrite a file with new content. Creates parent directories automatically.                              |
-| `mastra_workspace_edit_file`  | Edit an existing file by finding and replacing text. Useful for targeted changes without rewriting the entire file. |
-| `mastra_workspace_list_files` | List directory contents as a tree structure. Supports recursive listing with depth limits.                          |
-| `mastra_workspace_delete`     | Delete a file or directory. Supports recursive deletion for directories.                                            |
-| `mastra_workspace_file_stat`  | Get metadata about a file or directory including size, type, and modification time.                                 |
-| `mastra_workspace_mkdir`      | Create a directory. Creates parent directories automatically if they don't exist.                                   |
-
-Write tools (`write_file`, `edit_file`, `delete`, `mkdir`) are excluded when the filesystem is in read-only mode.
-
-### Sandbox tools
-
-Added when a sandbox is configured:
-
-| Tool                               | Description                                                                                                            |
-| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| `mastra_workspace_execute_command` | Execute a shell command with arguments. Returns stdout, stderr, and exit code. Supports timeouts and streaming output. |
-
-### Search tools
-
-Added when BM25 or vector search is configured:
-
-| Tool                      | Description                                                                                                           |
-| ------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| `mastra_workspace_search` | Search indexed content using keyword (BM25), semantic (vector), or hybrid search. Returns ranked results with scores. |
-| `mastra_workspace_index`  | Index content for search. Associates content with a path for later retrieval.                                         |
-
-The `index` tool is excluded when the filesystem is in read-only mode.