@felores/kie-ai-mcp-server 1.1.0 → 1.1.2

package/README.md

@@ -52,6 +52,7 @@ export KIE_AI_API_KEY="your-api-key-here"
 export KIE_AI_BASE_URL="https://api.kie.ai/api/v1"  # Default
 export KIE_AI_TIMEOUT="60000"                      # Default: 60 seconds
 export KIE_AI_DB_PATH="./tasks.db"                 # Default: ./tasks.db
+export KIE_AI_CALLBACK_URL="https://your-domain.com/api/callback"  # Default callback URL for video generation
 ```
 
 ### MCP Configuration
@@ -146,10 +147,12 @@ Generate videos using Veo3.
 - `prompt` (string, required): Video description
 - `imageUrls` (array, optional): Image for image-to-video (max 1)
 - `model` (enum, optional): "veo3" or "veo3_fast" (default: "veo3")
-- `aspectRatio` (enum, optional): "16:9" or "9:16" (default: "16:9")
+- `aspectRatio` (enum, optional): "16:9", "9:16", or "Auto" (default: "16:9", only 16:9 supports 1080P)
 - `seeds` (integer, optional): Random seed 10000-99999
 - `watermark` (string, optional): Watermark text
-- `enableFallback` (boolean, optional): Enable fallback mechanism
+- `callBackUrl` (string, optional): Callback URL for completion notifications
+- `enableFallback` (boolean, optional): Enable fallback mechanism (default: false, fallback videos cannot use 1080P endpoint)
+- `enableTranslation` (boolean, optional): Auto-translate prompts to English (default: true)
 
 **Example:**
 ```json
@@ -157,7 +160,8 @@ Generate videos using Veo3.
   "prompt": "A dog playing in a park",
   "model": "veo3",
   "aspectRatio": "16:9",
