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

package/.docs/docs/agents/channels.md

@@ -112,7 +112,7 @@ const deleteFile = createTool({
 
 When the agent calls this tool, users see a card with the tool name, arguments, and Approve/Deny buttons. The tool only executes after approval.
 
-Set `cards: false` on an adapter to render tool calls as plain text instead of interactive cards. When cards are disabled and a tool requires approval, the agent uses `autoResumeSuspendedTools` to let the LLM decide based on the conversation context.
+Set `toolDisplay: 'text'` on an adapter to render tool calls as plain text instead of interactive cards. In `'hidden'` mode the agent uses `autoResumeSuspendedTools` to let the LLM decide based on the conversation context, since hidden mode does not post approval buttons.
 
 ## Multi-user awareness
 

package/.docs/docs/observability/metrics/overview.md

@@ -11,6 +11,8 @@ Three categories of metrics are emitted automatically:
 > **Note:** Metrics require an OLAP-capable store for observability. Relational databases like PostgreSQL, LibSQL, etc. are not supported for metrics. In-memory storage resets on restart.
 >
 > For local development, use [DuckDB](https://duckdb.org/) through `@mastra/duckdb`. For production, use [ClickHouse](https://clickhouse.com/) through `@mastra/clickhouse`.
+>
+> Google Cloud Spanner supports metrics, but it is not recommended for heavy metrics workloads. The Spanner adapter disables metrics by default because metrics are write-heavy and scan-heavy. Set `disableMetrics: false` only for light workloads, or route metrics to an OLAP store.
 
 ## When to use metrics
 

package/.docs/docs/server/custom-api-routes.md

@@ -264,6 +264,21 @@ For more information about authentication providers, see the [Auth documentation
 
 Built-in streaming helpers such as [`chatRoute()`](https://mastra.ai/reference/ai-sdk/chat-route) forward the incoming request's `AbortSignal` to `agent.stream()`. That's the right default when a browser disconnect should cancel the model call.
 
+For custom streaming routes that should stop when the client disconnects, pass `c.req.raw.signal` to long-running work such as `agent.stream()`. Mastra's Node-based adapters also stop reading streamed `Response` bodies from custom routes when the client connection closes. Streamed response body errors that are not caused by client disconnects still propagate through the adapter's normal error handling. In Hono, disconnect behavior depends on the host runtime forwarding connection closes to `request.signal`.
+
+```typescript
+registerApiRoute('/stream', {
+  method: 'GET',
+  handler: async c => {
+    const stream = await agent.stream(prompt, {
+      abortSignal: c.req.raw.signal,
+    })
+
+    return stream.toTextStreamResponse()
+  },
+})
+```
+
 If you want the server to keep generating and persist the final response even after the client disconnects, build a custom route around the underlying `MastraModelOutput`. Start the agent stream without forwarding `c.req.raw.signal`, then call `consumeStream()` in the background so generation continues server-side.
 
 ```typescript

package/.docs/reference/agents/channels.md

@@ -62,7 +62,7 @@ const agent = new Agent({
     adapters: {
       discord: {
         adapter: createDiscordAdapter(),
-        cards: false,
+        toolDisplay: 'text',
         cors: {
           origin: ['https://customer-saas.example'],
           credentials: true,
@@ -79,14 +79,83 @@ const agent = new Agent({
 
 **gateway** (`boolean`): Start a persistent Gateway WebSocket listener for receiving DMs, @mentions, and reactions. Set to \`false\` for serverless deployments that only need webhook-based interactions. (Default: `true`)
 
-**cards** (`boolean`): Render tool calls as interactive rich cards with buttons. Set to \`false\` to use plain text formatting instead. When disabled and a tool requires approval, the agent uses \`autoResumeSuspendedTools\` to let the LLM decide based on conversation context. (Default: `true`)
+**cards** (`boolean`): \*\*Deprecated\*\* — use \`toolDisplay\` instead. When \`toolDisplay\` is not set, \`cards: true\` maps to \`toolDisplay: "cards"\` and \`cards: false\` maps to \`toolDisplay: "text"\`. IDEs flag the field with a strikethrough; runtime behavior is preserved.
 
 **cors** (`CorsOptions`): CORS configuration for this adapter webhook route. Use this for browser-based channel adapters that need cross-origin credentials.
 
-**formatToolCall** (`(info: { toolName, args, result, isError? }) => PostableMessage | null`): Override how tool calls are rendered in the chat. Called once per tool invocation after the result is available. Return \`null\` to suppress the message entirely.
-
 **formatError** (`(error: Error) => PostableMessage`): Override how errors are rendered in the chat. Return a user-friendly message instead of exposing the raw error. (Default: `"❌ Error: <error.message>"`)
 
+**formatToolCall** (`(args: { toolName: string; args: unknown; result: unknown; isError: boolean }) => PostableMessage | null`): \*\*Deprecated\*\* — use \`toolDisplay\` (function form) instead. When set, runs as a \`ToolDisplayFn\` that only fires on \`result\`/\`error\` events; \`running\` and \`approval\` events fall through to no render. Mutually exclusive with \`toolDisplay\` at the type level.
+
+**streaming** (`boolean | { updateIntervalMs?: number }`): Stream agent text deltas to the channel as the agent generates them instead of buffering and posting once per step. Requires the underlying adapter to support post-and-edit streaming. Slack defaults to \`true\`; other adapters default to \`false\`. (Default: `false (true for Slack)`)
+
+**toolDisplay** (`'cards' | 'text' | 'timeline' | 'grouped' | 'hidden' | ToolDisplayFn`): How tool calls are rendered in the channel. \`"cards"\` posts per-tool running/result cards as rich Block Kit. \`"text"\` posts the same lifecycle as plain text (no Block Kit). \`"timeline"\` and \`"grouped"\` stream tool state as inline \`task\_update\` chunks (requires \`streaming: true\`; Slack only today — other adapters may render a placeholder). \`"hidden"\` executes tools silently. Pass a function to render tool events yourself; return \`{ kind: "post", message }\` for a discrete post/edit, \`{ kind: "stream", chunk }\` to push into the active streaming widget, or \`undefined\` to skip rendering that event. Approve/deny prompts always render as a separate card regardless of mode. (Default: `'cards' ('grouped' for Slack)`)
+
+**typingStatus** (`boolean | ((chunk: AgentChunkType, ctx: TypingStatusContext) => string | false | null | undefined | void)`): Control the platform typing indicator. \`true\` uses built-in defaults (\`is typing…\` on text, \`is calling {tool}…\` on tool-call, \`is waiting for approval…\` on tool-call-approval). \`false\` suppresses typing entirely — useful when a live streaming widget (e.g. \`toolDisplay: "grouped"\` in Slack) already conveys progress. Pass a function to set custom status copy per chunk; return a string to set the status, or \`false\`/\`null\`/\`undefined\` to leave it unchanged. Compose with \`defaultTypingStatus\` (exported from \`@mastra/core/channels\`) to fall back to defaults for chunks you don't handle. (Default: `true`)
+
+## Tool display modes
+
+`toolDisplay` controls how tool calls render in chat. The default `'cards'` posts a "Running…" card per tool and edits it with the result, matching the behavior in earlier versions. `'text'` is the same lifecycle but without rich Block Kit, useful for platforms that don't render cards well.
+
+`'timeline'` and `'grouped'` stream tool state as inline `task_update` chunks alongside the agent's text. These modes require `streaming: true` and rely on the chat adapter to render the chunks. Slack supports both natively; other adapters may render a placeholder until they ship support. If `streaming` is disabled, the channel logs a one-time warning and falls back to `'cards'`.
+
+`'hidden'` executes tools silently. Only the typing status indicates work in progress.
+
+Pass a function to `toolDisplay` for fully custom rendering. The function receives a `ToolDisplayEvent` (`running` / `result` / `error` / `approval`) and a `ToolDisplayContext` (`{ mode, platform }`); return `{ kind: 'post', message }` for a discrete post/edit, `{ kind: 'stream', chunk }` to push into the active streaming widget, or `undefined` to skip rendering that event.
+
+Approve/deny prompts (`requireApproval`) always render as a separate card regardless of mode, because inline task entries can't carry interactive buttons.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { createSlackAdapter } from '@chat-adapter/slack'
+
+const agent = new Agent({
+  name: 'Streaming Agent',
+  instructions: '...',
+  model: 'openai/gpt-5.4',
+  channels: {
+    adapters: {
+      slack: {
+        adapter: createSlackAdapter(),
+        streaming: true, // already the Slack default
+        toolDisplay: 'timeline',
+      },
+    },
+  },
+})
+```
+
+## Custom typing status
+
+Pass a function to `typingStatus` to customize the status copy. The function is called once per stream chunk; return a string to set the status, or `false` / `null` / `undefined` to leave the current status unchanged. Return values are de-duplicated so the platform only sees a call when the status changes.
+
+`defaultTypingStatus` is exported from `@mastra/core/channels` so you can fall back to the built-in defaults for chunks you don't handle.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { defaultTypingStatus } from '@mastra/core/channels'
+import { createDiscordAdapter } from '@chat-adapter/discord'
+
+const agent = new Agent({
+  name: 'Custom Typing Agent',
+  instructions: '...',
+  model: 'openai/gpt-5.4',
+  channels: {
+    adapters: {
+      discord: {
+        adapter: createDiscordAdapter(),
+        typingStatus: (chunk, ctx) => {
+          if (chunk.type === 'tool-call' && chunk.payload.toolName === 'searchDocs') {
+            return 'is searching docs…'
+          }
+          return defaultTypingStatus(chunk, ctx)
+        },
+      },
+    },
+  },
+})
+```
+
 ## Handlers
 
 Override built-in event handlers. Each handler can be:

package/.docs/reference/index.md

@@ -208,6 +208,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Convex Storage](https://mastra.ai/reference/storage/convex)
 - [DuckDB Storage](https://mastra.ai/reference/storage/duckdb)
 - [DynamoDB Storage](https://mastra.ai/reference/storage/dynamodb)
+- [Google Cloud Spanner Storage](https://mastra.ai/reference/storage/spanner)
 - [LanceDB Storage](https://mastra.ai/reference/storage/lance)
 - [libSQL Storage](https://mastra.ai/reference/storage/libsql)
 - [MongoDB Storage](https://mastra.ai/reference/storage/mongodb)

package/.docs/reference/storage/spanner.md

@@ -0,0 +1,213 @@
+# Google Cloud Spanner storage
+
+The Google Cloud Spanner storage implementation provides a horizontally scalable, strongly consistent storage backend for Mastra. It targets the GoogleSQL dialect of Cloud Spanner.
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/spanner@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/spanner@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/spanner@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/spanner@latest
+```
+
+## Usage
+
+```typescript
+import { SpannerStore } from '@mastra/spanner'
+
+const storage = new SpannerStore({
+  id: 'spanner-storage',
+  projectId: process.env.SPANNER_PROJECT_ID!,
+  instanceId: process.env.SPANNER_INSTANCE_ID!,
+  databaseId: process.env.SPANNER_DATABASE_ID!,
+})
+```
+
+The instance and database must already exist. The adapter creates the required tables on first use, so the credentials provided to the Spanner client need permission to run schema changes (or run `storage.init()` once during a deploy step with elevated credentials).
+
+## Parameters
+
+**id** (`string`): Unique identifier for this storage instance.
+
+**projectId** (`string`): Google Cloud project ID. Required unless \`database\` is provided.
+
+**instanceId** (`string`): Cloud Spanner instance ID. Required unless \`database\` is provided.
+
+**databaseId** (`string`): Cloud Spanner database ID. Required unless \`database\` is provided.
+
+**database** (`@google-cloud/spanner Database`): Pre-configured Spanner Database handle. Use this when you manage the Spanner client elsewhere (for example, to share auth or connection options across services).
+
+**spannerOptions** (`object`): Options forwarded to the \`@google-cloud/spanner\` client constructor. Use this to set credentials, custom endpoints, or to point at the local emulator.
+
+**disableInit** (`boolean`): When true, skip automatic table creation on first use. You must call \`storage.init()\` explicitly during a separate deploy step. (Default: `false`)
+
+**skipDefaultIndexes** (`boolean`): When true, skip creation of default indexes during initialization. (Default: `false`)
+
+**indexes** (`CreateIndexOptions[]`): Custom secondary indexes to create. Each index must specify the table it belongs to. Indexes are routed to the appropriate domain based on the table name.
+
+**initMode** (`'sync' | 'validate'`): Controls schema-initialization behavior. \`'sync'\` creates missing tables, columns, and indexes during \`init()\` (the historical behavior). \`'validate'\` issues no DDL and instead verifies that every expected table, column, and default/custom index already exists, throwing a typed user error if anything is missing — useful when an external process (Terraform, Liquibase, a release pipeline, etc.) owns the schema and Mastra should only verify it. (Default: `'sync'`)
+
+## Constructor examples
+
+You can instantiate `SpannerStore` in several ways:
+
+```typescript
+import { Spanner } from '@google-cloud/spanner'
+import { SpannerStore } from '@mastra/spanner'
+
+// Using projectId / instanceId / databaseId
+const store1 = new SpannerStore({
+  id: 'spanner-storage-1',
+  projectId: 'my-gcp-project',
+  instanceId: 'my-instance',
+  databaseId: 'mastra',
+})
+
+// Reusing an existing Spanner Database handle
+const spanner = new Spanner({ projectId: 'my-gcp-project' })
+const database = spanner.instance('my-instance').database('mastra')
+
+const store2 = new SpannerStore({
+  id: 'spanner-storage-2',
+  database,
+})
+
+// Using the local Spanner emulator (set the SPANNER_EMULATOR_HOST env var)
+process.env.SPANNER_EMULATOR_HOST = 'localhost:9010'
+const store3 = new SpannerStore({
+  id: 'spanner-storage-emulator',
+  projectId: 'test-project',
+  instanceId: 'test-instance',
+  databaseId: 'test-db',
+  spannerOptions: { servicePath: 'localhost', port: 9010, sslCreds: undefined },
+})
+```
+
+## Additional notes
+
+### Schema management
+
+The storage adapter creates the following tables, all using the GoogleSQL dialect:
+
+- `mastra_workflow_snapshot`: workflow state and execution data
+- `mastra_threads`: conversation threads
+- `mastra_messages`: individual messages
+- `mastra_resources`: resource working memory
+- `mastra_scorers`: evaluation scores
+- `mastra_background_tasks`: background tool execution state
+- `mastra_agents`: thin agent records (id, status, active version)
+- `mastra_agent_versions`: versioned agent configuration snapshots
+- `mastra_mcp_clients` / `mastra_mcp_client_versions`: MCP client configurations and their version history
+- `mastra_mcp_servers` / `mastra_mcp_server_versions`: MCP server configurations and their version history
+- `mastra_skills` / `mastra_skill_versions`: skill records and versioned skill snapshots (instructions, references, scripts, assets, content tree)
+- `mastra_skill_blobs`: content-addressable blob store keyed by SHA-256 hash, used for skill version contents
+- `mastra_prompt_blocks` / `mastra_prompt_block_versions`: prompt block records and versioned content snapshots (template content, rules, request-context schema)
+- `mastra_scorer_definitions` / `mastra_scorer_definition_versions`: scorer definition records and versioned config snapshots (judge instructions, model, score range, preset config, default sampling)
+- `mastra_schedules` / `mastra_schedule_triggers`: cron-driven workflow schedules and trigger history, consumed by Mastra's built-in `WorkflowScheduler`
+- `mastra_ai_spans`: AI tracing spans for observability (per-trace and per-span records, used to power the Studio traces UI)
+
+Tables are created with `STRING(MAX)` for text and JSON payloads, `INT64`, `FLOAT64`, `BOOL`, and `TIMESTAMP`.
+
+Two tables also carry Spanner-specific `STORED` generated columns that the adapter populates from JSON payloads so common filters can use a regular secondary index instead of a `JSON_VALUE` scan:
+
+- `mastra_workflow_snapshot.snapshotStatus` — extracts `$.status` from `snapshot`; backs `listWorkflowRuns({ status })`.
+- `mastra_schedules.target_workflow_id` — extracts `$.workflowId` from `target`; backs `listSchedules({ workflowId })`.
+
+Both are added via `ALTER TABLE ... ADD COLUMN IF NOT EXISTS` during `init()` and skipped under `initMode: 'validate'` (where the schema is owned externally). When the column is absent, the adapter falls back to a `JSON_VALUE` filter at runtime.
+
+The adapter does not create or use named schemas; use a dedicated database for isolation.
+
+### Initialization
+
+When you pass storage to the `Mastra` class, `init()` is called automatically before any storage operation:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { SpannerStore } from '@mastra/spanner'
+
+const storage = new SpannerStore({
+  id: 'spanner-storage',
+  projectId: process.env.SPANNER_PROJECT_ID!,
+  instanceId: process.env.SPANNER_INSTANCE_ID!,
+  databaseId: process.env.SPANNER_DATABASE_ID!,
+})
+
+const mastra = new Mastra({
+  storage, // init() is called automatically
+})
+```
+
+If you use storage directly, call `init()` once before the first operation. Spanner does not allow concurrent schema changes, so `SpannerStore.init()` runs each domain's setup sequentially.
+
+```typescript
+const storage = new SpannerStore({
+  id: 'spanner-storage',
+  projectId: process.env.SPANNER_PROJECT_ID!,
+  instanceId: process.env.SPANNER_INSTANCE_ID!,
+  databaseId: process.env.SPANNER_DATABASE_ID!,
+})
+
+await storage.init()
+const memory = await storage.getStore('memory')
+const thread = await memory?.getThreadById({ threadId: '...' })
+```
+
+> **Warning:** If `init()` is not called and `disableInit` is true, the required tables will not exist and storage operations will fail.
+
+### GoogleSQL specifics
+
+A few behaviors differ from other relational adapters:
+
+- Upserts use `INSERT OR UPDATE`. Spanner does not provide a `RETURNING` clause for upserts, so callers needing the post-write state must read it back.
+- There is no `TRUNCATE`; `dangerouslyClearAll()` issues `DELETE WHERE TRUE`.
+- Identifiers are quoted with backticks.
+- DDL is applied through `database.updateSchema(...)`, which is asynchronous (long-running operation).
+- `NULLS FIRST/LAST` is not supported. Ordering with NULL handling is emulated through an `IS NULL` ordering key.
+- JSON containment is not supported natively. `listTraces` `metadata` and `scope` filters compile to per-key `JSON_VALUE(...) = @v` equality checks, and `tags` filters compile to `EXISTS` over `JSON_QUERY_ARRAY(...)`. This differs from Postgres' `@>` containment operator (which can match nested structure in a single index scan) — most one-shot lookups still work but deeply nested structural matches are not expressible.
+
+### Direct database access
+
+`SpannerStore` exposes the underlying Spanner client objects:
+
+```typescript
+store.database // @google-cloud/spanner Database
+store.instance // @google-cloud/spanner Instance (when created internally)
+store.spanner // @google-cloud/spanner Spanner client (when created internally)
+```
+
+These are intended for advanced scenarios such as bespoke transactions or schema introspection. When you reuse the database directly, you bypass the adapter's validation and JSON conversion logic.
+
+### Local development with the emulator
+
+Run the Cloud Spanner emulator locally with Docker:
+
+```bash
+docker run -p 9010:9010 -p 9020:9020 gcr.io/cloud-spanner-emulator/emulator
+```
+
+Set `SPANNER_EMULATOR_HOST=localhost:9010` and create the instance and database before running your app:
+
+```bash
+gcloud spanner instances create test-instance --config=emulator-config --nodes=1
+gcloud spanner databases create test-db --instance=test-instance
+```
+
+Then connect with the same env var set in your Node.js process; the `@google-cloud/spanner` client detects the emulator automatically.

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @mastra/mcp-docs-server
 
+## 1.1.40-alpha.15
+
+### Patch Changes
+
+- Updated dependencies [[`168fa09`](https://github.com/mastra-ai/mastra/commit/168fa09d6b39114cb8c13bd06f1dccb9bc81c6cd)]:
+  - @mastra/core@1.37.0-alpha.7
+
+## 1.1.40-alpha.13
+
+### Patch Changes
+
+- Updated dependencies [[`0cbece9`](https://github.com/mastra-ai/mastra/commit/0cbece9d832cb134a74cdbf3682d390a058215a4), [`7dfe1bc`](https://github.com/mastra-ai/mastra/commit/7dfe1bcfe71d261a6fd6bbf29b1dec49d78fb98f), [`70cb714`](https://github.com/mastra-ai/mastra/commit/70cb7149c8f16f478e15b58498254a53181750a4), [`7f9da22`](https://github.com/mastra-ai/mastra/commit/7f9da22efd5aa595e138a31de55a5f0f2f28b33d)]:
+  - @mastra/core@1.37.0-alpha.6
+
 ## 1.1.40-alpha.11
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.1.40-alpha.12",
+  "version": "1.1.40-alpha.16",
   "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/core": "1.37.0-alpha.5",
-    "@mastra/mcp": "^1.8.0"
+    "@mastra/mcp": "^1.8.0",
+    "@mastra/core": "1.37.0-alpha.7"
   },
   "devDependencies": {
     "@hono/node-server": "^1.19.11",
@@ -48,7 +48,7 @@
     "vitest": "4.1.5",
     "@internal/lint": "0.0.97",
     "@internal/types-builder": "0.0.72",
-    "@mastra/core": "1.37.0-alpha.5"
+    "@mastra/core": "1.37.0-alpha.7"
   },
   "homepage": "https://mastra.ai",
   "repository": {