@mindstone-engineering/mcp-server-elevenlabs 0.1.0

package/dist/auth.d.ts

@@ -0,0 +1,21 @@
+/**
+ * ElevenLabs authentication module.
+ *
+ * Simple API key management — stored via env var (ELEVENLABS_API_KEY)
+ * or configured at runtime via the configure_elevenlabs_api_key tool.
+ *
+ * Auth: xi-api-key header on all API requests (NOT Bearer).
+ */
+/**
+ * Get the current API key.
+ */
+export declare function getApiKey(): string;
+/**
+ * Set the API key at runtime (from configure tool).
+ */
+export declare function setApiKey(key: string): void;
+/**
+ * Check if an API key is configured.
+ */
+export declare function hasApiKey(): boolean;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.js

@@ -0,0 +1,29 @@
+/**
+ * ElevenLabs authentication module.
+ *
+ * Simple API key management — stored via env var (ELEVENLABS_API_KEY)
+ * or configured at runtime via the configure_elevenlabs_api_key tool.
+ *
+ * Auth: xi-api-key header on all API requests (NOT Bearer).
+ */
+/** Runtime API key — starts from env, can be updated via configure tool. */
+let apiKey = process.env.ELEVENLABS_API_KEY ?? '';
+/**
+ * Get the current API key.
+ */
+export function getApiKey() {
+    return apiKey;
+}
+/**
+ * Set the API key at runtime (from configure tool).
+ */
+export function setApiKey(key) {
+    apiKey = key;
+}
+/**
+ * Check if an API key is configured.
+ */
+export function hasApiKey() {
+    return apiKey.trim().length > 0;
+}
+//# sourceMappingURL=auth.js.map

package/dist/bridge.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Path to bridge state file, supporting both current and legacy env vars.
+ */
+export declare const BRIDGE_STATE_PATH: string;
+/**
+ * Send a request to the host app bridge.
+ *
+ * The bridge is an HTTP server running inside the host app (e.g. Rebel)
+ * that handles credential management and other cross-process operations.
+ */
+export declare const bridgeRequest: (urlPath: string, body: Record<string, unknown>) => Promise<{
+    success: boolean;
+    warning?: string;
+    error?: string;
+}>;
+//# sourceMappingURL=bridge.d.ts.map

package/dist/bridge.js

