@felores/kie-ai-mcp-server 1.1.3 → 1.2.0

package/README.md

@@ -9,6 +9,7 @@ An MCP (Model Context Protocol) server that provides access to Kie.ai's AI APIs
 - **Nano Banana Image Upscaling**: Upscale images 1-4x with optional face enhancement
 - **Veo3 Video Generation**: Professional-quality video generation with text-to-video and image-to-video capabilities
 - **1080p Video Upgrade**: Get high-definition versions of Veo3 videos
+- **Suno Music Generation**: AI-powered music creation with multiple models (V3_5, V4, V4_5, V4_5PLUS, V5)
 - **Task Management**: SQLite-based task tracking with status polling
 - **Smart Endpoint Routing**: Automatic detection of task types for status checking
 - **Error Handling**: Comprehensive error handling and validation
@@ -187,6 +188,38 @@ Get 1080P high-definition version of a Veo3 video.
 
 **Note**: Not available for videos generated with fallback mode.
 
+### 8. `suno_generate_music`
+Generate music with AI using Suno models.
+
+**Parameters:**
+- `prompt` (string, required): Description of desired audio content (max 5000 chars for V4_5+, V5; 3000 for V3_5, V4; 500 chars for non-custom mode)
+- `customMode` (boolean, required): Enable advanced parameter customization
+- `instrumental` (boolean, required): Generate instrumental music (no lyrics)
+- `model` (enum, required): AI model version - "V3_5", "V4", "V4_5", "V4_5PLUS", or "V5"
+- `callBackUrl` (string, required): URL to receive task completion updates
+- `style` (string, optional): Music style/genre (required in custom mode, max 1000 chars for V4_5+, V5; 200 for V3_5, V4)
+- `title` (string, optional): Track title (required in custom mode, max 80 chars)
+- `negativeTags` (string, optional): Music styles to exclude (max 200 chars)
+- `vocalGender` (enum, optional): Vocal gender preference - "m" or "f" (custom mode only)
+- `styleWeight` (number, optional): Style adherence strength (0-1, up to 2 decimal places)
+- `weirdnessConstraint` (number, optional): Creative deviation control (0-1, up to 2 decimal places)
+- `audioWeight` (number, optional): Audio feature balance (0-1, up to 2 decimal places)
+
+**Example:**
+```json
+{
+  "prompt": "A calm and relaxing piano track with soft melodies",
+  "customMode": true,
+  "instrumental": true,
+  "model": "V5",
+  "callBackUrl": "https://api.example.com/callback",
+  "style": "Classical",
+  "title": "Peaceful Piano Meditation"
+}
+```
+
+**Note**: In custom mode, `style` and `title` are required. If `instrumental` is false, `prompt` is used as exact lyrics.
+
 ## API Endpoints
 
 The server interfaces with these Kie.ai API endpoints:
@@ -198,6 +231,8 @@ The server interfaces with these Kie.ai API endpoints:
 - **Nano Banana Edit**: `POST /api/v1/jobs/createTask`
 - **Nano Banana Upscale**: `POST /api/v1/jobs/createTask`
 - **Nano Banana Status**: `GET /api/v1/jobs/recordInfo`
+- **Suno Music Generation**: `POST /api/v1/generate` ✅ **VALIDATED**
+- **Suno Music Status**: `GET /api/v1/generate?taskId=XXX` ✅ **VALIDATED**
 
 All endpoints follow official Kie.ai API documentation.
 
