@mindstone/mcp-server-elevenlabs 0.2.2 → 0.4.0

package/dist/tools/music.js

@@ -1,24 +1,121 @@
 import { z } from 'zod';
 import { getApiKey } from '../auth.js';
 import { elevenLabsJson, elevenLabsAudio } from '../client.js';
+import { ENDPOINTS } from '../endpoints.js';
 import { ElevenLabsError } from '../types.js';
+import { unwrapUntrustedJsonStrings, wrapUntrusted } from '../untrusted-content.js';
 import { withErrorHandling } from '../utils.js';
 const OUTPUT_FORMAT_ENUM = z.enum([
     'mp3_44100_128', 'mp3_44100_192',
     'pcm_16000', 'pcm_22050', 'pcm_24000', 'pcm_44100',
     'ulaw_8000',
 ]).optional();
+// Matches lyric section markers on their own line, with optional `]`, to
+// avoid false-positives on prose like `[intro to jazz]`.
+const LYRIC_MARKER_PATTERN = /(^|\n)\s*\[(verse|chorus|bridge|intro|outro|pre[- ]?chorus|hook|refrain)(\s\d+)?\s*\]/i;
+const MIN_TOTAL_MUSIC_MS = 3_000;
+const MAX_TOTAL_MUSIC_MS = 10 * 60 * 1_000; // 10 minutes per the API contract.
+/**
+ * Composition section schema — matches the live ElevenLabs API shape.
+ * Field names are NOT cosmetic: the API enforces these exact names with
+ * `additionalProperties: false`, so renaming any of them breaks generation.
+ *
+ * `positive_local_styles`, `negative_local_styles`, and `lines` are all
+ * required by the API even when empty. We accept them as optional in the
+ * input schema but `.default([])` them so a hand-written plan that omits an
+ * empty array still passes the API.
+ *
+ * `.strict()` rejects unknown keys — important because the prior connector
+ * version accepted a `{style, lyrics, ...}` shape, and we want to error fast
+ * if an LLM agent or older caller sends those (rather than silently strip
+ * them and ship a 422 from upstream). See planning doc
+ * 260520_elevenlabs_oss_connector_fix.md.
+ */
+const COMPOSITION_SECTION_SCHEMA = z.object({
+    section_name: z.string().min(1).max(100).describe('Section label like "Verse 1", "Chorus", "Bridge".'),
+    duration_ms: z.number().min(3000).max(120_000).describe('Section duration in milliseconds (3000-120000).'),
+    positive_local_styles: z.array(z.string()).max(50).default([])
+        .describe('Section-specific styles to include (max 50). Use for stage directions like "whispered vocals" or "male voice"; do NOT put these in lyrics. Pass [] for sections that have no special direction.'),
+    negative_local_styles: z.array(z.string()).max(50).default([])
+        .describe('Section-specific styles to avoid (max 50). Pass [] when nothing to avoid.'),
+    lines: z.array(z.string().max(200)).max(30).default([])
+        .describe('Lyric lines for this section (max 30 lines, 200 chars each). Singable/speakable text only — performance directions belong in positive_local_styles. Pass [] for instrumental sections.'),
+}).strict();
+const COMPOSITION_PLAN_SCHEMA = z.object({
+    positive_global_styles: z.array(z.string()).optional()
+        .describe('Styles to apply globally (genre, mood, tempo, key, BPM).'),
+    negative_global_styles: z.array(z.string()).optional()
+        .describe('Styles to avoid globally.'),
+    sections: z.array(COMPOSITION_SECTION_SCHEMA).min(1).max(30)
+        .describe('Array of sections (max 30). Total duration must be between 3 seconds and 10 minutes.'),
+})
+    .strict()
+    .superRefine((plan, ctx) => {
+    const total = plan.sections.reduce((acc, s) => acc + (s.duration_ms || 0), 0);
+    if (total < MIN_TOTAL_MUSIC_MS || total > MAX_TOTAL_MUSIC_MS) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['sections'],
+            message: `Total duration across sections must be between ${MIN_TOTAL_MUSIC_MS}ms (3s) and ${MAX_TOTAL_MUSIC_MS}ms (10min); got ${total}ms.`,
+        });
+    }
+})
+    .describe('Composition plan object — must match the shape returned by create_music_plan exactly. ' +
+    'Pass the plan through verbatim or edit individual fields. The legacy {style, lyrics} ' +
+    'shape used by ≤0.2.2 is no longer accepted (the API rejects it with HTTP 422).');
+function wrapMusicPlanArray(values, source) {
+    return values?.map((value, index) => wrapUntrusted(value, `${source}[${index}]`) ?? value);
+}
+function wrapMusicPlanForDisplay(plan) {
+    return {
+        ...plan,
+        positive_global_styles: wrapMusicPlanArray(plan.positive_global_styles, 'elevenlabs:create_music_plan:composition_plan:positive_global_styles'),
+        negative_global_styles: wrapMusicPlanArray(plan.negative_global_styles, 'elevenlabs:create_music_plan:composition_plan:negative_global_styles'),
+        sections: plan.sections.map((section, index) => ({
+            ...section,
+            section_name: wrapUntrusted(section.section_name, `elevenlabs:create_music_plan:composition_plan:sections[${index}]:section_name`) ?? section.section_name,
+            positive_local_styles: wrapMusicPlanArray(section.positive_local_styles, `elevenlabs:create_music_plan:composition_plan:sections[${index}]:positive_local_styles`),
+            negative_local_styles: wrapMusicPlanArray(section.negative_local_styles, `elevenlabs:create_music_plan:composition_plan:sections[${index}]:negative_local_styles`),
+            lines: wrapMusicPlanArray(section.lines, `elevenlabs:create_music_plan:composition_plan:sections[${index}]:lines`),
+        })),
+    };
+}
+function formatIssuePath(path) {
+    return path.length > 0 ? path.join('.') : 'composition_plan';
+}
+function parseCompositionPlanInput(value) {
+    const unwrapped = unwrapUntrustedJsonStrings(value);
+    const parsed = COMPOSITION_PLAN_SCHEMA.safeParse(unwrapped);
+    if (!parsed.success) {
+        const issues = parsed.error.issues
+            .map((issue) => `${formatIssuePath(issue.path)}: ${issue.message}`)
+            .join('; ');
+        throw new ElevenLabsError(`Invalid composition_plan: ${issues}`, 'INVALID_INPUT', 'Pass a composition_plan returned by create_music_plan, or provide sections with section_name, duration_ms, positive_local_styles, negative_local_styles, and lines.');
+    }
+    return parsed.data;
+}
 export function registerMusicTools(server) {
     // ── generate_music ────────────────────────────────────────────────────
     server.registerTool('generate_music', {
-        description: 'Generate music from a text prompt using ElevenLabs Music API. ' +
-            'Returns a saved audio file path. DURATION: 3-600 seconds (default 30). ' +
-            'COST: Consumes credits based on duration. ' +
-            'PROMPT TIPS: Describe genre, mood, instruments, style, lyrics.',
+        description: `Generate music from a text prompt using ElevenLabs Music API.
+
+WHEN TO USE:
+- Quick music bed from a genre/mood description
+- Vocal songs when the prompt includes [Verse]/[Chorus] lyric markers (do not set force_instrumental: true)
+
+EXAMPLE: {"prompt": "Upbeat jazz piano, 30 seconds", "duration_seconds": 30}
+
+RELATED TOOLS:
+- create_music_plan / generate_music_from_plan: per-section lyrics and styles
+- check_subscription: confirm credits before long tracks
+
+RETURNS: file_path, size_bytes, duration_seconds, format; warnings[] when force_instrumental conflicts with lyric markers.
+
+COST: Credits based on duration (3–600 seconds).`,
         inputSchema: z.object({
-            prompt: z.string().min(1).describe('Describe the music: genre, mood, instruments, style, lyrics.'),
+            prompt: z.string().min(1).describe('Describe the music: genre, mood, instruments, style. Include `[Verse]`/`[Chorus]`/`[Bridge]` blocks with lyrics if you want a vocal song.'),
             duration_seconds: z.number().min(3).max(600).optional().describe('Duration in seconds (3-600). Default: 30.'),
-            force_instrumental: z.boolean().optional().describe('Force instrumental-only output (no vocals). Default: false.'),
+            force_instrumental: z.boolean().optional().describe('Force instrumental-only output (no vocals). Default: false. WARNING: setting this to true overrides any lyrics in the prompt — do not enable for vocal songs.'),
             output_format: OUTPUT_FORMAT_ENUM.describe('Audio output format. Default: mp3_44100_128.'),
             seed: z.number().int().optional().describe('Random seed for reproducibility.'),
         }),
@@ -28,6 +125,15 @@ export function registerMusicTools(server) {
         if (!apiKey) {
             throw new ElevenLabsError('ElevenLabs API key not configured', 'AUTH_REQUIRED', 'Ask the user for their API key, then call configure_elevenlabs_api_key.');
         }
+        // Pre-call warning: force_instrumental + lyric markers means vocals get
+        // silently dropped. This bit a real conversation (260520) — emit a
+        // warning so the agent can self-correct rather than ship instrumental.
+        const warnings = [];
+        if (args.force_instrumental === true && LYRIC_MARKER_PATTERN.test(args.prompt)) {
+            warnings.push('force_instrumental: true was set, but the prompt contains lyric section ' +
+                'markers like [Verse]/[Chorus]. Vocals will be dropped. ' +
+                'Set force_instrumental: false (or omit it) to keep the vocal performance.');
+        }
         const durationSeconds = args.duration_seconds ?? 30;
         const durationMs = Math.max(3000, Math.min(600000, durationSeconds * 1000));
         const outputFormat = args.output_format ?? 'mp3_44100_128';
@@ -41,7 +147,7 @@ export function registerMusicTools(server) {
         if (args.seed !== undefined)
             body.seed = args.seed;
         const ext = outputFormat.startsWith('mp3') ? 'mp3' : 'wav';
-        const result = await elevenLabsAudio(apiKey, `/music?output_format=${outputFormat}`, { method: 'POST', body: JSON.stringify(body) }, ext);
+        const result = await elevenLabsAudio(apiKey, `${ENDPOINTS.MUSIC}?output_format=${outputFormat}`, { method: 'POST', body: JSON.stringify(body) }, ext);
         return JSON.stringify({
             ok: true,
             file_path: result.filePath,
@@ -49,13 +155,26 @@ export function registerMusicTools(server) {
             duration_seconds: durationSeconds,
             format: outputFormat,
             message: `Music generated and saved to ${result.filePath} (${(result.sizeBytes / 1024).toFixed(1)} KB, ${durationSeconds}s).`,
+            warnings: warnings.length > 0 ? warnings : undefined,
         });
     }));
     // ── create_music_plan ─────────────────────────────────────────────────
     server.registerTool('create_music_plan', {
-        description: 'Create a composition plan for music generation — FREE, no credits consumed. ' +
-            'Returns a structured plan with sections, styles, and lyrics. ' +
-            'Review the plan and pass it to generate_music_from_plan when ready.',
+        description: `Create a composition plan for music generation.
+
+WHEN TO USE:
+- Structure a song with per-section lyrics and styles before paying for generation
+- Review or edit sections before calling generate_music_from_plan
+
+EXAMPLE: {"prompt": "Acoustic folk ballad about the sea", "duration_seconds": 45}
+
+RELATED TOOLS:
+- generate_music_from_plan: generate audio from the returned composition_plan
+- generate_music: faster one-shot generation without a plan
+
+RETURNS: composition_plan (sections with section_name, duration_ms, styles, lines), total_duration_seconds.
+
+COST: FREE — no credits consumed.`,
         inputSchema: z.object({
             prompt: z.string().min(1).describe('Describe the music you want.'),
             duration_seconds: z.number().min(3).max(600).optional().describe('Target duration in seconds (3-600). Default: 30.'),
@@ -68,7 +187,7 @@ export function registerMusicTools(server) {
         }
         const durationSeconds = args.duration_seconds ?? 30;
         const durationMs = Math.max(3000, Math.min(600000, durationSeconds * 1000));
-        const plan = await elevenLabsJson(apiKey, '/music/plan', {
+        const plan = await elevenLabsJson(apiKey, ENDPOINTS.MUSIC_PLAN, {
             method: 'POST',
             body: JSON.stringify({
                 prompt: args.prompt,
@@ -77,30 +196,36 @@ export function registerMusicTools(server) {
             }),
         });
         const totalDurationMs = plan.sections.reduce((sum, s) => sum + (s.duration_ms || 0), 0);
+        const displayPlan = wrapMusicPlanForDisplay(plan);
         return JSON.stringify({
             ok: true,
-            composition_plan: plan,
+            composition_plan: displayPlan,
             total_duration_seconds: totalDurationMs / 1000,
             num_sections: plan.sections.length,
             cost: 'FREE — no credits consumed',
             message: `Composition plan created with ${plan.sections.length} sections (${(totalDurationMs / 1000).toFixed(1)}s total). Review the plan and pass it to generate_music_from_plan when ready.`,
-            hint: 'You can modify positive_global_styles, negative_global_styles, section styles, lyrics, and durations before generating.',
+            hint: 'You can modify positive_global_styles, negative_global_styles, and per-section positive_local_styles, negative_local_styles, lines (lyric lines), or duration_ms before generating.',
         });
     }));
     // ── generate_music_from_plan ──────────────────────────────────────────
     server.registerTool('generate_music_from_plan', {
-        description: 'Generate music from a composition plan (created by create_music_plan or manually crafted). ' +
-            'The plan must have at least one section. COST: Consumes credits based on duration.',
+        description: `Generate music from a composition plan.
+
+WHEN TO USE:
+- After create_music_plan when you want per-section control over lyrics and styles
+- When generate_music's single prompt is not precise enough
+
+EXAMPLE: pass the composition_plan object from create_music_plan verbatim
+
+RELATED TOOLS:
+- create_music_plan: produces the plan shape this tool expects
+- check_subscription: confirm credits before generation
+
+RETURNS: file_path, size_bytes, duration_seconds, format.
+
+COST: Credits based on total plan duration (3s–10min).`,
         inputSchema: z.object({
-            composition_plan: z.object({
-                positive_global_styles: z.array(z.string()).optional().describe('Styles to apply globally.'),
-                negative_global_styles: z.array(z.string()).optional().describe('Styles to avoid globally.'),
-                sections: z.array(z.object({
-                    style: z.string().optional(),
-                    lyrics: z.string().optional(),
-                    duration_ms: z.number().optional(),
-                })).min(1).describe('Array of sections, each with style, lyrics, and duration_ms.'),
-            }).describe('The composition plan object.'),
+            composition_plan: z.unknown().describe('Composition plan object from create_music_plan. Wrapped display text and raw manually edited text are both accepted; the plan is unwrapped and strictly validated before generation.'),
             seed: z.number().int().optional().describe('Random seed for reproducibility.'),
             output_format: OUTPUT_FORMAT_ENUM.describe('Audio output format. Default: mp3_44100_128.'),
         }),
@@ -110,7 +235,7 @@ export function registerMusicTools(server) {
         if (!apiKey) {
             throw new ElevenLabsError('ElevenLabs API key not configured', 'AUTH_REQUIRED', 'Ask the user for their API key, then call configure_elevenlabs_api_key.');
         }
-        const compositionPlan = args.composition_plan;
+        const compositionPlan = parseCompositionPlanInput(args.composition_plan);
         const outputFormat = args.output_format ?? 'mp3_44100_128';
         const body = {
             composition_plan: compositionPlan,
@@ -119,8 +244,8 @@ export function registerMusicTools(server) {
         if (args.seed !== undefined)
             body.seed = args.seed;
         const ext = outputFormat.startsWith('mp3') ? 'mp3' : 'wav';
-        const result = await elevenLabsAudio(apiKey, `/music?output_format=${outputFormat}`, { method: 'POST', body: JSON.stringify(body) }, ext);
-        const totalDurationMs = (compositionPlan.sections ?? []).reduce((sum, s) => sum + (s.duration_ms || 0), 0);
+        const result = await elevenLabsAudio(apiKey, `${ENDPOINTS.MUSIC}?output_format=${outputFormat}`, { method: 'POST', body: JSON.stringify(body) }, ext);
+        const totalDurationMs = compositionPlan.sections.reduce((sum, s) => sum + (s.duration_ms || 0), 0);
         return JSON.stringify({
             ok: true,
             file_path: result.filePath,

package/dist/tools/path-safety.d.ts

@@ -28,6 +28,7 @@ export declare function isRemoteUrl(input: string): boolean;
  *     than crashing.
  */
 export declare function getAudioWorkspaceRoot(): string;
+export declare function isInsideAudioWorkspaceRoot(resolvedPath: string, root?: string): boolean;
 /**
  * Validate that an LLM-supplied `file_path` argument resolves to a real
  * file under the audio workspace sandbox root, even after symlink

package/dist/tools/path-safety.js

@@ -36,6 +36,9 @@ export function getAudioWorkspaceRoot() {
         return lexical;
     }
 }
+export function isInsideAudioWorkspaceRoot(resolvedPath, root = getAudioWorkspaceRoot()) {
+    return resolvedPath === root || resolvedPath.startsWith(root + path.sep);
+}
 /**
  * Canonicalise the deepest existing ancestor of an absolute path and
  * re-append the missing tail (M3-fix-C). This lets the lexical-prefix
@@ -90,7 +93,7 @@ function canonicalisePrefix(absoluteLexical) {
 export function resolveAudioPath(filePath) {
     const root = getAudioWorkspaceRoot();
     const denyMessage = `file_path is outside the workspace sandbox root (${root}). Got: ${filePath}`;
-    const isInsideRoot = (p) => p === root || p.startsWith(root + path.sep);
+    const isInsideRoot = (p) => isInsideAudioWorkspaceRoot(p, root);
     // Step 1: lexical normalisation — expand `~`, collapse `..`, absolutise.
     const expanded = filePath.startsWith('~')
         ? path.join(os.homedir(), filePath.slice(1))

package/dist/tools/speech.js

@@ -1,31 +1,76 @@
 import { z } from 'zod';
 import { getApiKey } from '../auth.js';
 import { elevenLabsJson, elevenLabsAudio } from '../client.js';
-import { ElevenLabsError } from '../types.js';
+import { ENDPOINTS, voicesV2Url } from '../endpoints.js';
+import { ElevenLabsError, VOICE_NOT_FOUND_RESOLUTION } from '../types.js';
+import { wrapUntrusted } from '../untrusted-content.js';
 import { withErrorHandling } from '../utils.js';
 /**
  * Look up a voice by name via the ElevenLabs v2 voices API.
  */
 async function lookupVoiceByName(apiKey, name) {
-    const data = await elevenLabsJson(apiKey, `https://api.elevenlabs.io/v2/voices?search=${encodeURIComponent(name)}&page_size=5`);
+    const params = new URLSearchParams({
+        search: name,
+        page_size: '5',
+    });
+    const data = await elevenLabsJson(apiKey, voicesV2Url(params));
     if (!data.voices || data.voices.length === 0) {
-        throw new ElevenLabsError(`No voice found matching "${name}"`, 'VOICE_NOT_FOUND', `No voice matched "${name}". Use list_voices to browse available voices and get the exact voice_id.`);
+        throw new ElevenLabsError(`No voice found matching "${name}"`, 'VOICE_NOT_FOUND', VOICE_NOT_FOUND_RESOLUTION);
     }
     return data.voices[0];
 }
+/**
+ * Pick a sensible default voice from the account.
+ *
+ * The previous version of this connector hardcoded a "Rachel" lookup, which
+ * silently fails on accounts that don't have Rachel in their library (most
+ * personal/business accounts). We now ask the API for the first page of
+ * voices, prefer premade voices, and fall back to whatever the account has.
+ *
+ * If the account has zero voices we surface a clear VOICE_NOT_FOUND with a
+ * resolution that tells the agent to call list_voices first.
+ */
+async function pickDefaultVoice(apiKey) {
+    const params = new URLSearchParams({ page_size: '20' });
+    const data = await elevenLabsJson(apiKey, voicesV2Url(params));
+    if (!data.voices || data.voices.length === 0) {
+        throw new ElevenLabsError('No voice specified and the account has no voices.', 'VOICE_NOT_FOUND', VOICE_NOT_FOUND_RESOLUTION);
+    }
+    // Prefer premade voices (curated, generally suitable as defaults).
+    const premade = data.voices.find((v) => v.category === 'premade');
+    return premade ?? data.voices[0];
+}
 export function registerSpeechTools(server) {
     // ── generate_speech ───────────────────────────────────────────────────
     server.registerTool('generate_speech', {
-        description: 'Generate spoken audio from text using ElevenLabs text-to-speech. ' +
-            'Use voice_id (direct) or voice_name (fuzzy search). ' +
-            'Models: eleven_multilingual_v2 (default, 29 languages), eleven_monolingual_v1 (English), eleven_turbo_v2_5 (low latency). ' +
-            'COST: ~1 credit per 100 characters.',
+        description: `Generate spoken audio from text using ElevenLabs text-to-speech.
+
+WHEN TO USE:
+- Turn user text into a playable speech file
+- Narration, voiceovers, or reading content aloud
+
+EXAMPLE: {"text": "Hello world.", "voice_id": "21m00Tcm4TlvDq8ikWAM", "model_id": "eleven_v3"}
+
+RELATED TOOLS:
+- list_voices / search_shared_voices / get_voice: find voice_id
+- list_models: pick model_id (default eleven_v3)
+- check_subscription: confirm credits before long text
+
+RETURNS: file_path, size_bytes, voice_id, model, format. API-resolved voice names are enveloped.
+
+COST: ~1 credit per 100 characters.`,
         inputSchema: z.object({
             text: z.string().min(1).describe('Text to speak. Maximum ~5000 characters per request.'),
-            voice_id: z.string().optional().describe('Direct voice ID. Takes priority over voice_name.'),
-            voice_name: z.string().optional().describe('Voice name for fuzzy search (e.g., "Rachel", "Adam").'),
-            model_id: z.enum(['eleven_multilingual_v2', 'eleven_monolingual_v1', 'eleven_turbo_v2_5']).optional()
-                .describe('TTS model. Default: eleven_multilingual_v2.'),
+            voice_id: z.string().optional().describe('Direct voice ID (from list_voices). Takes priority over voice_name.'),
+            voice_name: z.string().optional().describe('Voice name for fuzzy search (e.g., "Bella", "Sarah"). Use list_voices first to find a name that exists on the account.'),
+            model_id: z.enum([
+                'eleven_v3',
+                'eleven_multilingual_v2',
+                'eleven_flash_v2_5',
+                'eleven_turbo_v2_5',
+                'eleven_monolingual_v1',
+            ]).optional()
+                .describe('TTS model. Default: eleven_v3.'),
             stability: z.number().min(0).max(1).optional().describe('Voice stability 0-1. Default: 0.5.'),
             similarity_boost: z.number().min(0).max(1).optional().describe('Voice similarity 0-1. Default: 0.75.'),
             output_format: z.enum(['mp3_44100_128', 'mp3_44100_192', 'pcm_16000', 'pcm_22050', 'pcm_24000', 'pcm_44100']).optional()
@@ -39,12 +84,17 @@ export function registerSpeechTools(server) {
         }
         let voiceId = args.voice_id;
         const voiceName = args.voice_name;
-        const modelId = args.model_id ?? 'eleven_multilingual_v2';
+        const modelId = args.model_id ?? 'eleven_v3';
         const stability = args.stability ?? 0.5;
         const similarityBoost = args.similarity_boost ?? 0.75;
         const outputFormat = args.output_format ?? 'mp3_44100_128';
-        // Voice lookup
+        // Voice lookup. When the name comes back from the API it is external,
+        // possibly attacker-authored text (e.g. a shared/cloned voice named to
+        // carry a prompt injection) and must be enveloped before being returned
+        // (AGENTS.md invariant #6). When voice_id is passed directly, the name
+        // is just the caller's own input echoed back — no envelope needed.
         let resolvedVoiceName = voiceName || 'default';
+        let voiceNameFromApi = false;
         if (!voiceId) {
             if (voiceName) {
                 const voice = await lookupVoiceByName(apiKey, voiceName);
@@ -52,20 +102,12 @@ export function registerSpeechTools(server) {
                 resolvedVoiceName = voice.name;
             }
             else {
-                // Default to Rachel if no voice specified
-                try {
-                    const voice = await lookupVoiceByName(apiKey, 'Rachel');
-                    voiceId = voice.voice_id;
-                    resolvedVoiceName = voice.name;
-                }
-                catch (err) {
-                    // Propagate the error so withErrorHandling emits isError: true
-                    if (err instanceof ElevenLabsError) {
-                        throw err;
-                    }
-                    throw new ElevenLabsError('No voice specified and default voice lookup failed.', 'VOICE_NOT_FOUND', 'Provide a voice_id or voice_name. Use list_voices to find available voices.');
-                }
+                // No voice specified — pick a sensible default from the account.
+                const voice = await pickDefaultVoice(apiKey);
+                voiceId = voice.voice_id;
+                resolvedVoiceName = voice.name;
             }
+            voiceNameFromApi = true;
         }
         const body = {
             text: args.text,
@@ -76,24 +118,38 @@ export function registerSpeechTools(server) {
             },
         };
         const ext = outputFormat.startsWith('mp3') ? 'mp3' : 'wav';
-        const result = await elevenLabsAudio(apiKey, `/text-to-speech/${voiceId}?output_format=${outputFormat}`, { method: 'POST', body: JSON.stringify(body) }, ext);
+        const result = await elevenLabsAudio(apiKey, ENDPOINTS.textToSpeech(voiceId, outputFormat), { method: 'POST', body: JSON.stringify(body) }, ext);
+        // The voice name lives ONLY in the (enveloped) `voice` field — never in
+        // `message`, so no unwrapped API-authored substring can reach the model.
         return JSON.stringify({
             ok: true,
             file_path: result.filePath,
             size_bytes: result.sizeBytes,
-            voice: resolvedVoiceName,
+            voice: voiceNameFromApi
+                ? wrapUntrusted(resolvedVoiceName, 'elevenlabs:generate_speech:voice_name')
+                : resolvedVoiceName,
             voice_id: voiceId,
             model: modelId,
             format: outputFormat,
-            message: `Speech generated with voice "${resolvedVoiceName}" and saved to ${result.filePath} (${(result.sizeBytes / 1024).toFixed(1)} KB).`,
+            message: `Speech generated and saved to ${result.filePath} (${(result.sizeBytes / 1024).toFixed(1)} KB).`,
         });
     }));
     // ── generate_sound_effect ─────────────────────────────────────────────
     server.registerTool('generate_sound_effect', {
-        description: 'Generate sound effects from a text description. ' +
-            'DURATION: 0.5-22 seconds (auto if omitted). ' +
-            'PROMPT INFLUENCE (0-1): How closely to follow the text prompt. Default: 0.3. ' +
-            'COST: Credits based on duration.',
+        description: `Generate sound effects from a text description.
+
+WHEN TO USE:
+- Short ambient or UI sounds from a natural-language prompt
+- Effects for video, games, or presentations
+
+EXAMPLE: {"prompt": "Soft rain on a tin roof", "duration_seconds": 3}
+
+RELATED TOOLS:
+- check_subscription: confirm credits before generation
+
+RETURNS: file_path, size_bytes, duration_seconds.
+
+COST: Credits based on duration (0.5–22 seconds).`,
         inputSchema: z.object({
             prompt: z.string().min(1).describe('Describe the sound effect. Be specific about characteristics.'),
             duration_seconds: z.number().min(0.5).max(22).optional().describe('Duration in seconds (0.5-22). Auto if omitted.'),
@@ -113,7 +169,7 @@ export function registerSpeechTools(server) {
         if (args.duration_seconds !== undefined) {
             body.duration_seconds = Math.max(0.5, Math.min(22, args.duration_seconds));
         }
-        const result = await elevenLabsAudio(apiKey, '/sound-generation', { method: 'POST', body: JSON.stringify(body) }, 'mp3');
+        const result = await elevenLabsAudio(apiKey, ENDPOINTS.SOUND_GENERATION, { method: 'POST', body: JSON.stringify(body) }, 'mp3');
         return JSON.stringify({
             ok: true,
             file_path: result.filePath,

package/dist/tools/transcription.js

@@ -1,20 +1,32 @@
 import { z } from 'zod';
-import * as fs from 'fs';
-import * as path from 'path';
 import { getApiKey } from '../auth.js';
 import { elevenLabsJson } from '../client.js';
+import { ENDPOINTS } from '../endpoints.js';
 import { ElevenLabsError } from '../types.js';
+import { wrapUntrusted } from '../untrusted-content.js';
 import { withErrorHandling } from '../utils.js';
-import { isRemoteUrl, resolveAudioPath } from './path-safety.js';
+import { readSandboxedFile, sandboxedFileToBlob } from './file-input.js';
 export function registerTranscriptionTools(server) {
     server.registerTool('transcribe_audio', {
-        description: 'Transcribe speech from an audio file to text using ElevenLabs Speech-to-Text. ' +
-            'INPUT: Local audio file path (.mp3, .wav, .m4a, .ogg, .flac, .webm, .mp4). ' +
-            'Auto-detects language by default. Specify language_code for better accuracy. ' +
-            'COST: Credits based on audio duration.',
+        description: `Transcribe speech from a local audio file to text.
+
+WHEN TO USE:
+- Convert meeting recordings or voice memos to text
+- Extract quotes from audio the user provides as a file path
+
+EXAMPLE: {"file_path": "/path/to/recording.mp3", "language_code": "en"}
+
+RELATED TOOLS:
+- generate_speech: the inverse operation (text to audio)
+
+RETURNS: enveloped text, word_count, language. File path must be inside MCP_WORKSPACE_PATH (or os.tmpdir()).
+
+COST: Credits based on audio duration.`,
         inputSchema: z.object({
             file_path: z.string().min(1).describe('Absolute path to local audio file to transcribe.'),
             language_code: z.string().optional().describe('Language code (e.g., "en", "es", "fr"). Auto-detected if omitted.'),
+            model_id: z.enum(['scribe_v1']).optional().describe('STT model. Default: scribe_v1.'),
+            tag_audio_events: z.boolean().optional().describe('When true, include non-speech events like "(laughter)" in the transcript. Default: false.'),
         }),
         annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
     }, withErrorHandling(async (args) => {
@@ -22,69 +34,30 @@ export function registerTranscriptionTools(server) {
         if (!apiKey) {
             throw new ElevenLabsError('ElevenLabs API key not configured', 'AUTH_REQUIRED', 'Ask the user for their API key, then call configure_elevenlabs_api_key.');
         }
-        const rawFilePath = args.file_path;
-        // ----------------------------------------------------------------
-        // SECURITY (M3.9): sandbox local audio reads to under
-        // `MCP_WORKSPACE_PATH` (or `os.tmpdir()` when unset). Without this,
-        // an LLM-supplied `file_path` could exfiltrate arbitrary host bytes
-        // (e.g. ~/.ssh/id_rsa, /etc/passwd) via the multipart upload to
-        // ElevenLabs Speech-to-Text.
-        //
-        // - Remote URL inputs bypass the sandbox: `transcribe_audio`
-        //   currently only handles local-file inputs, so a URL string falls
-        //   through to the existing FILE_NOT_FOUND branch (a non-sandbox
-        //   error code, preserving pre-fix behaviour for URL inputs).
-        // - Local paths run through `resolveAudioPath`, which:
-        //     1. Lexically resolves `~` and `..` and rejects paths outside
-        //        the workspace root before any disk read.
-        //     2. Canonicalises the file via `fs.realpathSync` so a symlink
-        //        inside the workspace pointing OUTSIDE the workspace is
-        //        refused.
-        // ----------------------------------------------------------------
-        let filePath;
-        if (isRemoteUrl(rawFilePath)) {
-            // Preserve pre-existing behaviour for URL inputs: the
-            // existsSync branch below will return a clean FILE_NOT_FOUND
-            // (a non-sandbox error code).
-            filePath = rawFilePath;
-        }
-        else {
-            const resolution = resolveAudioPath(rawFilePath);
-            if (!resolution.ok) {
-                // Surface the sandbox / not-found error via the standard
-                // ElevenLabsError path so withErrorHandling renders it with a
-                // stable shape and a code.
-                const code = resolution.error.startsWith('File not found')
-                    ? 'FILE_NOT_FOUND'
-                    : 'PATH_SANDBOX_VIOLATION';
-                throw new ElevenLabsError(resolution.error, code, 'Provide a path to an existing audio file inside MCP_WORKSPACE_PATH (or os.tmpdir() when unset). Remote URLs are not supported.');
-            }
-            filePath = resolution.path;
-        }
-        // Read local file
-        if (!fs.existsSync(filePath)) {
-            throw new ElevenLabsError(`File not found: ${rawFilePath}`, 'FILE_NOT_FOUND', 'Provide an absolute path to an existing audio file.');
-        }
-        // Defence-in-depth: re-canonicalise via realpathSync at the very
-        // last moment to close the (vanishingly small) TOCTOU window
-        // between sandbox validation and the readFileSync call. URL inputs
-        // skip this since they did not go through the sandbox.
-        const verifiedPath = isRemoteUrl(rawFilePath) ? filePath : fs.realpathSync(filePath);
-        const fileBuffer = fs.readFileSync(verifiedPath);
-        const fileName = path.basename(verifiedPath);
-        // Use FormData to send as multipart
+        // Sandbox local reads via shared file-input helper (MCP_WORKSPACE_PATH +
+        // realpathSync TOCTOU guard — see file-input.ts).
+        const fileInput = readSandboxedFile(args.file_path);
+        // Multipart upload. ElevenLabs Speech-to-Text v1 requires:
+        //   - field name `file` (NOT `audio`)
+        //   - `model_id` is mandatory (only `scribe_v1` is currently supported)
+        //   - `tag_audio_events=false` to avoid `(mouse click)` style noise
         const formData = new FormData();
-        formData.append('audio', new Blob([fileBuffer]), fileName);
+        formData.append('file', sandboxedFileToBlob(fileInput), fileInput.fileName);
+        formData.append('model_id', args.model_id ?? 'scribe_v1');
+        formData.append('tag_audio_events', String(args.tag_audio_events ?? false));
         if (args.language_code) {
             formData.append('language_code', args.language_code);
         }
-        const data = await elevenLabsJson(apiKey, '/speech-to-text', {
+        const data = await elevenLabsJson(apiKey, ENDPOINTS.SPEECH_TO_TEXT, {
             method: 'POST',
             body: formData,
         });
+        // AGENTS.md invariant #6: the transcript is whatever was SPOKEN in the
+        // audio — the most attacker-controllable text this connector returns.
+        // `message` stays numeric-only; never echo transcript substrings into it.
         return JSON.stringify({
             ok: true,
-            text: data.text,
+            text: wrapUntrusted(data.text, 'elevenlabs:transcribe_audio:text'),
             word_count: data.words?.length || 0,
             language: args.language_code || 'auto-detected',
             message: `Transcription complete: ${data.text.length} characters, ${data.words?.length || 0} words.`,

package/dist/tools/voice-changer.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerVoiceChangerTools(server: McpServer): void;
+//# sourceMappingURL=voice-changer.d.ts.map