luvvoice-mcp 1.0.0

package/dist/api-client.d.ts

@@ -0,0 +1,37 @@
+export interface TTSParams {
+    text: string;
+    voice_id: string;
+    rate?: number;
+    pitch?: number;
+    volume?: number;
+}
+export interface TTSResponse {
+    success: boolean;
+    audio_url?: string;
+    audio_data?: string;
+    message?: string;
+    credits_consumed: number;
+    credits_remaining: number;
+    duration_ms?: number;
+    error?: string;
+}
+export interface Voice {
+    voice_id: string;
+    name: string;
+    gender: string;
+    language: string;
+    language_name: string;
+}
+export interface VoicesResponse {
+    success: boolean;
+    voices: Voice[];
+    total_voices: number;
+    languages_supported: number;
+}
+export declare class LuvVoiceClient {
+    private token;
+    private baseUrl;
+    constructor(token: string, baseUrl?: string);
+    textToSpeech(params: TTSParams): Promise<TTSResponse>;
+    listVoices(): Promise<VoicesResponse>;
+}

package/dist/api-client.js

@@ -0,0 +1,34 @@
+const DEFAULT_BASE_URL = 'https://luvvoice.com/api/v1';
+export class LuvVoiceClient {
+    token;
+    baseUrl;
+    constructor(token, baseUrl) {
+        this.token = token;
+        this.baseUrl = baseUrl || DEFAULT_BASE_URL;
+    }
+    async textToSpeech(params) {
+        const res = await fetch(`${this.baseUrl}/text-to-speech`, {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${this.token}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(params),
+        });
+        if (!res.ok && res.status !== 402) {
+            throw new Error(`HTTP ${res.status}: ${res.statusText}`);
+        }
+        return res.json();
+    }
+    async listVoices() {
+        const res = await fetch(`${this.baseUrl}/text-to-speech?action=voices`, {
+            headers: {
+                'Authorization': `Bearer ${this.token}`,
+            },
+        });
+        if (!res.ok) {
+            throw new Error(`HTTP ${res.status}: ${res.statusText}`);
+        }
+        return res.json();
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from './server.js';
+const args = process.argv.slice(2);
+if (args.includes('--http')) {
+    startHttpServer();
+}
+else {
+    startStdioServer();
+}
+async function startStdioServer() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('LuvVoice MCP Server running on stdio');
+}
+async function startHttpServer() {
+    const { default: express } = await import('express');
+    const { StreamableHTTPServerTransport } = await import('@modelcontextprotocol/sdk/server/streamableHttp.js');
+    const { randomUUID } = await import('node:crypto');
+    const app = express();
+    app.use(express.json());
+    // Stateful session management
+    const sessions = new Map();
+    app.post('/mcp', async (req, res) => {
+        const sessionId = req.headers['mcp-session-id'];
+        // Existing session
+        if (sessionId && sessions.has(sessionId)) {
+            const session = sessions.get(sessionId);
+            await session.transport.handleRequest(req, res, req.body);
+            return;
+        }
+        // New session
+        const server = createServer();
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: () => randomUUID(),
+        });
+        await server.connect(transport);
+        // Store session after connection (transport now has sessionId)
+        const newSessionId = transport.sessionId;
+        if (newSessionId) {
+            sessions.set(newSessionId, { server, transport });
+        }
+        await transport.handleRequest(req, res, req.body);
+    });
+    app.get('/mcp', async (req, res) => {
+        const sessionId = req.headers['mcp-session-id'];
+        if (sessionId && sessions.has(sessionId)) {
+            const session = sessions.get(sessionId);
+            await session.transport.handleRequest(req, res);
+            return;
+        }
+        res.status(400).json({ error: 'Invalid or missing session. Send an initialize request first via POST.' });
+    });
+    app.delete('/mcp', async (req, res) => {
+        const sessionId = req.headers['mcp-session-id'];
+        if (sessionId && sessions.has(sessionId)) {
+            const session = sessions.get(sessionId);
+            await session.transport.handleRequest(req, res);
+            sessions.delete(sessionId);
+            return;
+        }
+        res.status(400).json({ error: 'Invalid or missing session.' });
+    });
+    const port = parseInt(process.env.PORT || '3000', 10);
+    app.listen(port, () => {
+        console.error(`LuvVoice MCP Server (Streamable HTTP) listening on http://localhost:${port}/mcp`);
+    });
+}

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function createServer(): McpServer;