@@ -209,7 +244,7 @@ The server uses SQLite to track tasks:
 CREATE TABLE tasks (
   id INTEGER PRIMARY KEY AUTOINCREMENT,
   task_id TEXT UNIQUE NOT NULL,
-  api_type TEXT NOT NULL,  -- 'nano-banana', 'nano-banana-edit', 'veo3'
+  api_type TEXT NOT NULL,  -- 'nano-banana', 'nano-banana-edit', 'veo3', 'suno'
   status TEXT DEFAULT 'pending',
   created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
   updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
@@ -335,44 +370,4 @@ MIT License - see LICENSE file for details.
 
 ## Changelog
 
-### v1.1.1 (2025-01-14)
-
-**Improvements:**
-- Added `KIE_AI_CALLBACK_URL` environment variable for default callback URL
-- Added `enableTranslation` parameter to Veo3 (auto-translate prompts to English)
-- Added `Auto` option to Veo3 `aspectRatio`
-- Exposed `callBackUrl` parameter in Veo3 tool schema
-- Veo3 tool now fully aligned with official Kie.ai API documentation
-
-### v1.1.0 (2025-01-14)
-
-**Breaking Changes:**
-- Migrated from `/playground/*` to official `/jobs/*` API endpoints for all Nano Banana operations
-- Updated status check endpoint from `/playground/recordInfo` to `/jobs/recordInfo`
-
-**New Features:**
-- Added `upscale_nano_banana` tool for image upscaling (1-4x) with optional GFPGAN face enhancement
-- Added `output_format` parameter (png/jpeg) to `generate_nano_banana` and `edit_nano_banana`
-- Added `image_size` parameter (11 aspect ratios) to `generate_nano_banana` and `edit_nano_banana`
-
-**Improvements:**
-- Increased prompt max length from 1,000 to 5,000 characters for Nano Banana tools
-- Increased max input images from 5 to 10 for `edit_nano_banana`
-- Enhanced `get_task_status` to properly parse `resultJson` and extract result URLs
-- Improved task status mapping: `waiting` → `processing`, `success` → `completed`, `fail` → `failed`
-- Task status now automatically updates local database with API responses
-- Better error message handling from API responses
-
-**Documentation:**
-- Updated README with all new parameters and tools
-- Corrected API endpoints to match official Kie.ai documentation
-- Added comprehensive examples for all tools
-
-### v1.0.0 (2024-12-XX)
-- Initial release
-- Nano Banana image generation and editing
-- Veo3 video generation
-- 1080p video upgrade support
-- SQLite task tracking
-- Smart endpoint routing
-- Comprehensive error handling
+See [CHANGELOG.md](CHANGELOG.md) for detailed version history and release notes.

package/dist/index.js

@@ -4,7 +4,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from '@modelcontextprotocol/sdk/types.js';
 import { KieAiClient } from './kie-ai-client.js';
 import { TaskDatabase } from './database.js';
-import { NanoBananaGenerateSchema, NanoBananaEditSchema, NanoBananaUpscaleSchema, Veo3GenerateSchema } from './types.js';
+import { NanoBananaGenerateSchema, NanoBananaEditSchema, NanoBananaUpscaleSchema, Veo3GenerateSchema, SunoGenerateSchema } from './types.js';
 class KieAiMcpServer {
     server;
     client;
@@ -12,7 +12,7 @@ class KieAiMcpServer {
     constructor() {
         this.server = new Server({
             name: 'kie-ai-mcp-server',
-            version: '1.1.3',
+            version: '1.2.0',
         });
         // Initialize client with config from environment
         const config = {
@@ -267,6 +267,81 @@ class KieAiMcpServer {
                             },
                             required: ['task_id']
                         }
+                    },
+                    {
+                        name: 'suno_generate_music',
+                        description: 'Generate music with AI using Suno models (V3_5, V4, V4_5, V4_5PLUS, V5)',
+                        inputSchema: {
+                            type: 'object',
+                            properties: {
+                                prompt: {
+                                    type: 'string',
+                                    description: 'Description of the desired audio content. In custom mode: used as exact lyrics (max 5000 chars for V4_5+, V5; 3000 for V3_5, V4). In non-custom mode: core idea for auto-generated lyrics (max 500 chars)',
+                                    minLength: 1,
+                                    maxLength: 5000
+                                },
+                                customMode: {
+                                    type: 'boolean',
+                                    description: 'Enable advanced parameter customization. If true: requires style and title. If false: simplified mode with only prompt required'
+                                },
+                                instrumental: {
+                                    type: 'boolean',
+                                    description: 'Generate instrumental music (no lyrics). In custom mode: if true, only style and title required; if false, prompt used as exact lyrics'
+                                },
+                                model: {
+                                    type: 'string',
+                                    description: 'AI model version for generation',
+                                    enum: ['V3_5', 'V4', 'V4_5', 'V4_5PLUS', 'V5']
+                                },
+                                callBackUrl: {
+                                    type: 'string',
+                                    description: 'URL to receive task completion updates (required for all requests)',
+                                    format: 'uri'
+                                },
+                                style: {
+                                    type: 'string',
+                                    description: 'Music style/genre (required in custom mode, max 1000 chars for V4_5+, V5; 200 for V3_5, V4)',
+                                    maxLength: 1000
+                                },
+                                title: {
+                                    type: 'string',
+                                    description: 'Track title (required in custom mode, max 80 chars)',
+                                    maxLength: 80
+                                },
+                                negativeTags: {
+                                    type: 'string',
+                                    description: 'Music styles to exclude (optional, max 200 chars)',
+                                    maxLength: 200
+                                },
+                                vocalGender: {
+                                    type: 'string',
+                                    description: 'Vocal gender preference (optional, only effective in custom mode)',
+                                    enum: ['m', 'f']
+                                },
+                                styleWeight: {
+                                    type: 'number',
+                                    description: 'Strength of style adherence (optional, range 0-1, up to 2 decimal places)',
+                                    minimum: 0,
+                                    maximum: 1,
+                                    multipleOf: 0.01
+                                },
+                                weirdnessConstraint: {
+                                    type: 'number',
+                                    description: 'Controls experimental/creative deviation (optional, range 0-1, up to 2 decimal places)',
+                                    minimum: 0,
+                                    maximum: 1,
+                                    multipleOf: 0.01
+                                },
+                                audioWeight: {
+                                    type: 'number',
+                                    description: 'Balance weight for audio features (optional, range 0-1, up to 2 decimal places)',
+                                    minimum: 0,
+                                    maximum: 1,
+                                    multipleOf: 0.01
+                                }
+                            },
+                            required: ['prompt', 'customMode', 'instrumental', 'model', 'callBackUrl']
+                        }
                     }
                 ]
             };
@@ -289,6 +364,8 @@ class KieAiMcpServer {
                         return await this.handleListTasks(args);
                     case 'veo3_get_1080p_video':
                         return await this.handleVeo3Get1080pVideo(args);
+                    case 'suno_generate_music':
+                        return await this.handleSunoGenerateMusic(args);
                     default:
                         throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
                 }
@@ -573,6 +650,62 @@ class KieAiMcpServer {
             });
         }
     }
