@mastra/mcp-docs-server 1.1.35-alpha.21 → 1.1.35-alpha.26

package/.docs/reference/tools/brightdata.md

@@ -0,0 +1,167 @@
+# Bright Data tools
+
+The `@mastra/brightdata` package wraps the [Bright Data SDK](https://github.com/brightdata/bright-data-sdk-node) as Mastra-compatible tools. It exposes factory functions for web search and web fetch — each returning a tool created with [`createTool()`](https://mastra.ai/reference/tools/create-tool) that includes full Zod input/output schemas.
+
+The search tool is backed by Bright Data's [SERP API](https://brightdata.com/products/serp-api) and the fetch tool by [Web Unlocker](https://brightdata.com/products/web-unlocker). Both bypass bot detection and CAPTCHAs.
+
+## Installation
+
+**npm**:
+
+```sh
+npm install @mastra/brightdata zod
+```
+
+**pnpm**:
+
+```sh
+pnpm add @mastra/brightdata zod
+```
+
+**Yarn**:
+
+```sh
+yarn add @mastra/brightdata zod
+```
+
+**Bun**:
+
+```sh
+bun add @mastra/brightdata zod
+```
+
+## Quick start
+
+Use `createBrightDataTools()` to get both tools with shared configuration:
+
+```typescript
+import { createBrightDataTools } from '@mastra/brightdata'
+
+const { webSearch, webFetch } = createBrightDataTools()
+// Or pass an explicit API key:
+// const { webSearch, webFetch } = createBrightDataTools({ apiKey: 'brd-...' })
+```
+
+Each tool can also be created individually:
+
+```typescript
+import { createBrightDataSearchTool, createBrightDataFetchTool } from '@mastra/brightdata'
+
+const searchTool = createBrightDataSearchTool()
+const fetchTool = createBrightDataFetchTool({ apiKey: 'brd-...' })
+```
+
+By default, all tools read `BRIGHTDATA_API_TOKEN` from the environment. You can pass `{ apiKey }` explicitly to override.
+
+## Configuration
+
+All factory functions accept `BrightDataClientOptions` from `@brightdata/sdk`:
+
+**apiKey** (`string`): Bright Data API token. Falls back to the \`BRIGHTDATA\_API\_TOKEN\` environment variable.
+
+Additional fields supported by the `bdclient` constructor (such as `timeout`, `webUnlockerZone`, `serpZone`, and `rateLimit`) can be passed through the same options object.
+
+## `createBrightDataTools()`
+
+Returns an object containing both tools with a shared configuration.
+
+```typescript
+import { createBrightDataTools } from '@mastra/brightdata'
+
+const tools = createBrightDataTools({ apiKey: 'brd-...' })
+// tools.webSearch, tools.webFetch
+```
+
+**Returns:** `{ webSearch, webFetch }`
+
+## `createBrightDataSearchTool()`
+
+Creates a tool that searches Google through Bright Data's SERP API. Returns parsed organic results.
+
+**Tool ID:** `brightdata-search`
+
+```typescript
+import { createBrightDataSearchTool } from '@mastra/brightdata'
+
+const searchTool = createBrightDataSearchTool()
+```
+
+### Input
+
+**query** (`string`): The search query.
+
+**country** (`string`): Two-letter country code for geo-targeted results (for example, \`us\` or \`gb\`).
+
+**start** (`number`): Result offset for pagination. For example, \`10\` returns the second page of 10 results.
+
+### Output
+
+**query** (`string`): The original search query.
+
+**results** (`SearchResult[]`): Organic search results. Entries missing a link or title are filtered out.
+
+**results.link** (`string`): Result URL.
+
+**results.title** (`string`): Result title.
+
+**results.description** (`string`): Result snippet.
+
+**currentPage** (`number`): Page number returned by the SERP API. Defaults to \`1\` when the upstream response omits or returns a non-positive value.
+
+## `createBrightDataFetchTool()`
+
+Creates a tool that fetches a webpage through Bright Data's Web Unlocker and returns the page content as Markdown.
+
+**Tool ID:** `brightdata-fetch`
+
+```typescript
+import { createBrightDataFetchTool } from '@mastra/brightdata'
+
+const fetchTool = createBrightDataFetchTool()
+```
+
+### Input
+
+**url** (`string`): The URL to fetch. Must be a valid HTTP or HTTPS URL.
+
+### Output
+
+**url** (`string`): The input URL.
+
+**content** (`string`): Page content as Markdown.
+
+## Agent example
+
+The following example demonstrates a research agent that combines search and fetch:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { createBrightDataTools } from '@mastra/brightdata'
+
+const { webSearch, webFetch } = createBrightDataTools()
+
+const agent = new Agent({
+  id: 'research-agent',
+  name: 'Research Agent',
+  model: 'anthropic/claude-sonnet-4-6',
+  instructions:
+    'You are a research assistant. Use the search tool to find relevant pages, then use the fetch tool to read full Markdown content from the best results.',
+  tools: {
+    webSearch,
+    webFetch,
+  },
+})
+```
+
+## Environment variables
+
+| Variable               | Description                                                                                        |
+| ---------------------- | -------------------------------------------------------------------------------------------------- |
+| `BRIGHTDATA_API_TOKEN` | Your Bright Data API token. Used as the default when `apiKey` is not passed to a factory function. |
+
+## Related
+
+- [`createTool()`](https://mastra.ai/reference/tools/create-tool)
+- [Bright Data SERP API](https://brightdata.com/products/serp-api)
+- [Bright Data Web Unlocker](https://brightdata.com/products/web-unlocker)
+- [Bright Data SDK for Node.js](https://github.com/brightdata/bright-data-sdk-node)

package/.docs/reference/voice/inworld.md

@@ -0,0 +1,133 @@
+# Inworld
+
+The Inworld voice implementation in Mastra provides streaming text-to-speech (TTS) and batch speech-to-text (STT) capabilities using Inworld AI's API. It supports multiple TTS and STT models, configurable audio encodings, and progressive audio streaming.
+
+## Usage example
+
+```typescript
+import { InworldVoice } from '@mastra/voice-inworld'
+
+// Initialize with default configuration (uses INWORLD_API_KEY environment variable)
+const voice = new InworldVoice()
+
+// Initialize with custom configuration
+const voice = new InworldVoice({
+  speechModel: {
+    name: 'inworld-tts-2',
+    apiKey: 'your-api-key',
+  },
+  listeningModel: {
+    name: 'groq/whisper-large-v3',
+    apiKey: 'your-api-key',
+  },
+  speaker: 'Dennis',
+})
+
+// Text-to-Speech (streaming)
+const audioStream = await voice.speak('Hello, world!')
+
+// Speech-to-Text
+const transcript = await voice.listen(audioStream)
+```
+
+## Constructor parameters
+
+**speechModel** (`InworldVoiceConfig`): Configuration for text-to-speech functionality. (Default: `{ name: 'inworld-tts-2' }`)
+
+**speechModel.name** (`'inworld-tts-2' | 'inworld-tts-1.5-max' | 'inworld-tts-1.5-mini'`): The Inworld TTS model to use.
+
+**speechModel.apiKey** (`string`): Inworld API key. Falls back to INWORLD\_API\_KEY environment variable.
+
+**listeningModel** (`InworldListeningConfig`): Configuration for speech-to-text functionality. (Default: `{ name: 'groq/whisper-large-v3' }`)
+
+**listeningModel.name** (`'groq/whisper-large-v3'`): The Inworld STT model to use.
+
+**listeningModel.apiKey** (`string`): Inworld API key. Falls back to INWORLD\_API\_KEY environment variable.
+
+**speaker** (`string`): Default voice ID to use for text-to-speech. (Default: `'Dennis'`)
+
+**audioEncoding** (`'LINEAR16' | 'MP3' | 'OGG_OPUS' | 'ALAW' | 'MULAW' | 'FLAC' | 'PCM' | 'WAV'`): Default audio encoding for TTS output. (Default: `'MP3'`)
+
+**sampleRateHertz** (`number`): Default sample rate for TTS output. (Default: `48000`)
+
+**language** (`string`): Default BCP-47 language code for STT. (Default: `'en-US'`)
+
+## Methods
+
+### `speak(input, options?)`
+
+Converts text to speech using Inworld's streaming TTS endpoint. Returns a readable stream that emits audio chunks progressively as they arrive.
+
+```typescript
+const audioStream = await voice.speak('Hello, world!', {
+  speaker: 'Olivia',
+  audioEncoding: 'WAV',
+  sampleRateHertz: 24000,
+  speakingRate: 1.2,
+  temperature: 0.8,
+})
+```
+
+**input** (`string | NodeJS.ReadableStream`): Text to convert to speech. If a stream is provided, it will be converted to text first.
+
+**options** (`InworldSpeakOptions`): Additional options for speech synthesis.
+
+**options.speaker** (`string`): Override the default speaker for this request.
+
+**options.audioEncoding** (`AudioEncoding`): Override the default audio encoding.
+
+**options.sampleRateHertz** (`number`): Override the default sample rate.
+
+**options.speakingRate** (`number`): Adjust the speaking rate.
+
+**options.temperature** (`number`): Controls voice variability. Honored on \`inworld-tts-1.5-\*\` models; ignored by \`inworld-tts-2\`.
+
+**options.deliveryMode** (`'STABLE' | 'BALANCED' | 'CREATIVE'`): Steering control for delivery style. Only honored by \`inworld-tts-2\`.
+
+**options.language** (`string`): BCP-47 language code for this request. Auto-detected when omitted.
+
+**Returns:** `Promise<NodeJS.ReadableStream>`
+
+### `listen(input, options?)`
+
+Converts speech to text using Inworld's batch STT endpoint.
+
+```typescript
+const transcript = await voice.listen(audioStream, {
+  audioEncoding: 'MP3',
+  sampleRateHertz: 44100,
+  language: 'ja-JP',
+})
+```
+
+**input** (`NodeJS.ReadableStream`): Audio stream to transcribe.
+
+**options** (`InworldListenOptions`): Additional options for transcription.
+
+**options.audioEncoding** (`'LINEAR16' | 'MP3' | 'OGG_OPUS' | 'FLAC' | 'AUTO_DETECT'`): Audio encoding of the input stream.
+
+**options.sampleRateHertz** (`number`): Sample rate of the input audio.
+
+**options.language** (`string`): BCP-47 language code for transcription.
+
+**options.numberOfChannels** (`number`): Number of audio channels in the input.
+
+**Returns:** `Promise<string>`
+
+### `getSpeakers()`
+
+Returns a list of available voices from the Inworld API.
+
+```typescript
+const speakers = await voice.getSpeakers()
+// [{ voiceId: 'Dennis', name: 'Dennis', language: 'en', description: '...', tags: ['friendly'], source: 'SYSTEM' }, ...]
+```
+
+**Returns:** `Promise<Array<{ voiceId: string; name: string; language: string; description: string; tags: string[]; source: string }>>`
+
+## Notes
+
+- The TTS endpoint uses progressive NDJSON streaming, so audio playback can begin before the full response is received.
+- An API key can be provided via the `speechModel` or `listeningModel` config, or the `INWORLD_API_KEY` environment variable. TTS and STT keys are resolved independently: passing distinct `speechModel.apiKey` and `listeningModel.apiKey` values lets each service use its own credential. If only one is provided, it is reused for both services as a fallback before the env var.
+- `inworld-tts-2` is the default flagship model. Use `deliveryMode` (`STABLE` | `BALANCED` | `CREATIVE`) to steer delivery style on this model. The `temperature` option is ignored on `inworld-tts-2`.
+- The `inworld-tts-1.5-mini` model offers lower latency at the cost of reduced voice quality compared to `inworld-tts-1.5-max`.

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @mastra/mcp-docs-server
 
+## 1.1.35-alpha.25
+
+### Patch Changes
+
+- Updated dependencies [[`f984b4d`](https://github.com/mastra-ai/mastra/commit/f984b4d6c60bf2ae2a9b156f0e8c35a66fe96c91), [`ce01024`](https://github.com/mastra-ai/mastra/commit/ce010242eee9bdfc09e4c26725b9d37998679a8d), [`f984b4d`](https://github.com/mastra-ai/mastra/commit/f984b4d6c60bf2ae2a9b156f0e8c35a66fe96c91), [`8373ff4`](https://github.com/mastra-ai/mastra/commit/8373ff46745d77af79f183c4470f80fa2727a6b2), [`11c1528`](https://github.com/mastra-ai/mastra/commit/11c152848c5d0ef227184853b5040f5b41ee7b1e)]:
+  - @mastra/core@1.33.0-alpha.13
+
+## 1.1.35-alpha.23
+
+### Patch Changes
+
+- Updated dependencies [[`b59316f`](https://github.com/mastra-ai/mastra/commit/b59316ffa0f7688165b0f9c81ccdf85da461e5b2), [`55f1e2d`](https://github.com/mastra-ai/mastra/commit/55f1e2d65425b95a49ae788053b266f256e38c96), [`d48a705`](https://github.com/mastra-ai/mastra/commit/d48a705ff3dfbdc7a996e07ecd8293b5effd9a2a)]:
+  - @mastra/core@1.33.0-alpha.12
+
+## 1.1.35-alpha.22
+
+### Patch Changes
+
+- Updated dependencies [[`37c0dc5`](https://github.com/mastra-ai/mastra/commit/37c0dc5697d343db98628bf867bf71ce6deec6d7), [`ef6b584`](https://github.com/mastra-ai/mastra/commit/ef6b5847ac33c0a7e80af3a86e8801e2933dd3ee), [`4dd900d`](https://github.com/mastra-ai/mastra/commit/4dd900d75dfe9be89f8c15188b368a8622aa1e18), [`4ff5bdf`](https://github.com/mastra-ai/mastra/commit/4ff5bdfe170cba6dfb5260c6af0f4ba668430772), [`bbcd93c`](https://github.com/mastra-ai/mastra/commit/bbcd93cf7d8aa1007d6d84bfd033b8015c912087), [`308bd07`](https://github.com/mastra-ai/mastra/commit/308bd074f35cef0c75d82fc1eb19382fe04ecf6f)]:
+  - @mastra/core@1.33.0-alpha.11
+
 ## 1.1.35-alpha.20
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.1.35-alpha.21",
+  "version": "1.1.35-alpha.26",
   "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.33.0-alpha.10",
-    "@mastra/mcp": "^1.7.0"
+    "@mastra/mcp": "^1.7.0",
+    "@mastra/core": "1.33.0-alpha.13"
   },
   "devDependencies": {
     "@hono/node-server": "^1.19.11",
@@ -46,9 +46,9 @@
     "tsx": "^4.21.0",
     "typescript": "^6.0.3",
     "vitest": "4.1.5",
-    "@mastra/core": "1.33.0-alpha.10",
+    "@internal/lint": "0.0.92",
     "@internal/types-builder": "0.0.67",
-    "@internal/lint": "0.0.92"
+    "@mastra/core": "1.33.0-alpha.13"
   },
   "homepage": "https://mastra.ai",
   "repository": {