@mastra/mcp-docs-server 1.2.23-alpha.10 → 1.2.23-alpha.11

package/.docs/integrations/voice/livekit.md

@@ -414,7 +414,7 @@ See [Realtime voice](#quickstart) for setup and concepts.
 The package has three entry points:
 
 - `@mastra/livekit`: server-side APIs, [`liveKitConnectionRoute()`](#livekitconnectionroute), [`dispatchVoiceSession()`](#dispatchvoicesession), [`pipeAgentReplyToWriter()`](#pipeagentreplytowriter), [`serializeSessionMetadata()`](#livekitsessionmetadata), and [`createEndCallTool()`](#createendcalltool). Import these from Mastra server code. This entry never loads the LiveKit agents runtime.
-- `@mastra/livekit/worker`: the worker runtime, [`createLiveKitWorker()`](#createlivekitworker), [`runLiveKitWorker()`](#runlivekitworker), [`chatContextToMessages()`](#chatcontexttomessages), and the session helpers [`speakGreeting()`](#speakgreeting), [`waitForAgentDoneSpeaking()`](#waitforagentdonespeaking), and [`runEndCall()`](#runendcall). Import it only from the worker entry file.
+- `@mastra/livekit/worker`: the worker runtime, [`createLiveKitWorker()`](#createlivekitworker), [`runLiveKitWorker()`](#runlivekitworker), [`chatContextToMessages()`](#chatcontexttomessages), the per-session agent class [`MastraVoiceAgent`](#mastravoiceagent), and the session helpers [`speakGreeting()`](#speakgreeting), [`waitForAgentDoneSpeaking()`](#waitforagentdonespeaking), and [`runEndCall()`](#runendcall). Import it only from the worker entry file.
 - `@mastra/livekit/plugin`: the LLM-component plugin, [`MastraLLM`](#mastrallm) and [`createRemoteAgentReplyGenerator()`](#createremoteagentreplygenerator). Import it in workers that build their own `voice.AgentSession`. `createRemoteAgentReplyGenerator()` is also exported from `@mastra/livekit/worker` because it plugs into `createLiveKitWorker()`'s `generate` option. `MastraLLM` is plugin-only.
 
 ### `createLiveKitWorker()`
@@ -551,6 +551,56 @@ export default createLiveKitWorker({
 
 Returns: `VoiceTurnMessage[]`, where each entry is `{ role: 'system' | 'user' | 'assistant'; content: string; id?: string }`.
 
+### `MastraVoiceAgent`
+
+The LiveKit `voice.Agent` subclass that [`createLiveKitWorker()`](#createlivekitworker) builds for every session. Replies come from a Mastra agent (or a custom `generate` source) through the agent's `llmNode`; LiveKit keeps the audio loop, turn detection, and barge-in. Construct it yourself when you own the `voice.AgentSession`, for example to test a Mastra-backed agent with `@livekit/agents`' `voice.testing` harness without speech-to-text, text-to-speech, or a live worker. `createMastraVoiceAgent(options)` is an equivalent factory.
+
+```typescript
+import { initializeLogger, voice } from '@livekit/agents'
+import { MastraVoiceAgent } from '@mastra/livekit/worker'
+import { supportAgent } from './agents/support'
+
+// Required outside a LiveKit worker: AgentSession needs the LiveKit logger initialized.
+initializeLogger({ level: 'silent', pretty: false })
+
+const session = new voice.AgentSession()
+await session.start({ agent: new MastraVoiceAgent({ agent: supportAgent, memory: false }) })
+
+// run() returns a RunResult, not a promise; wait() resolves when the turn completes.
+const result = session.run({ userInput: 'What are your opening hours?' })
+await result.wait()
+result.expect.nextEvent().isMessage({ role: 'assistant' })
+result.expect.noMoreEvents()
+```
+
+The agent carries its own placeholder `llm.LLM` so LiveKit runs the reply pipeline; generation always goes through `llmNode`, so a `FakeLLM` in the session's `llm` slot is ignored and calling the placeholder's `chat()` throws. To stub the model in tests, give the Mastra agent a mock model or pass a custom `generate` function.
+
+#### Options
+
+Provide exactly one reply source: `agent` or `generate`.
+
+**agent** (`Agent`): In-process Mastra agent. Tools and memory run inside it.
+
+**generate** (`VoiceReplyGenerator`): Custom reply source, for example from createRemoteAgentReplyGenerator(). A generate source owns its own hooks; toolFeedback, onToolCall, onTurnComplete, and streamOptions only apply to the agent source.
+
+**memory** (`MastraVoiceAgentMemory | false`): Conversation persistence as { thread, resource? }. When set, only messages new since the agent last spoke are sent each turn and Mastra Memory supplies history. When false, the full in-session LiveKit context is sent every turn. (Default: `false`)
+
+**requestContext** (`RequestContext | Record<string, unknown>`): Request context entries forwarded to every generation.
+
+**toolFeedback** (`(toolCall: VoiceToolCall) => string | undefined | void`): Return a short phrase to speak while a tool runs. Agent source only.
+
+**onToolCall** (`(toolCall: VoiceToolCall) => void`): Called as each tool call starts, before its result is known. Keep it cheap and non-throwing. Agent source only.
+
+**onTurnComplete** (`VoiceTurnCompleteHook`): Called once per turn after the reply finished streaming to text-to-speech. Fire-and-forget; errors are logged. Agent source only.
+
+**greetingReminder** (`{ everyMs: number; text?: string }`): Periodic AI re-disclosure: once everyMs has elapsed, the next reply is prefixed with text (spoken at the turn boundary). The worker derives this from configuration.greeting.repeatEvery / repeatText.
+
+**streamOptions** (`MastraStreamOptions`): Extra options merged into every agent.stream() call. Agent source only.
+
+**instructions** (`string`): LiveKit agent instructions. Not used for reply generation; the Mastra agent applies its own.
+
+**id / stt / vad / tts / turnHandling** (`voice.AgentOptions['id' | 'stt' | 'vad' | 'tts' | 'turnHandling']`): Passed through to the LiveKit voice.Agent constructor. Use them to set per-agent speech components or turn handling.
+
 ### `MastraLLM`
 
 A standard LiveKit LLM plugin (`llm.LLM`) backed by a Mastra agent. Use it when you build the `voice.AgentSession` yourself and want Mastra in the `llm` slot. [`createLiveKitWorker()`](#createlivekitworker) is the managed alternative. See [Use Mastra as the LLM component](#use-mastra-as-the-llm-component) for how to choose.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.2.23-alpha.10",
+  "version": "1.2.23-alpha.11",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -27,8 +27,8 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.4.3",
-    "@mastra/core": "1.64.0-alpha.4",
-    "@mastra/mcp": "^1.17.3-alpha.0"
+    "@mastra/core": "1.64.0-alpha.5",
+    "@mastra/mcp": "^1.17.3-alpha.1"
   },
   "devDependencies": {
     "@hono/node-server": "^2.0.0",
@@ -45,7 +45,7 @@
     "typescript": "^7.0.2",
     "vitest": "4.1.10",
     "@internal/lint": "0.0.129",
-    "@mastra/core": "1.64.0-alpha.4",
+    "@mastra/core": "1.64.0-alpha.5",
     "@internal/types-builder": "0.0.104"
   },
   "homepage": "https://mastra.ai",