@mindstone/mcp-server-elevenlabs 0.2.2

package/dist/tools/music.js

@@ -0,0 +1,134 @@
+import { z } from 'zod';
+import { getApiKey } from '../auth.js';
+import { elevenLabsJson, elevenLabsAudio } from '../client.js';
+import { ElevenLabsError } from '../types.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();
+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.',
+        inputSchema: z.object({
+            prompt: z.string().min(1).describe('Describe the music: genre, mood, instruments, style, lyrics.'),
+            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.'),
+            output_format: OUTPUT_FORMAT_ENUM.describe('Audio output format. Default: mp3_44100_128.'),
+            seed: z.number().int().optional().describe('Random seed for reproducibility.'),
+        }),
+        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 durationSeconds = args.duration_seconds ?? 30;
+        const durationMs = Math.max(3000, Math.min(600000, durationSeconds * 1000));
+        const outputFormat = args.output_format ?? 'mp3_44100_128';
+        const body = {
+            prompt: args.prompt,
+            music_length_ms: durationMs,
+            model_id: 'music_v1',
+        };
+        if (args.force_instrumental !== undefined)
+            body.force_instrumental = args.force_instrumental;
+        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);
+        return JSON.stringify({
+            ok: true,
+            file_path: result.filePath,
+            size_bytes: result.sizeBytes,
+            duration_seconds: durationSeconds,
+            format: outputFormat,
+            message: `Music generated and saved to ${result.filePath} (${(result.sizeBytes / 1024).toFixed(1)} KB, ${durationSeconds}s).`,
+        });
+    }));
+    // ── 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.',
+        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.'),
+        }),
+        annotations: { readOnlyHint: true, 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 durationSeconds = args.duration_seconds ?? 30;
+        const durationMs = Math.max(3000, Math.min(600000, durationSeconds * 1000));
+        const plan = await elevenLabsJson(apiKey, '/music/plan', {
+            method: 'POST',
+            body: JSON.stringify({
+                prompt: args.prompt,
+                music_length_ms: durationMs,
+                model_id: 'music_v1',
+            }),
+        });
+        const totalDurationMs = plan.sections.reduce((sum, s) => sum + (s.duration_ms || 0), 0);
+        return JSON.stringify({
+            ok: true,
+            composition_plan: plan,
+            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.',
+        });
+    }));
+    // ── 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.',
+        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.'),
+            seed: z.number().int().optional().describe('Random seed for reproducibility.'),
+            output_format: OUTPUT_FORMAT_ENUM.describe('Audio output format. Default: mp3_44100_128.'),
+        }),
+        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 compositionPlan = args.composition_plan;
+        const outputFormat = args.output_format ?? 'mp3_44100_128';
+        const body = {
+            composition_plan: compositionPlan,
+            model_id: 'music_v1',
+        };
+        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);
+        return JSON.stringify({
+            ok: true,
+            file_path: result.filePath,
+            size_bytes: result.sizeBytes,
+            duration_seconds: totalDurationMs / 1000,
+            format: outputFormat,
+            message: `Music generated from plan and saved to ${result.filePath} (${(result.sizeBytes / 1024).toFixed(1)} KB).`,
+        });
+    }));
+}
+//# sourceMappingURL=music.js.map

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

