@mastra/mcp-docs-server 1.1.40-alpha.16 → 1.1.40-alpha.17

package/.docs/docs/agents/signals.md

@@ -204,9 +204,30 @@ await subscription.processDataStream({
   onChunk: chunk => {
     console.log(chunk)
   },
+  reconnect: true,
 })
 ```
 
+Use `reconnect: true` for long-lived subscriptions. The client resubscribes when the stream closes or a reconnect request fails, such as after a proxy idle timeout or a dropped network connection.
+
+## Keep custom SSE subscriptions alive
+
+If you expose your own Server-Sent Events (SSE) endpoint for thread subscriptions, send periodic heartbeat frames while the stream is idle. This keeps browsers, proxies, and load balancers from closing the connection before the next signal or model chunk arrives.
+
+The following example sends an SSE comment every 25 seconds:
+
+```typescript
+const heartbeat = setInterval(() => {
+  controller.enqueue(encoder.encode(': keep-alive\n\n'))
+}, 25_000)
+
+request.signal.addEventListener('abort', () => {
+  clearInterval(heartbeat)
+})
+```
+
+Use heartbeats together with client-side reconnect logic. Heartbeats reduce idle disconnects, while reconnects recover when the network or runtime still closes the stream.
+
 ## Related
 
 - [`Agent.sendSignal()`](https://mastra.ai/reference/agents/agent)

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

@@ -23,6 +23,7 @@ Available providers:
 - [`GCSFilesystem`](https://mastra.ai/reference/workspace/gcs-filesystem): Stores files in Google Cloud Storage
 - [`GoogleDriveFilesystem`](https://mastra.ai/reference/workspace/google-drive-filesystem): Stores files inside a Google Drive folder
 - [`AzureBlobFilesystem`](https://mastra.ai/reference/workspace/azure-blob-filesystem): Stores files in Azure Blob Storage
+- [`FilesSDKFilesystem`](https://mastra.ai/reference/workspace/files-sdk-filesystem): Stores files in any [FilesSDK](https://files-sdk.dev) adapter (S3, R2, GCS, Azure Blob, Vercel Blob, local filesystem, and more) — useful when you want one provider that can target multiple backends
 - [`AgentFSFilesystem`](https://mastra.ai/reference/workspace/agentfs-filesystem): Stores files in a Turso/SQLite database via AgentFS
 
 > **Tip:** `LocalFilesystem` is the simplest way to get started as it requires no external services. For cloud storage, use `S3Filesystem`, `GCSFilesystem`, or `AzureBlobFilesystem`. For database-backed storage without external services, use `AgentFSFilesystem`.
@@ -223,6 +224,7 @@ When you configure a filesystem on a workspace, agents receive tools for reading
 - [GCSFilesystem reference](https://mastra.ai/reference/workspace/gcs-filesystem)
 - [GoogleDriveFilesystem reference](https://mastra.ai/reference/workspace/google-drive-filesystem)
 - [AzureBlobFilesystem reference](https://mastra.ai/reference/workspace/azure-blob-filesystem)
+- [FilesSDKFilesystem reference](https://mastra.ai/reference/workspace/files-sdk-filesystem)
 - [AgentFSFilesystem reference](https://mastra.ai/reference/workspace/agentfs-filesystem)
 - [Workspace overview](https://mastra.ai/docs/workspace/overview)
 - [Sandbox](https://mastra.ai/docs/workspace/sandbox)

package/.docs/reference/client-js/agents.md

@@ -228,18 +228,21 @@ const subscription = await agent.subscribeToThread({
 })
 
 await subscription.processDataStream({
-  onChunk: async chunk => {
+  onChunk: chunk => {
     console.log(chunk)
   },
+  reconnect: true,
 })
 ```
 
-`subscribeToThread()` returns the underlying `Response` plus a `processDataStream()` helper. The helper reads the subscription stream until the connection closes or the request is aborted.
+`subscribeToThread()` returns the underlying `Response` plus a `processDataStream()` helper. The helper reads the subscription stream until the connection closes or the request is aborted. Pass `reconnect: true` to resubscribe when the transport closes or a reconnect request fails, such as after a proxy idle timeout.
 
 **resourceId** (`string`): Resource ID for the memory thread.
 
 **threadId** (`string`): Thread ID to subscribe to.
 
