@mastra/mcp-docs-server 1.2.7 → 1.2.8-alpha.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (147) hide show
  1. package/.docs/docs/agent-builder/deploying.md +1 -0
  2. package/.docs/docs/agent-builder/integrations.md +1 -3
  3. package/.docs/docs/agent-builder/overview.md +1 -1
  4. package/.docs/docs/agent-controller/overview.md +1 -1
  5. package/.docs/docs/agents/overview.md +17 -13
  6. package/.docs/docs/agents/skills.md +1 -3
  7. package/.docs/docs/agents/structured-output.md +14 -7
  8. package/.docs/docs/agents/using-tools.md +80 -26
  9. package/.docs/docs/browser/agent-browser.md +1 -0
  10. package/.docs/docs/browser/firecrawl.md +129 -0
  11. package/.docs/docs/browser/overview.md +16 -2
  12. package/.docs/docs/capabilities/channels/other-adapters.md +1 -1
  13. package/.docs/docs/capabilities/channels/overview.md +1 -0
  14. package/.docs/docs/capabilities/channels/slack.md +113 -3
  15. package/.docs/docs/deployment/mastra-server.md +35 -0
  16. package/.docs/docs/deployment/monorepo.md +2 -0
  17. package/.docs/docs/deployment/overview.md +6 -0
  18. package/.docs/docs/deployment/sandbox.md +277 -0
  19. package/.docs/docs/editor/overview.md +2 -6
  20. package/.docs/docs/editor/tools.md +2 -6
  21. package/.docs/docs/evals/multi-turn.md +178 -0
  22. package/.docs/docs/evals/overview.md +1 -0
  23. package/.docs/docs/evals/running-in-ci.md +3 -9
  24. package/.docs/docs/getting-started/file-based-agents.md +2 -2
  25. package/.docs/docs/index.md +17 -13
  26. package/.docs/docs/long-running-agents/background-tasks.md +2 -2
  27. package/.docs/docs/long-running-agents/durable-agents.md +2 -1
  28. package/.docs/docs/long-running-agents/schedules.md +2 -2
  29. package/.docs/docs/mastra-platform/database.md +13 -6
  30. package/.docs/docs/mastra-platform/deploy.md +17 -8
  31. package/.docs/docs/mastra-platform/environments.md +5 -4
  32. package/.docs/docs/mastra-platform/regions.md +73 -0
  33. package/.docs/docs/mcp/overview.md +1 -1
  34. package/.docs/docs/memory/multi-user-threads.md +4 -4
  35. package/.docs/docs/memory/observational-memory.md +78 -3
  36. package/.docs/docs/memory/overview.md +4 -0
  37. package/.docs/docs/memory/working-memory.md +1 -1
  38. package/.docs/docs/observability/integrations/bridges/otel.md +1 -3
  39. package/.docs/docs/observability/integrations/exporters/braintrust.md +34 -2
  40. package/.docs/docs/observability/integrations/exporters/otel.md +1 -3
  41. package/.docs/docs/server/auth/simple-auth.md +1 -3
  42. package/.docs/docs/server/request-context.md +2 -0
  43. package/.docs/docs/studio/overview.md +2 -0
  44. package/.docs/docs/voice/livekit.md +1 -1
  45. package/.docs/docs/workflows/control-flow.md +1 -3
  46. package/.docs/guides/build-your-ui/ai-sdk-ui.md +1 -0
  47. package/.docs/guides/guide/signal-provider.md +2 -0
  48. package/.docs/guides/migrations/vnext-to-standard-apis.md +1 -3
  49. package/.docs/models/environment-variables.md +1 -0
  50. package/.docs/models/gateways/openrouter.md +339 -345
  51. package/.docs/models/gateways/vercel.md +6 -5
  52. package/.docs/models/index.md +1 -1
  53. package/.docs/models/providers/ambient.md +12 -10
  54. package/.docs/models/providers/baseten.md +3 -2
  55. package/.docs/models/providers/crossmodel.md +2 -1
  56. package/.docs/models/providers/deepinfra.md +4 -7
  57. package/.docs/models/providers/empiriolabs.md +2 -1
  58. package/.docs/models/providers/evroc.md +3 -2
  59. package/.docs/models/providers/google.md +2 -2
  60. package/.docs/models/providers/kilo.md +1 -1
  61. package/.docs/models/providers/kimi-for-coding.md +10 -11
  62. package/.docs/models/providers/llmgateway.md +3 -8
  63. package/.docs/models/providers/moonshotai-cn.md +3 -2
  64. package/.docs/models/providers/moonshotai.md +3 -2
  65. package/.docs/models/providers/nebius.md +3 -1
  66. package/.docs/models/providers/ollama-cloud.md +25 -42
  67. package/.docs/models/providers/opencode-go.md +5 -3
  68. package/.docs/models/providers/orcarouter.md +1 -1
  69. package/.docs/models/providers/privatemode-ai.md +10 -10
  70. package/.docs/models/providers/thinkingmachines.md +73 -0
  71. package/.docs/models/providers/togetherai.md +2 -6
  72. package/.docs/models/providers/zenmux.md +2 -1
  73. package/.docs/models/providers.md +1 -0
  74. package/.docs/reference/acp/acp-agent.md +2 -0
  75. package/.docs/reference/acp/create-acp-tool.md +28 -0
  76. package/.docs/reference/agent-controller/agent-controller-class.md +1 -1
  77. package/.docs/reference/agent-controller/session.md +15 -0
  78. package/.docs/reference/agents/agent.md +14 -2
  79. package/.docs/reference/agents/durable-agent.md +23 -0
  80. package/.docs/reference/agents/generate.md +19 -1
  81. package/.docs/reference/browser/firecrawl-browser.md +71 -0
  82. package/.docs/reference/cli/mastra.md +14 -6
  83. package/.docs/reference/code-sdk/mount-agent-controller.md +1 -3
  84. package/.docs/reference/core/getMCPServer.md +1 -3
  85. package/.docs/reference/core/getMCPServerById.md +1 -3
  86. package/.docs/reference/core/getTool.md +33 -0
  87. package/.docs/reference/core/getToolById.md +48 -0
  88. package/.docs/reference/core/getWorkflow.md +1 -3
  89. package/.docs/reference/core/listMCPServers.md +2 -6
  90. package/.docs/reference/core/listTools.md +38 -0
  91. package/.docs/reference/core/mastra-class.md +1 -1
  92. package/.docs/reference/datasets/addItem.md +1 -3
  93. package/.docs/reference/datasets/addItems.md +1 -3
  94. package/.docs/reference/datasets/compareExperiments.md +1 -3
  95. package/.docs/reference/datasets/create.md +1 -3
  96. package/.docs/reference/datasets/dataset.md +2 -6
  97. package/.docs/reference/datasets/datasets-manager.md +5 -15
  98. package/.docs/reference/datasets/delete.md +1 -3
  99. package/.docs/reference/datasets/deleteExperiment.md +1 -3
  100. package/.docs/reference/datasets/deleteItem.md +1 -3
  101. package/.docs/reference/datasets/deleteItems.md +1 -3
  102. package/.docs/reference/datasets/get.md +1 -3
  103. package/.docs/reference/datasets/getDetails.md +1 -3
  104. package/.docs/reference/datasets/getExperiment.md +1 -3
  105. package/.docs/reference/datasets/getItem.md +1 -3
  106. package/.docs/reference/datasets/getItemHistory.md +1 -3
  107. package/.docs/reference/datasets/list.md +1 -3
  108. package/.docs/reference/datasets/listExperimentResults.md +1 -3
  109. package/.docs/reference/datasets/listExperiments.md +1 -3
  110. package/.docs/reference/datasets/listItems.md +1 -3
  111. package/.docs/reference/datasets/listVersions.md +1 -3
  112. package/.docs/reference/datasets/startExperiment.md +1 -3
  113. package/.docs/reference/datasets/startExperimentAsync.md +1 -3
  114. package/.docs/reference/datasets/update.md +1 -3
  115. package/.docs/reference/datasets/updateItem.md +1 -3
  116. package/.docs/reference/editor/mastra-editor.md +1 -3
  117. package/.docs/reference/evals/create-scorer.md +4 -10
  118. package/.docs/reference/evals/mastra-scorer.md +1 -3
  119. package/.docs/reference/evals/run-evals.md +94 -2
  120. package/.docs/reference/file-based-agents/logger.md +1 -1
  121. package/.docs/reference/file-based-agents/tools.md +7 -6
  122. package/.docs/reference/index.md +5 -0
  123. package/.docs/reference/memory/observational-memory.md +21 -0
  124. package/.docs/reference/observability/tracing/processors/sensitive-data-filter.md +1 -3
  125. package/.docs/reference/processors/token-limiter-processor.md +1 -3
  126. package/.docs/reference/rag/database-config.md +12 -0
  127. package/.docs/reference/storage/clickhouse.md +1 -1
  128. package/.docs/reference/storage/convex.md +17 -10
  129. package/.docs/reference/storage/retention.md +1 -1
  130. package/.docs/reference/streaming/agents/stream.md +3 -1
  131. package/.docs/reference/tools/create-tool.md +78 -52
  132. package/.docs/reference/tools/mcp-client.md +104 -24
  133. package/.docs/reference/tools/mcp-server.md +143 -44
  134. package/.docs/reference/tools/task-tools.md +2 -2
  135. package/.docs/reference/tools/tavily.md +1 -1
  136. package/.docs/reference/tools/vector-query-tool.md +22 -0
  137. package/.docs/reference/vectors/mongodb.md +2 -0
  138. package/.docs/reference/vectors/turbopuffer.md +4 -0
  139. package/.docs/reference/voice/mistral.md +127 -0
  140. package/.docs/reference/workspace/daytona-sandbox.md +2 -6
  141. package/CHANGELOG.md +64 -0
  142. package/dist/{chunk-GLPCVXXO.js → chunk-HGADBLKG.js} +2 -2
  143. package/dist/{chunk-GLPCVXXO.js.map → chunk-HGADBLKG.js.map} +1 -1
  144. package/dist/index.js +1 -1
  145. package/dist/stdio.js +1 -1
  146. package/dist/tools/docs.d.ts.map +1 -1
  147. package/package.json +7 -7