-  "seeds": 12345
+  "seeds": 12345,
+  "enableTranslation": true
 }
 ```
 
@@ -331,6 +335,15 @@ 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:**

package/dist/index.js

@@ -12,7 +12,7 @@ class KieAiMcpServer {
     constructor() {
         this.server = new Server({
             name: 'kie-ai-mcp-server',
-            version: '1.1.0',
+            version: '1.1.2',
         });
         // Initialize client with config from environment
         const config = {
@@ -27,6 +27,40 @@ class KieAiMcpServer {
         this.db = new TaskDatabase(process.env.KIE_AI_DB_PATH);
         this.setupHandlers();
     }
+    formatError(toolName, error, paramDescriptions) {
+        let errorMessage = 'Unknown error';
+        let errorDetails = '';
+        if (error instanceof Error) {
+            errorMessage = error.message;
+            // Check for Zod validation errors
+            if (errorMessage.includes('ZodError')) {
+                const lines = errorMessage.split('\n');
+                const validationErrors = lines.filter(line => line.includes('Expected') || line.includes('Required') || line.includes('Invalid'));
+                if (validationErrors.length > 0) {
+                    errorDetails = `Validation errors:\n${validationErrors.map(err => `- ${err.trim()}`).join('\n')}`;
+                }
+            }
+        }
+        // Build parameter guidance
+        const paramGuidance = Object.entries(paramDescriptions)
+            .map(([param, desc]) => `- ${param}: ${desc}`)
+            .join('\n');
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        success: false,
+                        tool: toolName,
+                        error: errorMessage,
+                        details: errorDetails,
+                        parameter_guidance: paramGuidance,
+                        message: `Failed to execute ${toolName}. Check parameters and try again.`
+                    }, null, 2)
+                }
+            ]
+        };
+    }
     setupHandlers() {
         this.server.setRequestHandler(ListToolsRequestSchema, async () => {
             return {
@@ -152,8 +186,8 @@ class KieAiMcpServer {
                                 },
                                 aspectRatio: {
                                     type: 'string',
-                                    enum: ['16:9', '9:16'],
-                                    description: 'Video aspect ratio',
+                                    enum: ['16:9', '9:16', 'Auto'],
+                                    description: 'Video aspect ratio (16:9 supports 1080P)',
                                     default: '16:9'
                                 },
                                 seeds: {
@@ -162,10 +196,20 @@ class KieAiMcpServer {
                                     minimum: 10000,
                                     maximum: 99999
                                 },
+                                callBackUrl: {
+                                    type: 'string',
+                                    format: 'uri',
+                                    description: 'Callback URL for task completion notifications'
+                                },
                                 enableFallback: {
                                     type: 'boolean',
-                                    description: 'Enable fallback mechanism for content policy failures',
+                                    description: 'Enable fallback mechanism for content policy failures (Note: fallback videos cannot use 1080P endpoint)',
                                     default: false
+                                },
+                                enableTranslation: {
+                                    type: 'boolean',
+                                    description: 'Auto-translate prompts to English for better results',
+                                    default: true
                                 }
                             },
                             required: ['prompt']
@@ -259,8 +303,8 @@ class KieAiMcpServer {
         });
     }
     async handleGenerateNanoBanana(args) {
-        const request = NanoBananaGenerateSchema.parse(args);
         try {
+            const request = NanoBananaGenerateSchema.parse(args);
             const response = await this.client.generateNanoBanana(request);
             if (response.data?.taskId) {
                 await this.db.createTask({
@@ -284,23 +328,16 @@ class KieAiMcpServer {
             };
         }
         catch (error) {
-            const message = error instanceof Error ? error.message : 'Generation failed';
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: JSON.stringify({
-                            success: false,
-                            error: message
-                        }, null, 2)
-                    }
-                ]
-            };
+            return this.formatError('generate_nano_banana', error, {
+                prompt: 'Required: text description of image to generate (max 5000 chars)',
+                output_format: 'Optional: "png" or "jpeg"',
+                image_size: 'Optional: aspect ratio like "16:9", "1:1", etc.'
+            });
         }
     }
     async handleEditNanoBanana(args) {
-        const request = NanoBananaEditSchema.parse(args);
         try {
+            const request = NanoBananaEditSchema.parse(args);
             const response = await this.client.editNanoBanana(request);
             if (response.data?.taskId) {
                 await this.db.createTask({
@@ -324,23 +361,17 @@ class KieAiMcpServer {
             };
         }
         catch (error) {
-            const message = error instanceof Error ? error.message : 'Editing failed';
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: JSON.stringify({
-                            success: false,
-                            error: message
-                        }, null, 2)
-                    }
-                ]
-            };
+            return this.formatError('edit_nano_banana', error, {
+                prompt: 'Required: editing instructions (max 5000 chars)',
+                image_urls: 'Required: array of 1-10 image URLs to edit',
+                output_format: 'Optional: "png" or "jpeg"',
+                image_size: 'Optional: aspect ratio like "16:9", "1:1", etc.'
+            });
         }
     }
     async handleUpscaleNanoBanana(args) {
-        const request = NanoBananaUpscaleSchema.parse(args);
         try {
+            const request = NanoBananaUpscaleSchema.parse(args);
             const response = await this.client.upscaleNanaBanana(request);
             if (response.data?.taskId) {
                 await this.db.createTask({
@@ -364,23 +395,20 @@ class KieAiMcpServer {
             };
         }
         catch (error) {
-            const message = error instanceof Error ? error.message : 'Upscale failed';
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: JSON.stringify({
-                            success: false,
-                            error: message
-                        }, null, 2)
-                    }
-                ]
-            };
+            return this.formatError('upscale_nano_banana', error, {
+                image: 'Required: URL of image to upscale (jpeg/png/webp, max 10MB)',
+                scale: 'Optional: upscale factor 1-4 (default: 2)',
+                face_enhance: 'Optional: enable face enhancement (default: false)'
+            });
         }
     }
     async handleGenerateVeo3Video(args) {
-        const request = Veo3GenerateSchema.parse(args);
         try {
+            const request = Veo3GenerateSchema.parse(args);
+            // Use environment variable as fallback if callBackUrl not provided
+            if (!request.callBackUrl && process.env.KIE_AI_CALLBACK_URL) {
+                request.callBackUrl = process.env.KIE_AI_CALLBACK_URL;
+            }
             const response = await this.client.generateVeo3Video(request);
             if (response.data?.taskId) {
                 await this.db.createTask({
@@ -404,26 +432,25 @@ class KieAiMcpServer {
             };
         }
         catch (error) {
-            const message = error instanceof Error ? error.message : 'Video generation failed';
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: JSON.stringify({
-                            success: false,
-                            error: message
-                        }, null, 2)
-                    }
-                ]
-            };
+            return this.formatError('generate_veo3_video', error, {
+                prompt: 'Required: video description (max 2000 chars)',
+                imageUrls: 'Optional: array with 1 image URL for image-to-video',
+                model: 'Optional: "veo3" (quality) or "veo3_fast" (cost-efficient)',
+                watermark: 'Optional: watermark text (max 100 chars)',
+                aspectRatio: 'Optional: "16:9", "9:16", or "Auto"',
+                seeds: 'Optional: random seed (10000-99999)',
+                callBackUrl: 'Optional: callback URL for notifications',
+                enableFallback: 'Optional: enable fallback for content policy failures',
+                enableTranslation: 'Optional: auto-translate prompts to English'
+            });
         }
     }
     async handleGetTaskStatus(args) {
-        const { task_id } = args;
-        if (!task_id || typeof task_id !== 'string') {
-            throw new McpError(ErrorCode.InvalidParams, 'task_id is required and must be a string');
-        }
         try {
+            const { task_id } = args;
+            if (!task_id || typeof task_id !== 'string') {
+                throw new McpError(ErrorCode.InvalidParams, 'task_id is required and must be a string');
+            }
             const localTask = await this.db.getTask(task_id);
             // Always try to get updated status from API, passing api_type if available
             let apiResponse = null;
@@ -481,23 +508,14 @@ class KieAiMcpServer {
             };
         }
         catch (error) {
-            const message = error instanceof Error ? error.message : 'Failed to get task status';
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: JSON.stringify({
-                            success: false,
-                            error: message
-                        }, null, 2)
-                    }
-                ]
-            };
+            return this.formatError('get_task_status', error, {
+                task_id: 'Required: task ID to check status for'
+            });
         }
     }
     async handleListTasks(args) {
-        const { limit = 20, status } = args;
         try {
+            const { limit = 20, status } = args;
             let tasks;
             if (status) {
                 tasks = await this.db.getTasksByStatus(status, limit);
@@ -520,26 +538,18 @@ class KieAiMcpServer {
             };
         }
         catch (error) {
-            const message = error instanceof Error ? error.message : 'Failed to list tasks';
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: JSON.stringify({
-                            success: false,
-                            error: message
-                        }, null, 2)
-                    }
-                ]
-            };
+            return this.formatError('list_tasks', error, {
+                limit: 'Optional: max tasks to return (1-100, default: 20)',
+                status: 'Optional: filter by status (pending, processing, completed, failed)'
+            });
         }
     }
     async handleGetVeo1080pVideo(args) {
-        const { task_id, index } = args;
-        if (!task_id || typeof task_id !== 'string') {
-            throw new McpError(ErrorCode.InvalidParams, 'task_id is required and must be a string');
-        }
         try {
+            const { task_id, index } = args;
+            if (!task_id || typeof task_id !== 'string') {
+                throw new McpError(ErrorCode.InvalidParams, 'task_id is required and must be a string');
+            }
             const response = await this.client.getVeo1080pVideo(task_id, index);
             return {
                 content: [
@@ -557,18 +567,10 @@ class KieAiMcpServer {
             };
         }
         catch (error) {
-            const message = error instanceof Error ? error.message : 'Failed to get 1080p video';
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: JSON.stringify({
-                            success: false,
-                            error: message
-                        }, null, 2)
-                    }
-                ]
-            };
+            return this.formatError('get_veo3_1080p_video', error, {
+                task_id: 'Required: Veo3 task ID to get 1080p video for',
+                index: 'Optional: video index (for multiple video results)'
+            });
         }
     }
     async run() {

package/dist/types.d.ts

@@ -46,28 +46,31 @@ export declare const Veo3GenerateSchema: z.ZodObject<{
     imageUrls: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     model: z.ZodDefault<z.ZodEnum<["veo3", "veo3_fast"]>>;
     watermark: z.ZodOptional<z.ZodString>;
-    aspectRatio: z.ZodDefault<z.ZodEnum<["16:9", "9:16"]>>;
+    aspectRatio: z.ZodDefault<z.ZodEnum<["16:9", "9:16", "Auto"]>>;
     seeds: z.ZodOptional<z.ZodNumber>;
     callBackUrl: z.ZodOptional<z.ZodString>;
     enableFallback: z.ZodDefault<z.ZodBoolean>;
+    enableTranslation: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
 }, "strip", z.ZodTypeAny, {
     prompt: string;
     model: "veo3" | "veo3_fast";
-    aspectRatio: "9:16" | "16:9";
+    aspectRatio: "9:16" | "16:9" | "Auto";
     enableFallback: boolean;
     imageUrls?: string[] | undefined;
     watermark?: string | undefined;
     seeds?: number | undefined;
     callBackUrl?: string | undefined;
+    enableTranslation?: boolean | undefined;
 }, {
     prompt: string;
     imageUrls?: string[] | undefined;
     model?: "veo3" | "veo3_fast" | undefined;
     watermark?: string | undefined;
-    aspectRatio?: "9:16" | "16:9" | undefined;
+    aspectRatio?: "9:16" | "16:9" | "Auto" | undefined;
     seeds?: number | undefined;
     callBackUrl?: string | undefined;
     enableFallback?: boolean | undefined;
+    enableTranslation?: boolean | undefined;
 }>;
 export type NanoBananaGenerateRequest = z.infer<typeof NanoBananaGenerateSchema>;
 export type NanaBananaEditRequest = z.infer<typeof NanoBananaEditSchema>;

package/dist/types.js

@@ -21,8 +21,9 @@ export const Veo3GenerateSchema = z.object({
     imageUrls: z.array(z.string().url()).max(1).optional(),
     model: z.enum(['veo3', 'veo3_fast']).default('veo3'),
     watermark: z.string().max(100).optional(),
-    aspectRatio: z.enum(['16:9', '9:16']).default('16:9'),
+    aspectRatio: z.enum(['16:9', '9:16', 'Auto']).default('16:9'),
     seeds: z.number().int().min(10000).max(99999).optional(),
     callBackUrl: z.string().url().optional(),
-    enableFallback: z.boolean().default(false)
+    enableFallback: z.boolean().default(false),
+    enableTranslation: z.boolean().default(true).optional()
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@felores/kie-ai-mcp-server",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "MCP server for Kie.ai APIs (Nano Banana image generation/editing and Veo3 video generation)",
   "main": "dist/index.js",
   "bin": {