+**processDataStream().reconnect** (`boolean | { maxRetries?: number; delayMs?: number }`): Reconnects the subscription stream after it closes or a reconnect request fails. \`true\` retries indefinitely with a one-second delay.
+
 ### `streamUntilIdle()`
 
 Stream a response and keep the stream open until every [background task](https://mastra.ai/docs/agents/background-tasks) dispatched during the run completes. The server re-enters the agentic loop on each task completion so the LLM can react to results in the same call. Requires background tasks to be [enabled on the Mastra instance](https://mastra.ai/reference/configuration) and a memory thread; otherwise the call falls through to a plain `stream()`.

package/.docs/reference/index.md

@@ -309,6 +309,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [DaytonaSandbox](https://mastra.ai/reference/workspace/daytona-sandbox)
 - [DockerSandbox](https://mastra.ai/reference/workspace/docker-sandbox)
 - [E2BSandbox](https://mastra.ai/reference/workspace/e2b-sandbox)
+- [FilesSDKFilesystem](https://mastra.ai/reference/workspace/files-sdk-filesystem)
 - [GCSFilesystem](https://mastra.ai/reference/workspace/gcs-filesystem)
 - [GoogleDriveFilesystem](https://mastra.ai/reference/workspace/google-drive-filesystem)
 - [LocalFilesystem](https://mastra.ai/reference/workspace/local-filesystem)

package/.docs/reference/workspace/files-sdk-filesystem.md

@@ -0,0 +1,187 @@
+# FilesSDKFilesystem
+
+Stores files in any storage backend supported by [FilesSDK](https://files-sdk.dev) — a unified abstraction over S3, Cloudflare R2, Google Cloud Storage, Azure Blob, Vercel Blob, MinIO, the local filesystem, and more.
+
+> **Info:** For interface details, see [WorkspaceFilesystem Interface](https://mastra.ai/reference/workspace/filesystem).
+
+Use `FilesSDKFilesystem` when you want a single adapter that can target multiple storage backends with the same code. Swap the underlying driver without changing the workspace setup. If you only target one backend and want first-class options for that backend, prefer the dedicated provider (for example [`S3Filesystem`](https://mastra.ai/reference/workspace/s3-filesystem) or [`GCSFilesystem`](https://mastra.ai/reference/workspace/gcs-filesystem)).
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/files-sdk files-sdk
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/files-sdk files-sdk
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/files-sdk files-sdk
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/files-sdk files-sdk
+```
+
+`files-sdk` is a peer dependency you configure with the adapter you want to use.
+
+## Usage
+
+Create a `Files` instance from FilesSDK with the adapter of your choice, then pass it to `FilesSDKFilesystem`:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Workspace } from '@mastra/core/workspace'
+import { FilesSDKFilesystem } from '@mastra/files-sdk'
+import { Files } from 'files-sdk'
+import { s3 } from 'files-sdk/s3'
+
+const files = new Files({
+  adapter: s3({
+    bucket: 'my-bucket',
+    region: 'us-east-1',
+  }),
+})
+
+const workspace = new Workspace({
+  filesystem: new FilesSDKFilesystem({ files }),
+})
+
+const agent = new Agent({
+  name: 'file-agent',
+  model: 'anthropic/claude-opus-4-6',
+  workspace,
+})
+```
+
+### Swapping adapters
+
+The same `FilesSDKFilesystem` works with any FilesSDK adapter. Replace the driver factory to switch backends:
+
+```typescript
+import { Files } from 'files-sdk'
+import { r2 } from 'files-sdk/r2'
+import { gcs } from 'files-sdk/gcs'
+import { azure } from 'files-sdk/azure'
+import { fs } from 'files-sdk/fs'
+
+// Cloudflare R2
+const r2Files = new Files({ adapter: r2({ accountId, bucket, accessKeyId, secretAccessKey }) })
+
+// Google Cloud Storage
+const gcsFiles = new Files({ adapter: gcs({ bucket, projectId }) })
+
+// Azure Blob
+const azureFiles = new Files({ adapter: azure({ container, connectionString }) })
+
+// Local filesystem (useful for tests and development)
+const localFiles = new Files({ adapter: fs({ root: './workspace' }) })
+```
+
+See the [FilesSDK documentation](https://files-sdk.dev) for the full adapter catalog and configuration options.
+
+### Read-only mounts
+
+```typescript
+const filesystem = new FilesSDKFilesystem({
+  files,
+  readOnly: true,
+})
+```
+
+All write operations (`writeFile`, `appendFile`, `deleteFile`, `copyFile`, `moveFile`, `mkdir`, `rmdir`) throw `WorkspaceReadOnlyError` while reads succeed.
+
+## Constructor parameters
+
+**files** (`Files`): A pre-configured FilesSDK \`Files\` instance bound to the adapter and credentials you want to use.
+
+**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`)
+
+## Properties
+
+**id** (`string`): Filesystem instance identifier.
+
+**name** (`string`): Provider name ('FilesSDKFilesystem').
+
+**provider** (`string`): Provider identifier ('files-sdk').
+
+**readOnly** (`boolean | undefined`): Whether the filesystem is in read-only mode.
+
+## Methods
+
+`FilesSDKFilesystem` 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 (no-op for object stores)
+- `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 that the configured adapter can list keys with the supplied credentials.
+
+```typescript
+await filesystem.init()
+```
+
+### `getInfo()`
+
+Returns metadata about this filesystem instance.
+
+```typescript
+const info = filesystem.getInfo()
+// { id: '...', name: 'FilesSDKFilesystem', provider: 'files-sdk', status: 'ready' }
+```
+
+### `files`
+
+The underlying FilesSDK `Files` instance is exposed as a public property if you need to call adapter-specific APIs directly.
+
+```typescript
+const url = await filesystem.files.url('reports/q3.pdf')
+```
+
+## Object-store semantics
+
+`FilesSDKFilesystem` treats the configured backend as an object store, even when the underlying adapter is hierarchical (such as `fs`). This keeps behavior consistent across adapters:
+
+- **`mkdir`** is a no-op. Directories exist implicitly when keys with that prefix exist.
+- **`exists`** returns `true` only when an exact key is present as a file, or when the path is a prefix that contains at least one child key. Empty leftover directories on hierarchical adapters do not count.
+- **`deleteFile`** throws `FileNotFoundError` when the key does not exist, unless `{ force: true }` is passed.
+- **`deleteFile`** on a directory delegates to `rmdir({ recursive: true })`, matching the [`S3Filesystem`](https://mastra.ai/reference/workspace/s3-filesystem) and [`GCSFilesystem`](https://mastra.ai/reference/workspace/gcs-filesystem) behavior.
+- **`moveFile`** is implemented as `copyFile` followed by `deleteFile`. It is **not atomic** — if the source delete fails after a successful copy, the destination remains and the source is not removed.
+- **`appendFile`** is a read-modify-write operation. Concurrent appends to the same key may overwrite each other; this is inherent to object storage and not specific to FilesSDK.
+- **`readdir({ recursive: true })`** emits intermediate directory entries (for example, `a/b` is emitted alongside `a/b/c.txt`).
+
+## Related
+
+- [WorkspaceFilesystem interface](https://mastra.ai/reference/workspace/filesystem)
+- [S3Filesystem reference](https://mastra.ai/reference/workspace/s3-filesystem)
+- [GCSFilesystem reference](https://mastra.ai/reference/workspace/gcs-filesystem)
+- [AzureBlobFilesystem reference](https://mastra.ai/reference/workspace/azure-blob-filesystem)
+- [Workspace overview](https://mastra.ai/docs/workspace/overview)
+- [FilesSDK documentation](https://files-sdk.dev)

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @mastra/mcp-docs-server
 
+## 1.1.40-alpha.17
+
+### Patch Changes
+
+- Updated dependencies [[`9d2c663`](https://github.com/mastra-ai/mastra/commit/9d2c663b88f5b12bc3fea1c97f40b4eeb3665df1), [`c35b962`](https://github.com/mastra-ai/mastra/commit/c35b9625c7e854fcfdeee226a3338a750d0ff211), [`4084113`](https://github.com/mastra-ai/mastra/commit/408411370fc48a822e8b616b3b63f9409774e0e9)]:
+  - @mastra/mcp@1.8.1-alpha.0
+  - @mastra/core@1.37.0-alpha.8
+
 ## 1.1.40-alpha.15
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.1.40-alpha.16",
+  "version": "1.1.40-alpha.17",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -28,9 +28,9 @@
     "@modelcontextprotocol/sdk": "^1.27.1",
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
-    "zod": "^4.3.6",
-    "@mastra/mcp": "^1.8.0",
-    "@mastra/core": "1.37.0-alpha.7"
+    "zod": "^4.4.3",
+    "@mastra/core": "1.37.0-alpha.8",
+    "@mastra/mcp": "^1.8.1-alpha.0"
   },
   "devDependencies": {
     "@hono/node-server": "^1.19.11",
@@ -46,9 +46,9 @@
     "tsx": "^4.21.0",
     "typescript": "^6.0.3",
     "vitest": "4.1.5",
+    "@mastra/core": "1.37.0-alpha.8",
     "@internal/lint": "0.0.97",
-    "@internal/types-builder": "0.0.72",
-    "@mastra/core": "1.37.0-alpha.7"
+    "@internal/types-builder": "0.0.72"
   },
   "homepage": "https://mastra.ai",
   "repository": {