Advanced TTS MCP Server

Instructions

Input Schema

Input Schema (JSON Schema)

Implementation Reference

• src/typescript/index.ts:236-341 (handler)

  Main handler function for synthesize_speech tool. Validates inputs, enhances text for natural speech, calculates adjusted speed, and orchestrates native TTS synthesis.
  async synthesizeSpeech(params: { text: string; voiceId?: string; speed?: number; emotion?: keyof typeof VoiceEmotions; pacing?: keyof typeof PacingStyles; volume?: number; outputFormat?: string; saveFile?: boolean; filename?: string; }) { const { text, voiceId = this.config.defaultVoice, speed = this.config.defaultSpeed, emotion = this.config.defaultEmotion as keyof typeof VoiceEmotions, pacing = this.config.defaultPacing as keyof typeof PacingStyles, volume = 1.0, outputFormat = 'wav', saveFile = this.config.enableFileOutput, filename } = params; // Ensure TTS engine is initialized await this.ensureInitialized(); // Input validation and sanitization if (!text || typeof text !== 'string') { throw new Error('Text must be a non-empty string'); } if (text.length > this.config.maxTextLength) { throw new Error(`Text length (${text.length}) exceeds maximum allowed (${this.config.maxTextLength})`); } // Validate voice ID if (voiceId && !Object.keys(AvailableVoices).includes(voiceId)) { throw new Error(`Invalid voice ID: ${voiceId}`); } // Validate speed range if (speed < 0.25 || speed > 3.0) { throw new Error(`Speed ${speed} out of range (0.25-3.0)`); } // Validate volume range if (volume < 0.1 || volume > 2.0) { throw new Error(`Volume ${volume} out of range (0.1-2.0)`); } // Validate output format if (!AudioFormats.includes(outputFormat as any)) { throw new Error(`Unsupported output format: ${outputFormat}`); } // Sanitize text input const sanitizedText = text .replace(/[<>]/g, '') // Remove HTML-like tags .replace(/[\x00-\x1F\x7F]/g, '') // Remove control characters .trim(); if (!sanitizedText) { throw new Error('Text is empty after sanitization'); } // Enhance text for natural speech const enhancedText = this.enhanceTextForSpeech(sanitizedText, emotion, pacing); // Calculate final speed const finalSpeed = this.calculateFinalSpeed(speed, emotion, pacing); // Synthesize using native TypeScript TTS engine const result = await this.synthesizeWithNativeTTS( enhancedText, voiceId, finalSpeed, emotion, pacing, volume, outputFormat, saveFile, filename ); if (result.success) { this.activeRequests.set(result.requestId, { status: 'completed', result }); return { success: true, requestId: result.requestId, duration: result.duration, voiceUsed: voiceId, speedUsed: finalSpeed, emotion, pacing, outputFormat, filePath: saveFile ? result.audioPath : undefined, message: `Successfully synthesized ${text.length} characters with ${voiceId} voice` }; } else { throw new Error(result.error || 'Synthesis failed'); } }
• src/typescript/index.ts:569-630 (registration)

  Tool registration in MCP ListTools handler defining name, description, and input schema.
  { name: 'synthesize_speech', description: 'Convert text to speech with advanced voice controls and natural expression', inputSchema: { type: 'object', properties: { text: { type: 'string', description: 'Text to convert to speech', maxLength: config.maxTextLength, }, voiceId: { type: 'string', description: 'Voice to use for synthesis', enum: Object.keys(AvailableVoices), default: config.defaultVoice, }, speed: { type: 'number', description: 'Speech speed (0.25-3.0)', minimum: 0.25, maximum: 3.0, default: config.defaultSpeed, }, emotion: { type: 'string', description: 'Voice emotion', enum: Object.keys(VoiceEmotions), default: config.defaultEmotion, }, pacing: { type: 'string', description: 'Speech pacing style', enum: Object.keys(PacingStyles), default: config.defaultPacing, }, volume: { type: 'number', description: 'Audio volume (0.1-2.0)', minimum: 0.1, maximum: 2.0, default: 1.0, }, outputFormat: { type: 'string', description: 'Audio output format', enum: [...AudioFormats], default: 'wav', }, saveFile: { type: 'boolean', description: 'Save audio to file', default: config.enableFileOutput, }, filename: { type: 'string', description: 'Custom filename for saved audio', }, }, required: ['text'], }, },
• src/typescript/index.ts:739-757 (handler)

  MCP CallToolRequestSchema handler case that receives tool call and invokes the synthesizeSpeech implementation.
  case 'synthesize_speech': const result = await ttsServer.synthesizeSpeech(args as any); return { content: [ { type: 'text', text: `🎙️ **TTS Synthesis Complete**\n\n` + `**Request ID:** ${result.requestId}\n` + `**Voice:** ${result.voiceUsed} (${AvailableVoices[result.voiceUsed as keyof typeof AvailableVoices]?.name})\n` + `**Duration:** ${result.duration?.toFixed(2)}s\n` + `**Speed:** ${result.speedUsed?.toFixed(2)}x\n` + `**Emotion:** ${result.emotion}\n` + `**Pacing:** ${result.pacing}\n` + `**Format:** ${result.outputFormat.toUpperCase()}\n` + `${result.filePath ? `**File:** ${result.filePath}\n` : ''}` + `\n${result.message}`, }, ], };
• src/typescript/index.ts:573-628 (schema)

  JSON schema for synthesize_speech tool inputs including all parameters and validation rules.
  type: 'object', properties: { text: { type: 'string', description: 'Text to convert to speech', maxLength: config.maxTextLength, }, voiceId: { type: 'string', description: 'Voice to use for synthesis', enum: Object.keys(AvailableVoices), default: config.defaultVoice, }, speed: { type: 'number', description: 'Speech speed (0.25-3.0)', minimum: 0.25, maximum: 3.0, default: config.defaultSpeed, }, emotion: { type: 'string', description: 'Voice emotion', enum: Object.keys(VoiceEmotions), default: config.defaultEmotion, }, pacing: { type: 'string', description: 'Speech pacing style', enum: Object.keys(PacingStyles), default: config.defaultPacing, }, volume: { type: 'number', description: 'Audio volume (0.1-2.0)', minimum: 0.1, maximum: 2.0, default: 1.0, }, outputFormat: { type: 'string', description: 'Audio output format', enum: [...AudioFormats], default: 'wav', }, saveFile: { type: 'boolean', description: 'Save audio to file', default: config.enableFileOutput, }, filename: { type: 'string', description: 'Custom filename for saved audio', }, }, required: ['text'],
• src/typescript/native-tts.ts:74-108 (helper)

  NativeTTSEngine.synthesizeText - Low-level TTS synthesis called by main handler to produce raw audio data.
  async synthesizeText( text: string, voiceConfig: VoiceConfig, outputFormat: string = 'wav' ): Promise<SynthesisResult> { const requestId = randomUUID(); try { await this.initialize(); // Validate inputs if (!text || text.length === 0) { throw new Error('Text cannot be empty'); } if (text.length > 50000) { throw new Error(`Text too long: ${text.length} characters (max 50000)`); } // Simulate neural TTS synthesis const audioSegment = await this.generateAudioSegment(text, voiceConfig); return { success: true, audioSegment, requestId }; } catch (error) { return { success: false, error: error instanceof Error ? error.message : String(error), requestId }; }