@@ -0,0 +1,43 @@
+import * as fs from 'fs';
+import { REQUEST_TIMEOUT_MS } from './types.js';
+/**
+ * Path to bridge state file, supporting both current and legacy env vars.
+ */
+export const BRIDGE_STATE_PATH = process.env.MCP_HOST_BRIDGE_STATE || process.env.MINDSTONE_REBEL_BRIDGE_STATE || '';
+const loadBridgeState = () => {
+    if (!BRIDGE_STATE_PATH)
+        return null;
+    try {
+        const raw = fs.readFileSync(BRIDGE_STATE_PATH, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Send a request to the host app bridge.
+ *
+ * The bridge is an HTTP server running inside the host app (e.g. Rebel)
+ * that handles credential management and other cross-process operations.
+ */
+export const bridgeRequest = async (urlPath, body) => {
+    const bridge = loadBridgeState();
+    if (!bridge) {
+        return { success: false, error: 'Bridge not available' };
+    }
+    const response = await fetch(`http://127.0.0.1:${bridge.port}${urlPath}`, {
+        method: 'POST',
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${bridge.token}`,
+        },
+        body: JSON.stringify(body),
+    });
+    if (response.status === 401 || response.status === 403) {
+        return { success: false, error: `Bridge returned ${response.status}: unauthorized. Check host app authentication.` };
+    }
+    return response.json();
+};
+//# sourceMappingURL=bridge.js.map

package/dist/client.d.ts

@@ -0,0 +1,25 @@
+/**
+ * ElevenLabs API HTTP client.
+ *
+ * Centralises xi-api-key header injection, error handling, rate-limit
+ * messaging, and timeout handling for all ElevenLabs API calls.
+ *
+ * Auth: xi-api-key: {key} (NOT Bearer, NOT Basic)
+ * Base URL: https://api.elevenlabs.io/v1
+ * Voices URL: https://api.elevenlabs.io/v2/voices
+ */
+import { type AudioResult } from './types.js';
+/**
+ * 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>;
+/**
+ * Make a JSON API call and parse the response.
+ */
+export declare function elevenLabsJson<T>(apiKey: string, urlPath: string, options?: RequestInit): Promise<T>;
+/**
+ * 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>;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.js

@@ -0,0 +1,108 @@
+/**
+ * ElevenLabs API HTTP client.
+ *
+ * Centralises xi-api-key header injection, error handling, rate-limit
+ * messaging, and timeout handling for all ElevenLabs API calls.
+ *
+ * Auth: xi-api-key: {key} (NOT Bearer, NOT Basic)
+ * Base URL: https://api.elevenlabs.io/v1
+ * Voices URL: https://api.elevenlabs.io/v2/voices
+ */
+import * as fs from 'fs';
+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';
+/**
+ * Make an authenticated request to the ElevenLabs API.
+ * Returns a raw Response object.
+ */
+export async function elevenLabsFetch(apiKey, urlPath, options = {}) {
+    if (!apiKey || apiKey.trim().length === 0) {
+        throw new ElevenLabsError('ElevenLabs API key not configured', 'AUTH_REQUIRED', 'Configure your ElevenLabs API key in Settings. Get one at https://elevenlabs.io/app/settings/api-keys');
+    }
+    const url = urlPath.startsWith('https://')
+        ? urlPath
+        : `${ELEVENLABS_API_BASE}${urlPath}`;
+    const headers = {
+        'xi-api-key': apiKey,
+        ...(options.headers || {}),
+    };
+    // Only set Content-Type for JSON bodies (not FormData)
+    if (!(options.body instanceof FormData) && !headers['Content-Type']) {
+        headers['Content-Type'] = 'application/json';
+    }
+    console.error(`[ElevenLabs API] ${options.method || 'GET'} ${url}`);
+    let response;
+    try {
+        response = await fetch(url, {
+            ...options,
+            signal: options.signal ?? AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            headers,
+        });
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === 'TimeoutError') {
+            throw new ElevenLabsError('Request to ElevenLabs API timed out', 'TIMEOUT', 'The request took too long. Try again or check if the ElevenLabs API is available.');
+        }
+        throw error;
+    }
+    // Handle rate limiting
+    if (response.status === 429) {
+        throw new ElevenLabsError('Rate limited. Please wait a moment before retrying.', 'RATE_LIMITED', getErrorResolution(429));
+    }
+    // Handle auth errors
+    if (response.status === 401) {
+        throw new ElevenLabsError('Authentication failed', 'AUTH_FAILED', 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 */ }
+        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 */ }
+        throw new ElevenLabsError(`ElevenLabs API error (HTTP ${response.status}): ${detail || response.statusText}`, `HTTP_${response.status}`, getErrorResolution(response.status, detail));
+    }
+    return response;
+}
+/**
+ * Make a JSON API call and parse the response.
+ */
+export async function elevenLabsJson(apiKey, urlPath, options = {}) {
+    const response = await elevenLabsFetch(apiKey, urlPath, options);
+    return (await response.json());
+}
+/**
+ * Make an API call that returns raw audio binary. Save to file and return path.
+ */
+export async function elevenLabsAudio(apiKey, urlPath, options = {}, fileExtension = 'mp3') {
+    const response = await elevenLabsFetch(apiKey, urlPath, options);
+    const buffer = Buffer.from(await response.arrayBuffer());
+    const fileName = `elevenlabs_${crypto.randomUUID()}.${fileExtension}`;
+    const filePath = path.join(os.tmpdir(), fileName);
+    fs.writeFileSync(filePath, buffer);
+    return { filePath, sizeBytes: buffer.length };
+}
+//# sourceMappingURL=client.js.map

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * ElevenLabs MCP Server
+ *
+ * Provides ElevenLabs audio integration via Model Context Protocol.
+ * Music generation, text-to-speech, sound effects, voice browsing, transcription.
+ *
+ * Environment variables:
+ * - ELEVENLABS_API_KEY: ElevenLabs API key (required, starts with sk_)
+ * - MCP_HOST_BRIDGE_STATE: Path to host app bridge state file (optional)
+ * - MINDSTONE_REBEL_BRIDGE_STATE: Legacy bridge state path (optional)
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+/**
+ * ElevenLabs MCP Server
+ *
+ * Provides ElevenLabs audio integration via Model Context Protocol.
+ * Music generation, text-to-speech, sound effects, voice browsing, transcription.
+ *
+ * Environment variables:
+ * - ELEVENLABS_API_KEY: ElevenLabs API key (required, starts with sk_)
+ * - MCP_HOST_BRIDGE_STATE: Path to host app bridge state file (optional)
+ * - MINDSTONE_REBEL_BRIDGE_STATE: Legacy bridge state path (optional)
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from './server.js';
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('ElevenLabs MCP server running on stdio');
+}
+main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/server.d.ts

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

package/dist/server.js

@@ -0,0 +1,15 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { registerConfigureTools, registerMusicTools, registerSpeechTools, registerVoiceTools, registerTranscriptionTools, } from './tools/index.js';
+export function createServer() {
+    const server = new McpServer({
+        name: 'elevenlabs-mcp-server',
+        version: '0.1.0',
+    });
+    registerConfigureTools(server);
+    registerMusicTools(server);
+    registerSpeechTools(server);
+    registerVoiceTools(server);
+    registerTranscriptionTools(server);
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/tools/configure.d.ts

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

package/dist/tools/configure.js

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+import { setApiKey } from '../auth.js';
+import { bridgeRequest, BRIDGE_STATE_PATH } from '../bridge.js';
+import { ElevenLabsError } from '../types.js';
+import { withErrorHandling } from '../utils.js';
+export function registerConfigureTools(server) {
+    server.registerTool('configure_elevenlabs_api_key', {
+        description: 'Save your ElevenLabs API key. Call this when the user provides their key. ' +
+            'WHERE TO GET A KEY: Go to https://elevenlabs.io/app/settings/api-keys → Create new API key → Copy the key (starts with "sk_"). ' +
+            'FREE TIER: 10,000 characters/month for TTS. Music generation requires a paid plan.',
+        inputSchema: z.object({
+            api_key: z.string().min(1).describe('ElevenLabs API key (starts with "sk_").'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, withErrorHandling(async (args) => {
+        const key = args.api_key.trim();
+        // If bridge is available, persist via bridge
+        if (BRIDGE_STATE_PATH) {
+            try {
+                const result = await bridgeRequest('/bundled/elevenlabs/configure', { apiKey: key });
+                if (result.success) {
+                    setApiKey(key);
+                    const message = result.warning
+                        ? `ElevenLabs API key configured successfully. Note: ${result.warning}`
+                        : 'ElevenLabs API key configured successfully! You can now generate music, speech, sound effects, and more.';
+                    return JSON.stringify({ ok: true, message });
+                }
+                // Bridge returned failure — surface as error, do NOT fall through
+                throw new ElevenLabsError(result.error || 'Bridge configuration failed', 'BRIDGE_ERROR', 'The host app bridge rejected the configuration request. Check the host app logs.');
+            }
+            catch (error) {
+                if (error instanceof ElevenLabsError)
+                    throw error;
+                // Bridge request failed (network, timeout, etc.) — surface as error
+                throw new ElevenLabsError(`Bridge request failed: ${error instanceof Error ? error.message : String(error)}`, 'BRIDGE_ERROR', 'Could not reach the host app bridge. Ensure the host app is running.');
+            }
+        }
+        // No bridge — store in-memory
+        setApiKey(key);
+        return JSON.stringify({
+            ok: true,
+            message: 'ElevenLabs API key configured successfully! You can now generate music, speech, sound effects, and more.',
+        });
+    }));
+}
+//# sourceMappingURL=configure.js.map

package/dist/tools/index.d.ts

@@ -0,0 +1,6 @@
+export { registerConfigureTools } from './configure.js';
+export { registerMusicTools } from './music.js';
+export { registerSpeechTools } from './speech.js';
+export { registerVoiceTools } from './voices.js';
+export { registerTranscriptionTools } from './transcription.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/index.js

@@ -0,0 +1,6 @@
+export { registerConfigureTools } from './configure.js';
+export { registerMusicTools } from './music.js';
+export { registerSpeechTools } from './speech.js';
+export { registerVoiceTools } from './voices.js';
+export { registerTranscriptionTools } from './transcription.js';
+//# sourceMappingURL=index.js.map

package/dist/tools/music.d.ts

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

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 },
+    }, 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 },
+    }, 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 },
+    }, 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/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 },
+    }, 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 },
+    }, 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,50 @@
+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';
+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 },
+    }, 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 filePath = args.file_path;
+        // Read local file
+        if (!fs.existsSync(filePath)) {
+            throw new ElevenLabsError(`File not found: ${filePath}`, 'FILE_NOT_FOUND', 'Provide an absolute path to an existing audio file.');
+        }
+        const fileBuffer = fs.readFileSync(filePath);
+        const fileName = path.basename(filePath);
+        // 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 },
+    }, 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

package/dist/types.d.ts

@@ -0,0 +1,60 @@
+export declare const REQUEST_TIMEOUT_MS = 30000;
+export interface BridgeState {
+    port: number;
+    token: string;
+}
+export declare class ElevenLabsError extends Error {
+    readonly code: string;
+    readonly resolution: string;
+    constructor(message: string, code: string, resolution: string);
+}
+export interface VoiceResult {
+    voice_id: string;
+    name: string;
+    category?: string;
+    description?: string;
+    preview_url?: string;
+    labels?: Record<string, string>;
+}
+export interface VoicesResponse {
+    voices: VoiceResult[];
+    has_more?: boolean;
+}
+export interface CompositionSection {
+    style?: string;
+    lyrics?: string;
+    duration_ms?: number;
+}
+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;
+    }>;
+}
+export interface TranscriptionWord {
+    text: string;
+    start: number;
+    end: number;
+    type?: string;
+}
+export interface TranscriptionResponse {
+    text: string;
+    words?: TranscriptionWord[];
+}
+export interface AudioResult {
+    filePath: string;
+    sizeBytes: number;
+}
+/**
+ * Resolve an error status code to an actionable resolution string.
+ */
+export declare function getErrorResolution(status: number, detail?: string): string;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,34 @@
+export const REQUEST_TIMEOUT_MS = 30_000;
+export class ElevenLabsError extends Error {
+    code;
+    resolution;
+    constructor(message, code, resolution) {
+        super(message);
+        this.code = code;
+        this.resolution = resolution;
+        this.name = 'ElevenLabsError';
+    }
+}
+/**
+ * Resolve an error status code to an actionable resolution string.
+ */
+export function getErrorResolution(status, detail) {
+    const msg = (detail || '').toLowerCase();
+    if (status === 401 || msg.includes('unauthorized') || msg.includes('invalid api key')) {
+        return 'Authentication failed. Check your ElevenLabs API key in Settings. Get one at https://elevenlabs.io/app/settings/api-keys';
+    }
+    if (status === 403 || msg.includes('quota') || msg.includes('limit') || msg.includes('credits')) {
+        return 'Insufficient credits or quota exceeded. Check usage at https://elevenlabs.io/app/usage';
+    }
+    if (status === 422 || msg.includes('validation')) {
+        return 'Invalid request parameters. Check the input values and try again.';
+    }
+    if (status === 429) {
+        return 'Rate limited. Wait a moment and try again.';
+    }
+    if (msg.includes('content') || msg.includes('policy') || msg.includes('moderation')) {
+        return 'Content policy violation. Try a different prompt.';
+    }
+    return 'Please try again. If the issue persists, check your API key and credits at https://elevenlabs.io/app/settings/api-keys';
+}
+//# sourceMappingURL=types.js.map

package/dist/utils.d.ts

@@ -0,0 +1,14 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+type ToolHandler<T> = (args: T, extra: unknown) => Promise<CallToolResult>;
+/**
+ * Wraps a tool handler with standard error handling.
+ *
+ * - On success: returns the string result as a text content block.
+ * - On ElevenLabsError: returns a structured JSON error with code and resolution.
+ * - On unknown error: returns a generic error message.
+ *
+ * Secrets are never exposed in error messages.
+ */
+export declare function withErrorHandling<T>(fn: (args: T, extra: unknown) => Promise<string>): ToolHandler<T>;
+export {};
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.js

@@ -0,0 +1,42 @@
+import { ElevenLabsError } from './types.js';
+/**
+ * Wraps a tool handler with standard error handling.
+ *
+ * - On success: returns the string result as a text content block.
+ * - On ElevenLabsError: returns a structured JSON error with code and resolution.
+ * - On unknown error: returns a generic error message.
+ *
+ * Secrets are never exposed in error messages.
+ */
+export function withErrorHandling(fn) {
+    return async (args, extra) => {
+        try {
+            const result = await fn(args, extra);
+            return { content: [{ type: 'text', text: result }] };
+        }
+        catch (error) {
+            if (error instanceof ElevenLabsError) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                ok: false,
+                                error: error.message,
+                                code: error.code,
+                                resolution: error.resolution,
+                            }),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ ok: false, error: errorMessage }) }],
+                isError: true,
+            };
+        }
+    };
+}
+//# sourceMappingURL=utils.js.map

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@mindstone-engineering/mcp-server-elevenlabs",
+  "version": "0.1.0",
+  "description": "ElevenLabs MCP server for Model Context Protocol hosts — music, TTS, sound effects, voices, transcription",
+  "license": "FSL-1.1-MIT",
+  "type": "module",
+  "bin": {
+    "mcp-server-elevenlabs": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nspr-io/mcp-servers.git",
+    "directory": "connectors/elevenlabs"
+  },
+  "homepage": "https://github.com/nspr-io/mcp-servers/tree/main/connectors/elevenlabs",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc && shx chmod +x dist/index.js",
+    "prepare": "npm run build",
+    "watch": "tsc --watch",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@mindstone-engineering/mcp-test-harness": "file:../../test-harness",
+    "@types/node": "^22",
+    "@vitest/coverage-v8": "^4.1.3",
+    "msw": "^2.13.2",
+    "shx": "^0.3.4",
+    "typescript": "^5.8.2",
+    "vitest": "^4.1.3"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}