@@ -187,9 +187,7 @@ const server = new MCPServer({
187
187
  id: 'my-server',
188
188
  name: 'My Server',
189
189
  version: '1.0.0',
190
- tools: {
191
- /* ... */
192
- },
190
+ tools: {/* ... */},
193
191
  })
194
192
  await server.startStdio()
195
193
  ```
@@ -353,9 +351,7 @@ const server = new MCPServer({
353
351
  id: 'my-serverless-mcp',
354
352
  name: 'My Serverless MCP',
355
353
  version: '1.0.0',
356
- tools: {
357
- /* your tools */
358
- },
354
+ tools: {/* your tools */},
359
355
  })
360
356
 
361
357
  serve(async req => {
@@ -637,9 +633,7 @@ const serverWithResources = new MCPServer({
637
633
  id: 'resourceful-server',
638
634
  name: 'Resourceful Server',
639
635
  version: '1.0.0',
640
- tools: {
641
- /* ... your tools ... */
642
- },
636
+ tools: {/* ... your tools ... */},
643
637
  resources: myResourceHandlers,
644
638
  })
645
639
  ```
@@ -768,9 +762,7 @@ const serverWithPrompts = new MCPServer({
768
762
  id: 'promptful-server',
769
763
  name: 'Promptful Server',
770
764
  version: '1.0.0',
771
- tools: {
772
- /* ... */
773
- },
765
+ tools: {/* ... */},
774
766
  prompts: myPromptHandlers,
775
767
  })