+    async handleSunoGenerateMusic(args) {
+        try {
+            const request = SunoGenerateSchema.parse(args);
+            const response = await this.client.generateSunoMusic(request);
+            if (response.code === 200 && response.data?.taskId) {
+                // Store task in database
+                await this.db.createTask({
+                    task_id: response.data.taskId,
+                    api_type: 'suno',
+                    status: 'pending'
+                });
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: true,
+                                task_id: response.data.taskId,
+                                message: 'Music generation task created successfully',
+                                parameters: {
+                                    model: request.model,
+                                    customMode: request.customMode,
+                                    instrumental: request.instrumental,
+                                    callBackUrl: request.callBackUrl
+                                },
+                                next_steps: [
+                                    'Use get_task_status to check generation progress',
+                                    'Task completion will be sent to the provided callback URL',
+                                    'Generation typically takes 1-3 minutes depending on model and length'
+                                ]
+                            }, null, 2)
+                        }
+                    ]
+                };
+            }
+            else {
+                throw new Error(response.msg || 'Failed to create music generation task');
+            }
+        }
+        catch (error) {
+            return this.formatError('suno_generate_music', error, {
+                prompt: 'Required: Description of desired audio content',
+                customMode: 'Required: Enable advanced customization (true/false)',
+                instrumental: 'Required: Generate instrumental music (true/false)',
+                model: 'Required: AI model version (V3_5, V4, V4_5, V4_5PLUS, V5)',
+                callBackUrl: 'Required: URL for task completion notifications',
+                style: 'Optional: Music style/genre (required in custom mode)',
+                title: 'Optional: Track title (required in custom mode, max 80 chars)',
+                negativeTags: 'Optional: Styles to exclude (max 200 chars)',
+                vocalGender: 'Optional: Vocal gender preference (m/f, custom mode only)',
+                styleWeight: 'Optional: Style adherence strength (0-1, 2 decimal places)',
+                weirdnessConstraint: 'Optional: Creative deviation control (0-1, 2 decimal places)',
+                audioWeight: 'Optional: Audio feature balance (0-1, 2 decimal places)'
+            });
+        }
+    }
     async run() {
         const transport = new StdioServerTransport();
         await this.server.connect(transport);

package/dist/kie-ai-client.d.ts

@@ -1,4 +1,4 @@
-import { KieAiConfig, KieAiResponse, NanoBananaGenerateRequest, NanaBananaEditRequest, NanoBananaUpscaleRequest, Veo3GenerateRequest, ImageResponse, TaskResponse } from './types.js';
+import { KieAiConfig, KieAiResponse, NanoBananaGenerateRequest, NanaBananaEditRequest, NanoBananaUpscaleRequest, Veo3GenerateRequest, SunoGenerateRequest, ImageResponse, TaskResponse } from './types.js';
 export declare class KieAiClient {
     private config;
     constructor(config: KieAiConfig);
@@ -8,5 +8,6 @@ export declare class KieAiClient {
     upscaleNanaBanana(request: NanoBananaUpscaleRequest): Promise<KieAiResponse<ImageResponse>>;
     generateVeo3Video(request: Veo3GenerateRequest): Promise<KieAiResponse<TaskResponse>>;
     getTaskStatus(taskId: string, apiType?: string): Promise<KieAiResponse<any>>;
+    generateSunoMusic(request: SunoGenerateRequest): Promise<KieAiResponse<TaskResponse>>;
     getVeo1080pVideo(taskId: string, index?: number): Promise<KieAiResponse<any>>;
 }

package/dist/kie-ai-client.js

@@ -77,7 +77,10 @@ export class KieAiClient {
         else if (apiType === 'nano-banana' || apiType === 'nano-banana-edit' || apiType === 'nano-banana-upscale') {
             return this.makeRequest(`/jobs/recordInfo?taskId=${taskId}`, 'GET');
         }
-        // Fallback: try jobs first, then veo (for tasks not in database)
+        else if (apiType === 'suno') {
+            return this.makeRequest(`/generate?taskId=${taskId}`, 'GET');
+        }
+        // Fallback: try jobs first, then veo, then generate (for tasks not in database)
         try {
             return await this.makeRequest(`/jobs/recordInfo?taskId=${taskId}`, 'GET');
         }
@@ -86,10 +89,18 @@ export class KieAiClient {
                 return await this.makeRequest(`/veo/record-info?taskId=${taskId}`, 'GET');
             }
             catch (veoError) {
-                throw error;
+                try {
+                    return await this.makeRequest(`/generate?taskId=${taskId}`, 'GET');
+                }
+                catch (sunoError) {
+                    throw error;
+                }
             }
         }
     }
+    async generateSunoMusic(request) {
+        return this.makeRequest('/generate', 'POST', request);
+    }
     async getVeo1080pVideo(taskId, index) {
         const params = new URLSearchParams({ taskId });
         if (index !== undefined) {

package/dist/types.d.ts

@@ -72,10 +72,77 @@ export declare const Veo3GenerateSchema: z.ZodObject<{
     enableFallback?: boolean | undefined;
     enableTranslation?: boolean | undefined;
 }>;
+export declare const SunoGenerateSchema: z.ZodEffects<z.ZodObject<{
+    prompt: z.ZodString;
+    customMode: z.ZodBoolean;
+    instrumental: z.ZodBoolean;
+    model: z.ZodEnum<["V3_5", "V4", "V4_5", "V4_5PLUS", "V5"]>;
+    callBackUrl: z.ZodString;
+    style: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    negativeTags: z.ZodOptional<z.ZodString>;
+    vocalGender: z.ZodOptional<z.ZodEnum<["m", "f"]>>;
+    styleWeight: z.ZodOptional<z.ZodNumber>;
+    weirdnessConstraint: z.ZodOptional<z.ZodNumber>;
+    audioWeight: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    prompt: string;
+    model: "V3_5" | "V4" | "V4_5" | "V4_5PLUS" | "V5";
+    callBackUrl: string;
+    customMode: boolean;
+    instrumental: boolean;
+    style?: string | undefined;
+    title?: string | undefined;
+    negativeTags?: string | undefined;
+    vocalGender?: "m" | "f" | undefined;
+    styleWeight?: number | undefined;
+    weirdnessConstraint?: number | undefined;
+    audioWeight?: number | undefined;
+}, {
+    prompt: string;
+    model: "V3_5" | "V4" | "V4_5" | "V4_5PLUS" | "V5";
+    callBackUrl: string;
+    customMode: boolean;
+    instrumental: boolean;
+    style?: string | undefined;
+    title?: string | undefined;
+    negativeTags?: string | undefined;
+    vocalGender?: "m" | "f" | undefined;
+    styleWeight?: number | undefined;
+    weirdnessConstraint?: number | undefined;
+    audioWeight?: number | undefined;
+}>, {
+    prompt: string;
+    model: "V3_5" | "V4" | "V4_5" | "V4_5PLUS" | "V5";
+    callBackUrl: string;
+    customMode: boolean;
+    instrumental: boolean;
+    style?: string | undefined;
+    title?: string | undefined;
+    negativeTags?: string | undefined;
+    vocalGender?: "m" | "f" | undefined;
+    styleWeight?: number | undefined;
+    weirdnessConstraint?: number | undefined;
+    audioWeight?: number | undefined;
+}, {
+    prompt: string;
+    model: "V3_5" | "V4" | "V4_5" | "V4_5PLUS" | "V5";
+    callBackUrl: string;
+    customMode: boolean;
+    instrumental: boolean;
+    style?: string | undefined;
+    title?: string | undefined;
+    negativeTags?: string | undefined;
+    vocalGender?: "m" | "f" | undefined;
+    styleWeight?: number | undefined;
+    weirdnessConstraint?: number | undefined;
+    audioWeight?: number | undefined;
+}>;
 export type NanoBananaGenerateRequest = z.infer<typeof NanoBananaGenerateSchema>;
 export type NanaBananaEditRequest = z.infer<typeof NanoBananaEditSchema>;
 export type NanoBananaUpscaleRequest = z.infer<typeof NanoBananaUpscaleSchema>;
 export type Veo3GenerateRequest = z.infer<typeof Veo3GenerateSchema>;
+export type SunoGenerateRequest = z.infer<typeof SunoGenerateSchema>;
 export interface KieAiResponse<T = any> {
     code: number;
     msg: string;
@@ -91,7 +158,7 @@ export interface TaskResponse {
 export interface TaskRecord {
     id?: number;
     task_id: string;
-    api_type: 'nano-banana' | 'nano-banana-edit' | 'nano-banana-upscale' | 'veo3';
+    api_type: 'nano-banana' | 'nano-banana-edit' | 'nano-banana-upscale' | 'veo3' | 'suno';
     status: 'pending' | 'processing' | 'completed' | 'failed';
     created_at: string;
     updated_at: string;

package/dist/types.js

@@ -27,3 +27,30 @@ export const Veo3GenerateSchema = z.object({
     enableFallback: z.boolean().default(false),
     enableTranslation: z.boolean().default(true).optional()
 });
+export const SunoGenerateSchema = z.object({
+    prompt: z.string().min(1).max(5000),
+    customMode: z.boolean(),
+    instrumental: z.boolean(),
+    model: z.enum(['V3_5', 'V4', 'V4_5', 'V4_5PLUS', 'V5']),
+    callBackUrl: z.string().url(),
+    style: z.string().max(1000).optional(),
+    title: z.string().max(80).optional(),
+    negativeTags: z.string().max(200).optional(),
+    vocalGender: z.enum(['m', 'f']).optional(),
+    styleWeight: z.number().min(0).max(1).multipleOf(0.01).optional(),
+    weirdnessConstraint: z.number().min(0).max(1).multipleOf(0.01).optional(),
+    audioWeight: z.number().min(0).max(1).multipleOf(0.01).optional()
+}).refine((data) => {
+    if (data.customMode) {
+        if (data.instrumental) {
+            return data.style && data.title;
+        }
+        else {
+            return data.style && data.title && data.prompt;
+        }
+    }
+    return true;
+}, {
+    message: "In customMode: style and title are always required, prompt is required when instrumental is false",
+    path: ["customMode"]
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@felores/kie-ai-mcp-server",
-  "version": "1.1.3",
+  "version": "1.2.0",
   "description": "MCP server for Kie.ai APIs (Nano Banana image generation/editing and Veo3 video generation)",
   "main": "dist/index.js",
   "bin": {
@@ -34,6 +34,13 @@
   "bugs": {
     "url": "https://github.com/felores/kie-ai-mcp-server/issues"
   },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/felores/kie-ai-mcp-server.git"
+  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^0.4.0",
     "sqlite3": "^5.1.6",