### Install kie-cli via npm

Source: https://github.com/felores/kie-cli-mcp/blob/main/skills/kie-ai/SKILL.md

Install the kie-cli globally using npm. This is the preferred method for installation. It also includes a verification step to confirm the installation.

```bash
npm i -g @felores/kie-cli && kie-cli --help | head -1   # install + verify
```

--------------------------------

### Install and Run ngrok for Local Development

Source: https://github.com/felores/kie-cli-mcp/blob/main/docs/kie/runway_aleph_video.md

Use ngrok to expose your local server to the internet for testing callbacks. Install it globally and then run it to expose a specific port.

```bash
# Install ngrok
npm install -g ngrok

# Expose local port 3000
ngrok http 3000

# Use the provided HTTPS URL as your callback URL
# Example: https://abc123.ngrok.io/webhook/aleph-callback
```

--------------------------------

### Install KIE CLI MCP from Source

Source: https://github.com/felores/kie-cli-mcp/blob/main/README.md

Clone the repository, navigate to the directory, and install dependencies using npm. Build the project and run type checks or tests as needed for development.

```bash
git clone https://github.com/felores/kie-cli-mcp.git
cd kie-cli-mcp
npm install
npm run build       # build all workspaces
npm run typecheck   # type-check all workspaces
npm test            # run the test suite
```

--------------------------------

### Install Package from GitHub Packages

Source: https://github.com/felores/kie-cli-mcp/blob/main/AGENTS.md

Install the package from the GitHub Packages registry. This requires authentication with a GitHub token that has the 'read:packages' scope.

```bash
npm install @felores/kie-ai-mcp-server --registry https://npm.pkg.github.com/
```

--------------------------------

### Verify Local Installation

Source: https://github.com/felores/kie-cli-mcp/blob/main/AGENTS.md

Verify that a package can be installed correctly from a local source or registry.

```bash
npm install @felores/kie-ai-mcp-server
```

--------------------------------

### Minimal Setup Configuration

Source: https://github.com/felores/kie-cli-mcp/blob/main/docs/PRD_TOOL_FILTERING.md

Configure the MCP server with a minimal setup, enabling only specific, explicitly listed tools. This is ideal for testing or environments where only a few tools are required.

```json
{
  "mcpServers": {
    "kie-ai-minimal": {
      "command": "npx",
      "args": ["-y", "@felores/kie-ai-mcp-server"],
      "env": {
        "KIE_AI_API_KEY": "your-key",
        "KIE_AI_ENABLED_TOOLS": "nano_banana_image,veo3_generate_video,suno_generate_music"
      }
    }
  }
}
```

--------------------------------

### Install kie-cli Globally

Source: https://github.com/felores/kie-cli-mcp/blob/main/packages/cli/README.md

Install the @felores/kie-cli package globally using npm to make it available on your system.

```bash
npm install -g @felores/kie-cli
```

--------------------------------

### Install MCP TypeScript SDK

Source: https://github.com/felores/kie-cli-mcp/blob/main/docs/mcp/mcp_typescript_sdk_readme.md

Install the MCP SDK using npm. This command should be run in your project directory.

```bash
npm install @modelcontextprotocol/sdk
```

--------------------------------

### Build and Install kie-cli from Monorepo

Source: https://github.com/felores/kie-cli-mcp/blob/main/skills/kie-ai/SKILL.md

Alternative installation method for kie-cli if the npm package is not available. This involves cloning the repository, building the CLI bundle, and linking it globally.

```bash
REPO="$HOME/Documents/GitHub/mcp/kie-ai-mcp-server"
[ -d "$REPO" ] || git clone https://github.com/felores/kie-cli-mcp "$REPO"
cd "$REPO"
npm install
npm run build -w @felores/kie-ai-core && npm run bundle -w @felores/kie-cli
chmod +x packages/cli/dist/index.js
ln -sf "$PWD/packages/cli/dist/index.js" "$(npm config get prefix)/bin/kie-cli"
kie-cli --help | head -1       # verify
```

--------------------------------

### Quick Workflow for Adding Tools

Source: https://github.com/felores/kie-cli-mcp/blob/main/CLAUDE.md

A step-by-step guide for quickly adding new tools. This includes scraping, scaffolding, schema definition, client method implementation, tool logic, and testing.