package/dist/server.js

@@ -0,0 +1,259 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { LuvVoiceClient } from './api-client.js';
+export function createServer() {
+    const token = process.env.LUVVOICE_API_TOKEN;
+    if (!token) {
+        console.error('Error: LUVVOICE_API_TOKEN environment variable is required.');
+        console.error('Get your token at: https://luvvoice.com/dashboard/api-tokens');
+        process.exit(1);
+    }
+    const client = new LuvVoiceClient(token, process.env.LUVVOICE_API_BASE_URL);
+    const server = new McpServer({
+        name: 'luvvoice',
+        version: '1.0.0',
+    });
+    // --- Tools ---
+    server.registerTool('text_to_speech', {
+        title: 'Text to Speech',
+        description: 'Convert text into natural-sounding speech using AI voices. ' +
+            'Supports 70+ languages and 200+ voices. Returns an audio URL and/or base64-encoded MP3 audio data, ' +
+            'along with credits consumed and remaining.',
+        inputSchema: {
+            text: z
+                .string()
+                .max(20000)
+                .describe('The text to convert to speech (max 20,000 characters)'),
+            voice_id: z
+                .string()
+                .describe('Voice ID, e.g. "voice-001" (Jenny, English Female). Use the list_voices tool to discover available voices.'),
+            rate: z
+                .number()
+                .min(-50)
+                .max(50)
+                .optional()
+                .describe('Speech rate/speed (-50 to 50, default 0). Positive = faster, negative = slower.'),
+            pitch: z
+                .number()
+                .min(-50)
+                .max(50)
+                .optional()
+                .describe('Speech pitch (-50 to 50, default 0). Positive = higher, negative = lower.'),
+            volume: z
+                .number()
+                .min(-50)
+                .max(50)
+                .optional()
+                .describe('Speech volume (-50 to 50, default 0). Positive = louder, negative = quieter.'),
+        },
+    }, async ({ text, voice_id, rate, pitch, volume }) => {
+        try {
+            const result = await client.textToSpeech({
+                text,
+                voice_id,
+                rate,
+                pitch,
+                volume,
+            });
+            if (!result.success) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error: ${result.error || result.message || 'Text-to-speech conversion failed'}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const content = [];
+            if (result.audio_data) {
+                content.push({
+                    type: 'audio',
+                    data: result.audio_data,
+                    mimeType: 'audio/mpeg',
+                });
+            }
+            let summary = '';
+            if (result.audio_url) {
+                summary += `Audio URL: ${result.audio_url}\n`;
+            }
+            summary += `Credits consumed: ${result.credits_consumed} | Remaining: ${result.credits_remaining}`;
+            if (result.duration_ms) {
+                summary += ` | Processing: ${result.duration_ms}ms`;
+            }
+            content.push({ type: 'text', text: summary });
+            return { content };
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Request failed: ${err instanceof Error ? err.message : String(err)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool('list_voices', {
+        title: 'List Available Voices',
+        description: 'Get all available TTS voices. Optionally filter by language code (e.g. "en-US", "zh-CN", "ja-JP") ' +
+            'or gender ("Female", "Male"). Returns voice IDs needed for text_to_speech.',
+        inputSchema: {
+            language: z
+                .string()
+                .optional()
+                .describe('Filter by language code, e.g. "en-US", "zh-CN", "ja-JP", "es-ES". Leave empty for all voices.'),
+            gender: z
+                .enum(['Female', 'Male'])
+                .optional()
+                .describe('Filter by gender: "Female" or "Male". Leave empty for all.'),
+        },
+    }, async ({ language, gender }) => {
+        try {
+            const result = await client.listVoices();
+            if (!result.success) {
+                return {
+                    content: [{ type: 'text', text: 'Failed to retrieve voice list.' }],
+                    isError: true,
+                };
+            }
+            let voices = result.voices;
+            if (language) {
+                voices = voices.filter((v) => v.language.toLowerCase().includes(language.toLowerCase()));
+            }
+            if (gender) {
+                voices = voices.filter((v) => v.gender === gender);
+            }
+            const header = `Found ${voices.length} voice(s)${language ? ` for "${language}"` : ''}${gender ? ` (${gender})` : ''} — ${result.total_voices} total voices across ${result.languages_supported} languages\n\n`;
+            const voiceList = voices
+                .map((v) => `${v.voice_id}: ${v.name} (${v.gender}) - ${v.language_name} [${v.language}]`)
+                .join('\n');
+            return {
+                content: [{ type: 'text', text: header + voiceList }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Request failed: ${err instanceof Error ? err.message : String(err)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // --- Resources ---
+    server.registerResource('api-docs', 'luvvoice://api-docs', {
+        title: 'LuvVoice API Documentation',
+        description: 'Complete documentation for the LuvVoice Text-to-Speech API',
+        mimeType: 'text/markdown',
+    }, async (uri) => ({
+        contents: [
+            {
+                uri: uri.href,
+                text: API_DOCS,
+            },
+        ],
+    }));
+    server.registerResource('voices', 'luvvoice://voices', {
+        title: 'Available Voices',
+        description: 'Complete list of all available TTS voices with IDs, names, genders, and languages',
+        mimeType: 'application/json',
+    }, async (uri) => {
+        const result = await client.listVoices();
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    });
+    return server;
+}
+const API_DOCS = `# LuvVoice API Documentation
+
+## Overview
+LuvVoice is an AI-powered text-to-speech service supporting 70+ languages and 200+ voices.
+
+## Base URL
+\`https://luvvoice.com/api/v1/text-to-speech\`
+
+## Authentication
+All requests require a Bearer token in the Authorization header:
+\`Authorization: Bearer YOUR_API_TOKEN\`
+
+Get your token at: https://luvvoice.com/dashboard/api-tokens
+API access requires a Pro or Enterprise plan.
+
+## Endpoints
+
+### POST /text-to-speech
+Convert text to speech.
+
+**Request Body (JSON):**
+| Parameter | Type   | Required | Description                           |
+|-----------|--------|----------|---------------------------------------|
+| text      | string | Yes      | Text to convert (max 20,000 chars)    |
+| voice_id  | string | Yes      | Voice ID, e.g. "voice-001"            |
+| rate      | number | No       | Speech speed (-50 to 50, default 0)   |
+| pitch     | number | No       | Speech pitch (-50 to 50, default 0)   |
+| volume    | number | No       | Speech volume (-50 to 50, default 0)  |
+
+**Success Response (200):**
+\`\`\`json
+{
+  "success": true,
+  "audio_url": "https://cdn.luvvoice.com/audio/generated_123.mp3",
+  "audio_data": "<base64-encoded-mp3>",
+  "credits_consumed": 42,
+  "credits_remaining": 9958,
+  "duration_ms": 1234
+}
+\`\`\`
+
+### GET /text-to-speech?action=voices
+Get all available voices.
+
+**Response:**
+\`\`\`json
+{
+  "success": true,
+  "voices": [
+    { "voice_id": "voice-001", "name": "Jenny", "gender": "Female", "language": "en-US", "language_name": "English (United States)" }
+  ],
+  "total_voices": 290,
+  "languages_supported": 85
+}
+\`\`\`
+
+## Popular Voices
+- voice-001: Jenny (Female, English US)
+- voice-002: Guy (Male, English US)
+- voice-050: Alvaro (Male, Spanish)
+- voice-093: Xiaoxiao (Female, Chinese)
+- voice-111: Katja (Female, German)
+- voice-120: Nanami (Female, Japanese)
+
+## Rate Limits
+- 10 requests per minute
+- 5 requests per second (burst protection)
+- 20 requests per 10 seconds
+- Max 20,000 characters per request
+
+## Error Codes
+| Code | Description                              |
+|------|------------------------------------------|
+| 400  | Bad Request - invalid parameters         |
+| 401  | Unauthorized - invalid API token         |
+| 402  | Payment Required - insufficient credits  |
+| 403  | Forbidden - not a Pro/Enterprise user    |
+| 429  | Too Many Requests - rate limit exceeded  |
+| 500  | Internal Server Error                    |
+`;

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "luvvoice-mcp",
+  "version": "1.0.0",
+  "description": "MCP Server for LuvVoice Text-to-Speech API - Convert text to natural-sounding speech with 200+ AI voices in 70+ languages",
+  "type": "module",
+  "bin": {
+    "luvvoice-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc && node -e \"const fs=require('fs');const f='dist/index.js';fs.writeFileSync(f,'#!/usr/bin/env node\\n'+fs.readFileSync(f));fs.chmodSync(f,0o755)\"",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "start:http": "node dist/index.js --http"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "text-to-speech",
+    "tts",
+    "ai-voice",
+    "luvvoice"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "express": "^4.21.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  }
+}