@mastra/mcp-docs-server 1.2.4-alpha.1 → 1.2.4-alpha.6

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

@@ -0,0 +1,321 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# MesaFilesystem
+
+Stores workspace files in [Mesa](https://docs.mesa.dev/content/getting-started/introduction) repos through the standard Mastra `WorkspaceFilesystem` interface.
+
+Use `MesaFilesystem` when agents need versioned file storage. For a local directory, use [`LocalFilesystem`](https://mastra.ai/reference/workspace/local-filesystem). For object storage, use [`S3Filesystem`](https://mastra.ai/reference/workspace/s3-filesystem), [`GCSFilesystem`](https://mastra.ai/reference/workspace/gcs-filesystem), or [`AzureBlobFilesystem`](https://mastra.ai/reference/workspace/azure-blob-filesystem).
+
+> **Info:** `MesaFilesystem` runs in the Mastra process.
+>
+> [Mesa's POSIX mount](https://docs.mesa.dev/content/mesafs/posix-mount) (for using a Mesa filesystem within a sandbox) is not yet part of the `@mastra/mesa` package. Support is coming soon.
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/mesa
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/mesa
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/mesa
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/mesa
+```
+
+## Usage example
+
+Mount one Mesa repo and pass the filesystem to a workspace:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Workspace } from '@mastra/core/workspace'
+import { MesaFilesystem } from '@mastra/mesa'
+
+const workspace = new Workspace({
+  filesystem: new MesaFilesystem({
+    apiKey: process.env.MESA_API_KEY,
+    org: 'acme',
+    repos: [{ name: 'docs', bookmark: 'main' }],
+  }),
+})
+
+const agent = new Agent({
+  id: 'file-agent',
+  name: 'file-agent',
+  model: 'anthropic/claude-opus-4-7',
+  workspace,
+})
+```
+
+`apiKey` falls back to `MESA_API_KEY` when omitted.
+
+## Constructor parameters
+
+**apiKey** (`string`): Mesa API key. Falls back to \`MESA\_API\_KEY\` when omitted.
+
+**org** (`string`): Mesa org slug. When omitted, the Mesa SDK resolves the default org.
+
+**repos** (`RepoConfig[]`): Mesa repos to mount.
+
+**cache** (`{ diskCache?: { path: string; maxSizeBytes?: number } }`): Mesa filesystem cache configuration.
+
+**ttl** (`number`): Mesa mount token lifetime in seconds.
+
+**readOnly** (`boolean`): Mount all repos as read-only. (Default: `false`)
+
+## Properties
+
+**id** (`string`): Filesystem instance identifier.
+
+**name** (`string`): Provider name (\`'MesaFilesystem'\`).
+
+**provider** (`string`): Provider identifier (\`'mesa'\`).
+
+**readOnly** (`boolean | undefined`): Whether write operations are blocked.
+
+**client** (`Mesa | undefined`): Mesa SDK client created by this provider. Undefined before initialization.
+
+**filesystem** (`MesaFileSystem`): Active Mesa filesystem. Access this after initialization when you need the raw Mesa SDK filesystem.
+
+**change** (`MesaFileSystem["change"]`): Mesa change management operations for the mounted filesystem.
+
+**bookmark** (`MesaFileSystem["bookmark"]`): Mesa bookmark management operations for the mounted filesystem.
+
+## Methods
+
+`MesaFilesystem` implements the [WorkspaceFilesystem interface](https://mastra.ai/reference/workspace/filesystem).
+
+### File operations
+
+#### `readFile(path, options?)`
+
+Reads a file from Mesa.
+
+```typescript
+const content = await filesystem.readFile('/acme/docs/README.md', {
+  encoding: 'utf-8',
+})
+```
+
+Returns: `Promise<string | Buffer>`
+
+#### `writeFile(path, content, options?)`
+
+Writes a file to Mesa.
+
+```typescript
+await filesystem.writeFile('/acme/docs/report.md', '# Report')
+```
+
+Returns: `Promise<void>`
+
+#### `appendFile(path, content)`
+
+Appends content to a file.
+
+```typescript
+await filesystem.appendFile('/acme/docs/log.txt', 'new line\n')
+```
+
+Returns: `Promise<void>`
+
+#### `deleteFile(path, options?)`
+
+Deletes a file.
+
+```typescript
+await filesystem.deleteFile('/acme/docs/old-report.md')
+```
+
+Returns: `Promise<void>`
+
+#### `copyFile(src, dest, options?)`
+
+Copies a file.
+
+```typescript
+await filesystem.copyFile('/acme/docs/report.md', '/acme/docs/archive/report.md')
+```
+
+Returns: `Promise<void>`
+
+#### `moveFile(src, dest, options?)`
+
+Moves or renames a file.
+
+```typescript
+await filesystem.moveFile('/acme/docs/draft.md', '/acme/docs/final.md')
+```
+
+Returns: `Promise<void>`
+
+### Directory operations
+
+#### `mkdir(path, options?)`
+
+Creates a directory.
+
+```typescript
+await filesystem.mkdir('/acme/docs/reports', { recursive: true })
+```
+
+Returns: `Promise<void>`
+
+#### `rmdir(path, options?)`
+
+Removes a directory.
+
+```typescript
+await filesystem.rmdir('/acme/docs/reports', { recursive: true })
+```
+
+Returns: `Promise<void>`
+
+#### `readdir(path, options?)`
+
+Lists directory entries.
+
+```typescript
+const entries = await filesystem.readdir('/acme/docs', {
+  recursive: true,
+  extension: '.md',
+})
+```
+
+Returns: `Promise<FileEntry[]>`
+
+### Path operations
+
+#### `exists(path)`
+
+Checks whether a path exists.
+
+```typescript
+const exists = await filesystem.exists('/acme/docs/README.md')
+```
+
+Returns: `Promise<boolean>`
+
+#### `stat(path)`
+
+Returns file or directory metadata.
+
+```typescript
+const stat = await filesystem.stat('/acme/docs/README.md')
+```
+
+Returns: `Promise<FileStat>`
+
+#### `realpath(path)`
+
+Returns the canonical path from Mesa.
+
+```typescript
+const realPath = await filesystem.realpath('/acme/docs/README.md')
+```
+
+Returns: `Promise<string>`
+
+### Mesa operations
+
+#### `bash(options?)`
+
+Creates a Mesa-backed Bash runtime for this filesystem.
+
+```typescript
+const bash = await filesystem.bash({
+  cwd: '/acme/docs',
+})
+```
+
+Returns: `Promise<Bash>`
+
+## Path semantics
+
+Methods expect absolute paths. For `MesaFilesystem`, paths are rooted at the Mesa mount and must include the org slug and repo name:
+
+```typescript
+await filesystem.readFile('/acme/docs/README.md')
+```
+
+Do not omit the leading slash:
+
+```typescript
+await filesystem.readFile('acme/docs/README.md') // Incorrect
+await filesystem.readFile('/acme/docs/README.md') // Correct
+```
+
+The org comes from `org` in the constructor, or from the Mesa SDK's default org inference when `org` is omitted. It still appears as the first path segment.
+
+When you mount multiple repos, each repo is available under the org segment:
+
+```typescript
+const filesystem = new MesaFilesystem({
+  org: 'acme',
+  repos: [
+    { name: 'docs', bookmark: 'main' },
+    { name: 'website', bookmark: 'main' },
+  ],
+})
+
+await filesystem.readFile('/acme/docs/README.md')
+await filesystem.readFile('/acme/website/package.json')
+```
+
+## Mesa versioning APIs
+
+Access the underlying Mesa filesystem for Mesa-specific change and bookmark operations:
+
+```typescript
+await filesystem.writeFile('/acme/docs/draft.md', 'Draft')
+
+const current = await filesystem.change.current({
+  repo: 'docs',
+})
+
+await filesystem.bookmark.move({
+  repo: 'docs',
+  name: 'main',
+  changeId: current.changeId,
+})
+```
+
+More details on versioning semantics can be found in [Mesa's docs](https://docs.mesa.dev/content/concepts/versioning).
+
+## Read-only mode
+
+Set `readOnly: true` to block write operations through Mastra:
+
+```typescript
+const filesystem = new MesaFilesystem({
+  repos: [{ name: 'docs', bookmark: 'main' }],
+  readOnly: true,
+})
+```
+
+Read operations still work. Write operations throw `WorkspaceReadOnlyError`.
+
+## Concurrency
+
+`overwrite: false` and `expectedMtime` use preflight checks before writing. These checks are not atomic unless Mesa adds native conditional writes for app mounts.
+
+## Related
+
+- [WorkspaceFilesystem interface](https://mastra.ai/reference/workspace/filesystem)
+- [Filesystem docs](https://mastra.ai/docs/workspace/filesystem)
+- [Workspace overview](https://mastra.ai/docs/workspace/overview)
+- [Mesa documentation](https://docs.mesa.dev/content/getting-started/introduction)

package/.docs/reference/workspace/modal-sandbox.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # ModalSandbox
 
 Executes commands in isolated [Modal](https://modal.com) cloud sandboxes. Provides secure, ephemeral environments backed by Modal's infrastructure.

package/.docs/reference/workspace/process-manager.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # SandboxProcessManager
 
 **Added in:** `@mastra/core@1.7.0`

package/.docs/reference/workspace/railway-sandbox.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # RailwaySandbox
 
 Executes commands in ephemeral, isolated [Railway](https://docs.railway.com/sandboxes) sandboxes. Each sandbox is an isolated Debian Linux VM provisioned on demand through the Railway TypeScript SDK. Supports command execution with streaming output, command timeouts, configurable idle timeout, `ISOLATED`/`PRIVATE` network isolation, custom base images via the Railway template builder, forking a running sandbox, and reattaching to an existing sandbox by ID.

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

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # S3Filesystem
 
 Stores files in Amazon S3 or S3-compatible storage services like Cloudflare R2, MinIO, DigitalOcean Spaces, and Tigris.
@@ -49,6 +51,7 @@ const workspace = new Workspace({
 })
 
 const agent = new Agent({
+  id: 'file-agent',
   name: 'file-agent',
   model: 'anthropic/claude-opus-4-7',
   workspace,

package/.docs/reference/workspace/sandbox.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # WorkspaceSandbox
 
 **Added in:** `@mastra/core@1.1.0`

package/.docs/reference/workspace/vercel-microvm-sandbox.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # VercelMicroVMSandbox
 
 Executes commands inside [Vercel Sandbox](https://vercel.com/docs/vercel-sandbox) — an ephemeral [Firecracker](https://firecracker-microvm.github.io/) MicroVM running Amazon Linux 2023. Provides a persistent in-session filesystem, `sudo` access, exposed ports, and background processes.

package/.docs/reference/workspace/vercel.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # VercelSandbox
 
 Executes commands as [Vercel](https://vercel.com) serverless functions. Provides globally-distributed, zero-infrastructure execution with automatic scaling.
@@ -50,6 +52,7 @@ const workspace = new Workspace({
 })
 
 const agent = new Agent({
+  id: 'dev-agent',
   name: 'dev-agent',
   model: 'anthropic/claude-sonnet-4-6',
   workspace,

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

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Workspace class
 
 **Added in:** `@mastra/core@1.1.0`

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @mastra/mcp-docs-server
 
+## 1.2.4-alpha.6
+
+### Patch Changes
+
+- Updated dependencies [[`700619b`](https://github.com/mastra-ai/mastra/commit/700619b61d572e592cbaaf758121d168844ca4d2), [`0c3d4bc`](https://github.com/mastra-ai/mastra/commit/0c3d4bcae13ea3699d379403e6f350d5cf4efe9f), [`17369b2`](https://github.com/mastra-ai/mastra/commit/17369b25250561e9ed994ae509be1d15bfb33bcb), [`bcae929`](https://github.com/mastra-ai/mastra/commit/bcae929945cbf265bd9f327cc715ecafa072b5b9), [`b33822e`](https://github.com/mastra-ai/mastra/commit/b33822e8d470884954b02f7b0745407ee4ef74b1), [`d5c11e3`](https://github.com/mastra-ai/mastra/commit/d5c11e3ba5045969caa7272a7bd1fd141c93ab6c), [`ff80671`](https://github.com/mastra-ai/mastra/commit/ff8067185e208b27198b4e5b71803013175c3643), [`dab1257`](https://github.com/mastra-ai/mastra/commit/dab1257b64e4ed576dc5038bb7a3f7072338bc9f), [`df25635`](https://github.com/mastra-ai/mastra/commit/df25635b954e63b5dbf8f1636af953b95c631809), [`705ff39`](https://github.com/mastra-ai/mastra/commit/705ff3969e57214ff2fdaf3815d751dd558886ed), [`e6fbd5b`](https://github.com/mastra-ai/mastra/commit/e6fbd5bfdc28e92c0c0433f29aa1bc152d3430f6), [`6f2026c`](https://github.com/mastra-ai/mastra/commit/6f2026cdf114ff1e21e49133ca774ec7d5085059), [`f890eda`](https://github.com/mastra-ai/mastra/commit/f890eda2c8a2ae83d9b30bc6d85842f93b6c266b)]:
+  - @mastra/core@1.49.0-alpha.3
+  - @mastra/mcp@1.13.0-alpha.1
+
+## 1.2.4-alpha.4
+
+### Patch Changes
+
+- Updated dependencies [[`1340fb7`](https://github.com/mastra-ai/mastra/commit/1340fb76262a3ca062130aa71859f07257a0a5a4)]:
+  - @mastra/core@1.49.0-alpha.2
+
+## 1.2.4-alpha.2
+
+### Patch Changes
+
+- Updated dependencies [[`cc440a3`](https://github.com/mastra-ai/mastra/commit/cc440a39400d8ce06655462b26c1666a1b3d4320), [`ea6327b`](https://github.com/mastra-ai/mastra/commit/ea6327ba2d63ca647804bc97b347e03a58617162), [`3439fa8`](https://github.com/mastra-ai/mastra/commit/3439fa836ecfcaa257b40c20b30ac2a8be22e9ea), [`85107f2`](https://github.com/mastra-ai/mastra/commit/85107f2758b527147fccbedff962961927c2d3b8), [`06ff9e0`](https://github.com/mastra-ai/mastra/commit/06ff9e0befd1d642ab87ff749285ee4091205c7e), [`7f5e1ff`](https://github.com/mastra-ai/mastra/commit/7f5e1ff695a92f672bb3976363925d1e9136b54a), [`b8375c1`](https://github.com/mastra-ai/mastra/commit/b8375c1f8fe905df8ae2ae9a893bb365f17aec4e), [`9ab5faa`](https://github.com/mastra-ai/mastra/commit/9ab5faaff673ee9953ab4604cec217ee57875cd5), [`003f35d`](https://github.com/mastra-ai/mastra/commit/003f35d19e07b23b4bacc591c8bc0c59b42124ae)]:
+  - @mastra/core@1.49.0-alpha.1
+  - @mastra/mcp@1.13.0-alpha.0
+
 ## 1.2.4-alpha.0
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.2.4-alpha.1",
+  "version": "1.2.4-alpha.6",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -28,8 +28,8 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.4.3",
-    "@mastra/core": "1.48.1-alpha.0",
-    "@mastra/mcp": "^1.12.1"
+    "@mastra/core": "1.49.0-alpha.3",
+    "@mastra/mcp": "^1.13.0-alpha.1"
   },
   "devDependencies": {
     "@hono/node-server": "^1.19.11",
@@ -47,7 +47,7 @@
     "vitest": "4.1.8",
     "@internal/lint": "0.0.110",
     "@internal/types-builder": "0.0.85",
-    "@mastra/core": "1.48.1-alpha.0"
+    "@mastra/core": "1.49.0-alpha.3"
   },
   "homepage": "https://mastra.ai",
   "repository": {