776
768
  ```
@@ -966,9 +958,7 @@ execute: async (inputData, context) => {
966
958
  // Use elicitation capabilities
967
959
  const result = await context.mcp.elicitation.sendRequest({
968
960
  message: 'Please provide information',
969
- requestedSchema: {
970
- /* schema */
971
- },
961
+ requestedSchema: {/* schema */},
972
962
  })
973
963
 
974
964
  return result
@@ -1159,9 +1149,7 @@ const mcpServer = new MCPServer({
1159
1149
  id: 'protected-server',
1160
1150
  name: 'Protected MCP Server',
1161
1151
  version: '1.0.0',
1162
- tools: {
1163
- /* your tools */
1164
- },
1152
+ tools: {/* your tools */},
1165
1153
  })
1166
1154
 
1167
1155
  // Create OAuth middleware
@@ -1342,21 +1330,48 @@ To pass data to your tools, populate `req.auth` on the Node.js request object in
1342
1330
  ```typescript
1343
1331
  import express from 'express'
1344
1332
 
1333
+ type MCPAuthenticatedRequest = express.Request & {
1334
+ auth?: {
1335
+ token: string
1336
+ clientId: string
1337
+ scopes: string[]
1338
+ expiresAt?: number
1339
+ extra?: Record<string, unknown>
1340
+ }
1341
+ }
1342
+
1345
1343
  const app = express()
1346
1344
 
1347
1345
  // Auth middleware - set req.auth before the MCP handler
