@mindstone/mcp-server-elevenlabs 0.3.0 → 0.4.0

package/README.md

@@ -7,11 +7,10 @@ ElevenLabs MCP server for Model Context Protocol hosts. Generate speech, music,
 
 ## Status
 
-- **Version:** [0.3.0](./CHANGELOG.md) · [npm](https://www.npmjs.com/package/@mindstone/mcp-server-elevenlabs)
+- **Version:** [0.4.0](./CHANGELOG.md) · [npm](https://www.npmjs.com/package/@mindstone/mcp-server-elevenlabs)
 - **Auth:** API key ([`ELEVENLABS_API_KEY`](./server.json))
-- **Tools:** [8](./src/tools/) (voices, speech, music, transcription)
+- **Tools:** [24](./src/tools/) (account, voices, speech, music, transcription, voice conversion, isolation, alignment, cloning, dialogue, voice design, dubbing)
 - **Surface:** cloud-api
-- **Hosts tested:** Claude Desktop, Cursor, Mindstone Rebel
 - **Machine-readable:** [`STATUS.json`](./STATUS.json)
 
 ## Requirements
@@ -115,17 +114,39 @@ node dist/index.js
 }
 ```
 
-## Tools (8)
+## Tools (24)
 
 ### Configuration
 - `configure_elevenlabs_api_key` — Save your ElevenLabs API key
 
-### Voices
-- `list_voices` — Search and browse available ElevenLabs voices
+### Account & discovery (FREE)
+- `check_subscription` — Check subscription tier and character credit usage
+- `list_models` — List TTS models with languages and capabilities
 
-### Speech
+### Voices
+- `list_voices` — Search and browse voices on your account
+- `get_voice` — Get full details for one voice by voice_id
+- `search_shared_voices` — Search the public shared voice library (filters include accent)
+- `clone_voice` — Create an instant voice clone from local audio samples (`destructiveHint`)
+- `delete_voice` — Permanently delete a voice (`destructiveHint`)
+- `design_voice` — Generate voice-design previews from a text description (slow; previews saved to tmp files)
+- `create_voice_from_preview` — Save a design preview as a permanent voice (`destructiveHint`)
+
+### Speech & conversion
 - `generate_speech` — Generate spoken audio from text using text-to-speech
 - `generate_sound_effect` — Generate sound effects from a text description
+- `speech_to_speech` — Convert source audio to a different voice
+- `text_to_dialogue` — Multi-voice dialogue from a script (one voice per line)
+
+### Audio processing
+- `isolate_audio` — Remove background noise from an audio file (source must be ≥ ~4.6s; shorter clips fail upstream)
+- `forced_alignment` — Align transcript text to audio with per-word timestamps
+
+### Dubbing (v1 API — async submit → poll → download)
+- `create_dubbing` — Submit a dubbing job (local `file` via sandbox or `source_url` for ElevenLabs-side fetch)
+- `get_dubbing` — Poll job status until `dubbed`, `failed`, or `cancelled`
+- `download_dubbed_audio` — Download dubbed audio (Content-Type sniffed)
+- `delete_dubbing` — Permanently delete a dubbing job (`destructiveHint`)
 
 ### Music
 - `generate_music` — Generate music from a text prompt
@@ -135,6 +156,8 @@ node dist/index.js
 ### Transcription
 - `transcribe_audio` — Transcribe speech from an audio file to text
 
+Local file paths for upload tools must be inside `MCP_WORKSPACE_PATH` (or `os.tmpdir()` when unset). See `src/tools/file-input.ts`.
+
 ## Licence
 
 [FSL-1.1-MIT](./LICENSE) — Functional Source License, Version 1.1, with MIT future licence. The software converts to MIT licence on 2030-04-08.

package/dist/bridge.d.ts

@@ -12,5 +12,6 @@ export declare const bridgeRequest: (urlPath: string, body: Record<string, unkno
     success: boolean;
     warning?: string;
     error?: string;
+    message?: string;
 }>;
 //# sourceMappingURL=bridge.d.ts.map

package/dist/client.d.ts

@@ -9,17 +9,48 @@
  * Voices URL: https://api.elevenlabs.io/v2/voices
  */
 import { type AudioResult } from './types.js';
+export interface ElevenLabsFetchOptions extends RequestInit {
+    /** Per-call timeout override (default REQUEST_TIMEOUT_MS). Explicit `signal` wins. */
+    timeoutMs?: number;
+}
 /**
  * Make an authenticated request to the ElevenLabs API.
  * Returns a raw Response object.
  */
-export declare function elevenLabsFetch(apiKey: string, urlPath: string, options?: RequestInit): Promise<Response>;
+export declare function elevenLabsFetch(apiKey: string, urlPath: string, options?: ElevenLabsFetchOptions): Promise<Response>;
+/**
+ * Extract a human-readable detail message from an ElevenLabs error response.
+ *
+ * The API uses several detail shapes:
+ *  - `detail: "string message"` (legacy)
+ *  - `detail: { message: "...", status?: "..." }` (current auth/permission errors)
+ *  - `detail: [{ type, loc: ["body", "field", ...], msg, input }, ...]` (FastAPI 422)
+ *
+ * The 422 array form is the one that bit us in
+ * `generate_music_from_plan`: previously we threw away the field-level info
+ * and left the user with `HTTP 422: unknown`. We now flatten the validation
+ * errors into something like
+ *   `body.composition_plan.sections.0.section_name: Field required;
+ *    body.composition_plan.sections.0.lines: Field required`
+ * which is what an LLM agent actually needs to self-correct.
+ *
+ * Raw detail is third-party-authored — callers must envelope before exposing
+ * to model-visible output (see `envelopeApiErrorDetail`).
+ */
+export declare function extractErrorDetail(response: Response): Promise<string>;
 /**
  * Make a JSON API call and parse the response.
  */
-export declare function elevenLabsJson<T>(apiKey: string, urlPath: string, options?: RequestInit): Promise<T>;
+export declare function elevenLabsJson<T>(apiKey: string, urlPath: string, options?: ElevenLabsFetchOptions): Promise<T>;
+/** Map response Content-Type to a file extension (OpenAPI drift — don't trust empty schemas). */
+export declare function extensionFromContentType(contentType: string | null | undefined): string;
 /**
  * Make an API call that returns raw audio binary. Save to file and return path.
  */
-export declare function elevenLabsAudio(apiKey: string, urlPath: string, options?: RequestInit, fileExtension?: string): Promise<AudioResult>;
+export declare function elevenLabsAudio(apiKey: string, urlPath: string, options?: ElevenLabsFetchOptions, fileExtension?: string): Promise<AudioResult>;
+/**
+ * Download binary audio with content-type sniffing.
+ * When the API returns JSON (error body despite 200 drift), surfaces the flattened error.
+ */
+export declare function elevenLabsBinaryDownload(apiKey: string, urlPath: string, options?: ElevenLabsFetchOptions): Promise<AudioResult>;
 //# sourceMappingURL=client.d.ts.map

package/dist/client.js

@@ -13,7 +13,8 @@ import * as path from 'path';
 import * as os from 'os';
 import * as crypto from 'crypto';
 import { ElevenLabsError, REQUEST_TIMEOUT_MS, getErrorResolution, } from './types.js';
-const ELEVENLABS_API_BASE = 'https://api.elevenlabs.io/v1';
+import { ELEVENLABS_API_V1_BASE } from './endpoints.js';
+import { envelopeApiErrorDetail, formatApiErrorMessage } from './error-detail.js';
 /**
  * Make an authenticated request to the ElevenLabs API.
  * Returns a raw Response object.
@@ -24,21 +25,22 @@ export async function elevenLabsFetch(apiKey, urlPath, options = {}) {
     }
     const url = urlPath.startsWith('https://')
         ? urlPath
-        : `${ELEVENLABS_API_BASE}${urlPath}`;
+        : `${ELEVENLABS_API_V1_BASE}${urlPath}`;
+    const { timeoutMs, ...fetchOptions } = options;
     const headers = {
         'xi-api-key': apiKey,
-        ...(options.headers || {}),
+        ...(fetchOptions.headers || {}),
     };
     // Only set Content-Type for JSON bodies (not FormData)
-    if (!(options.body instanceof FormData) && !headers['Content-Type']) {
+    if (!(fetchOptions.body instanceof FormData) && !headers['Content-Type']) {
         headers['Content-Type'] = 'application/json';
     }
-    console.error(`[ElevenLabs API] ${options.method || 'GET'} ${url}`);
+    console.error(`[ElevenLabs API] ${fetchOptions.method || 'GET'} ${url}`);
     let response;
     try {
         response = await fetch(url, {
-            ...options,
-            signal: options.signal ?? AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            ...fetchOptions,
+            signal: fetchOptions.signal ?? AbortSignal.timeout(timeoutMs ?? REQUEST_TIMEOUT_MS),
             headers,
         });
     }
@@ -60,22 +62,30 @@ export async function elevenLabsFetch(apiKey, urlPath, options = {}) {
     if (response.status === 401) {
         const detail = await extractErrorDetail(response);
         const isMissingPermission = detail.includes('missing_permissions');
+        const envelopedDetail = detail ? envelopeApiErrorDetail(detail) : '';
         throw new ElevenLabsError(isMissingPermission
-            ? `API key missing required permission: ${detail}`
+            ? `API key missing required permission: ${envelopedDetail}`
             : detail
-                ? `Authentication failed: ${detail}`
+                ? formatApiErrorMessage('Authentication failed', detail)
                 : 'Authentication failed', isMissingPermission ? 'MISSING_PERMISSION' : 'AUTH_FAILED', isMissingPermission
             ? 'Regenerate your API key at https://elevenlabs.io/app/settings/api-keys with the missing permission enabled, then call configure_elevenlabs_api_key again.'
             : getErrorResolution(401));
     }
     if (response.status === 403) {
         const detail = await extractErrorDetail(response);
-        throw new ElevenLabsError(`Access forbidden: ${detail || 'insufficient permissions or quota'}`, 'AUTH_FAILED', getErrorResolution(403, detail));
+        throw new ElevenLabsError(detail
+            ? formatApiErrorMessage('Access forbidden', detail)
+            : 'Access forbidden: insufficient permissions or quota', 'AUTH_FAILED', getErrorResolution(403, detail));
     }
     // Handle other errors
     if (!response.ok) {
         const detail = await extractErrorDetail(response);
-        throw new ElevenLabsError(`ElevenLabs API error (HTTP ${response.status}): ${detail || response.statusText}`, `HTTP_${response.status}`, getErrorResolution(response.status, detail));
+        const statusText = response.statusText
+            ? envelopeApiErrorDetail(response.statusText)
+            : '';
+        throw new ElevenLabsError(detail
+            ? `ElevenLabs API error (HTTP ${response.status}): ${envelopeApiErrorDetail(detail)}`
+            : `ElevenLabs API error (HTTP ${response.status})${statusText ? `: ${statusText}` : ''}`, `HTTP_${response.status}`, getErrorResolution(response.status, detail));
     }
     return response;
 }
@@ -94,8 +104,11 @@ export async function elevenLabsFetch(apiKey, urlPath, options = {}) {
  *   `body.composition_plan.sections.0.section_name: Field required;
  *    body.composition_plan.sections.0.lines: Field required`
  * which is what an LLM agent actually needs to self-correct.
+ *
+ * Raw detail is third-party-authored — callers must envelope before exposing
+ * to model-visible output (see `envelopeApiErrorDetail`).
  */
-async function extractErrorDetail(response) {
+export async function extractErrorDetail(response) {
     try {
         const errBody = (await response.clone().json());
         const d = errBody?.detail;
@@ -146,13 +159,54 @@ export async function elevenLabsJson(apiKey, urlPath, options = {}) {
     const response = await elevenLabsFetch(apiKey, urlPath, options);
     return (await response.json());
 }
+/** Map response Content-Type to a file extension (OpenAPI drift — don't trust empty schemas). */
+export function extensionFromContentType(contentType) {
+    if (!contentType)
+        return 'mp3';
+    const ct = contentType.split(';')[0]?.trim().toLowerCase() ?? '';
+    const map = {
+        'audio/mpeg': 'mp3',
+        'audio/mp3': 'mp3',
+        'audio/wav': 'wav',
+        'audio/x-wav': 'wav',
+        'audio/wave': 'wav',
+        'audio/ogg': 'ogg',
+        'audio/flac': 'flac',
+        'audio/mp4': 'm4a',
+        'audio/aac': 'aac',
+        'audio/webm': 'webm',
+    };
+    return map[ct] ?? 'mp3';
+}
 /**
  * Make an API call that returns raw audio binary. Save to file and return path.
  */
-export async function elevenLabsAudio(apiKey, urlPath, options = {}, fileExtension = 'mp3') {
+export async function elevenLabsAudio(apiKey, urlPath, options = {}, fileExtension) {
     const response = await elevenLabsFetch(apiKey, urlPath, options);
+    const contentType = response.headers.get('content-type');
+    const ext = fileExtension ?? extensionFromContentType(contentType);
+    const buffer = Buffer.from(await response.arrayBuffer());
+    const fileName = `elevenlabs_${crypto.randomUUID()}.${ext}`;
+    const filePath = path.join(os.tmpdir(), fileName);
+    fs.writeFileSync(filePath, buffer);
+    return { filePath, sizeBytes: buffer.length };
+}
+/**
+ * Download binary audio with content-type sniffing.
+ * When the API returns JSON (error body despite 200 drift), surfaces the flattened error.
+ */
+export async function elevenLabsBinaryDownload(apiKey, urlPath, options = {}) {
+    const response = await elevenLabsFetch(apiKey, urlPath, options);
+    const contentType = response.headers.get('content-type') ?? '';
+    if (contentType.includes('application/json')) {
+        const detail = await extractErrorDetail(response);
+        throw new ElevenLabsError(detail
+            ? formatApiErrorMessage('Download failed', detail)
+            : 'Download failed: API returned JSON instead of audio', 'DOWNLOAD_FAILED', detail ? getErrorResolution(422, detail) : 'Verify dubbing status with get_dubbing before downloading.');
+    }
+    const ext = extensionFromContentType(contentType);
     const buffer = Buffer.from(await response.arrayBuffer());
-    const fileName = `elevenlabs_${crypto.randomUUID()}.${fileExtension}`;
+    const fileName = `elevenlabs_${crypto.randomUUID()}.${ext}`;
     const filePath = path.join(os.tmpdir(), fileName);
     fs.writeFileSync(filePath, buffer);
     return { filePath, sizeBytes: buffer.length };

package/dist/endpoints.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Canonical ElevenLabs API endpoint paths.
+ *
+ * Every path used by this connector lives here so a wrong path is a
+ * one-line fix. v1 paths are relative to `ELEVENLABS_API_V1_BASE`; v2 voice
+ * listing uses the separate v2 base URL.
+ */
+export declare const ELEVENLABS_API_V1_BASE = "https://api.elevenlabs.io/v1";
+export declare const ELEVENLABS_API_V2_BASE = "https://api.elevenlabs.io/v2";
+/** v1 relative paths — pass to `elevenLabsFetch` / `elevenLabsJson`. */
+export declare const ENDPOINTS: {
+    readonly USER_SUBSCRIPTION: "/user/subscription";
+    readonly MODELS: "/models";
+    readonly SHARED_VOICES: "/shared-voices";
+    readonly SOUND_GENERATION: "/sound-generation";
+    readonly MUSIC: "/music";
+    readonly MUSIC_PLAN: "/music/plan";
+    readonly SPEECH_TO_TEXT: "/speech-to-text";
+    readonly AUDIO_ISOLATION: "/audio-isolation";
+    readonly FORCED_ALIGNMENT: "/forced-alignment";
+    readonly VOICES_ADD: "/voices/add";
+    readonly TEXT_TO_DIALOGUE: "/text-to-dialogue";
+    readonly TEXT_TO_VOICE_DESIGN: "/text-to-voice/design";
+    readonly TEXT_TO_VOICE: "/text-to-voice";
+    readonly DUBBING: "/dubbing";
+    readonly voice: (voiceId: string) => string;
+    readonly dubbing: (dubbingId: string) => string;
+    readonly dubbingAudio: (dubbingId: string, languageCode: string) => string;
+    readonly speechToSpeech: (voiceId: string) => string;
+    readonly textToSpeech: (voiceId: string, outputFormat: string) => string;
+};
+/** Build a full v2 voices list/search URL with optional query string. */
+export declare function voicesV2Url(params?: URLSearchParams): string;
+//# sourceMappingURL=endpoints.d.ts.map

package/dist/endpoints.js

@@ -0,0 +1,37 @@
+/**
+ * Canonical ElevenLabs API endpoint paths.
+ *
+ * Every path used by this connector lives here so a wrong path is a
+ * one-line fix. v1 paths are relative to `ELEVENLABS_API_V1_BASE`; v2 voice
+ * listing uses the separate v2 base URL.
+ */
+export const ELEVENLABS_API_V1_BASE = 'https://api.elevenlabs.io/v1';
+export const ELEVENLABS_API_V2_BASE = 'https://api.elevenlabs.io/v2';
+/** v1 relative paths — pass to `elevenLabsFetch` / `elevenLabsJson`. */
+export const ENDPOINTS = {
+    USER_SUBSCRIPTION: '/user/subscription',
+    MODELS: '/models',
+    SHARED_VOICES: '/shared-voices',
+    SOUND_GENERATION: '/sound-generation',
+    MUSIC: '/music',
+    MUSIC_PLAN: '/music/plan',
+    SPEECH_TO_TEXT: '/speech-to-text',
+    AUDIO_ISOLATION: '/audio-isolation',
+    FORCED_ALIGNMENT: '/forced-alignment',
+    VOICES_ADD: '/voices/add',
+    TEXT_TO_DIALOGUE: '/text-to-dialogue',
+    TEXT_TO_VOICE_DESIGN: '/text-to-voice/design',
+    TEXT_TO_VOICE: '/text-to-voice',
+    DUBBING: '/dubbing',
+    voice: (voiceId) => `/voices/${encodeURIComponent(voiceId)}`,
+    dubbing: (dubbingId) => `/dubbing/${encodeURIComponent(dubbingId)}`,
+    dubbingAudio: (dubbingId, languageCode) => `/dubbing/${encodeURIComponent(dubbingId)}/audio/${encodeURIComponent(languageCode)}`,
+    speechToSpeech: (voiceId) => `/speech-to-speech/${encodeURIComponent(voiceId)}`,
+    textToSpeech: (voiceId, outputFormat) => `/text-to-speech/${encodeURIComponent(voiceId)}?output_format=${encodeURIComponent(outputFormat)}`,
+};
+/** Build a full v2 voices list/search URL with optional query string. */
+export function voicesV2Url(params) {
+    const qs = params?.toString();
+    return `${ELEVENLABS_API_V2_BASE}/voices${qs ? `?${qs}` : ''}`;
+}
+//# sourceMappingURL=endpoints.js.map

package/dist/error-detail.d.ts

@@ -0,0 +1,5 @@
+/** Wrap API-authored error detail for inclusion in ElevenLabsError message/resolution. */
+export declare function envelopeApiErrorDetail(detail: string): string;
+/** Prefix + enveloped detail, or the prefix alone when detail is empty. */
+export declare function formatApiErrorMessage(prefix: string, detail: string): string;
+//# sourceMappingURL=error-detail.d.ts.map

package/dist/error-detail.js

@@ -0,0 +1,20 @@
+/**
+ * Envelope third-party API error `detail` strings before they reach model-visible
+ * tool error output (message + resolution). FastAPI-422 flattening stays intact —
+ * we wrap the flattened string, we do not discard field-path usefulness.
+ */
+import { wrapUntrusted } from './untrusted-content.js';
+const ERROR_DETAIL_SOURCE = 'elevenlabs:api:error_detail';
+/** Wrap API-authored error detail for inclusion in ElevenLabsError message/resolution. */
+export function envelopeApiErrorDetail(detail) {
+    if (!detail)
+        return '';
+    return wrapUntrusted(detail, ERROR_DETAIL_SOURCE);
+}
+/** Prefix + enveloped detail, or the prefix alone when detail is empty. */
+export function formatApiErrorMessage(prefix, detail) {
+    if (!detail)
+        return prefix;
+    return `${prefix}: ${envelopeApiErrorDetail(detail)}`;
+}
+//# sourceMappingURL=error-detail.js.map

package/dist/server.js

@@ -1,6 +1,6 @@
 import { createRequire } from 'node:module';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { registerConfigureTools, registerMusicTools, registerSpeechTools, registerVoiceTools, registerTranscriptionTools, } from './tools/index.js';
+import { registerConfigureTools, registerAccountTools, registerMusicTools, registerSpeechTools, registerVoiceTools, registerTranscriptionTools, registerVoiceChangerTools, registerAudioIsolationTools, registerAlignmentTools, registerVoiceCloneTools, registerDialogueTools, registerVoiceDesignTools, registerDubbingTools, } from './tools/index.js';
 const require = createRequire(import.meta.url);
 const pkg = require('../package.json');
 export function createServer() {
@@ -9,10 +9,18 @@ export function createServer() {
         version: pkg.version,
     });
     registerConfigureTools(server);
+    registerAccountTools(server);
     registerMusicTools(server);
     registerSpeechTools(server);
     registerVoiceTools(server);
     registerTranscriptionTools(server);
+    registerVoiceChangerTools(server);
+    registerAudioIsolationTools(server);
+    registerAlignmentTools(server);
+    registerVoiceCloneTools(server);
+    registerDialogueTools(server);
+    registerVoiceDesignTools(server);
+    registerDubbingTools(server);
     return server;
 }
 //# sourceMappingURL=server.js.map

package/dist/tools/account.d.ts

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

package/dist/tools/account.js

@@ -0,0 +1,105 @@
+import { z } from 'zod';
+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';
+export function registerAccountTools(server) {
+    server.registerTool('check_subscription', {
+        description: `Check ElevenLabs subscription tier and character credit usage.
+
+WHEN TO USE:
+- Before expensive generation calls (speech, music, sound effects) to confirm credits remain
+- When a tool returns quota or 403 errors — read remaining characters and next reset
+- To answer "how much ElevenLabs credit do I have left?"
+
+EXAMPLE: {} (no arguments)
+
+RELATED TOOLS:
+- generate_speech, generate_music, generate_sound_effect: credit-consuming generation
+- list_models: discover which models your tier can use
+
+RETURNS: tier, character_count, character_limit, characters_remaining, next_character_count_reset_unix (and ISO), status when present.
+
+COST: FREE — no credits consumed.`,
+        inputSchema: z.object({}),
+        annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
+    }, withErrorHandling(async () => {
+        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 data = await elevenLabsJson(apiKey, ENDPOINTS.USER_SUBSCRIPTION);
+        const characterCount = data.character_count ?? 0;
+        const characterLimit = data.character_limit ?? 0;
+        const remaining = Math.max(0, characterLimit - characterCount);
+        const resetUnix = data.next_character_count_reset_unix;
+        const resetIso = resetUnix
+            ? new Date(resetUnix * 1000).toISOString()
+            : undefined;
+        return JSON.stringify({
+            ok: true,
+            tier: wrapUntrusted(data.tier ?? undefined, 'elevenlabs:check_subscription:tier'),
+            status: wrapUntrusted(data.status ?? undefined, 'elevenlabs:check_subscription:status'),
+            character_count: characterCount,
+            character_limit: characterLimit,
+            characters_remaining: remaining,
+            next_character_count_reset_unix: resetUnix,
+            next_character_count_reset_iso: resetIso,
+            voice_slots_used: data.voice_slots_used,
+            voice_limit: data.voice_limit,
+            cost: 'FREE — no credits consumed',
+            message: `${remaining.toLocaleString()} of ${characterLimit.toLocaleString()} characters remaining` +
+                (resetIso ? `; next reset ${resetIso}` : '') +
+                '. See tier field for plan name.',
+            hint: 'Call this before large batch generations. Quota errors elsewhere should be resolved by waiting for reset or upgrading the plan.',
+        });
+    }));
+    server.registerTool('list_models', {
+        description: `List ElevenLabs models with languages and capability flags.
+
+WHEN TO USE:
+- Pick a TTS model_id for generate_speech (e.g. eleven_v3, eleven_multilingual_v2)
+- Verify a model supports the language or capability you need before calling generation tools
+- Discover model IDs after an invalid model_id error
+
+EXAMPLE: {} (no arguments)
+
+RELATED TOOLS:
+- generate_speech: consumes a model_id from this list
+- check_subscription: confirm credits before generation
+
+RETURNS: models[] with model_id, name, languages[], and capability booleans (TTS, voice conversion, finetuning).
+
+COST: FREE — no credits consumed.`,
+        inputSchema: z.object({}),
+        annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
+    }, withErrorHandling(async () => {
+        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 raw = await elevenLabsJson(apiKey, ENDPOINTS.MODELS);
+        const models = (Array.isArray(raw) ? raw : []).map((m) => ({
+            model_id: m.model_id,
+            name: wrapUntrusted(m.name, 'elevenlabs:list_models:name'),
+            can_do_text_to_speech: m.can_do_text_to_speech,
+            can_do_voice_conversion: m.can_do_voice_conversion,
+            can_be_finetuned: m.can_be_finetuned,
+            token_cost_factor: m.token_cost_factor,
+            languages: (m.languages ?? []).map((lang) => ({
+                language_id: lang.language_id,
+                name: wrapUntrusted(lang.name, 'elevenlabs:list_models:language_name'),
+            })),
+        }));
+        return JSON.stringify({
+            ok: true,
+            models,
+            count: models.length,
+            cost: 'FREE — no credits consumed',
+            message: `Found ${models.length} model${models.length === 1 ? '' : 's'}. Use model_id with generate_speech.`,
+        });
+    }));
+}
+//# sourceMappingURL=account.js.map

package/dist/tools/alignment.d.ts

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

package/dist/tools/alignment.js

@@ -0,0 +1,55 @@
+import { z } from 'zod';
+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 { readSandboxedFile, sandboxedFileToBlob } from './file-input.js';
+export function registerAlignmentTools(server) {
+    server.registerTool('forced_alignment', {
+        description: `Align a transcript to audio and return per-word timestamps.
+
+WHEN TO USE:
+- Build karaoke-style captions or precise edit markers from audio + transcript
+- Verify that spoken words match a provided script
+
+EXAMPLE: {"file_path": "/path/to/clip.mp3", "text": "Hello world."}
+
+RELATED TOOLS:
+- transcribe_audio: generate transcript text from audio alone
+- generate_speech: create audio from text (inverse workflow)
+
+RETURNS: words[] with enveloped aligned text and start/end times, plus loss score. Input transcript text is caller-supplied and not echoed raw.
+
+COST: Credits based on audio duration.`,
+        inputSchema: z.object({
+            file_path: z.string().min(1).describe('Absolute path to local audio inside MCP_WORKSPACE_PATH (or os.tmpdir()).'),
+            text: z.string().min(1).describe('Transcript text to align against the audio.'),
+        }),
+        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 fileInput = readSandboxedFile(args.file_path);
+        const formData = new FormData();
+        formData.append('file', sandboxedFileToBlob(fileInput), fileInput.fileName);
+        formData.append('text', args.text);
+        const data = await elevenLabsJson(apiKey, ENDPOINTS.FORCED_ALIGNMENT, { method: 'POST', body: formData });
+        const words = (data.words ?? []).map((w) => ({
+            text: wrapUntrusted(w.text, 'elevenlabs:forced_alignment:word_text'),
+            start: w.start,
+            end: w.end,
+        }));
+        return JSON.stringify({
+            ok: true,
+            words,
+            word_count: words.length,
+            loss: data.loss,
+            message: `Aligned ${words.length} word${words.length === 1 ? '' : 's'} to audio.`,
+        });
+    }));
+}
+//# sourceMappingURL=alignment.js.map

package/dist/tools/audio-isolation.d.ts

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

package/dist/tools/audio-isolation.js

@@ -0,0 +1,51 @@
+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 registerAudioIsolationTools(server) {
+    server.registerTool('isolate_audio', {
+        description: `Remove background noise from an audio file (audio isolation).
+
+WHEN TO USE:
+- Clean up meeting recordings or voice memos with background noise
+- Prepare a cleaner clip before transcription or voice cloning
+- Source audio is at least ~4.6 seconds long (shorter clips fail upstream)
+
+COMMON MISTAKES:
+- Clips under ~4.6 seconds — the API rejects them; trim/merge or pick a longer sample first
+
+EXAMPLE: {"audio_path": "/path/to/noisy.mp3"}
+
+RELATED TOOLS:
+- transcribe_audio: transcribe the isolated clip
+- speech_to_speech: apply a different voice after isolation
+- clone_voice: clone from a cleaner sample
+
+RETURNS: file_path and size_bytes for the isolated audio (saved under os.tmpdir()).
+
+COST: Credits based on audio duration.`,
+        inputSchema: z.object({
+            audio_path: z.string().min(1).describe('Absolute path to local audio inside MCP_WORKSPACE_PATH (or os.tmpdir()).'),
+        }),
+        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);
+        const result = await elevenLabsAudio(apiKey, ENDPOINTS.AUDIO_ISOLATION, { method: 'POST', body: formData }, 'mp3');
+        return JSON.stringify({
+            ok: true,
+            file_path: result.filePath,
+            size_bytes: result.sizeBytes,
+            message: `Isolated audio saved to ${result.filePath} (${(result.sizeBytes / 1024).toFixed(1)} KB).`,
+        });
+    }));
+}
+//# sourceMappingURL=audio-isolation.js.map