@mindstone/mcp-server-elevenlabs 0.2.2 → 0.3.0

package/README.md

@@ -5,11 +5,52 @@
 
 ElevenLabs MCP server for Model Context Protocol hosts. Generate speech, music, and sound effects, browse voices, and transcribe audio using the ElevenLabs API through a standardised MCP interface.
 
+## Status
+
+- **Version:** [0.3.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)
+- **Surface:** cloud-api
+- **Hosts tested:** Claude Desktop, Cursor, Mindstone Rebel
+- **Machine-readable:** [`STATUS.json`](./STATUS.json)
+
 ## Requirements
 
 - Node.js 20+
 - npm
 
+<!-- BEGIN INSTALL_LINKS: do not edit by hand; regenerated by scripts/gen-install-links.mjs -->
+## One-click install
+
+[![Add to Cursor](https://img.shields.io/badge/Add_to_Cursor-black?style=for-the-badge&logo=cursor&logoColor=white)](cursor://anysphere.cursor-deeplink/mcp/install?name=ElevenLabs&config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBtaW5kc3RvbmUvbWNwLXNlcnZlci1lbGV2ZW5sYWJzIl0sImVudiI6eyJFTEVWRU5MQUJTX0FQSV9LRVkiOiIifX0)
+[![Add to VS Code](https://img.shields.io/badge/Add_to_VS_Code-007ACC?style=for-the-badge&logo=visual-studio-code&logoColor=white)](vscode:mcp/install?%7B%22name%22%3A%22ElevenLabs%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40mindstone%2Fmcp-server-elevenlabs%22%5D%2C%22env%22%3A%7B%22ELEVENLABS_API_KEY%22%3A%22%22%7D%7D)
+[![Add to VS Code Insiders](https://img.shields.io/badge/Add_to_VS_Code_Insiders-24bfa5?style=for-the-badge&logo=visual-studio-code&logoColor=white)](vscode-insiders:mcp/install?%7B%22name%22%3A%22ElevenLabs%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40mindstone%2Fmcp-server-elevenlabs%22%5D%2C%22env%22%3A%7B%22ELEVENLABS_API_KEY%22%3A%22%22%7D%7D)
+
+After clicking the button, your host will prompt you to fill: `ELEVENLABS_API_KEY`.
+
+<details>
+<summary>Manual config for Claude Desktop / Claude Code / Goose / Continue.dev (ElevenLabs)</summary>
+
+```json
+{
+  "mcpServers": {
+    "ElevenLabs": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@mindstone/mcp-server-elevenlabs"
+      ],
+      "env": {
+        "ELEVENLABS_API_KEY": ""
+      }
+    }
+  }
+}
+```
+
+</details>
+<!-- END INSTALL_LINKS -->
+
 ## Quick Start
 
 ### Install & build

package/dist/client.js

@@ -52,41 +52,93 @@ export async function elevenLabsFetch(apiKey, urlPath, options = {}) {
     if (response.status === 429) {
         throw new ElevenLabsError('Rate limited. Please wait a moment before retrying.', 'RATE_LIMITED', getErrorResolution(429));
     }
-    // Handle auth errors
+    // Handle auth errors. ElevenLabs returns 401 both for genuinely invalid
+    // keys AND for valid keys missing a specific scope (e.g. sound_generation).
+    // The latter ships a `detail.status = "missing_permissions"` payload that
+    // the user needs to see in order to fix the key permissions; previously we
+    // threw it away and emitted a bare "Authentication failed".
     if (response.status === 401) {
-        throw new ElevenLabsError('Authentication failed', 'AUTH_FAILED', getErrorResolution(401));
+        const detail = await extractErrorDetail(response);
+        const isMissingPermission = detail.includes('missing_permissions');
+        throw new ElevenLabsError(isMissingPermission
+            ? `API key missing required permission: ${detail}`
+            : detail
+                ? `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) {
-        let detail = '';
-        try {
-            const errBody = await response.clone().json();
-            if (typeof errBody.detail === 'string') {
-                detail = errBody.detail;
-            }
-            else if (errBody.detail?.message) {
-                detail = errBody.detail.message;
-            }
-        }
-        catch { /* not JSON */ }
+        const detail = await extractErrorDetail(response);
         throw new ElevenLabsError(`Access forbidden: ${detail || 'insufficient permissions or quota'}`, 'AUTH_FAILED', getErrorResolution(403, detail));
     }
     // Handle other errors
     if (!response.ok) {
-        let detail = '';
-        try {
-            const errBody = await response.clone().json();
-            if (typeof errBody.detail === 'string') {
-                detail = errBody.detail;
-            }
-            else if (errBody.detail?.message) {
-                detail = errBody.detail.message;
-            }
-        }
-        catch { /* not JSON */ }
+        const detail = await extractErrorDetail(response);
         throw new ElevenLabsError(`ElevenLabs API error (HTTP ${response.status}): ${detail || response.statusText}`, `HTTP_${response.status}`, getErrorResolution(response.status, detail));
     }
     return 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.
+ */
+async function extractErrorDetail(response) {
+    try {
+        const errBody = (await response.clone().json());
+        const d = errBody?.detail;
+        if (d == null)
+            return '';
+        if (typeof d === 'string')
+            return d;
+        if (Array.isArray(d)) {
+            // FastAPI validation errors → "loc.path: msg" joined by "; ".
+            // Skip null/non-object entries defensively rather than throwing.
+            const parts = d
+                .map((e) => {
+                if (!e || typeof e !== 'object')
+                    return '';
+                const entry = e;
+                const loc = Array.isArray(entry.loc) ? entry.loc.join('.') : '';
+                const msg = typeof entry.msg === 'string'
+                    ? entry.msg
+                    : typeof entry.type === 'string'
+                        ? entry.type
+                        : 'invalid';
+                return loc ? `${loc}: ${msg}` : msg;
+            })
+                .filter((s) => s.length > 0);
+            return parts.join('; ');
+        }
+        if (typeof d === 'object') {
+            const o = d;
+            const parts = [];
+            if (typeof o.status === 'string')
+                parts.push(o.status);
+            if (typeof o.message === 'string')
+                parts.push(o.message);
+            if (typeof o.cause === 'string')
+                parts.push(`cause: ${o.cause}`);
+            return parts.join(' — ');
+        }
+        return '';
+    }
+    catch {
+        return '';
+    }
+}
 /**
  * Make a JSON API call and parse the response.
  */

package/dist/tools/music.js

@@ -8,17 +8,76 @@ const OUTPUT_FORMAT_ENUM = z.enum([
     'pcm_16000', 'pcm_22050', 'pcm_24000', 'pcm_44100',
     'ulaw_8000',
 ]).optional();
+// Matches lyric section markers on their own line, with optional `]`, to
+// avoid false-positives on prose like `[intro to jazz]`.
+const LYRIC_MARKER_PATTERN = /(^|\n)\s*\[(verse|chorus|bridge|intro|outro|pre[- ]?chorus|hook|refrain)(\s\d+)?\s*\]/i;
+const MIN_TOTAL_MUSIC_MS = 3_000;
+const MAX_TOTAL_MUSIC_MS = 10 * 60 * 1_000; // 10 minutes per the API contract.
+/**
+ * Composition section schema — matches the live ElevenLabs API shape.
+ * Field names are NOT cosmetic: the API enforces these exact names with
+ * `additionalProperties: false`, so renaming any of them breaks generation.
+ *
+ * `positive_local_styles`, `negative_local_styles`, and `lines` are all
+ * required by the API even when empty. We accept them as optional in the
+ * input schema but `.default([])` them so a hand-written plan that omits an
+ * empty array still passes the API.
+ *
+ * `.strict()` rejects unknown keys — important because the prior connector
+ * version accepted a `{style, lyrics, ...}` shape, and we want to error fast
+ * if an LLM agent or older caller sends those (rather than silently strip
+ * them and ship a 422 from upstream). See planning doc
+ * 260520_elevenlabs_oss_connector_fix.md.
+ */
+const COMPOSITION_SECTION_SCHEMA = z.object({
+    section_name: z.string().min(1).max(100).describe('Section label like "Verse 1", "Chorus", "Bridge".'),
+    duration_ms: z.number().min(3000).max(120_000).describe('Section duration in milliseconds (3000-120000).'),
+    positive_local_styles: z.array(z.string()).max(50).default([])
+        .describe('Section-specific styles to include (max 50). Use for stage directions like "whispered vocals" or "male voice"; do NOT put these in lyrics. Pass [] for sections that have no special direction.'),
+    negative_local_styles: z.array(z.string()).max(50).default([])
+        .describe('Section-specific styles to avoid (max 50). Pass [] when nothing to avoid.'),
+    lines: z.array(z.string().max(200)).max(30).default([])
+        .describe('Lyric lines for this section (max 30 lines, 200 chars each). Singable/speakable text only — performance directions belong in positive_local_styles. Pass [] for instrumental sections.'),
+}).strict();
+const COMPOSITION_PLAN_SCHEMA = z.object({
+    positive_global_styles: z.array(z.string()).optional()
+        .describe('Styles to apply globally (genre, mood, tempo, key, BPM).'),
+    negative_global_styles: z.array(z.string()).optional()
+        .describe('Styles to avoid globally.'),
+    sections: z.array(COMPOSITION_SECTION_SCHEMA).min(1).max(30)
+        .describe('Array of sections (max 30). Total duration must be between 3 seconds and 10 minutes.'),
+})
+    .strict()
+    .superRefine((plan, ctx) => {
+    const total = plan.sections.reduce((acc, s) => acc + (s.duration_ms || 0), 0);
+    if (total < MIN_TOTAL_MUSIC_MS || total > MAX_TOTAL_MUSIC_MS) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['sections'],
+            message: `Total duration across sections must be between ${MIN_TOTAL_MUSIC_MS}ms (3s) and ${MAX_TOTAL_MUSIC_MS}ms (10min); got ${total}ms.`,
+        });
+    }
+})
+    .describe('Composition plan object — must match the shape returned by create_music_plan exactly. ' +
+    'Pass the plan through verbatim or edit individual fields. The legacy {style, lyrics} ' +
+    'shape used by ≤0.2.2 is no longer accepted (the API rejects it with HTTP 422).');
 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.',
+            '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.',
         inputSchema: z.object({
-            prompt: z.string().min(1).describe('Describe the music: genre, mood, instruments, style, lyrics.'),
+            prompt: z.string().min(1).describe('Describe the music: genre, mood, instruments, style. Include `[Verse]`/`[Chorus]`/`[Bridge]` blocks with lyrics if you want a vocal song.'),
             duration_seconds: z.number().min(3).max(600).optional().describe('Duration in seconds (3-600). Default: 30.'),
-            force_instrumental: z.boolean().optional().describe('Force instrumental-only output (no vocals). Default: false.'),
+            force_instrumental: z.boolean().optional().describe('Force instrumental-only output (no vocals). Default: false. WARNING: setting this to true overrides any lyrics in the prompt — do not enable for vocal songs.'),
             output_format: OUTPUT_FORMAT_ENUM.describe('Audio output format. Default: mp3_44100_128.'),
             seed: z.number().int().optional().describe('Random seed for reproducibility.'),
         }),
@@ -28,6 +87,15 @@ export function registerMusicTools(server) {
         if (!apiKey) {
             throw new ElevenLabsError('ElevenLabs API key not configured', 'AUTH_REQUIRED', 'Ask the user for their API key, then call configure_elevenlabs_api_key.');
         }
+        // Pre-call warning: force_instrumental + lyric markers means vocals get
+        // silently dropped. This bit a real conversation (260520) — emit a
+        // warning so the agent can self-correct rather than ship instrumental.
+        const warnings = [];
+        if (args.force_instrumental === true && LYRIC_MARKER_PATTERN.test(args.prompt)) {
+            warnings.push('force_instrumental: true was set, but the prompt contains lyric section ' +
+                'markers like [Verse]/[Chorus]. Vocals will be dropped. ' +
+                'Set force_instrumental: false (or omit it) to keep the vocal performance.');
+        }
         const durationSeconds = args.duration_seconds ?? 30;
         const durationMs = Math.max(3000, Math.min(600000, durationSeconds * 1000));
         const outputFormat = args.output_format ?? 'mp3_44100_128';
@@ -49,6 +117,7 @@ export function registerMusicTools(server) {
             duration_seconds: durationSeconds,
             format: outputFormat,
             message: `Music generated and saved to ${result.filePath} (${(result.sizeBytes / 1024).toFixed(1)} KB, ${durationSeconds}s).`,
+            warnings: warnings.length > 0 ? warnings : undefined,
         });
     }));
     // ── create_music_plan ─────────────────────────────────────────────────
@@ -84,23 +153,19 @@ export function registerMusicTools(server) {
             num_sections: plan.sections.length,
             cost: 'FREE — no credits consumed',
             message: `Composition plan created with ${plan.sections.length} sections (${(totalDurationMs / 1000).toFixed(1)}s total). Review the plan and pass it to generate_music_from_plan when ready.`,
-            hint: 'You can modify positive_global_styles, negative_global_styles, section styles, lyrics, and durations before generating.',
+            hint: 'You can modify positive_global_styles, negative_global_styles, and per-section positive_local_styles, negative_local_styles, lines (lyric lines), or duration_ms before generating.',
         });
     }));
     // ── generate_music_from_plan ──────────────────────────────────────────
     server.registerTool('generate_music_from_plan', {
         description: 'Generate music from a composition plan (created by create_music_plan or manually crafted). ' +
-            'The plan must have at least one section. COST: Consumes credits based on duration.',
+            '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.',
         inputSchema: z.object({
-            composition_plan: z.object({
-                positive_global_styles: z.array(z.string()).optional().describe('Styles to apply globally.'),
-                negative_global_styles: z.array(z.string()).optional().describe('Styles to avoid globally.'),
-                sections: z.array(z.object({
-                    style: z.string().optional(),
-                    lyrics: z.string().optional(),
-                    duration_ms: z.number().optional(),
-                })).min(1).describe('Array of sections, each with style, lyrics, and duration_ms.'),
-            }).describe('The composition plan object.'),
+            composition_plan: COMPOSITION_PLAN_SCHEMA,
             seed: z.number().int().optional().describe('Random seed for reproducibility.'),
             output_format: OUTPUT_FORMAT_ENUM.describe('Audio output format. Default: mp3_44100_128.'),
         }),
@@ -120,7 +185,7 @@ export function registerMusicTools(server) {
             body.seed = args.seed;
         const ext = outputFormat.startsWith('mp3') ? 'mp3' : 'wav';
         const result = await elevenLabsAudio(apiKey, `/music?output_format=${outputFormat}`, { method: 'POST', body: JSON.stringify(body) }, ext);
-        const totalDurationMs = (compositionPlan.sections ?? []).reduce((sum, s) => sum + (s.duration_ms || 0), 0);
+        const totalDurationMs = compositionPlan.sections.reduce((sum, s) => sum + (s.duration_ms || 0), 0);
         return JSON.stringify({
             ok: true,
             file_path: result.filePath,

package/dist/tools/speech.js

@@ -13,19 +13,51 @@ async function lookupVoiceByName(apiKey, name) {
     }
     return data.voices[0];
 }
+/**
+ * Pick a sensible default voice from the account.
+ *
+ * The previous version of this connector hardcoded a "Rachel" lookup, which
+ * silently fails on accounts that don't have Rachel in their library (most
+ * personal/business accounts). We now ask the API for the first page of
+ * voices, prefer premade voices, and fall back to whatever the account has.
+ *
+ * If the account has zero voices we surface a clear VOICE_NOT_FOUND with a
+ * resolution that tells the agent to call list_voices first.
+ */
+async function pickDefaultVoice(apiKey) {
+    const data = await elevenLabsJson(apiKey, 'https://api.elevenlabs.io/v2/voices?page_size=20');
+    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.');
+    }
+    // Prefer premade voices (curated, generally suitable as defaults).
+    const premade = data.voices.find((v) => v.category === 'premade');
+    return premade ?? data.voices[0];
+}
 export function registerSpeechTools(server) {
     // ── generate_speech ───────────────────────────────────────────────────
     server.registerTool('generate_speech', {
         description: 'Generate spoken audio from text using ElevenLabs text-to-speech. ' +
-            'Use voice_id (direct) or voice_name (fuzzy search). ' +
-            'Models: eleven_multilingual_v2 (default, 29 languages), eleven_monolingual_v1 (English), eleven_turbo_v2_5 (low latency). ' +
+            '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.',
         inputSchema: z.object({
             text: z.string().min(1).describe('Text to speak. Maximum ~5000 characters per request.'),
-            voice_id: z.string().optional().describe('Direct voice ID. Takes priority over voice_name.'),
-            voice_name: z.string().optional().describe('Voice name for fuzzy search (e.g., "Rachel", "Adam").'),
-            model_id: z.enum(['eleven_multilingual_v2', 'eleven_monolingual_v1', 'eleven_turbo_v2_5']).optional()
-                .describe('TTS model. Default: eleven_multilingual_v2.'),
+            voice_id: z.string().optional().describe('Direct voice ID (from list_voices). Takes priority over voice_name.'),
+            voice_name: z.string().optional().describe('Voice name for fuzzy search (e.g., "Bella", "Sarah"). Use list_voices first to find a name that exists on the account.'),
+            model_id: z.enum([
+                'eleven_v3',
+                'eleven_multilingual_v2',
+                'eleven_flash_v2_5',
+                'eleven_turbo_v2_5',
+                'eleven_monolingual_v1',
+            ]).optional()
+                .describe('TTS model. Default: eleven_v3.'),
             stability: z.number().min(0).max(1).optional().describe('Voice stability 0-1. Default: 0.5.'),
             similarity_boost: z.number().min(0).max(1).optional().describe('Voice similarity 0-1. Default: 0.75.'),
             output_format: z.enum(['mp3_44100_128', 'mp3_44100_192', 'pcm_16000', 'pcm_22050', 'pcm_24000', 'pcm_44100']).optional()
@@ -39,7 +71,7 @@ export function registerSpeechTools(server) {
         }
         let voiceId = args.voice_id;
         const voiceName = args.voice_name;
-        const modelId = args.model_id ?? 'eleven_multilingual_v2';
+        const modelId = args.model_id ?? 'eleven_v3';
         const stability = args.stability ?? 0.5;
         const similarityBoost = args.similarity_boost ?? 0.75;
         const outputFormat = args.output_format ?? 'mp3_44100_128';
@@ -52,19 +84,10 @@ export function registerSpeechTools(server) {
                 resolvedVoiceName = voice.name;
             }
             else {
-                // Default to Rachel if no voice specified
-                try {
-                    const voice = await lookupVoiceByName(apiKey, 'Rachel');
-                    voiceId = voice.voice_id;
-                    resolvedVoiceName = voice.name;
-                }
-                catch (err) {
-                    // Propagate the error so withErrorHandling emits isError: true
-                    if (err instanceof ElevenLabsError) {
-                        throw err;
-                    }
-                    throw new ElevenLabsError('No voice specified and default voice lookup failed.', 'VOICE_NOT_FOUND', 'Provide a voice_id or voice_name. Use list_voices to find available voices.');
-                }
+                // No voice specified — pick a sensible default from the account.
+                const voice = await pickDefaultVoice(apiKey);
+                voiceId = voice.voice_id;
+                resolvedVoiceName = voice.name;
             }
         }
         const body = {

package/dist/tools/transcription.js

@@ -15,6 +15,8 @@ export function registerTranscriptionTools(server) {
         inputSchema: z.object({
             file_path: z.string().min(1).describe('Absolute path to local audio file to transcribe.'),
             language_code: z.string().optional().describe('Language code (e.g., "en", "es", "fr"). Auto-detected if omitted.'),
+            model_id: z.enum(['scribe_v1']).optional().describe('STT model. Default: scribe_v1.'),
+            tag_audio_events: z.boolean().optional().describe('When true, include non-speech events like "(laughter)" in the transcript. Default: false.'),
         }),
         annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
     }, withErrorHandling(async (args) => {
@@ -72,9 +74,14 @@ export function registerTranscriptionTools(server) {
         const verifiedPath = isRemoteUrl(rawFilePath) ? filePath : fs.realpathSync(filePath);
         const fileBuffer = fs.readFileSync(verifiedPath);
         const fileName = path.basename(verifiedPath);
-        // Use FormData to send as multipart
+        // Multipart upload. ElevenLabs Speech-to-Text v1 requires:
+        //   - field name `file` (NOT `audio` — see planning doc 260520)
+        //   - `model_id` is mandatory (only `scribe_v1` is currently supported)
+        //   - `tag_audio_events=false` to avoid `(mouse click)` style noise
         const formData = new FormData();
-        formData.append('audio', new Blob([fileBuffer]), fileName);
+        formData.append('file', new Blob([fileBuffer]), 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);
         }

package/dist/types.d.ts

@@ -20,24 +20,30 @@ export interface VoicesResponse {
     voices: VoiceResult[];
     has_more?: boolean;
 }
+/**
+ * ElevenLabs music composition section.
+ *
+ * Field names match the live ElevenLabs API exactly. The previous version of
+ * this connector (≤0.2.2) shipped a `{ style, lyrics, duration_ms }` shape
+ * that the API rejects with HTTP 422; see planning doc
+ * `docs/plans/260520_elevenlabs_oss_connector_fix.md` in MindstoneRebel for
+ * the live-capture trace.
+ */
 export interface CompositionSection {
-    style?: string;
-    lyrics?: string;
-    duration_ms?: number;
+    section_name: string;
+    duration_ms: number;
+    positive_local_styles?: string[];
+    negative_local_styles?: string[];
+    /** Lyric lines for the section. Empty array (or omit) for instrumental sections. */
+    lines?: string[];
 }
 export interface CompositionPlan {
     positive_global_styles?: string[];
     negative_global_styles?: string[];
-    sections?: CompositionSection[];
-}
-export interface MusicPlanResponse {
-    positive_global_styles: string[];
-    negative_global_styles: string[];
-    sections: Array<{
-        style: string;
-        lyrics: string;
-        duration_ms: number;
-    }>;
+    sections: CompositionSection[];
+}
+export interface MusicPlanResponse extends CompositionPlan {
+    sections: CompositionSection[];
 }
 export interface TranscriptionWord {
     text: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindstone/mcp-server-elevenlabs",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "mcpName": "io.github.mindstone/mcp-server-elevenlabs",
   "description": "ElevenLabs MCP server for Model Context Protocol hosts \u2014 music, TTS, sound effects, voices, transcription",
   "license": "FSL-1.1-MIT",