```bash
1. Scrape https://kie.ai/{endpoint} for parameters and pricing
2. npm run add-tool -- <tool_name> [image|video|audio|utility]   # scaffolds + registers
3. Move the Zod schema into packages/core/src/types.ts (use mode detection pattern)
4. Add the client method in packages/core/src/kie-ai-client.ts
5. Fill in description + run() body + db api_type in packages/core/src/tools/<tool_name>.ts
6. Update EXPECTED_TOOL_NAMES in packages/core/src/__tests__/registry.test.ts
7. npm run build && npm test, then bump versions, update docs, publish
```

--------------------------------

### List All Available Tools

Source: https://github.com/felores/kie-cli-mcp/blob/main/packages/cli/README.md

Use the --help flag with the kie-cli command to list all available tools, which correspond to the MCP tools.

```bash
kie-cli --help
```

--------------------------------

### Get Task Info

Source: https://github.com/felores/kie-cli-mcp/blob/main/docs/kie/recraft_remove_background.md

Polls the status of a generation task by sending a GET request to the recordInfo endpoint.

```APIDOC
## GET https://api.kie.ai/api/v1/jobs/recordInfo

### Description
Retrieves information about a specific generation task, including its status.

### Method
GET

### Endpoint
https://api.kie.ai/api/v1/jobs/recordInfo

### Query Parameters
- **taskId** (string) - Required - The unique identifier of the task to retrieve information for.

### Response
#### Success Response (200)
- **taskId** (string) - The unique identifier for the task.
- **state** (string) - The current state of the task (e.g., 'pending', 'success', 'failed').
- **resultJson** (object) - The generation results, available when the task state is 'success'.
```

--------------------------------

### Discover All Commands

Source: https://github.com/felores/kie-cli-mcp/blob/main/skills/kie-ai/SKILL.md

Use the `--help` flag on the main command to see all available tools and their groupings.

```bash
kie-cli --help                 # all commands, grouped [image]/[video]/[audio]/[utility]
```

--------------------------------

### Follow the Add Tool Workflow

Source: https://github.com/felores/kie-cli-mcp/blob/main/history/2025-12-06-110426_mcp-tool-sync-workflow-handoff.md

This comment references the detailed guide for adding new tools to the MCP server. Refer to the specified documentation file for the complete workflow.

```bash
# See: docs/ADD_TOOL_GUIDE.md
```

--------------------------------

### 401 Unauthorized Response Example

Source: https://github.com/felores/kie-cli-mcp/blob/main/docs/mcp/streamable_http_security.md

An example of an HTTP 401 Unauthorized response from an MCP server, advertising resource metadata.

```APIDOC
## 401 Unauthorized Response Example

### Description
This example shows a typical HTTP 401 Unauthorized response that an MCP server might return when a request is not authorized. It includes the `WWW-Authenticate` header with details on how to obtain resource metadata.

### Response Example
```http
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource",
                  scope="mcp:tools"
```
```

--------------------------------

### Example JSON-RPC Error Response

Source: https://github.com/felores/kie-cli-mcp/blob/main/docs/mcp/mcp_server_resources.md

This is an example of a JSON-RPC error response for a 'Resource not found' scenario, using code -32002.

```json
{
  "jsonrpc": "2.0",
  "id": 5,
  "error": {
    "code": -32002,
    "message": "Resource not found",
    "data": {
      "uri": "file:///nonexistent.txt"
    }
  }
}
```

--------------------------------

### Build an Echo Server with Resources, Tools, and Prompts

Source: https://github.com/felores/kie-cli-mcp/blob/main/docs/mcp/mcp_typescript_sdk_readme.md

A basic server demonstrating how to register tools, resources, and prompts using the MCP SDK. Input and output schemas are defined using Zod.

```typescript
import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
import { z } from 'zod';

const server = new McpServer({
    name: 'echo-server',
    version: '1.0.0'
});

server.registerTool(
    'echo',
    {
        title: 'Echo Tool',
        description: 'Echoes back the provided message',
        inputSchema: { message: z.string() },
        outputSchema: { echo: z.string() }
    },
    async ({ message }) => {
        const output = { echo: `Tool echo: ${message}` };
        return {
            content: [{ type: 'text', text: JSON.stringify(output) }],
            structuredContent: output
        };
    }
);

server.registerResource(
    'echo',
    new ResourceTemplate('echo://{message}', { list: undefined }),
    {
        title: 'Echo Resource',
        description: 'Echoes back messages as resources'
    },
    async (uri, { message }) => ({
        contents: [
            {
                uri: uri.href,
                text: `Resource echo: ${message}`
            }
        ]
    })
);

server.registerPrompt(
    'echo',
    {
        title: 'Echo Prompt',
        description: 'Creates a prompt to process a message',
        argsSchema: { message: z.string() }
    },
    ({ message }) => ({
        messages: [
            {
                role: 'user',
                content: {
                    type: 'text',
                    text: `Please process this message: ${message}`
                }
            }
        ]
    })
);
```

