@felores/kie-ai-mcp-server 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 andrewlwn77
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,313 @@
+# Kie.ai MCP Server
+
+An MCP (Model Context Protocol) server that provides access to Kie.ai's AI APIs including Nano Banana image generation/editing and Veo3 video generation.
+
+## Features
+
+- **Nano Banana Image Generation**: Text-to-image generation using Google's Gemini 2.5 Flash Image Preview
+- **Nano Banana Image Editing**: Natural language image editing with up to 5 input images
+- **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
+- **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
+
+## Prerequisites
+
+- Node.js 18+ 
+- Kie.ai API key from https://kie.ai/api-key
+
+## Installation
+
+### From NPM
+
+```bash
+npm install -g @andrewlwn77/kie-ai-mcp-server
+```
+
+### From Source
+
+```bash
+# Clone the repository
+git clone https://github.com/andrewlwn77/kie-ai-mcp-server.git
+cd kie-ai-mcp-server
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+```
+
+## Configuration
+
+### Environment Variables
+
+```bash
+# Required
+export KIE_AI_API_KEY="your-api-key-here"
+
+# Optional
+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
+```
+
+### MCP Configuration
+
+Add to your Claude Desktop or MCP client configuration:
+
+```json
+{
+  "kie-ai-mcp-server": {
+    "command": "node",
+    "args": ["/path/to/kie-ai-mcp-server/dist/index.js"],
+    "env": {
+      "KIE_AI_API_KEY": "your-api-key-here"
+    }
+  }
+}
+```
+
+Or if installed globally:
+
+```json
+{
+  "kie-ai-mcp-server": {
+    "command": "npx",
+    "args": ["-y", "@andrewlwn77/kie-ai-mcp-server"],
+    "env": {
+      "KIE_AI_API_KEY": "your-api-key-here"
+    }
+  }
+}
+```
+
+## Available Tools
+
+### 1. `generate_nano_banana`
+Generate images using Nano Banana.
+
+**Parameters:**
+- `prompt` (string, required): Text description of the image to generate
+
+**Example:**
+```json
+{
+  "prompt": "A surreal painting of a giant banana floating in space"
+}
+```
+
+### 2. `edit_nano_banana`
+Edit images using natural language prompts.
+
+**Parameters:**
+- `prompt` (string, required): Description of edits to make
+- `image_urls` (array, required): URLs of images to edit (max 5)
+
+**Example:**
+```json
+{
+  "prompt": "Add a rainbow arching over the mountains",
+  "image_urls": ["https://example.com/image.jpg"]
+}
+```
+
+### 3. `generate_veo3_video`
+Generate videos using Veo3.
+
+**Parameters:**
+- `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")
+- `seeds` (integer, optional): Random seed 10000-99999
+- `watermark` (string, optional): Watermark text
+- `enableFallback` (boolean, optional): Enable fallback mechanism
+
+**Example:**
+```json
+{
+  "prompt": "A dog playing in a park",
+  "model": "veo3",
+  "aspectRatio": "16:9",
+  "seeds": 12345
+}
+```
+
+### 4. `get_task_status`
+Check the status of a generation task.
+
+**Parameters:**
+- `task_id` (string, required): Task ID to check
+
+### 5. `list_tasks`
+List recent tasks with their status.
+
+**Parameters:**
+- `limit` (integer, optional): Max tasks to return (default: 20, max: 100)
+- `status` (string, optional): Filter by status ("pending", "processing", "completed", "failed")
+
+### 6. `get_veo3_1080p_video`
+Get 1080P high-definition version of a Veo3 video.
+
+**Parameters:**
+- `task_id` (string, required): Veo3 task ID to get 1080p video for
+- `index` (integer, optional): Video index (for multiple video results)
+
+**Note**: Not available for videos generated with fallback mode.
+
+## API Endpoints
+
+The server interfaces with these Kie.ai API endpoints:
+
+- **Veo3 Video Generation**: `POST /api/v1/veo/generate` ✅ **VALIDATED**
+- **Veo3 Video Status**: `GET /api/v1/veo/record-info` ✅ **VALIDATED**  
+- **Veo3 1080p Upgrade**: `GET /api/v1/veo/get-1080p-video` ✅ **VALIDATED**
+- **Nano Banana Generation**: `POST /api/v1/playground/createTask` ✅ **VALIDATED**
+- **Nano Banana Status**: `GET /api/v1/playground/recordInfo` ✅ **VALIDATED**
+
+All endpoints have been tested and validated with live API responses.
+
+## Database Schema
+
+The server uses SQLite to track tasks:
+
+```sql
+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'
+  status TEXT DEFAULT 'pending',
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  result_url TEXT,
+  error_message TEXT
+);
+```
+
+## Usage Examples
+
+### Basic Image Generation
+```bash
+# Generate an image
+curl -X POST http://localhost:3000/tools/call \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "generate_nano_banana",
+    "arguments": {
+      "prompt": "A cat wearing a space helmet"
+    }
+  }'
+```
+
+### Video Generation with Options
+```bash
+# Generate a video
+curl -X POST http://localhost:3000/tools/call \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "generate_veo3_video",
+    "arguments": {
+      "prompt": "A peaceful garden with blooming flowers",
+      "aspectRatio": "16:9",
+      "model": "veo3_fast"
+    }
+  }'
+```
+
+## Error Handling
+
+The server handles these HTTP error codes from Kie.ai:
+
+- **200**: Success
+- **400**: Content policy violation / English prompts only
+- **401**: Unauthorized (invalid API key)
+- **402**: Insufficient credits
+- **404**: Resource not found
+- **422**: Validation error / record is null
+- **429**: Rate limited
+- **451**: Image access limits
+- **455**: Service maintenance
+- **500**: Server error / timeout
+- **501**: Generation failed
+
+## Development
+
+```bash
+# Run tests
+npm test
+
+# Development mode with auto-reload
+npm run dev
+
+# Type checking
+npx tsc --noEmit
+
+# Build for production
+npm run build
+```
+
+## Pricing
+
+Based on Kie.ai documentation:
+- **Nano Banana**: $0.020 per image (4 credits)
+- **Veo3 Quality**: Higher cost tier
+- **Veo3 Fast**: ~20% of Quality model pricing
+
+See https://kie.ai/billing for detailed pricing.
+
+## Production Tips
+
+1. **Database Location**: Set `KIE_AI_DB_PATH` to a persistent location
+2. **API Key Security**: Never commit API keys to version control
+3. **Rate Limiting**: Implement client-side rate limiting for high-volume usage
+4. **Monitoring**: Monitor task status and handle failed generations appropriately
+5. **Storage**: Consider automatic cleanup of old task records
+
+## Troubleshooting
+
+### Common Issues
+
+**"Unauthorized" errors**
+- Verify `KIE_AI_API_KEY` is set correctly
+- Check API key is valid at https://kie.ai/api-key
+
+**"Task not found" errors**
+- Tasks may expire after 14 days
+- Check task ID format matches expected pattern
+
+**Generation failures**
+- Check content policy compliance
+- Verify prompt is in English
+- Ensure sufficient API credits
+
+## Support
+
+For issues related to:
+- **MCP Server**: Open an issue at https://github.com/andrewlwn77/kie-ai-mcp-server/issues
+- **Kie.ai API**: Contact support@kie.ai or check https://docs.kie.ai/
+- **API Keys**: Visit https://kie.ai/api-key
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests if applicable
+5. Submit a pull request
+
+## Changelog
+
+### v1.0.0
+- Initial release
+- Nano Banana image generation and editing
+- Veo3 video generation
+- 1080p video upgrade support
+- SQLite task tracking
+- Smart endpoint routing
+- Comprehensive error handling

package/dist/database.d.ts

@@ -0,0 +1,12 @@
+import { TaskRecord } from './types.js';
+export declare class TaskDatabase {
+    private db;
+    constructor(dbPath?: string);
+    private initializeDatabase;
+    createTask(taskData: Omit<TaskRecord, 'id' | 'created_at' | 'updated_at'>): Promise<void>;
+    getTask(taskId: string): Promise<TaskRecord | null>;
+    updateTask(taskId: string, updates: Partial<TaskRecord>): Promise<void>;
+    getAllTasks(limit?: number): Promise<TaskRecord[]>;
+    getTasksByStatus(status: string, limit?: number): Promise<TaskRecord[]>;
+    close(): Promise<void>;
+}

package/dist/database.js

@@ -0,0 +1,105 @@
+import sqlite3 from 'sqlite3';
+export class TaskDatabase {
+    db;
+    constructor(dbPath = './tasks.db') {
+        this.db = new sqlite3.Database(dbPath);
+        this.initializeDatabase();
+    }
+    initializeDatabase() {
+        this.db.serialize(() => {
+            this.db.run(`
+        CREATE TABLE IF NOT EXISTS tasks (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          task_id TEXT UNIQUE NOT NULL,
+          api_type TEXT NOT NULL,
+          status TEXT DEFAULT 'pending',
+          created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+          updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+          result_url TEXT,
+          error_message TEXT
+        )
+      `);
+            this.db.run(`CREATE INDEX IF NOT EXISTS idx_task_id ON tasks(task_id)`);
+            this.db.run(`CREATE INDEX IF NOT EXISTS idx_status ON tasks(status)`);
+        });
+    }
+    async createTask(taskData) {
+        return new Promise((resolve, reject) => {
+            this.db.run(`INSERT INTO tasks (task_id, api_type, status, result_url, error_message) 
+         VALUES (?, ?, ?, ?, ?)`, [taskData.task_id, taskData.api_type, taskData.status, taskData.result_url || null, taskData.error_message || null], function (err) {
+                if (err)
+                    reject(err);
+                else
+                    resolve();
+            });
+        });
+    }
+    async getTask(taskId) {
+        return new Promise((resolve, reject) => {
+            this.db.get(`SELECT * FROM tasks WHERE task_id = ?`, [taskId], (err, row) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve(row || null);
+            });
+        });
+    }
+    async updateTask(taskId, updates) {
+        const updateFields = [];
+        const values = [];
+        if (updates.status) {
+            updateFields.push('status = ?');
+            values.push(updates.status);
+        }
+        if (updates.result_url) {
+            updateFields.push('result_url = ?');
+            values.push(updates.result_url);
+        }
+        if (updates.error_message) {
+            updateFields.push('error_message = ?');
+            values.push(updates.error_message);
+        }
+        updateFields.push('updated_at = CURRENT_TIMESTAMP');
+        values.push(taskId);
+        if (updateFields.length > 1) {
+            return new Promise((resolve, reject) => {
+                this.db.run(`UPDATE tasks SET ${updateFields.join(', ')} WHERE task_id = ?`, values, function (err) {
+                    if (err)
+                        reject(err);
+                    else
+                        resolve();
+                });
+            });
+        }
+    }
+    async getAllTasks(limit = 100) {
+        return new Promise((resolve, reject) => {
+            this.db.all(`SELECT * FROM tasks ORDER BY created_at DESC LIMIT ?`, [limit], (err, rows) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve(rows);
+            });
+        });
+    }
+    async getTasksByStatus(status, limit = 50) {
+        return new Promise((resolve, reject) => {
+            this.db.all(`SELECT * FROM tasks WHERE status = ? ORDER BY created_at DESC LIMIT ?`, [status, limit], (err, rows) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve(rows);
+            });
+        });
+    }
+    async close() {
+        return new Promise((resolve, reject) => {
+            this.db.close((err) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve();
+            });
+        });
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,455 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+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, Veo3GenerateSchema } from './types.js';
+class KieAiMcpServer {
+    server;
+    client;
+    db;
+    constructor() {
+        this.server = new Server({
+            name: 'kie-ai-mcp-server',
+            version: '1.0.0',
+        });
+        // Initialize client with config from environment
+        const config = {
+            apiKey: process.env.KIE_AI_API_KEY || '',
+            baseUrl: process.env.KIE_AI_BASE_URL || 'https://api.kie.ai/api/v1',
+            timeout: parseInt(process.env.KIE_AI_TIMEOUT || '60000')
+        };
+        if (!config.apiKey) {
+            throw new Error('KIE_AI_API_KEY environment variable is required');
+        }
+        this.client = new KieAiClient(config);
+        this.db = new TaskDatabase(process.env.KIE_AI_DB_PATH);
+        this.setupHandlers();
+    }
+    setupHandlers() {
+        this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+            return {
+                tools: [
+                    {
+                        name: 'generate_nano_banana',
+                        description: 'Generate images using Google\'s Gemini 2.5 Flash Image Preview (Nano Banana)',
+                        inputSchema: {
+                            type: 'object',
+                            properties: {
+                                prompt: {
+                                    type: 'string',
+                                    description: 'Text prompt for image generation',
+                                    minLength: 1,
+                                    maxLength: 1000
+                                }
+                            },
+                            required: ['prompt']
+                        }
+                    },
+                    {
+                        name: 'edit_nano_banana',
+                        description: 'Edit images using natural language prompts with Nano Banana Edit',
+                        inputSchema: {
+                            type: 'object',
+                            properties: {
+                                prompt: {
+                                    type: 'string',
+                                    description: 'Text prompt for image editing',
+                                    minLength: 1,
+                                    maxLength: 1000
+                                },
+                                image_urls: {
+                                    type: 'array',
+                                    description: 'URLs of input images for editing (max 5)',
+                                    items: { type: 'string', format: 'uri' },
+                                    minItems: 1,
+                                    maxItems: 5
+                                }
+                            },
+                            required: ['prompt', 'image_urls']
+                        }
+                    },
+                    {
+                        name: 'generate_veo3_video',
+                        description: 'Generate professional-quality videos using Google\'s Veo3 API',
+                        inputSchema: {
+                            type: 'object',
+                            properties: {
+                                prompt: {
+                                    type: 'string',
+                                    description: 'Text prompt describing desired video content',
+                                    minLength: 1,
+                                    maxLength: 2000
+                                },
+                                imageUrls: {
+                                    type: 'array',
+                                    description: 'Image URLs for image-to-video generation (max 1)',
+                                    items: { type: 'string', format: 'uri' },
+                                    maxItems: 1
+                                },
+                                model: {
+                                    type: 'string',
+                                    enum: ['veo3', 'veo3_fast'],
+                                    description: 'Model type: veo3 (quality) or veo3_fast (cost-efficient)',
+                                    default: 'veo3'
+                                },
+                                watermark: {
+                                    type: 'string',
+                                    description: 'Watermark text to add to video',
+                                    maxLength: 100
+                                },
+                                aspectRatio: {
+                                    type: 'string',
+                                    enum: ['16:9', '9:16'],
+                                    description: 'Video aspect ratio',
+                                    default: '16:9'
+                                },
+                                seeds: {
+                                    type: 'integer',
+                                    description: 'Random seed for consistent results',
+                                    minimum: 10000,
+                                    maximum: 99999
+                                },
+                                enableFallback: {
+                                    type: 'boolean',
+                                    description: 'Enable fallback mechanism for content policy failures',
+                                    default: false
+                                }
+                            },
+                            required: ['prompt']
+                        }
+                    },
+                    {
+                        name: 'get_task_status',
+                        description: 'Get the status of a generation task',
+                        inputSchema: {
+                            type: 'object',
+                            properties: {
+                                task_id: {
+                                    type: 'string',
+                                    description: 'Task ID to check status for'
+                                }
+                            },
+                            required: ['task_id']
+                        }
+                    },
+                    {
+                        name: 'list_tasks',
+                        description: 'List recent tasks with their status',
+                        inputSchema: {
+                            type: 'object',
+                            properties: {
+                                limit: {
+                                    type: 'integer',
+                                    description: 'Maximum number of tasks to return',
+                                    default: 20,
+                                    maximum: 100
+                                },
+                                status: {
+                                    type: 'string',
+                                    description: 'Filter by status',
+                                    enum: ['pending', 'processing', 'completed', 'failed']
+                                }
+                            }
+                        }
+                    },
+                    {
+                        name: 'get_veo3_1080p_video',
+                        description: 'Get 1080P high-definition version of a Veo3 video (not available for fallback mode videos)',
+                        inputSchema: {
+                            type: 'object',
+                            properties: {
+                                task_id: {
+                                    type: 'string',
+                                    description: 'Veo3 task ID to get 1080p video for'
+                                },
+                                index: {
+                                    type: 'integer',
+                                    description: 'Video index (optional, for multiple video results)',
+                                    minimum: 0
+                                }
+                            },
+                            required: ['task_id']
+                        }
+                    }
+                ]
+            };
+        });
+        this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+            try {
+                const { name, arguments: args } = request.params;
+                switch (name) {
+                    case 'generate_nano_banana':
+                        return await this.handleGenerateNanoBanana(args);
+                    case 'edit_nano_banana':
+                        return await this.handleEditNanoBanana(args);
+                    case 'generate_veo3_video':
+                        return await this.handleGenerateVeo3Video(args);
+                    case 'get_task_status':
+                        return await this.handleGetTaskStatus(args);
+                    case 'list_tasks':
+                        return await this.handleListTasks(args);
+                    case 'get_veo3_1080p_video':
+                        return await this.handleGetVeo1080pVideo(args);
+                    default:
+                        throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+                }
+            }
+            catch (error) {
+                if (error instanceof McpError) {
+                    throw error;
+                }
+                const message = error instanceof Error ? error.message : 'Unknown error';
+                throw new McpError(ErrorCode.InternalError, message);
+            }
+        });
+    }
+    async handleGenerateNanoBanana(args) {
+        const request = NanoBananaGenerateSchema.parse(args);
+        try {
+            const response = await this.client.generateNanoBanana(request);
+            if (response.data?.taskId) {
+                await this.db.createTask({
+                    task_id: response.data.taskId,
+                    api_type: 'nano-banana',
+                    status: 'pending',
+                    result_url: response.data.imageUrl
+                });
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            response: response,
+                            message: 'Nano Banana image generation initiated'
+                        }, null, 2)
+                    }
+                ]
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Generation failed';
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: message
+                        }, null, 2)
+                    }
+                ]
+            };
+        }
+    }
+    async handleEditNanoBanana(args) {
+        const request = NanoBananaEditSchema.parse(args);
+        try {
+            const response = await this.client.editNanoBanana(request);
+            if (response.data?.taskId) {
+                await this.db.createTask({
+                    task_id: response.data.taskId,
+                    api_type: 'nano-banana-edit',
+                    status: 'pending',
+                    result_url: response.data.imageUrl
+                });
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            response: response,
+                            message: 'Nano Banana image editing initiated'
+                        }, null, 2)
+                    }
+                ]
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Editing failed';
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: message
+                        }, null, 2)
+                    }
+                ]
+            };
+        }
+    }
+    async handleGenerateVeo3Video(args) {
+        const request = Veo3GenerateSchema.parse(args);
+        try {
+            const response = await this.client.generateVeo3Video(request);
+            if (response.data?.taskId) {
+                await this.db.createTask({
+                    task_id: response.data.taskId,
+                    api_type: 'veo3',
+                    status: 'pending'
+                });
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            task_id: response.data?.taskId,
+                            message: 'Veo3 video generation task created successfully',
+                            note: 'Use get_task_status to check progress'
+                        }, null, 2)
+                    }
+                ]
+            };
+        }
+        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)
+                    }
+                ]
+            };
+        }
+    }
+    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 localTask = await this.db.getTask(task_id);
+            // Always try to get updated status from API, passing api_type if available
+            let apiResponse = null;
+            try {
+                apiResponse = await this.client.getTaskStatus(task_id, localTask?.api_type);
+            }
+            catch (error) {
+                // API call failed, use local data if available
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            local_task: localTask,
+                            api_response: apiResponse,
+                            message: localTask ? 'Task found' : 'Task not found in local database'
+                        }, null, 2)
+                    }
+                ]
+            };
+        }
+        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)
+                    }
+                ]
+            };
+        }
+    }
+    async handleListTasks(args) {
+        const { limit = 20, status } = args;
+        try {
+            let tasks;
+            if (status) {
+                tasks = await this.db.getTasksByStatus(status, limit);
+            }
+            else {
+                tasks = await this.db.getAllTasks(limit);
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            tasks: tasks,
+                            count: tasks.length,
+                            message: `Retrieved ${tasks.length} tasks`
+                        }, null, 2)
+                    }
+                ]
+            };
+        }
+        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)
+                    }
+                ]
+            };
+        }
+    }
+    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 response = await this.client.getVeo1080pVideo(task_id, index);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            task_id: task_id,
+                            response: response,
+                            message: 'Retrieved 1080p video URL',
+                            note: 'Not available for videos generated with fallback mode'
+                        }, null, 2)
+                    }
+                ]
+            };
+        }
+        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)
+                    }
+                ]
+            };
+        }
+    }
+    async run() {
+        const transport = new StdioServerTransport();
+        await this.server.connect(transport);
+    }
+}
+// Start the server
+const server = new KieAiMcpServer();
+server.run().catch(console.error);

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

@@ -0,0 +1,11 @@
+import { KieAiConfig, KieAiResponse, NanoBananaGenerateRequest, NanaBananaEditRequest, Veo3GenerateRequest, ImageResponse, TaskResponse } from './types.js';
+export declare class KieAiClient {
+    private config;
+    constructor(config: KieAiConfig);
+    private makeRequest;
+    generateNanoBanana(request: NanoBananaGenerateRequest): Promise<KieAiResponse<ImageResponse>>;
+    editNanoBanana(request: NanaBananaEditRequest): Promise<KieAiResponse<ImageResponse>>;
+    generateVeo3Video(request: Veo3GenerateRequest): Promise<KieAiResponse<TaskResponse>>;
+    getTaskStatus(taskId: string, apiType?: string): Promise<KieAiResponse<any>>;
+    getVeo1080pVideo(taskId: string, index?: number): Promise<KieAiResponse<any>>;
+}

package/dist/kie-ai-client.js

@@ -0,0 +1,85 @@
+export class KieAiClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async makeRequest(endpoint, method = 'POST', body) {
+        const url = `${this.config.baseUrl}${endpoint}`;
+        const headers = {
+            'Authorization': `Bearer ${this.config.apiKey}`,
+            'Content-Type': 'application/json'
+        };
+        const requestOptions = {
+            method,
+            headers,
+            signal: AbortSignal.timeout(this.config.timeout)
+        };
+        if (body && method === 'POST') {
+            requestOptions.body = JSON.stringify(body);
+        }
+        try {
+            const response = await fetch(url, requestOptions);
+            const data = await response.json();
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}: ${data.msg || 'Unknown error'}`);
+            }
+            return data;
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                throw new Error(`Request failed: ${error.message}`);
+            }
+            throw error;
+        }
+    }
+    async generateNanoBanana(request) {
+        const playgroundRequest = {
+            model: 'google/nano-banana',
+            input: {
+                prompt: request.prompt
+            }
+        };
+        return this.makeRequest('/playground/createTask', 'POST', playgroundRequest);
+    }
+    async editNanoBanana(request) {
+        const playgroundRequest = {
+            model: 'google/nano-banana-edit',
+            input: {
+                prompt: request.prompt,
+                image_urls: request.image_urls
+            }
+        };
+        return this.makeRequest('/playground/createTask', 'POST', playgroundRequest);
+    }
+    async generateVeo3Video(request) {
+        return this.makeRequest('/veo/generate', 'POST', request);
+    }
+    async getTaskStatus(taskId, apiType) {
+        // Use api_type to determine correct endpoint, with fallback strategy
+        if (apiType === 'veo3') {
+            return this.makeRequest(`/veo/record-info?taskId=${taskId}`, 'GET');
+        }
+        else if (apiType === 'nano-banana' || apiType === 'nano-banana-edit') {
+            return this.makeRequest(`/playground/recordInfo?taskId=${taskId}`, 'GET');
+        }
+        // Fallback: try playground first, then veo (for tasks not in database)
+        try {
+            return await this.makeRequest(`/playground/recordInfo?taskId=${taskId}`, 'GET');
+        }
+        catch (error) {
+            try {
+                return await this.makeRequest(`/veo/record-info?taskId=${taskId}`, 'GET');
+            }
+            catch (veoError) {
+                throw error;
+            }
+        }
+    }
+    async getVeo1080pVideo(taskId, index) {
+        const params = new URLSearchParams({ taskId });
+        if (index !== undefined) {
+            params.append('index', index.toString());
+        }
+        return this.makeRequest(`/veo/get-1080p-video?${params}`, 'GET');
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,76 @@
+import { z } from 'zod';
+export declare const NanoBananaGenerateSchema: z.ZodObject<{
+    prompt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    prompt: string;
+}, {
+    prompt: string;
+}>;
+export declare const NanoBananaEditSchema: z.ZodObject<{
+    prompt: z.ZodString;
+    image_urls: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    prompt: string;
+    image_urls: string[];
+}, {
+    prompt: string;
+    image_urls: string[];
+}>;
+export declare const Veo3GenerateSchema: z.ZodObject<{
+    prompt: z.ZodString;
+    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"]>>;
+    seeds: z.ZodOptional<z.ZodNumber>;
+    callBackUrl: z.ZodOptional<z.ZodString>;
+    enableFallback: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    prompt: string;
+    model: "veo3" | "veo3_fast";
+    aspectRatio: "16:9" | "9:16";
+    enableFallback: boolean;
+    imageUrls?: string[] | undefined;
+    watermark?: string | undefined;
+    seeds?: number | undefined;
+    callBackUrl?: string | undefined;
+}, {
+    prompt: string;
+    imageUrls?: string[] | undefined;
+    model?: "veo3" | "veo3_fast" | undefined;
+    watermark?: string | undefined;
+    aspectRatio?: "16:9" | "9:16" | undefined;
+    seeds?: number | undefined;
+    callBackUrl?: string | undefined;
+    enableFallback?: boolean | undefined;
+}>;
+export type NanoBananaGenerateRequest = z.infer<typeof NanoBananaGenerateSchema>;
+export type NanaBananaEditRequest = z.infer<typeof NanoBananaEditSchema>;
+export type Veo3GenerateRequest = z.infer<typeof Veo3GenerateSchema>;
+export interface KieAiResponse<T = any> {
+    code: number;
+    msg: string;
+    data?: T;
+}
+export interface ImageResponse {
+    imageUrl?: string;
+    taskId?: string;
+}
+export interface TaskResponse {
+    taskId: string;
+}
+export interface TaskRecord {
+    id?: number;
+    task_id: string;
+    api_type: 'nano-banana' | 'nano-banana-edit' | 'veo3';
+    status: 'pending' | 'processing' | 'completed' | 'failed';
+    created_at: string;
+    updated_at: string;
+    result_url?: string;
+    error_message?: string;
+}
+export interface KieAiConfig {
+    apiKey: string;
+    baseUrl: string;
+    timeout: number;
+}

package/dist/types.js

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+// Zod schemas for request validation
+export const NanoBananaGenerateSchema = z.object({
+    prompt: z.string().min(1).max(1000)
+});
+export const NanoBananaEditSchema = z.object({
+    prompt: z.string().min(1).max(1000),
+    image_urls: z.array(z.string().url()).min(1).max(5)
+});
+export const Veo3GenerateSchema = z.object({
+    prompt: z.string().min(1).max(2000),
+    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'),
+    seeds: z.number().int().min(10000).max(99999).optional(),
+    callBackUrl: z.string().url().optional(),
+    enableFallback: z.boolean().default(false)
+});

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@felores/kie-ai-mcp-server",
+  "version": "1.0.0",
+  "description": "MCP server for Kie.ai APIs (Nano Banana image generation/editing and Veo3 video generation)",
+  "main": "dist/index.js",
+  "bin": {
+    "kie-ai-mcp-server": "dist/index.js"
+  },
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "test": "jest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "kie.ai",
+    "ai",
+    "image-generation",
+    "video-generation",
+    "nano-banana",
+    "veo3",
+    "model-context-protocol"
+  ],
+  "author": "felores",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/felo/kie-ai-mcp-server.git"
+  },
+  "homepage": "https://github.com/felo/kie-ai-mcp-server#readme",
+  "bugs": {
+    "url": "https://github.com/felo/kie-ai-mcp-server/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^0.4.0",
+    "sqlite3": "^5.1.6",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "@types/sqlite3": "^3.1.11",
+    "typescript": "^5.3.0",
+    "tsx": "^4.6.0",
+    "jest": "^29.7.0",
+    "@types/jest": "^29.5.8"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ]
+}