@@ -0,0 +1,51 @@
+export type ResolveResult = {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Detect URL-shaped inputs so the caller can bypass the local-path sandbox.
+ * `transcribe_audio` does not currently accept URL inputs (it reads bytes
+ * from disk), but a URL string supplied by the LLM must NOT surface as a
+ * sandbox-violation — it should fall through to the existing not-found
+ * code path so the error remains stable.
+ */
+export declare function isRemoteUrl(input: string): boolean;
+/**
+ * Derive the canonical workspace root for READING audio files supplied to
+ * `transcribe_audio`.
+ *
+ *   - `MCP_WORKSPACE_PATH` if set (and non-empty), else `os.tmpdir()`.
+ *   - The root is canonicalised through `fs.realpathSync` so the prefix
+ *     check in `resolveAudioPath` is stable on platforms where the system
+ *     tmpdir itself is reached through a symlink (e.g. macOS:
+ *     /var/folders/... -> /private/var/folders/..., or /tmp -> /private/tmp).
+ *   - If `realpathSync` fails (e.g. user pointed `MCP_WORKSPACE_PATH` at a
+ *     non-existent dir), we fall back to the lexically-resolved path so the
+ *     subsequent containment check still produces a clean refusal rather
+ *     than crashing.
+ */
+export declare function getAudioWorkspaceRoot(): string;
+/**
+ * Validate that an LLM-supplied `file_path` argument resolves to a real
+ * file under the audio workspace sandbox root, even after symlink
+ * resolution. Returns the canonicalised path on success.
+ *
+ * Security rules:
+ *  - Tilde (`~`) is expanded lexically; the expanded path must still be
+ *    inside the workspace root.
+ *  - Lexical `path.resolve` collapses `..` segments; a path that resolves
+ *    outside the root is rejected before any disk read.
+ *  - Existing files have their canonical path computed via
+ *    `fs.realpathSync` so a symlink inside the root pointing OUTSIDE the
+ *    root is refused.
+ *  - Remote URL inputs (https://, http://) MUST be detected and bypassed
+ *    by the caller via `isRemoteUrl` BEFORE invoking this helper.
+ *
+ * On rejection, the error string includes both the substring "workspace"
+ * and "sandbox" so validators / log scanners can match either keyword.
+ */
+export declare function resolveAudioPath(filePath: string): ResolveResult;
+//# sourceMappingURL=path-safety.d.ts.map

package/dist/tools/path-safety.js

@@ -0,0 +1,135 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+/**
+ * Detect URL-shaped inputs so the caller can bypass the local-path sandbox.
+ * `transcribe_audio` does not currently accept URL inputs (it reads bytes
+ * from disk), but a URL string supplied by the LLM must NOT surface as a
+ * sandbox-violation — it should fall through to the existing not-found
+ * code path so the error remains stable.
+ */
+export function isRemoteUrl(input) {
+    return /^https?:\/\//i.test(input);
+}
+/**
+ * Derive the canonical workspace root for READING audio files supplied to
+ * `transcribe_audio`.
+ *
+ *   - `MCP_WORKSPACE_PATH` if set (and non-empty), else `os.tmpdir()`.
+ *   - The root is canonicalised through `fs.realpathSync` so the prefix
+ *     check in `resolveAudioPath` is stable on platforms where the system
+ *     tmpdir itself is reached through a symlink (e.g. macOS:
+ *     /var/folders/... -> /private/var/folders/..., or /tmp -> /private/tmp).
+ *   - If `realpathSync` fails (e.g. user pointed `MCP_WORKSPACE_PATH` at a
+ *     non-existent dir), we fall back to the lexically-resolved path so the
+ *     subsequent containment check still produces a clean refusal rather
+ *     than crashing.
+ */
+export function getAudioWorkspaceRoot() {
+    const envRoot = process.env.MCP_WORKSPACE_PATH;
+    const raw = envRoot && envRoot.trim() ? envRoot.trim() : os.tmpdir();
+    const lexical = path.resolve(raw);
+    try {
+        return fs.realpathSync(lexical);
+    }
+    catch {
+        return lexical;
+    }
+}
+/**
+ * Canonicalise the deepest existing ancestor of an absolute path and
+ * re-append the missing tail (M3-fix-C). This lets the lexical-prefix
+ * containment check accept in-workspace files supplied via a symlinked
+ * alias of the workspace root (e.g. `/tmp` → `/private/tmp` on macOS)
+ * while still rejecting `..` traversal and out-of-root absolutes
+ * deterministically WITHOUT requiring the leaf file to exist. Critical
+ * for the ENOENT branch: the in-workspace-but-missing case must classify
+ * as FILE_NOT_FOUND, not as a sandbox-deny.
+ */
+function canonicalisePrefix(absoluteLexical) {
+    const tail = [];
+    let cur = absoluteLexical;
+    while (true) {
+        try {
+            const real = fs.realpathSync(cur);
+            return tail.length === 0 ? real : path.join(real, ...tail.reverse());
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== 'ENOENT' && code !== 'ENOTDIR') {
+                throw err;
+            }
+        }
+        const parent = path.dirname(cur);
+        if (parent === cur) {
+            return absoluteLexical;
+        }
+        tail.push(path.basename(cur));
+        cur = parent;
+    }
+}
+/**
+ * Validate that an LLM-supplied `file_path` argument resolves to a real
+ * file under the audio workspace sandbox root, even after symlink
+ * resolution. Returns the canonicalised path on success.
+ *
+ * Security rules:
+ *  - Tilde (`~`) is expanded lexically; the expanded path must still be
+ *    inside the workspace root.
+ *  - Lexical `path.resolve` collapses `..` segments; a path that resolves
+ *    outside the root is rejected before any disk read.
+ *  - Existing files have their canonical path computed via
+ *    `fs.realpathSync` so a symlink inside the root pointing OUTSIDE the
+ *    root is refused.
+ *  - Remote URL inputs (https://, http://) MUST be detected and bypassed
+ *    by the caller via `isRemoteUrl` BEFORE invoking this helper.
+ *
+ * On rejection, the error string includes both the substring "workspace"
+ * and "sandbox" so validators / log scanners can match either keyword.
+ */
+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);
+    // Step 1: lexical normalisation — expand `~`, collapse `..`, absolutise.
+    const expanded = filePath.startsWith('~')
+        ? path.join(os.homedir(), filePath.slice(1))
+        : filePath;
+    const lexical = path.resolve(expanded);
+    // Step 2: canonicalise the deepest existing ancestor (M3-fix-C) and
+    // run the prefix check against the canonical candidate. This is what
+    // makes `/tmp/foo.mp3` work when the workspace root is the symlinked
+    // alias `/tmp` and the canonical root is `/private/tmp`. Doing this
+    // BEFORE the realpath of the leaf is crucial for the ENOENT branch:
+    // an in-workspace-but-missing file must classify as FILE_NOT_FOUND,
+    // not as a sandbox-deny. Conversely, `..` traversal and out-of-root
+    // absolutes still fail this check without requiring the leaf to
+    // exist.
+    const canonicalCandidate = canonicalisePrefix(lexical);
+    if (!isInsideRoot(canonicalCandidate)) {
+        return { ok: false, error: denyMessage };
+    }
+    // Step 3: full realpath on the input. This catches the (rare) case
+    // where the leaf itself is a symlink inside the root pointing OUTSIDE
+    // the root. If the file does not exist, surface FILE_NOT_FOUND now
+    // that we know the candidate is in-workspace.
+    let canonical;
+    try {
+        canonical = fs.realpathSync(lexical);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            return { ok: false, error: `File not found: ${filePath}` };
+        }
+        throw err;
+    }
+    if (!isInsideRoot(canonical)) {
+        return {
+            ok: false,
+            error: `file_path resolves outside the workspace sandbox root (${root}); ` +
+                `symlinks may not escape the workspace. Got: ${filePath}`,
+        };
+    }
+    return { ok: true, path: canonical };
+}
+//# sourceMappingURL=path-safety.js.map