--------------------------------

### MCP Tool Call Example

Source: https://github.com/felores/kie-cli-mcp/blob/main/README.md

Example of a JSON payload for calling an MCP tool, specifying the tool name and its arguments.

```json
{
  "tool": "nano_banana_image",
  "arguments": {
    "prompt": "A futuristic city at sunset, cyberpunk style",
    "aspect_ratio": "16:9",
    "resolution": "2K",
    "output_format": "png"
  }
}
```

--------------------------------

### Pre-publish Checklist

Source: https://github.com/felores/kie-cli-mcp/blob/main/CLAUDE.md

Run these commands to ensure the package is built correctly and to preview the publication.

```bash
npm run build
npx tsc --noEmit
npm publish --dry-run
```

--------------------------------

### Task Status Response Example

Source: https://github.com/felores/kie-cli-mcp/blob/main/docs/kie/kling_v2-1-pro.md

This is an example of a successful response when querying task status. The 'state' field indicates the current status of the task.

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "281e5b0*********************f39b9",
    "model": "kling/v2-1-pro",
    "state": "waiting",
    "param": "{\"model\":\"kling/v2-1-pro\",\"input\":{\"prompt\":\"POV shot of a gravity surfer diving between ancient ruins suspended midair, glowing moss lights the path, the board hisses as it carves through thin mist, echoes rise with speed ",\"image_url\":\"https://file.aiquickdraw.com/custom-page/akr/section-images/1754892534386c8wt0qfs.webp\",\"duration\":\"5\",\"negative_prompt\":\"blur, distort, and low quality\",\"cfg_scale\":0.5,\"tail_image_url\":\"\"}}",
    "resultJson": "{\"resultUrls\":[\"https://file.aiquickdraw.com/custom-page/akr/section-images/1755252994715824whwzh.mp4\"]}",
    "failCode": null,
    "failMsg": null,
    "costTime": null,
    "completeTime": null,
    "createTime": 1757584164490
  }
}
```

--------------------------------

### Implement LLM Sampling Server with MCP SDK

Source: https://github.com/felores/kie-cli-mcp/blob/main/docs/mcp/mcp_typescript_sdk_readme.md

Set up an MCP server that can request LLM completions from connected clients using sampling. This example demonstrates registering a 'summarize' tool that calls the LLM via `server.server.createMessage` and integrates with an Express HTTP server.

```typescript
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
import express from 'express';
import { z } from 'zod';

const mcpServer = new McpServer({
    name: 'tools-with-sample-server',
    version: '1.0.0'
});

// Tool that uses LLM sampling to summarize any text
mcpServer.registerTool(
    'summarize',
    {
        title: 'Text Summarizer',
        description: 'Summarize any text using an LLM',
        inputSchema: {
            text: z.string().describe('Text to summarize')
        },
        outputSchema: { summary: z.string() }
    },
    async ({ text }) => {
        // Call the LLM through MCP sampling
        const response = await mcpServer.server.createMessage({
            messages: [
                {
                    role: 'user',
                    content: {
                        type: 'text',
                        text: `Please summarize the following text concisely:\n\n${text}`
                    }
                }
            ],
            maxTokens: 500
        });

        const summary = response.content.type === 'text' ? response.content.text : 'Unable to generate summary';
        const output = { summary };
        return {
            content: [{ type: 'text', text: JSON.stringify(output) }],
            structuredContent: output
        };
    }
);

const app = express();
app.use(express.json());

app.post('/mcp', async (req, res) => {
    const transport = new StreamableHTTPServerTransport({
        sessionIdGenerator: undefined,
        enableJsonResponse: true
    });

    res.on('close', () => {
        transport.close();
    });

    await mcpServer.connect(transport);
    await transport.handleRequest(req, res, req.body);
});

const port = parseInt(process.env.PORT || '3000');
app.listen(port, () => {
    console.log(`MCP Server running on http://localhost:${port}/mcp`);
}).on('error', error => {
    console.error('Server error:', error);
    process.exit(1);
});
```

--------------------------------

### Example 401 Unauthorized Response

Source: https://github.com/felores/kie-cli-mcp/blob/main/docs/mcp/streamable_http_security.md

An example of an HTTP 401 Unauthorized response from an MCP server, advertising resource metadata via the WWW-Authenticate header.

```http
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource",
                  scope="mcp:tools"
