@mastra/mcp-docs-server 1.2.8-alpha.7 → 1.2.8

package/.docs/reference/tools/mcp-server.md

@@ -187,9 +187,7 @@ const server = new MCPServer({
   id: 'my-server',
   name: 'My Server',
   version: '1.0.0',
-  tools: {
-    /* ... */
-  },
+  tools: {/* ... */},
 })
 await server.startStdio()
 ```
@@ -353,9 +351,7 @@ const server = new MCPServer({
   id: 'my-serverless-mcp',
   name: 'My Serverless MCP',
   version: '1.0.0',
-  tools: {
-    /* your tools */
-  },
+  tools: {/* your tools */},
 })
 
 serve(async req => {
@@ -637,9 +633,7 @@ const serverWithResources = new MCPServer({
   id: 'resourceful-server',
   name: 'Resourceful Server',
   version: '1.0.0',
-  tools: {
-    /* ... your tools ... */
-  },
+  tools: {/* ... your tools ... */},
   resources: myResourceHandlers,
 })
 ```
@@ -768,9 +762,7 @@ const serverWithPrompts = new MCPServer({
   id: 'promptful-server',
   name: 'Promptful Server',
   version: '1.0.0',
-  tools: {
-    /* ... */
-  },
+  tools: {/* ... */},
   prompts: myPromptHandlers,
 })
 ```
@@ -966,9 +958,7 @@ execute: async (inputData, context) => {
   // Use elicitation capabilities
   const result = await context.mcp.elicitation.sendRequest({
     message: 'Please provide information',
-    requestedSchema: {
-      /* schema */
-    },
+    requestedSchema: {/* schema */},
   })
 
   return result
@@ -1159,9 +1149,7 @@ const mcpServer = new MCPServer({
   id: 'protected-server',
   name: 'Protected MCP Server',
   version: '1.0.0',
-  tools: {
-    /* your tools */
-  },
+  tools: {/* your tools */},
 })
 
 // Create OAuth middleware
@@ -1342,21 +1330,48 @@ To pass data to your tools, populate `req.auth` on the Node.js request object in
 ```typescript
 import express from 'express'
 
+type MCPAuthenticatedRequest = express.Request & {
+  auth?: {
+    token: string
+    clientId: string
+    scopes: string[]
+    expiresAt?: number
+    extra?: Record<string, unknown>
+  }
+}
+
 const app = express()
 
 // Auth middleware - set req.auth before the MCP handler
