@mindstone/mcp-server-elevenlabs 0.3.0 → 0.4.0

package/dist/tools/music.js

@@ -1,7 +1,9 @@
 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',
@@ -61,19 +63,55 @@ const COMPOSITION_PLAN_SCHEMA = z.object({
     .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.\n\n' +
-            'PROMPT TIPS — to get a song WITH VOCALS:\n' +
-            '  1. Do NOT set force_instrumental: true (it silently drops all vocals).\n' +
-            '  2. Embed lyrics in the prompt using ElevenLabs section markers: ' +
-            '`[Verse 1] ... [Chorus] ... [Bridge] ...`. Each marker is on its own ' +
-            'line followed by the lines for that section.\n' +
-            'For fine-grained control (per-section style + lyrics), use create_music_plan ' +
-            'then generate_music_from_plan instead.',
+        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. 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.'),
@@ -109,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,
@@ -122,9 +160,21 @@ export function registerMusicTools(server) {
     }));
     // ── 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.'),
@@ -137,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,
@@ -146,9 +196,10 @@ 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',
@@ -158,14 +209,23 @@ export function registerMusicTools(server) {
     }));
     // ── 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. Each section requires section_name, duration_ms, ' +
-            'positive_local_styles, negative_local_styles, and lines. Pass plans from create_music_plan ' +
-            'through verbatim — the field names are enforced by the ElevenLabs API.\n\n' +
-            'COST: Consumes credits based on duration. ' +
-            'Total duration: 3s-10min. Each section: 3-120s.',
+        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: COMPOSITION_PLAN_SCHEMA,
+            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.'),
         }),
@@ -175,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,
@@ -184,7 +244,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);
         const totalDurationMs = compositionPlan.sections.reduce((sum, s) => sum + (s.duration_ms || 0), 0);
         return JSON.stringify({
             ok: true,

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,15 +1,21 @@
 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];
 }
@@ -25,9 +31,10 @@ async function lookupVoiceByName(apiKey, name) {
  * resolution that tells the agent to call list_voices first.
  */
 async function pickDefaultVoice(apiKey) {
-    const data = await elevenLabsJson(apiKey, 'https://api.elevenlabs.io/v2/voices?page_size=20');
+    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', 'Add a voice in https://elevenlabs.io/app/voice-library or pass a voice_id / voice_name explicitly.');
+        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');
@@ -36,16 +43,22 @@ async function pickDefaultVoice(apiKey) {
 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). If neither is provided, ' +
-            'a premade voice from the account is used.\n\n' +
-            'MODELS:\n' +
-            '  - eleven_v3 (default) — most expressive, 70+ languages\n' +
-            '  - eleven_multilingual_v2 — proven multilingual, 29 languages\n' +
-            '  - eleven_flash_v2_5 — low latency\n' +
-            '  - eleven_turbo_v2_5 — low latency variant\n' +
-            '  - eleven_monolingual_v1 — English-only legacy model (kept for backwards compatibility)\n\n' +
-            '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 (from list_voices). Takes priority over voice_name.'),
@@ -75,8 +88,13 @@ export function registerSpeechTools(server) {
         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);
@@ -89,6 +107,7 @@ export function registerSpeechTools(server) {
                 voiceId = voice.voice_id;
                 resolvedVoiceName = voice.name;
             }
+            voiceNameFromApi = true;
         }
         const body = {
             text: args.text,
@@ -99,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.'),
@@ -136,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,17 +1,27 @@
 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.'),
@@ -24,74 +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);
+        // 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` — see planning doc 260520)
+        //   - 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('file', 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

package/dist/tools/voice-changer.js

@@ -0,0 +1,62 @@
+import { z } from 'zod';
+import { getApiKey } from '../auth.js';
+import { elevenLabsAudio } from '../client.js';
+import { ENDPOINTS } from '../endpoints.js';
+import { ElevenLabsError } from '../types.js';
+import { withErrorHandling } from '../utils.js';
+import { readSandboxedFile, sandboxedFileToBlob } from './file-input.js';
+export function registerVoiceChangerTools(server) {
+    server.registerTool('speech_to_speech', {
+        description: `Convert an audio clip to sound like a different voice (voice conversion).
+
+WHEN TO USE:
+- Change the speaker voice of an existing recording while preserving timing
+- Apply a premade or cloned voice_id to source audio the user provides as a file
+
+EXAMPLE: {"audio_path": "/path/to/source.mp3", "voice_id": "21m00Tcm4TlvDq8ikWAM"}
+
+RELATED TOOLS:
+- list_voices / get_voice: resolve voice_id
+- generate_speech: synthesize new speech from text instead of converting audio
+- check_subscription: confirm credits before conversion
+
+RETURNS: file_path and size_bytes for the converted audio (saved under os.tmpdir()).
+
+COST: Credits based on source audio duration.`,
+        inputSchema: z.object({
+            audio_path: z.string().min(1).describe('Absolute path to local source audio inside MCP_WORKSPACE_PATH (or os.tmpdir()).'),
+            voice_id: z.string().min(1).describe('Target voice ID from list_voices or search_shared_voices.'),
+            model_id: z.string().optional().describe('STS model ID. Omit to use the API default.'),
+            remove_background_noise: z.boolean().optional().describe('When true, reduce background noise during conversion. Default: false.'),
+            voice_settings: z.object({
+                stability: z.number().min(0).max(1).optional(),
+                similarity_boost: z.number().min(0).max(1).optional(),
+            }).optional().describe('Optional voice settings JSON object (stability, similarity_boost).'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    }, withErrorHandling(async (args) => {
+        const apiKey = getApiKey();
+        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 fileInput = readSandboxedFile(args.audio_path);
+        const formData = new FormData();
+        formData.append('audio', sandboxedFileToBlob(fileInput), fileInput.fileName);
+        if (args.model_id) {
+            formData.append('model_id', args.model_id);
+        }
+        if (args.voice_settings) {
+            formData.append('voice_settings', JSON.stringify(args.voice_settings));
+        }
+        formData.append('remove_background_noise', String(args.remove_background_noise ?? false));
+        const result = await elevenLabsAudio(apiKey, ENDPOINTS.speechToSpeech(args.voice_id), { method: 'POST', body: formData }, 'mp3');
+        return JSON.stringify({
+            ok: true,
+            file_path: result.filePath,
+            size_bytes: result.sizeBytes,
+            voice_id: args.voice_id,
+            message: `Speech-to-speech conversion saved to ${result.filePath} (${(result.sizeBytes / 1024).toFixed(1)} KB).`,
+        });
+    }));
+}
+//# sourceMappingURL=voice-changer.js.map

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

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