```

--------------------------------

### Configure Multi-Environment .env Files

Source: https://github.com/felores/kie-cli-mcp/blob/main/docs/ADMIN.md

Define environment-specific variables for API keys, fallback callback URLs, and database paths. Load the appropriate file using the 'source' command before running the server.

```bash
# .env.development
KIE_AI_API_KEY=dev-api-key-xxx
KIE_AI_CALLBACK_URL_FALLBACK=https://dev-webhook.yourapp.com/kie
KIE_AI_DB_PATH=./dev-tasks.db

# .env.staging
KIE_AI_API_KEY=staging-api-key-xxx
KIE_AI_CALLBACK_URL_FALLBACK=https://staging-webhook.yourapp.com/kie
KIE_AI_DB_PATH=./staging-tasks.db

# .env.production
KIE_AI_API_KEY=prod-api-key-xxx
KIE_AI_CALLBACK_URL_FALLBACK=https://webhook.yourapp.com/kie
KIE_AI_DB_PATH=/var/lib/kie-ai/tasks.db
```

```bash
# Development
source .env.development && npx @felores/kie-ai-mcp-server

# Staging
source .env.staging && npx @felores/kie-ai-mcp-server

# Production
source .env.production && npx @felores/kie-ai-mcp-server
```

--------------------------------

### Scaffold and Register a New Tool

Source: https://github.com/felores/kie-cli-mcp/blob/main/CLAUDE.md

Use this npm script to scaffold a new tool and register it. It automates the initial setup process.

```bash
npm run add-tool -- <tool_name> [image|video|audio|utility]
```

--------------------------------

### Complete Veo3 Text-to-Image Workflow in Node.js

Source: https://github.com/felores/kie-cli-mcp/blob/main/docs/kie/google_veo3-text-to-image.md

This Node.js example demonstrates a full workflow for generating a video from a text prompt using the Veo3 API. It covers video generation, status checking, waiting for completion, and downloading the final video. Ensure you replace 'YOUR_API_KEY' with your actual API key.

```javascript
const fs = require('fs');
const https = require('https');

class Veo31Client {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://api.kie.ai';
    this.headers = {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    };
  }

  // Generate video
  async generateVideo(prompt, options = {}) {
    const payload = {
      prompt,
      model: options.model || 'veo3',
      aspectRatio: options.aspectRatio || '16:9',
      ...options
    };

    try {
      const response = await fetch(`${this.baseUrl}/api/v1/veo/generate`, {
        method: 'POST',
        headers: this.headers,
        body: JSON.stringify(payload)
      });
      
      const data = await response.json();
      
      if (response.ok && data.code === 200) {
        return data.data.taskId;
      } else {
        throw new Error(`Video generation failed: ${data.msg || 'Unknown error'}`);
      }
    } catch (error) {
      throw new Error(`Video generation failed: ${error.message}`);
    }
  }

  // Check status
  async getStatus(taskId) {
    try {
      const response = await fetch(`${this.baseUrl}/api/v1/veo/record-info?taskId=${taskId}`, {
        method: 'GET',
        headers: { 'Authorization': `Bearer ${this.apiKey}` }
      });
      
      const data = await response.json();
      
      if (response.ok && data.code === 200) {
        return data.data;
      } else {
        throw new Error(`Status check failed: ${data.msg || 'Unknown error'}`);
      }
    } catch (error) {
      throw new Error(`Status check failed: ${error.message}`);
    }
  }

  // Wait for completion
  async waitForCompletion(taskId, maxWaitTime = 600000) { // Default max wait 10 minutes
    const startTime = Date.now();
    
    while (Date.now() - startTime < maxWaitTime) {
      const status = await this.getStatus(taskId);
      
      console.log(`Task ${taskId} status: ${status.successFlag}`);
      
      if (status.successFlag === 1) {
        return JSON.parse(status.resultUrls);
      } else if (status.successFlag === 2 || status.successFlag === 3) {
        throw new Error('Video generation failed');
      }
      
      await new Promise(resolve => setTimeout(resolve, 30000)); // Wait 30 seconds
    }
    
    throw new Error('Task timeout');
  }

  // Download video
  async downloadVideo(url, filename) {
    return new Promise((resolve, reject) => {
      const file = fs.createWriteStream(filename);
      
      https.get(url, (response) => {
        if (response.statusCode === 200) {
          response.pipe(file);
          file.on('finish', () => {
            file.close();
            console.log(`Video downloaded: ${filename}`);
            resolve(filename);
          });
        } else {
          reject(new Error(`Download failed: HTTP ${response.statusCode}`));
        }
      }).on('error', reject);
    });
  }

  // Complete workflow
  async generateAndDownload(prompt, filename = 'video.mp4', options = {}) {
    try {
      console.log('Starting video generation...');
      const taskId = await this.generateVideo(prompt, options);
      console.log(`Task submitted: ${taskId}`);
      
      console.log('Waiting for completion...');
      const videoUrls = await this.waitForCompletion(taskId);
      console.log('Video generation completed!');
      
      console.log('Starting video download...');
      await this.downloadVideo(videoUrls[0], filename);
      
      return { taskId, videoUrls, filename };
    } catch (error) {
      console.error('Error:', error.message);
      throw error;
    }
  }
}