package/dist/tools/speech.d.ts

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

package/dist/tools/speech.js

@@ -0,0 +1,126 @@
+import { z } from 'zod';
+import { getApiKey } from '../auth.js';
+import { elevenLabsJson, elevenLabsAudio } from '../client.js';
+import { ElevenLabsError } from '../types.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`);
+    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.`);
+    }
+    return 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.',
+        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.'),
+            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()
+                .describe('Audio output format. Default: mp3_44100_128.'),
+        }),
+        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.');
+        }
+        let voiceId = args.voice_id;
+        const voiceName = args.voice_name;
+        const modelId = args.model_id ?? 'eleven_multilingual_v2';
+        const stability = args.stability ?? 0.5;
+        const similarityBoost = args.similarity_boost ?? 0.75;
+        const outputFormat = args.output_format ?? 'mp3_44100_128';
+        // Voice lookup
+        let resolvedVoiceName = voiceName || 'default';
+        if (!voiceId) {
+            if (voiceName) {
+                const voice = await lookupVoiceByName(apiKey, voiceName);
+                voiceId = voice.voice_id;
+                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.');
+                }
+            }
+        }
+        const body = {
+            text: args.text,
+            model_id: modelId,
+            voice_settings: {
+                stability,
+                similarity_boost: similarityBoost,
+            },
+        };
+        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);
+        return JSON.stringify({
+            ok: true,
+            file_path: result.filePath,
+            size_bytes: result.sizeBytes,
+            voice: 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).`,
+        });
+    }));
+    // ── 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.',
+        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.'),
+            prompt_influence: z.number().min(0).max(1).optional().describe('How closely to follow the prompt (0-1). Default: 0.3.'),
+        }),
+        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 promptInfluence = args.prompt_influence ?? 0.3;
+        const body = {
+            text: args.prompt,
+            prompt_influence: promptInfluence,
+        };
+        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');
+        return JSON.stringify({
+            ok: true,
+            file_path: result.filePath,
+            size_bytes: result.sizeBytes,
+            duration_seconds: args.duration_seconds ?? 'auto',
+            message: `Sound effect generated and saved to ${result.filePath} (${(result.sizeBytes / 1024).toFixed(1)} KB).`,
+        });
+    }));
+}
+//# sourceMappingURL=speech.js.map

