@mastra/mcp-docs-server 1.1.32-alpha.0 → 1.1.32-alpha.2

package/.docs/docs/agents/processors.md

@@ -367,6 +367,14 @@ See the [`TokenLimiterProcessor` reference](https://mastra.ai/reference/processo
 
 Removes tool calls and results from messages sent to the LLM, saving tokens on verbose tool interactions. Optionally exclude only specific tools. This filter only affects the LLM input, filtered messages are still saved to memory.
 
+By default, `ToolCallFilter` filters the initial input before the agent loop starts. Use `filterAfterToolSteps` to also filter during each loop step while preserving recent tool-producing steps.
+
+```typescript
+new ToolCallFilter({
+  filterAfterToolSteps: 2,
+})
+```
+
 See the [`ToolCallFilter` reference](https://mastra.ai/reference/processors/tool-call-filter) for configuration options and the [Memory Processors](https://mastra.ai/docs/memory/memory-processors) page for pre-memory filtering.
 
 ### `ToolSearchProcessor`

package/.docs/docs/agents/supervisor-agents.md

@@ -167,6 +167,22 @@ const stream = await supervisor.stream('Research AI trends', {
 
 The callback receives `messages` (the full conversation history), `primitiveId` (the subagent ID), and `prompt` (the delegation prompt). Return the filtered array of messages.
 
+## Subagent result context
+
+When a subagent completes, the supervisor model receives the subagent's text response in later iterations. Nested tool calls and subagent metadata, such as thread and resource IDs, are not added to the supervisor model context.
+
+Application code and UI integrations can still inspect the raw delegation result, including `subAgentToolResults`, from the tool result payload. This keeps debugging and display data available without sending nested tool arguments or outputs back into the supervisor's next model call.
+
+Set `includeSubAgentToolResultsInModelContext` to include the full subagent result, including nested tool results and subagent metadata, in the supervisor model context.
+
+```typescript
+await supervisor.generate('Research AI trends', {
+  delegation: {
+    includeSubAgentToolResultsInModelContext: true,
+  },
+})
+```
+
 ## Iteration monitoring
 
 `onIterationComplete` is called after each iteration of the supervisor loop. Use it to log progress, inject feedback, or stop execution early.

package/.docs/docs/observability/tracing/overview.md

@@ -341,6 +341,28 @@ execute: async (inputData, context) => {
 
 Metadata set here will be shown in all configured exporters.
 
+### Tagging traces with the deployment environment
+
+Set the top-level `environment` field on Mastra to automatically attach the deployment environment to all observability signals without passing `tracingOptions.metadata.environment` on each call.
+
+```ts
+export const mastra = new Mastra({
+  environment: 'production',
+  observability: new Observability({
+    configs: {
+      default: {
+        serviceName: 'my-service',
+        exporters: [new DefaultExporter()],
+      },
+    },
+  }),
+})
+```
+
+If `environment` is not set, Mastra falls back to `process.env.NODE_ENV`. If neither is set, the field is left undefined rather than guessed.
+
+Per-call `tracingOptions.metadata.environment` always takes precedence, so individual calls can still override the value when needed.
+
 ### Automatic Metadata from `RequestContext`
 
 Instead of manually adding metadata to each span, you can configure Mastra to automatically extract values from RequestContext and attach them as metadata to all spans in a trace. This is useful for consistently tracking user identifiers, environment information, feature flags, or any request-scoped data across your entire trace.

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

@@ -21,6 +21,7 @@ Available providers:
 - [`LocalFilesystem`](https://mastra.ai/reference/workspace/local-filesystem): Stores files in a directory on disk
 - [`S3Filesystem`](https://mastra.ai/reference/workspace/s3-filesystem): Stores files in Amazon S3 or S3-compatible storage (R2, MinIO, Tigris)
 - [`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
 - [`AgentFSFilesystem`](https://mastra.ai/reference/workspace/agentfs-filesystem): Stores files in a Turso/SQLite database via AgentFS
 
@@ -220,6 +221,7 @@ When you configure a filesystem on a workspace, agents receive tools for reading
 - [LocalFilesystem reference](https://mastra.ai/reference/workspace/local-filesystem)
 - [S3Filesystem reference](https://mastra.ai/reference/workspace/s3-filesystem)
 - [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)
 - [AgentFSFilesystem reference](https://mastra.ai/reference/workspace/agentfs-filesystem)
 - [Workspace overview](https://mastra.ai/docs/workspace/overview)

package/.docs/models/gateways/azure-openai.md

@@ -92,6 +92,41 @@ export const mastra = new Mastra({
 
 The Service Principal requires "Cognitive Services User" role. See [Azure documentation](https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal).
 
+### Microsoft Entra ID authentication
+
+Use Microsoft Entra ID authentication when API keys are disabled for your Azure OpenAI resource. Pass any Azure SDK-compatible credential, such as `DefaultAzureCredential` from `@azure/identity`.
+
+Install `@azure/identity` in your Mastra project if you use `DefaultAzureCredential`.
+
+```typescript
+import { DefaultAzureCredential } from "@azure/identity";
+import { Mastra } from "@mastra/core";
+import { AzureOpenAIGateway } from "@mastra/core/llm";
+
+export const mastra = new Mastra({
+  gateways: [
+    new AzureOpenAIGateway({
+      resourceName: "my-openai-resource",
+      authentication: {
+        type: "entraId",
+        credential: new DefaultAzureCredential(),
+      },
+      deployments: ["gpt-4-prod", "gpt-35-turbo-dev"],
+    }),
+  ],
+});
+```
+
+The identity needs permission to call Azure OpenAI, such as the `Cognitive Services OpenAI User` role.
+
+For a specific managed identity, pass `ManagedIdentityCredential` instead.
+
+```typescript
+import { ManagedIdentityCredential } from "@azure/identity";
+
+const credential = new ManagedIdentityCredential("client-id");
+```
+
 ### Manual Deployment Names
 
 Provide resource name and API key only. Specify deployment names when creating agents. No IDE autocomplete.
@@ -112,17 +147,21 @@ export const mastra = new Mastra({
 
 ## Configuration Reference
 
-| Option                      | Type       | Required | Description                                 |
-| --------------------------- | ---------- | -------- | ------------------------------------------- |
-| `resourceName`              | `string`   | Yes      | Azure OpenAI resource name                  |
-| `apiKey`                    | `string`   | Yes      | API key from "Keys and Endpoint"            |
-| `apiVersion`                | `string`   | No       | API version (default: `2024-04-01-preview`) |
-| `deployments`               | `string[]` | No       | Deployment names for static mode            |
-| `management`                | `object`   | No       | Management API credentials                  |
-| `management.tenantId`       | `string`   | Yes\*    | Azure AD tenant ID                          |
-| `management.clientId`       | `string`   | Yes\*    | Service Principal client ID                 |
-| `management.clientSecret`   | `string`   | Yes\*    | Service Principal secret                    |
-| `management.subscriptionId` | `string`   | Yes\*    | Azure subscription ID                       |
-| `management.resourceGroup`  | `string`   | Yes\*    | Resource group name                         |
-
-\* Required if `management` is provided
+| Option                      | Type              | Required | Description                                                           |
+| --------------------------- | ----------------- | -------- | --------------------------------------------------------------------- |
+| `resourceName`              | `string`          | Yes      | Azure OpenAI resource name                                            |
+| `apiKey`                    | `string`          | Yes\*    | API key from "Keys and Endpoint"                                      |
+| `authentication`            | `object`          | No       | Microsoft Entra ID authentication                                     |
+| `authentication.type`       | `"entraId"`       | Yes\*    | Authentication mode                                                   |
+| `authentication.credential` | `TokenCredential` | Yes\*    | Azure SDK-compatible credential for `entraId` authentication mode     |
+| `authentication.scope`      | `string`          | No       | Token scope (default: `https://cognitiveservices.azure.com/.default`) |
+| `apiVersion`                | `string`          | No       | API version (default: `2024-04-01-preview`)                           |
+| `deployments`               | `string[]`        | No       | Deployment names for static mode                                      |
+| `management`                | `object`          | No       | Management API credentials                                            |
+| `management.tenantId`       | `string`          | Yes\*    | Azure AD tenant ID                                                    |
+| `management.clientId`       | `string`          | Yes\*    | Service Principal client ID                                           |
+| `management.clientSecret`   | `string`          | Yes\*    | Service Principal secret                                              |
+| `management.subscriptionId` | `string`          | Yes\*    | Azure subscription ID                                                 |
+| `management.resourceGroup`  | `string`          | Yes\*    | Resource group name                                                   |
+
+\* Provide either `apiKey` or `authentication.type: "entraId"`. Management fields are required if `management` is provided.

package/.docs/models/index.md

@@ -1,6 +1,6 @@
 # Model Providers
 
-Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 3778 models from 106 providers through a single API.
+Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 3779 models from 106 providers through a single API.
 
 ## Features
 

package/.docs/models/providers/berget.md

@@ -1,6 +1,6 @@
 # ![Berget.AI logo](https://models.dev/logos/berget.svg)Berget.AI
 
-Access 5 Berget.AI models through Mastra's model router. Authentication is handled automatically using the `BERGET_API_KEY` environment variable.
+Access 6 Berget.AI models through Mastra's model router. Authentication is handled automatically using the `BERGET_API_KEY` environment variable.
 
 Learn more in the [Berget.AI documentation](https://api.berget.ai).
 
@@ -36,6 +36,7 @@ for await (const chunk of stream) {
 | ------------------------------------------------------ | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
 | `berget/google/gemma-4-31B-it`                         | 128K    |       |           |       |       |       | $0.28      | $0.55       |
 | `berget/meta-llama/Llama-3.3-70B-Instruct`             | 128K    |       |           |       |       |       | $0.99      | $0.99       |
+| `berget/mistralai/Mistral-Medium-3.5-128B`             | 262K    |       |           |       |       |       | $2         | $6          |
 | `berget/mistralai/Mistral-Small-3.2-24B-Instruct-2506` | 32K     |       |           |       |       |       | $0.33      | $0.33       |
 | `berget/openai/gpt-oss-120b`                           | 128K    |       |           |       |       |       | $0.44      | $0.99       |
 | `berget/zai-org/GLM-4.7`                               | 128K    |       |           |       |       |       | $0.77      | $3          |

package/.docs/models/providers/cortecs.md

@@ -62,7 +62,7 @@ for await (const chunk of stream) {
 | `cortecs/minimax-m2`                     | 400K    |       |           |       |       |       | $0.39      | $2          |
 | `cortecs/minimax-m2.1`                   | 196K    |       |           |       |       |       | $0.34      | $1          |
 | `cortecs/minimax-m2.5`                   | 197K    |       |           |       |       |       | $0.32      | $1          |
-| `cortecs/minimax-M2.7`                   | 203K    |       |           |       |       |       | $0.47      | $1          |
+| `cortecs/minimax-m2.7`                   | 203K    |       |           |       |       |       | $0.47      | $1          |
 | `cortecs/nova-pro-v1`                    | 300K    |       |           |       |       |       | $1         | $4          |
 | `cortecs/qwen3-32b`                      | 16K     |       |           |       |       |       | $0.10      | $0.33       |
 | `cortecs/qwen3-coder-480b-a35b-instruct` | 262K    |       |           |       |       |       | $0.44      | $2          |

package/.docs/reference/core/mastra-class.md

@@ -49,6 +49,8 @@ Visit the [Configuration reference](https://mastra.ai/reference/configuration) f
 
 **observability** (`ObservabilityEntrypoint`): Observability configuration for tracing and monitoring
 
+**environment** (`string`): Deployment environment name (e.g. \`production\`, \`staging\`, \`development\`). When set, automatically attached to all observability signals so they can be filtered by environment without passing \`tracingOptions.metadata.environment\` on each call. Falls back to \`process.env.NODE\_ENV\` when unset; left undefined if neither is set. Per-call \`tracingOptions.metadata.environment\` always takes precedence.
+
 **deployer** (`MastraDeployer`): An instance of a MastraDeployer for managing deployments.
 
 **server** (`ServerConfig`): Server configuration including port, host, timeout, API routes, middleware, CORS settings, and build options for Swagger UI, API request logging, and OpenAPI docs.

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

@@ -152,6 +152,14 @@ Return a read-only snapshot of the current harness state.
 const state = harness.getState()
 ```
 
+#### `getDisplayState()`
+
+Return the current `HarnessDisplayState` snapshot for UI rendering.
+
+```typescript
+const displayState = harness.getDisplayState()
+```
+
 #### `setState(updates)`
 
 Update the harness state. Validates against `stateSchema` if provided, and emits a `state_changed` event with the new state and changed keys.
@@ -722,10 +730,35 @@ Forked mode trades isolation for context inheritance. If the subagent should run
 
 ### Events
 
+#### `subscribeDisplayState(listener, options?)`
+
+Register a listener for coalesced display state snapshots. Use this method for UI, Server-Sent Events (SSE), terminal UI (TUI), and bridge rendering paths that only need the latest `HarnessDisplayState`. Use [`subscribe`](#subscribelistener) when you need the raw event log.
+
+```typescript
+const unsubscribe = harness.subscribeDisplayState(displayState => {
+  render(displayState)
+})
+
+// Optional tuning:
+harness.subscribeDisplayState(render, {
+  windowMs: 250,
+  maxWaitMs: 500,
+})
+
+// Later:
+unsubscribe()
+```
+
+Returns: `() => void`
+
+`subscribeDisplayState()` does not call the listener immediately. Call [`getDisplayState`](#getdisplaystate) first if the UI needs an initial render before the next harness event.
+
 #### `subscribe(listener)`
 
 Register an event listener. Returns an unsubscribe function.
 
+Use this method for audit logs, debugging, analytics, deterministic replay, or consumers that need every raw event. For display rendering, prefer [`subscribeDisplayState`](#subscribedisplaystatelistener-options) so high-frequency events such as `message_update`, `tool_update`, and `tool_input_delta` are coalesced into the latest display state snapshot.
+
 ```typescript
 const unsubscribe = harness.subscribe(event => {
   switch (event.type) {

package/.docs/reference/index.md

@@ -296,6 +296,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [DockerSandbox](https://mastra.ai/reference/workspace/docker-sandbox)
 - [E2BSandbox](https://mastra.ai/reference/workspace/e2b-sandbox)
 - [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)
 - [LocalSandbox](https://mastra.ai/reference/workspace/local-sandbox)
 - [ModalSandbox](https://mastra.ai/reference/workspace/modal-sandbox)

package/.docs/reference/processors/skill-search-processor.md

@@ -2,6 +2,15 @@
 
 The `SkillSearchProcessor` is an **input processor** that enables on-demand skill discovery and loading. Instead of injecting all skill metadata into the system prompt upfront (like `SkillsProcessor`), it gives the agent two meta-tools (`search_skills` and `load_skill`) that let it find and load skills on demand. This reduces context token usage when workspaces have many skills.
 
+By default, when you attach only `SkillSearchProcessor` to an agent with a skill-enabled `Workspace`, the agent treats skills as on-demand:
+
+- The default eager `SkillsProcessor` is not auto-added.
+- `search_skills` and `load_skill` are exposed for discovery and instruction loading.
+- Overlapping `skill` and `skill_search` tools are hidden.
+- `skill_read` remains available so the agent can read supporting skill files such as references, scripts, and assets.
+
+If you explicitly configure `SkillsProcessor` alongside `SkillSearchProcessor`, the agent preserves the eager `skill` and `skill_search` tools as an opt-in path.
+
 ## Usage example
 
 ```typescript
@@ -36,6 +45,8 @@ const skillSearch = new SkillSearchProcessor({
 
 **name** (`string`): Processor display name set to 'Skill Search Processor'
 
+**providesSkillDiscovery** (`'on-demand'`): Signals to the agent that this processor owns skill discovery and instruction loading.
+
 **processInputStep** (`(args: ProcessInputStepArgs) => Promise<ProcessInputStepResult>`): Processes each step to inject search/load meta-tools and any previously loaded skill instructions as system messages.
 
 ## Extended usage example
@@ -77,6 +88,14 @@ The agent workflow is:
 4. The skill's instructions appear as system messages on the next turn
 5. Agent follows the loaded skill's instructions
 
+## Workspace file tools
+
+`SkillSearchProcessor` loads skill instructions into the conversation. It does not block workspace file tools from reading files.
+
+Use `skill_read` for supporting files that belong to a loaded skill, such as files under `references/`, `scripts/`, or `assets/`.
+
+Reserve workspace file tools such as `mastra_workspace_read_file` for explicit file inspection or editing workflows. During normal task execution, the agent does not need to read the same `SKILL.md` file after `load_skill` succeeds.
+
 ## Compared to SkillsProcessor
 
 |                | SkillsProcessor            | SkillSearchProcessor               |

package/.docs/reference/processors/tool-call-filter.md

@@ -14,6 +14,11 @@ const filterAll = new ToolCallFilter()
 const filterSpecific = new ToolCallFilter({
   exclude: ['searchDatabase', 'sendEmail'],
 })
+
+// Enable filtering during agent loops and keep the two most recent tool-producing steps
+const filterAfterRecentTools = new ToolCallFilter({
+  filterAfterToolSteps: 2,
+})
 ```
 
 ## Constructor parameters
@@ -22,6 +27,8 @@ const filterSpecific = new ToolCallFilter({
 
 **options.exclude** (`string[]`): List of specific tool names to exclude. If not provided or undefined, all tool calls are excluded
 
+**options.filterAfterToolSteps** (`number`): Enables filtering during agent loops and preserves tool calls and results from this many recent tool-producing steps. If undefined, step filtering is disabled
+
 ## Returns
 
 **id** (`string`): Processor identifier set to 'tool-call-filter'
@@ -30,6 +37,22 @@ const filterSpecific = new ToolCallFilter({
 
 **processInput** (`(args: { messages: MastraDBMessage[]; messageList: MessageList; abort: (reason?: string) => never; requestContext?: RequestContext }) => Promise<MessageList | MastraDBMessage[]>`): Processes input messages to filter out tool calls and their results based on configuration
 
+**processInputStep** (`(args: ProcessInputStepArgs) => Promise<ProcessInputStepResult>`): Processes agent loop step input when filterAfterToolSteps is configured. Returns no changes when step filtering is disabled
+
+## Step filtering
+
+By default, `ToolCallFilter` filters only the initial input before the agent loop starts. Set `filterAfterToolSteps` to also filter during each loop step.
+
+`filterAfterToolSteps` counts tool-producing steps. For example, `filterAfterToolSteps: 2` keeps tool calls and results from the two most recent tool-producing steps and filters older tool calls and results. Non-tool text remains in context.
+
+Set `filterAfterToolSteps: 0` to filter all previous tool calls and results on each step.
+
+```typescript
+const filter = new ToolCallFilter({
+  filterAfterToolSteps: 2,
+})
+```
+
 ## Extended usage example
 
 ```typescript

package/.docs/reference/storage/clickhouse.md

@@ -101,7 +101,27 @@ New projects should use `ObservabilityStorageClickhouseVNext` instead.
 
 ### ClickHouse for every domain
 
-`ClickhouseStore` implements the `memory`, `workflows`, and `observability` domains, and is suitable when you want ClickHouse to back the entire application. Its built-in observability domain uses the legacy adapter, so wrap it in a composite store that overrides the `observability` domain with `ObservabilityStorageClickhouseVNext`:
+`ClickhouseStoreVNext` backs the `memory`, `workflows`, and `observability` domains with ClickHouse and uses the vNext observability adapter automatically. Use it when you want ClickHouse to back the entire application without wiring a composite store manually.
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { ClickhouseStoreVNext } from '@mastra/clickhouse'
+
+export const mastra = new Mastra({
+  storage: new ClickhouseStoreVNext({
+    id: 'clickhouse-storage',
+    url: process.env.CLICKHOUSE_URL!,
+    username: process.env.CLICKHOUSE_USERNAME!,
+    password: process.env.CLICKHOUSE_PASSWORD!,
+  }),
+})
+```
+
+`ClickhouseStoreVNext` accepts the same configuration as `ClickhouseStore` and reuses the same ClickHouse client across every domain.
+
+#### Manual composition
+
+`ClickhouseStore` is the long-standing class that backs every domain with the legacy observability adapter. New projects should prefer `ClickhouseStoreVNext`. If you need to customize the composite (for example, to override one domain with a different backend), build it manually:
 
 ```typescript
 import { Mastra } from '@mastra/core'

package/.docs/reference/vectors/mongodb.md

@@ -107,8 +107,6 @@ Searches for similar vectors with optional metadata filtering.
 
 **includeVector** (`boolean`): Whether to include vector data in results (Default: `false`)
 
-**minScore** (`number`): Minimum similarity score threshold (Default: `0`)
-
 ### `describeIndex()`
 
 Returns information about the index (collection).

package/.docs/reference/workspace/google-drive-filesystem.md

@@ -0,0 +1,185 @@
+# GoogleDriveFilesystem
+
+Stores files in a single Google Drive folder. Each directory maps to a Drive folder under the configured root, and paths use POSIX semantics (for example `/notes/todo.txt`).
+
+> **Info:** For interface details, see [WorkspaceFilesystem Interface](https://mastra.ai/reference/workspace/filesystem).
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/google-drive
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/google-drive
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/google-drive
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/google-drive
+```
+
+## Usage
+
+Add a `GoogleDriveFilesystem` to a workspace and assign it to an agent:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Workspace } from '@mastra/core/workspace'
+import { GoogleDriveFilesystem } from '@mastra/google-drive'
+
+const workspace = new Workspace({
+  filesystem: new GoogleDriveFilesystem({
+    folderId: process.env.GOOGLE_DRIVE_FOLDER_ID!,
+    accessToken: process.env.GOOGLE_DRIVE_ACCESS_TOKEN!,
+  }),
+})
+
+const agent = new Agent({
+  id: 'drive-agent',
+  name: 'Drive Agent',
+  model: 'openai/gpt-4o-mini',
+  workspace,
+})
+```
+
+### Authentication
+
+Supply one of the following authentication options:
+
+- **`accessToken`**: A pre-obtained OAuth access token. Use the `https://www.googleapis.com/auth/drive` scope so the token can see folders shared with the authenticated identity.
+- **`getAccessToken`**: A callback that returns a token. Useful when tokens are refreshed externally.
+- **`serviceAccount`**: A Google service account. Share the target folder with the service account email.
+
+#### Service account
+
+Service account auth is the recommended option for backend agents. There is no user consent flow and no token refresh handling. You only need **two values** from the service account JSON key file: `client_email` and `private_key`.
+
+##### Set up the service account
+
+1. Open the [Google Cloud Console](https://console.cloud.google.com/) and select or create a project.
+2. Go to **APIs & Services > Library**, search for **Google Drive API**, and select **Enable**.
+3. Go to **APIs & Services > Credentials**, select **Create credentials > Service account**, and complete the form. The role can be left blank — Drive permissions are granted by sharing folders, not by IAM roles.
+4. Open the new service account, go to the **Keys** tab, and select **Add key > Create new key > JSON**. The browser downloads a JSON key file.
+5. Copy the `client_email` value from the JSON file. This is the address you share Drive folders with.
+
+##### Share the Drive folder with the service account
+
+The service account is its own Google identity. It cannot see anything in Drive until you share with it explicitly.
+
+1. Open the target folder in [Google Drive](https://drive.google.com/).
+2. Select **Share**.
+3. Paste the service account's `client_email` address.
+4. Set the role to **Editor** (for read and write) or **Viewer** (for read-only access). Select **Send**.
+5. Copy the folder ID from the URL. It is the segment after `/folders/` in `https://drive.google.com/drive/folders/<folderId>`.
+
+> **Warning:** Service accounts cannot create files in standard "My Drive" folders. A service account has no personal Drive storage quota, so any file it creates needs to be owned by a quota-bearing entity. If you only share a personal Drive folder, read operations work but writes fail with a quota error.
+>
+> For write access, place the folder inside a **shared drive** (formerly Team Drive) and add the service account as a member of that shared drive. Shared drives provide the storage quota that service-account-created files need.
+>
+> Read-only workloads against a personal Drive folder do not have this restriction.
+
+##### Configure the filesystem
+
+Copy `client_email` and `private_key` from the JSON file into your environment:
+
+```bash
+GOOGLE_DRIVE_FOLDER_ID=1AbCdEfGhIjKlMnOpQrStUvWxYz
+GOOGLE_DRIVE_CLIENT_EMAIL=my-bot@my-project.iam.gserviceaccount.com
+# Wrap the value in quotes — the key contains newlines that must be preserved.
+GOOGLE_DRIVE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkq...\n-----END PRIVATE KEY-----\n"
+```
+
+```typescript
+import { GoogleDriveFilesystem } from '@mastra/google-drive'
+
+const filesystem = new GoogleDriveFilesystem({
+  folderId: process.env.GOOGLE_DRIVE_FOLDER_ID!,
+  serviceAccount: {
+    clientEmail: process.env.GOOGLE_DRIVE_CLIENT_EMAIL!,
+    privateKey: process.env.GOOGLE_DRIVE_PRIVATE_KEY!,
+  },
+})
+```
+
+You do **not** need to copy the entire JSON file or pass other fields like `project_id`, `client_id`, `private_key_id`, or `token_uri`. They are not used. Only `clientEmail` and `privateKey` are required. `privateKeyId`, `scopes`, and `subject` are optional. `scopes` defaults to `['https://www.googleapis.com/auth/drive']`, which is the scope required for the service account to see folders shared with it. The narrower `drive.file` scope only grants access to files the application created itself, so a folder shared with the service account would return `404 Not Found`.
+
+`GoogleDriveFilesystem` automatically normalizes the `privateKey` string before signing. It strips surrounding quotes (including escaped quotes from JSON-wrapped values), converts literal `\n` sequences to real newlines, normalizes `\r\n` line endings, and removes a trailing comma. The key works regardless of how your `.env` loader handles the value.
+
+##### Troubleshoot
+
+- **`404 File not found: <folderId>`**: The service account does not have access to the folder. Confirm the folder is shared with the exact `client_email` address and that the folder ID matches the URL.
+- **`storageQuotaExceeded` on write**: The folder is in a personal "My Drive". Move the folder to a shared drive and add the service account as a member.
+- **`error:1E08010C:DECODER routines::unsupported`**: The `privateKey` value is malformed. Confirm the value contains the full PEM block and that newlines are preserved (literal `\n` is fine).
+
+### Read-only mode
+
+Pass `readOnly: true` to block write operations (`writeFile`, `appendFile`, `deleteFile`, `copyFile`, `moveFile`, `mkdir`, `rmdir`).
+
+```typescript
+const filesystem = new GoogleDriveFilesystem({
+  folderId,
+  accessToken,
+  readOnly: true,
+})
+```
+
+## Constructor parameters
+
+**folderId** (`string`): ID of the Google Drive folder that acts as the workspace root. All paths are resolved inside this folder.
+
+**accessToken** (`string`): OAuth access token with access to the folder.
+
+**getAccessToken** (`() => string | Promise<string>`): Callback that returns a fresh OAuth access token. Called on every request that needs authorization.
+
+**serviceAccount** (`{ clientEmail: string; privateKey: string; privateKeyId?: string; scopes?: string[]; subject?: string }`): Service account credentials used to mint access tokens via the OAuth 2.0 JWT flow.
+
+**id** (`string`): Unique identifier for this filesystem instance (Default: `` `google-drive:${folderId}` ``)
+
+**readOnly** (`boolean`): When true, all write operations are blocked. (Default: `false`)
+
+**instructions** (`InstructionsOption`): Override the default instructions returned to tool descriptions.
+
+## Properties
+
+**id** (`string`): Filesystem instance identifier
+
+**name** (`string`): Provider name ('GoogleDriveFilesystem')
+
+**provider** (`string`): Provider identifier ('google-drive')
+
+**readOnly** (`boolean | undefined`): Whether the filesystem is in read-only mode
+
+## Methods
+
+GoogleDriveFilesystem implements the [WorkspaceFilesystem interface](https://mastra.ai/reference/workspace/filesystem), providing all standard filesystem methods:
+
+- `readFile(path, options?)` - Download file contents
+- `writeFile(path, content, options?)` - Upload or overwrite a file
+- `appendFile(path, content)` - Append content by reading and re-uploading the file
+- `deleteFile(path, options?)` - Delete a file
+- `copyFile(src, dest, options?)` - Copy a file using the Drive `files.copy` API
+- `moveFile(src, dest, options?)` - Move a file between folders by swapping parents
+- `mkdir(path, options?)` - Create a folder
+- `rmdir(path, options?)` - Remove a folder
+- `readdir(path, options?)` - List folder contents (supports `recursive` and `extension` filtering)
+- `stat(path)` - Return Drive metadata for a file or folder
+- `exists(path)` - Check if a file or folder exists
+
+## Notes
+
+- Google Drive allows multiple files with the same name in a folder. `GoogleDriveFilesystem` resolves paths by picking the first match, so keep names unique within each folder when you rely on path-based lookup.
+- `writeFile` creates parent folders automatically when `recursive` is unset (the default) or `true`. Set `recursive: false` to require the parent folder to already exist.
+- `expectedMtime` on `WriteOptions` is honored — when the stored `modifiedTime` differs, the write is rejected with `StaleFileError` to support optimistic concurrency.
+- The provider only exercises Drive REST endpoints (`https://www.googleapis.com/drive/v3` and `https://www.googleapis.com/upload/drive/v3`) through the built-in `fetch`; no additional dependencies are required.

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @mastra/mcp-docs-server
 
+## 1.1.32-alpha.2
+
+### Patch Changes
+
+- Updated dependencies [[`e109607`](https://github.com/mastra-ai/mastra/commit/e10960749251e34d46b480a20648c490fd30381b)]:
+  - @mastra/core@1.31.0-alpha.1
+
+## 1.1.32-alpha.1
+
+### Patch Changes
+
+- Updated dependencies [[`1723e09`](https://github.com/mastra-ai/mastra/commit/1723e099829892419ddbfe49287acfeac2522724), [`629f9e9`](https://github.com/mastra-ai/mastra/commit/629f9e9a7e56aa8f129515a3923c5813298790c7), [`25168fb`](https://github.com/mastra-ai/mastra/commit/25168fb9c1de9db7f8171df4f58ceb842c53aa29), [`ab34b5a`](https://github.com/mastra-ai/mastra/commit/ab34b5a2191b8e4353df1dbf7b9155e7d6628d79), [`5fb6c2a`](https://github.com/mastra-ai/mastra/commit/5fb6c2a95c1843cc231704b91354311fc1f34a71), [`394f0cf`](https://github.com/mastra-ai/mastra/commit/394f0cfc31e6b4d801219fdef2e9cc69e5bc8682), [`3d7f709`](https://github.com/mastra-ai/mastra/commit/3d7f709b615e588050bb6283c4ee5cfe2978cbde), [`48a42f1`](https://github.com/mastra-ai/mastra/commit/48a42f114a4006a95e0b7a1b5ad1a24815a175c2), [`2c83efc`](https://github.com/mastra-ai/mastra/commit/2c83efc4482b3efe50830e3b8b4ba9a8d219edff), [`282a10c`](https://github.com/mastra-ai/mastra/commit/282a10c9446e9922afe80e10e3770481c8ac8a28)]:
+  - @mastra/core@1.31.0-alpha.0
+
 ## 1.1.31
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.1.32-alpha.0",
+  "version": "1.1.32-alpha.2",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -29,8 +29,8 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.3.6",
-    "@mastra/mcp": "^1.6.0",
-    "@mastra/core": "1.30.0"
+    "@mastra/core": "1.31.0-alpha.1",
+    "@mastra/mcp": "^1.6.0"
   },
   "devDependencies": {
     "@hono/node-server": "^1.19.11",
@@ -46,9 +46,9 @@
     "tsx": "^4.21.0",
     "typescript": "^6.0.3",
     "vitest": "4.1.5",
-    "@internal/types-builder": "0.0.64",
     "@internal/lint": "0.0.89",
-    "@mastra/core": "1.30.0"
+    "@internal/types-builder": "0.0.64",
+    "@mastra/core": "1.31.0-alpha.1"
   },
   "homepage": "https://mastra.ai",
   "repository": {