// Usage example
async function main() {
  const client = new Veo31Client('YOUR_API_KEY');
  
  try {
    const result = await client.generateAndDownload(
      'A cute cat playing in a garden on a sunny day, high quality',
      'cute_cat.mp4',
      { aspectRatio: '16:9' }
    );
    
    console.log('Complete!', result);
  } catch (error) {
    console.error('Generation failed:', error.message);
  }
}

main();

```

--------------------------------

### Get Midjourney Task Details

Source: https://github.com/felores/kie-cli-mcp/blob/main/docs/kie/midjourney_generate.md

Use the get Midjourney task details endpoint to regularly query task status. We recommend querying every 30 seconds.

```APIDOC
## GET /api/v1/mj/record-info

### Description
Retrieve the status and details of an Midjourney generation task.

### Method
GET

### Endpoint
https://api.kie.ai/api/v1/mj/record-info

### Parameters
#### Query Parameters
- **taskId** (string) - Required - Task ID returned from the generation request

#### Request Body
None

### Response
#### Success Response (200)
- **code** (integer) - Response status code. Possible values include 200, 400, 401, 402, 404, 422, 429, 455, 500, 501, 505.

#### Response Example
```json
{
  "code": 200
}
```

#### Error Responses
- **400**: Bad Request - Invalid request parameters
- **401**: Unauthorized - Authentication credentials are missing or invalid
- **402**: Insufficient Credits - Account does not have enough credits to perform the operation
- **404**: Not Found - The requested resource or endpoint does not exist
- **422**: Validation Error - The request parameters failed validation checks
- **429**: Rate Limited - Request limit has been exceeded for this resource
- **455**: Service Unavailable - System is currently undergoing maintenance
- **500**: Server Error - An unexpected error occurred while processing the request
- **501**: Generation Failed - Image generation task failed
```

--------------------------------

### Professional Quality Video Generation Example

Source: https://github.com/felores/kie-cli-mcp/blob/main/docs/INTELLIGENCE.md

Illustrates automatic selection of high-quality video generation parameters for client presentations.

```text
"I need a high quality video for a client presentation"
```

--------------------------------

### Nano Banana 2 API Request Example

Source: https://github.com/felores/kie-cli-mcp/blob/main/docs/kie/google_nano-banana-2.md

Example of a JSON request payload for the Nano Banana 2 API, demonstrating the structure for model selection and input parameters.

```APIDOC
## API Request Example

This example shows the structure of a request to the Nano Banana 2 API.

### Request Body