package/dist/tools/transcription.d.ts

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

package/dist/tools/transcription.js

@@ -0,0 +1,94 @@
+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 { ElevenLabsError } from '../types.js';
+import { withErrorHandling } from '../utils.js';
+import { isRemoteUrl, resolveAudioPath } from './path-safety.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.',
+        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.'),
+        }),
+        annotations: { readOnlyHint: true, 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 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
+        const formData = new FormData();
+        formData.append('audio', new Blob([fileBuffer]), fileName);
+        if (args.language_code) {
+            formData.append('language_code', args.language_code);
+        }
+        const data = await elevenLabsJson(apiKey, '/speech-to-text', {
+            method: 'POST',
+            body: formData,
+        });
+        return JSON.stringify({
+            ok: true,
+            text: data.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.`,
+        });
+    }));
+}
+//# sourceMappingURL=transcription.js.map

package/dist/tools/voices.d.ts

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

package/dist/tools/voices.js

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+import { getApiKey } from '../auth.js';
+import { elevenLabsJson } from '../client.js';
+import { ElevenLabsError } from '../types.js';
+import { withErrorHandling } from '../utils.js';
+export function registerVoiceTools(server) {
+    server.registerTool('list_voices', {
+        description: 'Search and browse available ElevenLabs voices. FREE — no credits consumed. ' +
+            'Returns voice ID, name, description, category, preview URL, and labels. ' +
+            'Use voice_id from results with generate_speech.',
+        inputSchema: z.object({
+            search: z.string().optional().describe('Search query to filter voices by name.'),
+            category: z.enum(['premade', 'cloned', 'generated', 'professional']).optional()
+                .describe('Filter by voice category.'),
+            page_size: z.number().int().min(1).max(100).optional().describe('Number of results (1-100). Default: 20.'),
+        }),
+        annotations: { readOnlyHint: true, 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 params = new URLSearchParams();
+        if (args.search)
+            params.set('search', args.search);
+        if (args.category)
+            params.set('category', args.category);
+        params.set('page_size', String(Math.min(100, args.page_size ?? 20)));
+        const data = await elevenLabsJson(apiKey, `https://api.elevenlabs.io/v2/voices?${params.toString()}`);
+        const voices = data.voices.map((v) => ({
+            voice_id: v.voice_id,
+            name: v.name,
+            category: v.category,
+            description: v.description,
+            labels: v.labels,
+            preview_url: v.preview_url,
+        }));
+        return JSON.stringify({
+            ok: true,
+            voices,
+            count: voices.length,
+            has_more: data.has_more || false,
+            cost: 'FREE — no credits consumed',
+            message: `Found ${voices.length} voice${voices.length === 1 ? '' : 's'}${args.search ? ` matching "${args.search}"` : ''}.`,
+            hint: 'Use voice_id with generate_speech to create audio with a specific voice.',
+        });
+    }));
+}
+//# sourceMappingURL=voices.js.map