-app.use('/mcp', (req, res, next) => {
-  const token = req.headers.authorization?.replace('Bearer ', '')
-  const user = verifyToken(token)
-
-  // This entire object becomes context.mcp.extra.authInfo
-  // @ts-ignore - req.auth is read by the MCP SDK
-  req.auth = {
-    token,
-    userId: user.userId,
-    email: user.email,
+app.use('/mcp', async (req, res, next) => {
+  const authorization = req.headers.authorization
+
+  if (!authorization?.startsWith('Bearer ')) {
+    res.status(401).json({ error: 'Missing bearer token' })
+    return
+  }
+
+  const token = authorization.slice('Bearer '.length)
+
+  try {
+    const user = await verifyToken(token)
+
+    // This entire object becomes context.mcp.extra.authInfo
+    const authenticatedRequest = req as MCPAuthenticatedRequest
+    authenticatedRequest.auth = {
+      token,
+      clientId: user.clientId,
+      scopes: user.scopes,
+      expiresAt: user.expiresAt,
+      extra: {
+        userId: user.userId,
+        email: user.email,
+      },
+    }
+    next()
+  } catch {
+    res.status(401).json({ error: 'Invalid or expired token' })
   }
-  next()
 })
 
 app.all('/mcp', async (req, res) => {
@@ -1434,19 +1449,86 @@ The full `context.mcp.extra` object contains:
 
 ### Complete Example
 
-Here's a complete example showing the data flow from middleware to tool:
+Install [`jose`](https://github.com/panva/jose) to verify JSON Web Tokens (JWTs) against your identity provider's JSON Web Key Set (JWKS):
+
+**npm**:
+
+```shell
+npm install jose
+```
+
+**pnpm**:
+
+```shell
+pnpm add jose
+```
+
+**Yarn**:
+
+```shell
+yarn add jose
+```
+
+**Bun**:
+
+```shell
+bun add jose
+```
+
+The following example validates the token's signature, issuer, audience, algorithm, expiration, and required claims before passing its user data to the tool:
 
 ```typescript
 import express from 'express'
+import { createRemoteJWKSet, jwtVerify } from 'jose'
 import { MCPServer } from '@mastra/mcp'
 import { createTool } from '@mastra/core/tools'
 import { z } from 'zod'
 
-const verifyToken = (token: string) => {
-  // TODO: Implement token verification
+type MCPAuthenticatedRequest = express.Request & {
+  auth?: {
+    token: string
+    clientId: string
+    scopes: string[]
+    expiresAt?: number
+    extra?: Record<string, unknown>
+  }
+}
+
+const issuer = process.env.JWT_ISSUER
+const audience = process.env.JWT_AUDIENCE
+const jwksUri = process.env.JWT_JWKS_URI
+
+if (!issuer || !audience || !jwksUri) {
+  throw new Error('JWT_ISSUER, JWT_AUDIENCE, and JWT_JWKS_URI are required')
+}
+
+const jwks = createRemoteJWKSet(new URL(jwksUri))
+
+const verifyToken = async (token: string) => {
+  const { payload } = await jwtVerify(token, jwks, {
+    issuer,
+    audience,
+    algorithms: ['RS256'],
+    requiredClaims: ['exp'],
+  })
+
+  const clientId =
+    typeof payload.client_id === 'string'
+      ? payload.client_id
+      : typeof payload.azp === 'string'
+        ? payload.azp
+        : undefined
+
+  if (!payload.sub || typeof payload.email !== 'string' || !clientId || !payload.exp) {
+    throw new Error('Token must contain sub, email, exp, and client_id or azp claims')
+  }
+
   return {
-    userId: '123',
-    email: 'test@test.com',
+    userId: payload.sub,
+    clientId,
+    email: payload.email,
+    expiresAt: payload.exp,
+    scopes: typeof payload.scope === 'string' ? payload.scope.split(' ') : [],
   }
 }
 
@@ -1481,18 +1563,35 @@ const server = new MCPServer({
 // 3. Set up Express with auth middleware
 const app = express()
 
-app.use('/mcp', (req, res, next) => {
-  const token = req.headers.authorization?.replace('Bearer ', '')
-  const user = verifyToken(token)
+app.use('/mcp', async (req, res, next) => {
+  const authorization = req.headers.authorization
+
+  if (!authorization?.startsWith('Bearer ')) {
+    res.status(401).json({ error: 'Missing bearer token' })
+    return
+  }
 
-  // This entire object becomes context.mcp.extra.authInfo
-  // @ts-ignore - req.auth is read by the MCP SDK
-  req.auth = {
-    token,
-    userId: user.userId,
-    email: user.email,
+  const token = authorization.slice('Bearer '.length)
+
+  try {
+    const user = await verifyToken(token)
+
+    // This entire object becomes context.mcp.extra.authInfo
+    const authenticatedRequest = req as MCPAuthenticatedRequest
+    authenticatedRequest.auth = {
+      token,
+      clientId: user.clientId,
+      scopes: user.scopes,
+      expiresAt: user.expiresAt,
+      extra: {
+        userId: user.userId,
+        email: user.email,
+      },
+    }
+    next()
+  } catch {
+    res.status(401).json({ error: 'Invalid or expired token' })
   }
-  next()
 })
 
 app.all('/mcp', async (req, res) => {

package/.docs/reference/tools/tavily.md

@@ -59,7 +59,7 @@ All factory functions accept `TavilyClientOptions` from `@tavily/core`:
 
 **apiKey** (`string`): Tavily API key. Falls back to the TAVILY\_API\_KEY environment variable.
 
-**clientSource** (`string`): Attribution string sent with each request. (Default: `'mastra'`)
+**clientName** (`string`): Attribution string sent with each request in the X-Client-Name header. (Default: `'mastra'`)
 
 **apiBaseURL** (`string`): Base URL for the Tavily API.
 

package/.docs/reference/tools/vector-query-tool.md

@@ -269,6 +269,28 @@ const chromaQueryTool = createVectorQueryTool({
 - **whereDocument**: Filter by document content
 - **Use Cases**: Advanced filtering, content-based search
 
+**Turbopuffer**:
+
+### Turbopuffer Configuration
+
+```typescript
+const turbopufferQueryTool = createVectorQueryTool({
+  vectorStoreName: 'turbopuffer',
+  indexName: 'docs',
+  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
+  databaseConfig: {
+    turbopuffer: {
+      consistency: 'eventual', // Lower latency, recently written data may not be visible yet
+    },
+  },
+})
+```
+
+**Turbopuffer Features:**
+
+- **consistency**: Choose between `strong` (default, read-your-writes) and `eventual` (lower latency)
+- **Use Cases**: Latency-sensitive queries where slightly stale data is acceptable
+
 **Multiple Configs**:
 
 ### Multiple Database Configurations

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

@@ -89,6 +89,8 @@ Creates a new vector index (collection) in MongoDB.
 
 **metric** (`'cosine' | 'euclidean' | 'dotproduct'`): Distance metric for similarity search (Default: `cosine`)
 
+**filterFields** (`string[]`): Metadata field names to declare as filter fields in the Atlas vectorSearch index (registered as metadata.\<field>). Queries that filter only on declared fields are pushed directly into $vectorSearch instead of pre-filtering candidate \_ids, avoiding the 16 MB BSON limit on large result sets. Filters that reference an undeclared field, or use an operator $vectorSearch does not support, fall back to the pre-filter automatically.
+
 ### `waitForIndexReady()`
 
 Waits for an index to become ready after creation. Useful when you need to ensure an index is ready before performing operations.

package/.docs/reference/vectors/turbopuffer.md

@@ -18,6 +18,8 @@ The TurbopufferVector class provides vector search using [Turbopuffer](https://t
 
 **compression** (`boolean`): Whether to compress requests and accept compressed responses. (Default: `true`)
 
+**consistency** (`'strong' | 'eventual'`): The default consistency level for queries. Can be overridden per query. "strong" guarantees queries see all data written before the query started, at the cost of higher latency. "eventual" offers lower latency, but recently written data may not be visible yet. (Default: `strong`)
+
 **schemaConfigForIndex** (`function`): A callback function that takes an index name and returns a config object for that index. This allows you to define explicit schemas per index.
 
 ## Methods
@@ -50,6 +52,8 @@ The TurbopufferVector class provides vector search using [Turbopuffer](https://t
 
 **includeVector** (`boolean`): Whether to include vectors in the results (Default: `false`)
 
+**consistency** (`'strong' | 'eventual'`): The consistency level for this query. Overrides the consistency level set in the constructor. Defaults to "strong".
+
 ### `listIndexes()`
 
 Returns an array of index names as strings.

package/.docs/reference/voice/mistral.md

@@ -0,0 +1,127 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Mistral
+
+The MistralVoice class provides text-to-speech and speech-to-text capabilities using Mistral's Voxtral audio models. It supports buffered and streaming TTS, batch transcription with diarization, and voice cloning via reference audio.
+
+## Usage example
+
+```typescript
+import { MistralVoice } from '@mastra/voice-mistral'
+
+const voice = new MistralVoice()
+
+// Text-to-speech
+const audioStream = await voice.speak('Hello, how can I help you?', {
+  responseFormat: 'mp3',
+})
+
+// Speech-to-text
+const text = await voice.listen(audioStream, {
+  language: 'en',
+})
+
+// List available voices
+const speakers = await voice.getSpeakers()
+```
+
+```typescript
+import { MistralVoice } from '@mastra/voice-mistral'
+
+// Initialize with specific configuration
+const voice = new MistralVoice({
+  speechModel: {
+    name: 'voxtral-mini-tts-2603',
+    apiKey: 'your-mistral-api-key',
+  },
+  listeningModel: {
+    name: 'voxtral-mini-latest',
+    apiKey: 'your-mistral-api-key',
+  },
+  speaker: 'en_paul_neutral',
+})
+```
+
+## Constructor parameters
+
+**speechModel** (`MistralModelConfig`): Configuration for text-to-speech synthesis. (Default: `{ name: 'voxtral-mini-tts-2603' }`)
+
+**speechModel.name** (`string`): Model ID for speech synthesis.
+
+**speechModel.apiKey** (`string`): Mistral API key. Falls back to MISTRAL\_API\_KEY environment variable.
+
+**listeningModel** (`MistralModelConfig`): Configuration for speech-to-text recognition. (Default: `{ name: 'voxtral-mini-latest' }`)
+
+**listeningModel.name** (`string`): Model ID for transcription. Use 'voxtral-mini-2507' for a pinned version.
+
+**listeningModel.apiKey** (`string`): Mistral API key. Falls back to MISTRAL\_API\_KEY environment variable.
+
+**speaker** (`string`): Default voice ID for speech synthesis. Retrieve available IDs from getSpeakers(). (Default: `'en_paul_neutral'`)
+
+## Methods
+
+### `speak(input, options?)`
+
+Converts text to speech using Mistral's Voxtral TTS model. Supports both buffered and streaming output.
+
+**input** (`string | NodeJS.ReadableStream`): Text or text stream to convert to speech.
+
+**options** (`MistralSpeakOptions`): Configuration options.
+
+**options.speaker** (`string`): Voice ID to use. Overrides the constructor default.
+
+**options.responseFormat** (`'pcm' | 'wav' | 'mp3' | 'flac' | 'opus'`): Audio output format. Use 'pcm' for lowest latency streaming.
+
+**options.refAudio** (`string`): Base64-encoded reference audio for one-off voice cloning (minimum 2-3 seconds).
+
+**options.model** (`string`): Override the speech model for this call.
+
+**options.stream** (`boolean`): Enable streaming TTS. Audio chunks are written to the stream as they arrive.
+
+Returns: `Promise<NodeJS.ReadableStream>`
+
+### `listen(audioStream, options?)`
+
+Transcribes audio using Mistral's Voxtral transcription model. Supports diarization, context biasing, and timestamp granularity.
+
+**audioStream** (`NodeJS.ReadableStream`): Audio stream to transcribe.
+
+**options** (`MistralListenOptions`): Configuration options.
+
+**options.language** (`string`): Language code (e.g., 'en'). Improves accuracy when specified.
+
+**options.diarize** (`boolean`): Enable speaker diarization.
+
+**options.contextBias** (`string[]`): Words or phrases for vocabulary guidance.
+
+**options.timestampGranularities** (`('segment' | 'word')[]`): Timestamp detail level for transcription segments.
+
+**options.filetype** (`string`): Audio file extension hint for the input stream.
+
+Returns: `Promise<string>`
+
+### `getSpeakers()`
+
+Fetches available preset voices from the Mistral Voices API. Each entry contains:
+
+**voiceId** (`string`): Unique identifier for the voice.
+
+**name** (`string`): Display name of the voice.
+
+**languages** (`string[]`): Languages supported by the voice.
+
+**gender** (`string | null`): Gender of the voice.
+
+### `getListener()`
+
+Returns `{ enabled: true }`.
+
+## Notes
+
+- API keys can be provided via constructor options or the `MISTRAL_API_KEY` environment variable
+- TTS supports 9 languages: English, French, Spanish, Portuguese, Italian, Dutch, German, Hindi, Arabic
+- STT supports 13 languages: English, Chinese, Hindi, Spanish, Arabic, French, Portuguese, Russian, German, Japanese, Korean, Italian, Dutch
+- TTS input text should be kept under 300 words per request for best results
+- STT supports up to 3 hours of audio per request
+- Voice cloning via `refAudio` requires a minimum of 2-3 seconds of reference audio
+- `getSpeakers()` returns preset voices with UUID identifiers. The default `en_paul_neutral` is a named alias accepted by the TTS endpoint but not included in the list

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

@@ -440,12 +440,8 @@ Then use the snapshot name in your sandbox config:
 ```typescript
 const workspace = new Workspace({
   mounts: {
-    '/s3-data': new S3Filesystem({
-      /* ... */
-    }),
-    '/gcs-data': new GCSFilesystem({
-      /* ... */
-    }),
+    '/s3-data': new S3Filesystem({/* ... */}),
+    '/gcs-data': new GCSFilesystem({/* ... */}),
   },
   sandbox: new DaytonaSandbox({ snapshot: 'cloud-fs-mounting' }),
 })

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

@@ -0,0 +1,182 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# PlatformFilesystem
+
+Stores files in a Mastra Platform workspace bucket. Each Mastra Platform environment can have one bucket, and `PlatformFilesystem` gives agents `read`, `write`, `list`, `delete`, and `move` operations against it.
+
+Use `PlatformFilesystem` when your agent runs on a Mastra Platform deployment and you want the filesystem to be backed by the platform-provisioned bucket. For direct S3 access, see [`S3Filesystem`](https://mastra.ai/reference/workspace/s3-filesystem). For a local directory during development, see [`LocalFilesystem`](https://mastra.ai/reference/workspace/local-filesystem).
+
+> **Info:** For interface details, see [WorkspaceFilesystem interface](https://mastra.ai/reference/workspace/filesystem).
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/platform-workspace
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/platform-workspace
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/platform-workspace
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/platform-workspace
+```
+
+Configure the platform credentials. The access token, project ID, and bucket name fall back to environment variables, so a Mastra Platform deployment can pass zero constructor options.
+
+**.env file**:
+
+```bash
+MASTRA_PLATFORM_SECRET_KEY=your-platform-secret-key
+MASTRA_PROJECT_ID=your-project-id
+MASTRA_PLATFORM_BUCKET_NAME=your-bucket-name
+```
+
+**Constructor**:
+
+```typescript
+new PlatformFilesystem({
+  accessToken: 'your-platform-access-token',
+  projectId: 'your-project-id',
+  bucketName: 'your-bucket-name',
+})
+```
+
+On a Mastra Platform deployment these variables are injected automatically, so the constructor can be called with no options.
+
+## Usage
+
+Add a `PlatformFilesystem` to a workspace and assign it to an agent:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Workspace } from '@mastra/core/workspace'
+import { PlatformFilesystem } from '@mastra/platform-workspace'
+
+const workspace = new Workspace({
+  filesystem: new PlatformFilesystem({
+    // accessToken, projectId, bucketName all fall back to env vars
+  }),
+})
+
+const agent = new Agent({
+  id: 'file-agent',
+  name: 'File Agent',
+  instructions: 'You are a research assistant that reads and writes reports.',
+  model: 'anthropic/claude-sonnet-4-6',
+  workspace,
+})
+```
+
+### Reading and writing files
+
+Object keys are percent-encoded per segment, so filenames with `?`, `#`, `%`, `&`, `+`, or spaces are preserved end-to-end:
+
+```typescript
+const fs = new PlatformFilesystem()
+
+await fs.writeFile('/analyses/repo.md', markdown)
+const content = await fs.readFile('/analyses/repo.md')
+const entries = await fs.readdir('/analyses')
+await fs.moveFile('/analyses/repo.md', '/analyses/repo-final.md')
+```
+
+### Read-only mode
+
+Pass `readOnly: true` to mount the bucket read-only. Any mutating call throws `WorkspaceReadOnlyError`:
+
+```typescript
+const fs = new PlatformFilesystem({ readOnly: true })
+
+await fs.readFile('/analyses/repo.md') // ok
+await fs.writeFile('/analyses/repo.md', 'x') // throws WorkspaceReadOnlyError
+```
+
+### Overwrite semantics
+
+`writeFile` supports `overwrite: false` and throws `FileExistsError` when the destination already exists.
+
+`copyFile` and `moveFile` always overwrite the destination. Passing `overwrite: false` to either method throws an error rather than silently overwriting.
+
+### Appending files
+
+`appendFile` is a read-modify-write and is not atomic. Concurrent appends to the same path can overwrite each other. For concurrent writers, use `writeFile` with distinct keys.
+
+## Constructor parameters
+
+**accessToken** (`string`): Platform secret key. Falls back to the MASTRA\_PLATFORM\_SECRET\_KEY environment variable (MASTRA\_PLATFORM\_ACCESS\_TOKEN is a deprecated fallback).
+
+**projectId** (`string`): Platform project ID. Falls back to the MASTRA\_PROJECT\_ID environment variable.
+
+**bucketName** (`string`): Platform bucket name to store files in. Falls back to the MASTRA\_PLATFORM\_BUCKET\_NAME environment variable.
+
+**readOnly** (`boolean`): When true, all mutating calls throw WorkspaceReadOnlyError. (Default: `false`)
+
+**displayName** (`string`): Human-readable name shown in workspace UIs.
+
+**description** (`string`): Short description shown in workspace UIs.
+
+**icon** (`FilesystemIcon`): Icon shown in workspace UIs.
+
+**instructions** (`string | ((opts: { defaultInstructions: string; requestContext?: RequestContext }) => string)`): Custom instructions returned by getInstructions(). A string fully replaces the defaults; a function receives the defaults and can extend or customize them per-request.
+
+**id** (`string`): Unique identifier for this filesystem instance. (Default: `Auto-generated`)
+
+**fetch** (`typeof fetch`): Custom fetch implementation, mainly for testing.
+
+## Properties
+
+**id** (`string`): Filesystem instance identifier.
+
+**name** (`string`): Provider name ('PlatformFilesystem').
+
+**provider** (`string`): Provider identifier ('platform').
+
+**readOnly** (`boolean | undefined`): Whether the filesystem was mounted read-only.
+
+## Errors
+
+Filesystem-specific errors match the standard workspace error types:
+
+- `FileNotFoundError`: The path does not exist. Thrown by `readFile`, `stat`, and `deleteFile` (unless `force: true` is set).
+- `FileExistsError`: `writeFile` was called with `overwrite: false` and the destination already exists.
+- `WorkspaceReadOnlyError`: A mutating call was made on a read-only filesystem.
+
+Other Platform API failures raise `PlatformApiError`. Structured `{ error: { message, type } }` responses are parsed into `.code` (machine-readable kind) and `.proxyMessage` (human string):
+
+```typescript
+import { FileNotFoundError, PlatformApiError } from '@mastra/platform-workspace'
+
+try {
+  await fs.readFile('/missing.txt')
+} catch (err) {
+  if (err instanceof FileNotFoundError) {
+    // handle missing file
+  } else if (err instanceof PlatformApiError) {
+    if (err.code === 'authentication_error') {
+      // refresh token
+    }
+    console.error(err.status, err.code, err.proxyMessage)
+  }
+}
+```
+
+`code` and `proxyMessage` are `undefined` when the response body is not JSON, for example an HTML 502 from a load balancer.
+
+## Related
+
+- [PlatformSandbox reference](https://mastra.ai/reference/workspace/platform-sandbox)
+- [S3Filesystem reference](https://mastra.ai/reference/workspace/s3-filesystem)
+- [WorkspaceFilesystem interface](https://mastra.ai/reference/workspace/filesystem)