1348
- app.use('/mcp', (req, res, next) => {
1349
- const token = req.headers.authorization?.replace('Bearer ', '')
1350
- const user = verifyToken(token)
1351
-
1352
- // This entire object becomes context.mcp.extra.authInfo
1353
- // @ts-ignore - req.auth is read by the MCP SDK
1354
- req.auth = {
1355
- token,
1356
- userId: user.userId,
1357
- email: user.email,
1346
+ app.use('/mcp', async (req, res, next) => {
1347
+ const authorization = req.headers.authorization
1348
+
1349
+ if (!authorization?.startsWith('Bearer ')) {
1350
+ res.status(401).json({ error: 'Missing bearer token' })
1351
+ return
1352
+ }
1353
+
1354
+ const token = authorization.slice('Bearer '.length)
1355
+
1356
+ try {
1357
+ const user = await verifyToken(token)
1358
+
1359
+ // This entire object becomes context.mcp.extra.authInfo
1360
+ const authenticatedRequest = req as MCPAuthenticatedRequest
1361
+ authenticatedRequest.auth = {
1362
+ token,
1363
+ clientId: user.clientId,
1364
+ scopes: user.scopes,
1365
+ expiresAt: user.expiresAt,
1366
+ extra: {
1367
+ userId: user.userId,
1368
+ email: user.email,
1369
+ },
1370
+ }
1371
+ next()
1372
+ } catch {
1373
+ res.status(401).json({ error: 'Invalid or expired token' })
1358
1374
  }
1359
- next()
1360
1375
  })
1361
1376
 
1362
1377
  app.all('/mcp', async (req, res) => {
@@ -1434,19 +1449,86 @@ The full `context.mcp.extra` object contains:
1434
1449
 
1435
1450
  ### Complete Example
1436
1451
 
1437
- Here's a complete example showing the data flow from middleware to tool:
1452
+ Install [`jose`](https://github.com/panva/jose) to verify JSON Web Tokens (JWTs) against your identity provider's JSON Web Key Set (JWKS):
1453
+
1454
+ **npm**:
1455
+
1456
+ ```shell
1457
+ npm install jose
1458
+ ```
1459
+
1460
+ **pnpm**:
1461
+
1462
+ ```shell
1463
+ pnpm add jose
1464
+ ```
1465
+
1466
+ **Yarn**:
1467
+
1468
+ ```shell
1469
+ yarn add jose
1470
+ ```
1471
+
1472
+ **Bun**:
1473
+
1474
+ ```shell
1475
+ bun add jose
1476
+ ```
1477
+
1478
+ The following example validates the token's signature, issuer, audience, algorithm, expiration, and required claims before passing its user data to the tool:
1438
1479
 
1439
1480
  ```typescript
1440
1481
  import express from 'express'
1482
+ import { createRemoteJWKSet, jwtVerify } from 'jose'
1441
1483
  import { MCPServer } from '@mastra/mcp'
1442
1484
  import { createTool } from '@mastra/core/tools'
1443
1485
  import { z } from 'zod'
1444
1486
 
1445
- const verifyToken = (token: string) => {
1446
- // TODO: Implement token verification
1487
+ type MCPAuthenticatedRequest = express.Request & {
1488
+ auth?: {
1489
+ token: string
1490
+ clientId: string
1491
+ scopes: string[]
1492
+ expiresAt?: number
1493
+ extra?: Record<string, unknown>
1494
+ }
1495
+ }
1496
+
1497
+ const issuer = process.env.JWT_ISSUER
1498
+ const audience = process.env.JWT_AUDIENCE
1499
+ const jwksUri = process.env.JWT_JWKS_URI
1500
+
1501
+ if (!issuer || !audience || !jwksUri) {
1502
+ throw new Error('JWT_ISSUER, JWT_AUDIENCE, and JWT_JWKS_URI are required')
1503
+ }
1504
+
1505
+ const jwks = createRemoteJWKSet(new URL(jwksUri))
1506
+
1507
+ const verifyToken = async (token: string) => {
1508
+ const { payload } = await jwtVerify(token, jwks, {
1509
+ issuer,
1510
+ audience,
1511
+ algorithms: ['RS256'],
1512
+ requiredClaims: ['exp'],
1513
+ })
1514
+
1515
+ const clientId =
1516
+ typeof payload.client_id === 'string'
1517
+ ? payload.client_id
1518
+ : typeof payload.azp === 'string'
1519
+ ? payload.azp
1520
+ : undefined
1521
+
1522
+ if (!payload.sub || typeof payload.email !== 'string' || !clientId || !payload.exp) {
1523
+ throw new Error('Token must contain sub, email, exp, and client_id or azp claims')
1524
+ }
1525
+
1447
1526
  return {
1448
- userId: '123',
1449
- email: 'test@test.com',
1527
+ userId: payload.sub,
1528
+ clientId,
1529
+ email: payload.email,
1530
+ expiresAt: payload.exp,
1531
+ scopes: typeof payload.scope === 'string' ? payload.scope.split(' ') : [],
1450
1532
  }
1451
1533
  }
1452
1534
 
@@ -1481,18 +1563,35 @@ const server = new MCPServer({
1481
1563
  // 3. Set up Express with auth middleware
1482
1564
  const app = express()
1483
1565
 
1484
- app.use('/mcp', (req, res, next) => {
1485
- const token = req.headers.authorization?.replace('Bearer ', '')
1486
- const user = verifyToken(token)
1566
+ app.use('/mcp', async (req, res, next) => {
1567
+ const authorization = req.headers.authorization
1568
+
1569
+ if (!authorization?.startsWith('Bearer ')) {
1570
+ res.status(401).json({ error: 'Missing bearer token' })
1571
+ return
1572
+ }
1487
1573
 
1488
- // This entire object becomes context.mcp.extra.authInfo
1489
- // @ts-ignore - req.auth is read by the MCP SDK
1490
- req.auth = {
1491
- token,
1492
- userId: user.userId,
1493
- email: user.email,
1574
+ const token = authorization.slice('Bearer '.length)
1575
+
1576
+ try {
1577
+ const user = await verifyToken(token)
1578
+
1579
+ // This entire object becomes context.mcp.extra.authInfo
1580
+ const authenticatedRequest = req as MCPAuthenticatedRequest
1581
+ authenticatedRequest.auth = {
1582
+ token,
1583
+ clientId: user.clientId,
1584
+ scopes: user.scopes,
1585
+ expiresAt: user.expiresAt,
1586
+ extra: {
1587
+ userId: user.userId,
1588
+ email: user.email,
1589
+ },
1590
+ }
1591
+ next()
1592
+ } catch {
1593
+ res.status(401).json({ error: 'Invalid or expired token' })
1494
1594
  }
1495
- next()
1496
1595
  })
1497
1596
 
1498
1597
  app.all('/mcp', async (req, res) => {
@@ -85,7 +85,7 @@ At least one of `content`, `status`, or `activeForm` is required.
85
85
  ### Behavior
86
86
 
87
87
  - When the update sets a task to `in_progress`, any other `in_progress` task is automatically demoted to `pending`.
88
- - Returns an error with available task IDs when the ID is not found.
88
+ - Returns an error with available task IDs when the ID isn't found.
89
89
 
90
90
  ## `task_complete`
91
91
 
@@ -97,7 +97,7 @@ Mark one task completed by its stable ID.
97
97
 
98
98
  ### Behavior
99
99
 
100
- Returns an error with available task IDs when the ID is not found.
100
+ Returns an error with available task IDs when the ID isn't found.
101
101
 
102
102
  ## `task_check`
103
103
 
@@ -59,7 +59,7 @@ All factory functions accept `TavilyClientOptions` from `@tavily/core`:
59
59
 
60
60
  **apiKey** (`string`): Tavily API key. Falls back to the TAVILY\_API\_KEY environment variable.
61
61
 
62
- **clientSource** (`string`): Attribution string sent with each request. (Default: `'mastra'`)
62
+ **clientName** (`string`): Attribution string sent with each request in the X-Client-Name header. (Default: `'mastra'`)
63
63
 
64
64
  **apiBaseURL** (`string`): Base URL for the Tavily API.
65
65
 
@@ -269,6 +269,28 @@ const chromaQueryTool = createVectorQueryTool({
269
269
  - **whereDocument**: Filter by document content
270
270
  - **Use Cases**: Advanced filtering, content-based search
271
271
 
272
+ **Turbopuffer**:
273
+
274
+ ### Turbopuffer Configuration
275
+
276
+ ```typescript
277
+ const turbopufferQueryTool = createVectorQueryTool({
278
+ vectorStoreName: 'turbopuffer',
279
+ indexName: 'docs',
280
+ model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
281
+ databaseConfig: {
282
+ turbopuffer: {
283
+ consistency: 'eventual', // Lower latency, recently written data may not be visible yet
284
+ },
285
+ },
286
+ })
287
+ ```
288
+
289
+ **Turbopuffer Features:**
290
+
291
+ - **consistency**: Choose between `strong` (default, read-your-writes) and `eventual` (lower latency)
292
+ - **Use Cases**: Latency-sensitive queries where slightly stale data is acceptable
293
+
272
294
  **Multiple Configs**:
273
295
 
274
296
  ### Multiple Database Configurations
@@ -89,6 +89,8 @@ Creates a new vector index (collection) in MongoDB.
89
89
 
90
90
  **metric** (`'cosine' | 'euclidean' | 'dotproduct'`): Distance metric for similarity search (Default: `cosine`)
91
91
 
92
+ **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.
93
+
92
94
  ### `waitForIndexReady()`
93
95
 
94
96
  Waits for an index to become ready after creation. Useful when you need to ensure an index is ready before performing operations.
@@ -18,6 +18,8 @@ The TurbopufferVector class provides vector search using [Turbopuffer](https://t
18
18
 
19
19
  **compression** (`boolean`): Whether to compress requests and accept compressed responses. (Default: `true`)
20
20
 
21
+ **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`)
22
+
21
23
  **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.
22
24
 
23
25
  ## Methods
@@ -50,6 +52,8 @@ The TurbopufferVector class provides vector search using [Turbopuffer](https://t
50
52
 
51
53
  **includeVector** (`boolean`): Whether to include vectors in the results (Default: `false`)
52
54
 
55
+ **consistency** (`'strong' | 'eventual'`): The consistency level for this query. Overrides the consistency level set in the constructor. Defaults to "strong".
56
+
53
57
  ### `listIndexes()`
54
58
 
55
59
  Returns an array of index names as strings.
@@ -0,0 +1,127 @@
1
+ > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
2
+
3
+ # Mistral
4
+
5
+ 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.
6
+
7
+ ## Usage example
8
+
9
+ ```typescript
10
+ import { MistralVoice } from '@mastra/voice-mistral'
11
+
12
+ const voice = new MistralVoice()
13
+
14
+ // Text-to-speech
15
+ const audioStream = await voice.speak('Hello, how can I help you?', {
16
+ responseFormat: 'mp3',
17
+ })
18
+
19
+ // Speech-to-text
20
+ const text = await voice.listen(audioStream, {
21
+ language: 'en',
22
+ })
23
+
24
+ // List available voices
25
+ const speakers = await voice.getSpeakers()
26
+ ```
27
+
28
+ ```typescript
29
+ import { MistralVoice } from '@mastra/voice-mistral'
30
+
31
+ // Initialize with specific configuration
32
+ const voice = new MistralVoice({
33
+ speechModel: {
34
+ name: 'voxtral-mini-tts-2603',
35
+ apiKey: 'your-mistral-api-key',
36
+ },
37
+ listeningModel: {
38
+ name: 'voxtral-mini-latest',
39
+ apiKey: 'your-mistral-api-key',
40
+ },
41
+ speaker: 'en_paul_neutral',
42
+ })
43
+ ```
44
+
45
+ ## Constructor parameters
46
+
47
+ **speechModel** (`MistralModelConfig`): Configuration for text-to-speech synthesis. (Default: `{ name: 'voxtral-mini-tts-2603' }`)
48
+
49
+ **speechModel.name** (`string`): Model ID for speech synthesis.
50
+
51
+ **speechModel.apiKey** (`string`): Mistral API key. Falls back to MISTRAL\_API\_KEY environment variable.
52
+
53
+ **listeningModel** (`MistralModelConfig`): Configuration for speech-to-text recognition. (Default: `{ name: 'voxtral-mini-latest' }`)
54
+
55
+ **listeningModel.name** (`string`): Model ID for transcription. Use 'voxtral-mini-2507' for a pinned version.
56
+
57
+ **listeningModel.apiKey** (`string`): Mistral API key. Falls back to MISTRAL\_API\_KEY environment variable.
58
+
59
+ **speaker** (`string`): Default voice ID for speech synthesis. Retrieve available IDs from getSpeakers(). (Default: `'en_paul_neutral'`)
60
+
61
+ ## Methods
62
+
63
+ ### `speak(input, options?)`
64
+
65
+ Converts text to speech using Mistral's Voxtral TTS model. Supports both buffered and streaming output.
66
+
67
+ **input** (`string | NodeJS.ReadableStream`): Text or text stream to convert to speech.
68
+
69
+ **options** (`MistralSpeakOptions`): Configuration options.
70
+
71
+ **options.speaker** (`string`): Voice ID to use. Overrides the constructor default.
72
+
73
+ **options.responseFormat** (`'pcm' | 'wav' | 'mp3' | 'flac' | 'opus'`): Audio output format. Use 'pcm' for lowest latency streaming.
74
+
75
+ **options.refAudio** (`string`): Base64-encoded reference audio for one-off voice cloning (minimum 2-3 seconds).
76
+
77
+ **options.model** (`string`): Override the speech model for this call.
78
+
79
+ **options.stream** (`boolean`): Enable streaming TTS. Audio chunks are written to the stream as they arrive.
80
+
81
+ Returns: `Promise<NodeJS.ReadableStream>`
82
+
83
+ ### `listen(audioStream, options?)`
84
+
85
+ Transcribes audio using Mistral's Voxtral transcription model. Supports diarization, context biasing, and timestamp granularity.
86
+
87
+ **audioStream** (`NodeJS.ReadableStream`): Audio stream to transcribe.
88
+
89
+ **options** (`MistralListenOptions`): Configuration options.
90
+
91
+ **options.language** (`string`): Language code (e.g., 'en'). Improves accuracy when specified.
92
+
93
+ **options.diarize** (`boolean`): Enable speaker diarization.
94
+
95
+ **options.contextBias** (`string[]`): Words or phrases for vocabulary guidance.
96
+
97
+ **options.timestampGranularities** (`('segment' | 'word')[]`): Timestamp detail level for transcription segments.
98
+
99
+ **options.filetype** (`string`): Audio file extension hint for the input stream.
100
+
101
+ Returns: `Promise<string>`
102
+
103
+ ### `getSpeakers()`
104
+
105
+ Fetches available preset voices from the Mistral Voices API. Each entry contains:
106
+
107
+ **voiceId** (`string`): Unique identifier for the voice.
108
+
109
+ **name** (`string`): Display name of the voice.
110
+
111
+ **languages** (`string[]`): Languages supported by the voice.
112
+
113
+ **gender** (`string | null`): Gender of the voice.
114
+
115
+ ### `getListener()`
116
+
117
+ Returns `{ enabled: true }`.
118
+
119
+ ## Notes
120
+
121
+ - API keys can be provided via constructor options or the `MISTRAL_API_KEY` environment variable
122
+ - TTS supports 9 languages: English, French, Spanish, Portuguese, Italian, Dutch, German, Hindi, Arabic
123
+ - STT supports 13 languages: English, Chinese, Hindi, Spanish, Arabic, French, Portuguese, Russian, German, Japanese, Korean, Italian, Dutch
124
+ - TTS input text should be kept under 300 words per request for best results
125
+ - STT supports up to 3 hours of audio per request
126
+ - Voice cloning via `refAudio` requires a minimum of 2-3 seconds of reference audio
127
+ - `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
@@ -440,12 +440,8 @@ Then use the snapshot name in your sandbox config:
440
440
  ```typescript
441
441
  const workspace = new Workspace({
442
442
  mounts: {
443
- '/s3-data': new S3Filesystem({
444
- /* ... */
445
- }),
446
- '/gcs-data': new GCSFilesystem({
447
- /* ... */
448
- }),
443
+ '/s3-data': new S3Filesystem({/* ... */}),
444
+ '/gcs-data': new GCSFilesystem({/* ... */}),
449
445
  },
450
446
  sandbox: new DaytonaSandbox({ snapshot: 'cloud-fs-mounting' }),
451
447
  })
package/CHANGELOG.md CHANGED
@@ -1,5 +1,69 @@
1
1
  # @mastra/mcp-docs-server
2
2
 
3
+ ## 1.2.8-alpha.16
4
+
5
+ ### Patch Changes
6
+
7
+ - Updated dependencies [[`3b77e77`](https://github.com/mastra-ai/mastra/commit/3b77e7704936522e4769d29de1b5ea6901f302bd), [`6b1bf3b`](https://github.com/mastra-ai/mastra/commit/6b1bf3b9494bd51aa8f654c68c9355d6046fa2a1), [`72e437c`](https://github.com/mastra-ai/mastra/commit/72e437c515942c80b9def5b026e0bdee61b469d9)]:
8
+ - @mastra/core@1.52.0-alpha.8
9
+
10
+ ## 1.2.8-alpha.14
11
+
12
+ ### Patch Changes
13
+
14
+ - Updated dependencies [[`b7e79c3`](https://github.com/mastra-ai/mastra/commit/b7e79c3c02ac5cd415db34ba0975ceafc1464333), [`b75d749`](https://github.com/mastra-ai/mastra/commit/b75d749621ff5d17e86bcb4ee809d301fb4f7cf3), [`a8799bb`](https://github.com/mastra-ai/mastra/commit/a8799bb8e44f4a60d01e4e2acd3448ff80bf14f8)]:
15
+ - @mastra/core@1.52.0-alpha.7
16
+
17
+ ## 1.2.8-alpha.12
18
+
19
+ ### Patch Changes
20
+
21
+ - Updated dependencies [[`a40adeb`](https://github.com/mastra-ai/mastra/commit/a40adeb222b961a56a58af56a106106525721b74), [`821648b`](https://github.com/mastra-ai/mastra/commit/821648bf2871ef840100c7bacbecf676010bd12a), [`11f6cd9`](https://github.com/mastra-ai/mastra/commit/11f6cd96fe42582403416608beb212cc1a2cc79e)]:
22
+ - @mastra/core@1.52.0-alpha.6
23
+
24
+ ## 1.2.8-alpha.10
25
+
26
+ ### Patch Changes
27
+
28
+ - Updated dependencies [[`ec857fc`](https://github.com/mastra-ai/mastra/commit/ec857fc79c264b53b38e16478c789b7177f2ad59), [`e1f2fae`](https://github.com/mastra-ai/mastra/commit/e1f2faebaf048c3d4c2e2c01d293767c195d5794), [`63aa799`](https://github.com/mastra-ai/mastra/commit/63aa799c6b44eacc7806cda6846b7c5bbee06b37), [`73db8db`](https://github.com/mastra-ai/mastra/commit/73db8db90d69ab6153c7942749f624db0d96952d), [`73db8db`](https://github.com/mastra-ai/mastra/commit/73db8db90d69ab6153c7942749f624db0d96952d), [`76b7181`](https://github.com/mastra-ai/mastra/commit/76b71810366e6d90b9d3973149d1c7ba3659ffb9), [`0c0e8d7`](https://github.com/mastra-ai/mastra/commit/0c0e8d7becd4d1445c656b78d5d845f606c1ff9d), [`9f7c67a`](https://github.com/mastra-ai/mastra/commit/9f7c67abeeb52c41c51a9b5edee60b62afe7cd8d), [`3b65e68`](https://github.com/mastra-ai/mastra/commit/3b65e68d7f1c771c7a70eea42d83fefdd28cad88), [`e3868e2`](https://github.com/mastra-ai/mastra/commit/e3868e22babfffd0133771669ca724501c2dd58e)]:
29
+ - @mastra/core@1.52.0-alpha.5
30
+
31
+ ## 1.2.8-alpha.8
32
+
33
+ ### Patch Changes
34
+
35
+ - Updated dependencies [[`4cfdd64`](https://github.com/mastra-ai/mastra/commit/4cfdd645794feaea0c4ea711e70ecdfbef0c5b8e)]:
36
+ - @mastra/core@1.52.0-alpha.4
37
+
38
+ ## 1.2.8-alpha.6
39
+
40
+ ### Patch Changes
41
+
42
+ - Updated dependencies [[`1426af2`](https://github.com/mastra-ai/mastra/commit/1426af24975879c000d13ac75673f630fcc970c1), [`975295d`](https://github.com/mastra-ai/mastra/commit/975295d418552f0d46a59edfef4c3ee555f9930a), [`85e4fb5`](https://github.com/mastra-ai/mastra/commit/85e4fb50087a81c74df3a762f53b56373db0b912), [`ef03c0c`](https://github.com/mastra-ai/mastra/commit/ef03c0cfc62367a458e4cc56462e2148b35681c5), [`4fb4d88`](https://github.com/mastra-ai/mastra/commit/4fb4d881bc107acee13890ad4d78661016c510ed), [`4eba27a`](https://github.com/mastra-ai/mastra/commit/4eba27adcf60f991df0e62f94b3e75b4e67f3b4b), [`c701be3`](https://github.com/mastra-ai/mastra/commit/c701be32d7d9aa94a66da8c6cc38dcac6856f464)]:
43
+ - @mastra/core@1.52.0-alpha.3
44
+
45
+ ## 1.2.8-alpha.4
46
+
47
+ ### Patch Changes
48
+
49
+ - Updated dependencies [[`8b20926`](https://github.com/mastra-ai/mastra/commit/8b20926cd59e2ba3d66458e062fa0e6e2ada3e68), [`74faf8b`](https://github.com/mastra-ai/mastra/commit/74faf8bd9c1018f2492653c06b1e25fc8300e9e6), [`1fadac4`](https://github.com/mastra-ai/mastra/commit/1fadac44537caeefe81f9f775ae2f2f3d94e9069), [`970c032`](https://github.com/mastra-ai/mastra/commit/970c032502751ee5dd4d0b603331d9838cb538fc), [`792ec9a`](https://github.com/mastra-ai/mastra/commit/792ec9a0869bab8274cf5e0ed2840738737a1607), [`712b864`](https://github.com/mastra-ai/mastra/commit/712b864aa1ed12b14c54390ec17b69de163c37f7), [`8f7a5de`](https://github.com/mastra-ai/mastra/commit/8f7a5dedc246cdc938bb65516703cf9b27b03756), [`c0bec73`](https://github.com/mastra-ai/mastra/commit/c0bec732c93d1a22ae5e51ed66cf8cacca8bd6a6)]:
50
+ - @mastra/core@1.52.0-alpha.2
51
+ - @mastra/mcp@1.15.0-alpha.0
52
+
53
+ ## 1.2.8-alpha.3
54
+
55
+ ### Patch Changes
56
+
57
+ - Updated dependencies:
58
+ - @mastra/core@1.51.1-alpha.1
59
+
60
+ ## 1.2.8-alpha.1
61
+
62
+ ### Patch Changes
63
+
64
+ - Updated dependencies [[`8a0d145`](https://github.com/mastra-ai/mastra/commit/8a0d145aadbdf7278665aceaaec364b35dd9bd94), [`bd2f1d2`](https://github.com/mastra-ai/mastra/commit/bd2f1d274d05e60e2366f005ea0d94d5cea0d5ff), [`21a0eb8`](https://github.com/mastra-ai/mastra/commit/21a0eb86746ba0b703acea360d4f84c6a5a493f2), [`de86fd7`](https://github.com/mastra-ai/mastra/commit/de86fd7119f0438381d1a642e3d258143c0b9c29), [`2745031`](https://github.com/mastra-ai/mastra/commit/2745031d1d4a4978f037092da371428c32e2842a), [`db650ce`](https://github.com/mastra-ai/mastra/commit/db650ce490348914e85b93651d83acdf8f2a4c31), [`6354eeb`](https://github.com/mastra-ai/mastra/commit/6354eeb32efa9f5f68f51dda394e90e2ee76f1fb)]:
65
+ - @mastra/core@1.51.1-alpha.0
66
+
3
67
  ## 1.2.7
4
68
 
5
69
  ### Patch Changes
@@ -2071,5 +2071,5 @@ async function runServer() {
2071
2071
  }
2072
2072
 
2073
2073
  export { runServer, server, setLogLevel, writeErrorLog };
2074
- //# sourceMappingURL=chunk-GLPCVXXO.js.map
2075
- //# sourceMappingURL=chunk-GLPCVXXO.js.map
2074
+ //# sourceMappingURL=chunk-HGADBLKG.js.map
2075
+ //# sourceMappingURL=chunk-HGADBLKG.js.map