```json
{
  "model": "nano-banana-2",
  "input": {
    "prompt": "A beautiful sunset over mountains",
    "image_input": [],
    "output_format": "png",
    "aspect_ratio": "16:9",
    "resolution": "1K",
    "google_search": false
  }
}
```
```

--------------------------------

### Inspect PyPi Package Server

Source: https://github.com/felores/kie-cli-mcp/blob/main/docs/mcp/mcp_inspector.md

Start and inspect an MCP server package from PyPi using uvx. Provide the package name and any necessary arguments.

```bash
npx @modelcontextprotocol/inspector uvx <package-name> <args>
# For example
npx @modelcontextprotocol/inspector uvx mcp-server-git --repository ~/code/mcp/servers.git
```

--------------------------------

### Generate Video with KIE CLI and jq

Source: https://github.com/felores/kie-cli-mcp/blob/main/skills/kie-ai/SKILL.md

Example of generating a video using the veo3 tool. It demonstrates extracting the task ID using `jq` for subsequent status polling.

```bash
ID=$(kie-cli veo3_generate_video --prompt "drone shot over a canyon at sunrise" --json | jq -r '.task_id // .response.data.taskId')
kie-cli get_task_status --task_id "$ID" --json
```

--------------------------------

### OpenAPI Specification for Get 1080P Video

Source: https://github.com/felores/kie-cli-mcp/blob/main/docs/kie/google_veo3-text-to-image.md

This OpenAPI specification defines the GET /api/v1/veo/get-1080p-video endpoint. It includes request parameters, authentication details, and response schemas for successful and error cases.

```yaml
paths:
  path: /api/v1/veo/get-1080p-video
  method: get
  servers:
    - url: https://api.kie.ai
      description: API Server
  request:
    security:
      - title: BearerAuth
        parameters:
          query: {}
          header:
            Authorization:
              type: http
              scheme: bearer
              description: >-
                All APIs require authentication via Bearer Token.


                Get API Key: 

                1. Visit [API Key Management Page](https://kie.ai/api-key) to
                get your API Key


                Usage:

                Add to request header:

                Authorization: Bearer YOUR_API_KEY
          cookie: {}
    parameters:
      path: {}
      query:
        taskId:
          schema:
            - type: string
              required: true
              description: Task ID
        index:
          schema:
            - type: integer
              required: false
              description: video index
      header: {}
      cookie: {}
    body: {}
  response:
    '200':
      application/json:
        schemaArray:
          - type: object
            properties:
              code:
                allOf:
                  - type: integer
                    enum:
                      - 200
                      - 401
                      - 404
                      - 422
                      - 429
                      - 451
                      - 455
                      - 500
                    description: >-
                      Response status code


                      - **200**: Success - Request has been processed
                      successfully

                      - **401**: Unauthorized - Authentication credentials are
                      missing or invalid

                      - **404**: Not Found - The requested resource or endpoint
                      does not exist

                      - **422**: Validation Error - The request parameters
                      failed validation checks.

                      record is null.

                      Temporarily supports records within 14 days.

                      record result data is blank.

                      record status is not success.

                      record result data not exist.

                      record result data is empty.

                      - **429**: Rate Limited - Request limit has been exceeded
                      for this resource

                      - **451**: Failed to fetch the image. Kindly verify any
                      access limits set by you or your service provider.

                      - **455**: Service Unavailable - System is currently
                      undergoing maintenance

                      - **500**: Server Error - An unexpected error occurred
                      while processing the request
              msg:
                allOf:
                  - type: string
                    description: Error message when code != 200
                    example: success
              data:
                allOf:
                  - type: object
                    properties:
                      resultUrl:
                        type: string
                        description: 1080P high-definition video download URL
                        example: >-
                          https://tempfile.aiquickdraw.com/p/42f4f8facbb040c0ade87c27cb2d5e58_1749711595.mp4
        examples:
          example:
            value:
              code: 200
              msg: success
              data:
                resultUrl: >-
                  https://tempfile.aiquickdraw.com/p/42f4f8facbb040c0ade87c27cb2d5e58_1749711595.mp4
        description: Request successful
    '500':
      _mintlify/placeholder:
        schemaArray:
          - type: any
            description: Server Error
        examples: {}
        description: Server Error
  deprecated: false
  type: path
components:
  schemas: {}
```

--------------------------------

### HTTP Transport Route Definitions

Source: https://github.com/felores/kie-cli-mcp/blob/main/docs/STREAMABLE_HTTP_PLAN.md

Defines the routes for the HTTP transport, including POST for initialization and request handling, GET for SSE streams, DELETE for session termination, and an unauthenticated GET /health endpoint.

```typescript
POST: if `Mcp-Session-Id` present → reuse stored transport; if absent and
   body is `initialize` → create `new StreamableHTTPServerTransport({ sessionIdGenerator: () => randomUUID(), onsessioninitialized: store, onsessionclosed: evict, enableDnsRebindingProtection: true, allowedHosts: [...] })`, `createKieServer().connect(transport)`, then `handleRequest`.
GET: resume SSE stream for an existing session via `handleRequest`.
DELETE: terminate session, `transport.close()`, evict from map.
```

--------------------------------

### Enable Video and Audio Tools

Source: https://github.com/felores/kie-cli-mcp/blob/main/docs/PRD_TOOL_FILTERING.md

Configure the KIE_AI_TOOL_CATEGORIES environment variable with multiple comma-separated values, such as 'video,audio', to enable specific tool categories for multimedia content creation.

```bash
export KIE_AI_TOOL_CATEGORIES=video,audio
```

--------------------------------

### Text-to-Image API Request Example

Source: https://github.com/felores/kie-cli-mcp/blob/main/docs/kie/seedream_5-lite.md

Example of a JSON payload for generating an image from a text prompt using the Seedream 5.0 Lite text-to-image model. Includes parameters for prompt, aspect ratio, and quality.

```json
{
  "model": "seedream/5-lite-text-to-image",
  "input": {
    "prompt": "A photorealistic portrait",
    "aspect_ratio": "3:4",
    "quality": "basic"
  }
}
```

--------------------------------

### Run MCP Server with Docker

Source: https://github.com/felores/kie-cli-mcp/blob/main/docs/DEPLOY_HTTP.md

Build and run the MCP server as a Docker container. This example demonstrates setting environment variables for the API key, HTTP token, allowed hosts, and volume mounting for data persistence. It also includes the Docker command to run the container in detached mode.

```bash
docker build -f packages/mcp/Dockerfile -t kie-ai-mcp-http .
docker run -d --name kie-mcp -p 3000:3000 \
  -e KIE_AI_API_KEY=sk-...
  -e KIE_MCP_HTTP_TOKEN=$(openssl rand -hex 16) \
  -e MCP_ALLOWED_HOSTS=your-host.example.com \
  -v kie-mcp-data:/data \
  kie-ai-mcp-http
```

--------------------------------

### OpenAPI Specification for Get Aleph Video Details

Source: https://github.com/felores/kie-cli-mcp/blob/main/docs/kie/runway_aleph_video.md

This OpenAPI specification defines the GET /api/v1/aleph/record-info endpoint for retrieving details about Aleph video generation tasks. It includes details on authentication, request parameters, and possible response codes.

```yaml
paths:
  path: /api/v1/aleph/record-info
  method: get
  servers:
    - url: https://api.kie.ai
      description: API Server
  request:
    security:
      - title: BearerAuth
        parameters:
          query: {}
          header:
            Authorization:
              type: http
              scheme: bearer
              description: >-
                All APIs require authentication via Bearer Token.


                Get API Key:

                1. Visit [API Key Management Page](https://kie.ai/api-key) to
                get your API Key


                Usage:

                Add to request header:

                Authorization: Bearer YOUR_API_KEY


                Note:

                - Keep your API Key secure and do not share it with others

                - If you suspect your API Key has been compromised, reset it
                immediately in the management page
          cookie: {}
    parameters:
      path: {}
      query:
        taskId:
          schema:
            - type: string
              required: true
              description: >-
                Unique identifier of the Aleph video generation task. This is
                the taskId returned when creating an Aleph video.
      header: {}
      cookie: {}
    body: {}
  response:
    '200':
      application/json:
        schemaArray:
          - type: object
            properties:
              code:
                allOf:
                  - type: integer
                    enum:
                      - 200
                      - 401
                      - 404
                      - 422
                      - 429
                      - 451
                      - 455
                      - 500
                    description: >-
                      Response status code


                      - **200**: Success - Request has been processed
                      successfully

                      - **401**: Unauthorized - Authentication credentials are
                      missing or invalid

                      - **404**: Not Found - The requested resource or endpoint
                      does not exist

                      - **422**: Validation Error - The request parameters
                      failed validation checks

                      - **429**: Rate Limited - Request limit has been exceeded
                      for this resource

                      - **451**: Unauthorized - Failed to fetch the image. 
                      Kindly verify any access limits set by you or your service
                      provider.

                      - **455**: Service Unavailable - System is currently
                      undergoing maintenance

```

--------------------------------

### veo3_get_1080p_video

Source: https://github.com/felores/kie-cli-mcp/blob/main/docs/TOOLS.md

Get 1080P high-definition version of a Veo3 video.

```APIDOC
## veo3_get_1080p_video

### Description
Get 1080P high-definition version of a Veo3 video (not available for fallback mode videos).

### Parameters
#### Query Parameters
- **task_id** (string) - Required - Veo3 task ID to get 1080p video for
- **index** (integer) - Optional - Video index (optional, for multiple video results)
```

--------------------------------

### Migrating from Low-level Server to High-level McpServer

Source: https://github.com/felores/kie-cli-mcp/blob/main/docs/RESEARCH_FINDINGS.md

Compares the current low-level Server implementation with the recommended high-level McpServer for MCP SDK projects. Shows the syntax for registering tools and managing their state.

```typescript
// Current (low-level):
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
const server = new Server({ name: "...", version: "..." }, { capabilities: {...} });
server.setRequestHandler(ListToolsRequestSchema, async () => {...});

// Recommended (high-level):
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
const server = new McpServer({ name: "...", version: "..." });
const tool = server.registerTool('name', {...}, handler);
tool.disable(); // Built-in filtering!
```

--------------------------------

### Create MCP Server with Tools and Resources

Source: https://github.com/felores/kie-cli-mcp/blob/main/docs/mcp/mcp_typescript_sdk_readme.md

This TypeScript code sets up an MCP server that exposes an addition tool and a dynamic greeting resource. It uses Express for the HTTP transport. Ensure you have installed the necessary dependencies: `npm install @modelcontextprotocol/sdk express zod@3`.

```typescript
import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
import express from 'express';
import { z } from 'zod';

// Create an MCP server
const server = new McpServer({
    name: 'demo-server',
    version: '1.0.0'
});

// Add an addition tool
server.registerTool(
    'add',
    {
        title: 'Addition Tool',
        description: 'Add two numbers',
        inputSchema: { a: z.number(), b: z.number() },
        outputSchema: { result: z.number() }
    },
    async ({ a, b }) => {
        const output = { result: a + b };
        return {
            content: [{ type: 'text', text: JSON.stringify(output) }],
            structuredContent: output
        };
    }
);

// Add a dynamic greeting resource
server.registerResource(
    'greeting',
    new ResourceTemplate('greeting://{name}', { list: undefined }),
    {
        title: 'Greeting Resource', // Display name for UI
        description: 'Dynamic greeting generator'
    },
    async (uri, { name }) => ({
        contents: [
            {
                uri: uri.href,
                text: `Hello, ${name}வுகளை`
            }
        ]
    })
);

// Set up Express and HTTP transport
const app = express();
app.use(express.json());

app.post('/mcp', async (req, res) => {
    // Create a new transport for each request to prevent request ID collisions
    const transport = new StreamableHTTPServerTransport({
        sessionIdGenerator: undefined,
        enableJsonResponse: true
    });

    res.on('close', () => {
        transport.close();
    });

    await server.connect(transport);
    await transport.handleRequest(req, res, req.body);
});

const port = parseInt(process.env.PORT || '3000');
app.listen(port, () => {
    console.log(`Demo MCP Server running on http://localhost:${port}/mcp`);
}).on('error', error => {
    console.error('Server error:', error);
    process.exit(1);
});

```

--------------------------------

### Development Mode

Source: https://github.com/felores/kie-cli-mcp/blob/main/CLAUDE.md

Starts the project in development mode with auto-reloading using tsx.

```bash
npm run dev
```

--------------------------------

### Get Task Status

Source: https://github.com/felores/kie-cli-mcp/blob/main/docs/kie/kling_v2-5-turbo-text-to-video-pro.md

Polls the status of a video generation task using its ID.

```APIDOC
## GET https://api.kie.ai/api/v1/jobs/recordInfo

### Description
Retrieves the current status and results of a video generation task.

### Method
GET

### Endpoint
https://api.kie.ai/api/v1/jobs/recordInfo

### Query Parameters
- **taskId** (string) - Required - The ID of the task to query.

### Response
#### Success Response (200)
- **taskId** (string) - The unique identifier for the task.
- **state** (string) - The current state of the task (e.g., 'processing', 'success', 'failed').
- **resultJson** (object) - Contains the generation results if the task state is 'success'.
```

--------------------------------

### Pre-publish Checklist Commands

Source: https://github.com/felores/kie-cli-mcp/blob/main/AGENTS.md

Run these commands to ensure the package is ready for publishing. The build must succeed and there should be no TypeScript errors.

```bash
npm run build

npx tsc --noEmit

npm publish --dry-run
```

--------------------------------

### Systemd Service Deployment

Source: https://github.com/felores/kie-cli-mcp/blob/main/docs/ADMIN.md

Configure the Kie.ai MCP server as a systemd service. This example shows how to set environment variables and specify the execution command for the service.

```ini
[Unit]
Description=Kie.ai MCP Server
After=network.target

[Service]
Type=simple
User=mcp-service
Environment=KIE_AI_API_KEY=your-api-key
Environment=KIE_AI_CALLBACK_URL_FALLBACK=https://proxy.company.com/webhook
Environment=KIE_AI_DB_PATH=/var/lib/kie-ai/tasks.db
ExecStart=npx -y @felores/kie-ai-mcp-server
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target
```