@mindstone-engineering/mcp-server-kling 0.1.0

package/dist/auth.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Kling authentication module.
+ *
+ * Manages access key + secret key lifecycle — env vars on startup, runtime
+ * update via configure tool, and JWT generation with caching.
+ *
+ * Kling uses JWT signed with HS256 (access key as issuer, secret key as
+ * signing key). Tokens are valid for 30 minutes and cached until near expiry.
+ */
+/**
+ * Returns the current access key.
+ */
+export declare function getAccessKey(): string;
+/**
+ * Returns the current secret key.
+ */
+export declare function getSecretKey(): string;
+/**
+ * Returns true if both access key and secret key are configured.
+ */
+export declare function isConfigured(): boolean;
+/**
+ * Update the API keys at runtime (e.g. after configure_kling_api_keys).
+ * Clears the JWT cache to force re-generation with new credentials.
+ */
+export declare function setApiKeys(newAccessKey: string, newSecretKey: string): void;
+/**
+ * Generate a JWT token for Kling API authentication.
+ * Tokens are valid for 30 minutes; cached and reused until near expiry (60s buffer).
+ */
+export declare function getJwtToken(): Promise<string>;
+/**
+ * Clear the cached JWT token. Used when credentials are updated.
+ */
+export declare function clearTokenCache(): void;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.js

@@ -0,0 +1,73 @@
+/**
+ * Kling authentication module.
+ *
+ * Manages access key + secret key lifecycle — env vars on startup, runtime
+ * update via configure tool, and JWT generation with caching.
+ *
+ * Kling uses JWT signed with HS256 (access key as issuer, secret key as
+ * signing key). Tokens are valid for 30 minutes and cached until near expiry.
+ */
+import { SignJWT } from 'jose';
+let accessKey = process.env.KLING_ACCESS_KEY || '';
+let secretKey = process.env.KLING_SECRET_KEY || '';
+/** JWT token cache (refreshed when expired) */
+let cachedToken = null;
+/**
+ * Returns the current access key.
+ */
+export function getAccessKey() {
+    return accessKey;
+}
+/**
+ * Returns the current secret key.
+ */
+export function getSecretKey() {
+    return secretKey;
+}
+/**
+ * Returns true if both access key and secret key are configured.
+ */
+export function isConfigured() {
+    return accessKey.length > 0 && secretKey.length > 0;
+}
+/**
+ * Update the API keys at runtime (e.g. after configure_kling_api_keys).
+ * Clears the JWT cache to force re-generation with new credentials.
+ */
+export function setApiKeys(newAccessKey, newSecretKey) {
+    accessKey = newAccessKey;
+    secretKey = newSecretKey;
+    cachedToken = null;
+}
+/**
+ * Generate a JWT token for Kling API authentication.
+ * Tokens are valid for 30 minutes; cached and reused until near expiry (60s buffer).
+ */
+export async function getJwtToken() {
+    if (!accessKey || !secretKey) {
+        throw new Error('KLING_ACCESS_KEY and KLING_SECRET_KEY must be set');
+    }
+    // Return cached token if still valid (with 60s buffer)
+    const now = Math.floor(Date.now() / 1000);
+    if (cachedToken && cachedToken.expiresAt > now + 60) {
+        return cachedToken.jwt;
+    }
+    const secret = new TextEncoder().encode(secretKey);
+    const expiresAt = now + 1800; // 30 minutes
+    const jwt = await new SignJWT({
+        iss: accessKey,
+        exp: expiresAt,
+        nbf: now - 5, // Valid from 5 seconds ago (clock skew buffer)
+    })
+        .setProtectedHeader({ alg: 'HS256', typ: 'JWT' })
+        .sign(secret);
+    cachedToken = { jwt, expiresAt };
+    return jwt;
+}
+/**
+ * Clear the cached JWT token. Used when credentials are updated.
+ */
+export function clearTokenCache() {
+    cachedToken = null;
+}
+//# sourceMappingURL=auth.js.map

package/dist/bridge.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Path to bridge state file, supporting both current and legacy env vars.
+ */
+export declare const BRIDGE_STATE_PATH: string;
+/**
+ * Send a request to the host app bridge.
+ *
+ * The bridge is an HTTP server running inside the host app (e.g. Rebel)
+ * that handles credential management and other cross-process operations.
+ */
+export declare const bridgeRequest: (urlPath: string, body: Record<string, unknown>) => Promise<{
+    success: boolean;
+    warning?: string;
+    error?: string;
+}>;
+//# sourceMappingURL=bridge.d.ts.map

package/dist/bridge.js

@@ -0,0 +1,43 @@
+import * as fs from 'fs';
+import { REQUEST_TIMEOUT_MS } from './types.js';
+/**
+ * Path to bridge state file, supporting both current and legacy env vars.
+ */
+export const BRIDGE_STATE_PATH = process.env.MCP_HOST_BRIDGE_STATE || process.env.MINDSTONE_REBEL_BRIDGE_STATE || '';
+const loadBridgeState = () => {
+    if (!BRIDGE_STATE_PATH)
+        return null;
+    try {
+        const raw = fs.readFileSync(BRIDGE_STATE_PATH, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Send a request to the host app bridge.
+ *
+ * The bridge is an HTTP server running inside the host app (e.g. Rebel)
+ * that handles credential management and other cross-process operations.
+ */
+export const bridgeRequest = async (urlPath, body) => {
+    const bridge = loadBridgeState();
+    if (!bridge) {
+        return { success: false, error: 'Bridge not available' };
+    }
+    const response = await fetch(`http://127.0.0.1:${bridge.port}${urlPath}`, {
+        method: 'POST',
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${bridge.token}`,
+        },
+        body: JSON.stringify(body),
+    });
+    if (response.status === 401 || response.status === 403) {
+        return { success: false, error: `Bridge returned ${response.status}: unauthorized. Check host app authentication.` };
+    }
+    return response.json();
+};
+//# sourceMappingURL=bridge.js.map

package/dist/client.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Kling API HTTP client.
+ *
+ * Centralises JWT Bearer auth injection, error handling, rate-limit
+ * messaging, and timeout handling for all Kling API calls.
+ */
+/**
+ * Make an authenticated request to the Kling API.
+ *
+ * @param path  API path relative to base, e.g. `/videos/text2video`
+ * @param options  Additional fetch options
+ * @returns Parsed response data (unwrapped from Kling's { code, message, data } envelope)
+ */
+export declare function klingFetch<T>(path: string, options?: RequestInit): Promise<T>;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.js

@@ -0,0 +1,126 @@
+/**
+ * Kling API HTTP client.
+ *
+ * Centralises JWT Bearer auth injection, error handling, rate-limit
+ * messaging, and timeout handling for all Kling API calls.
+ */
+import { isConfigured, getJwtToken } from './auth.js';
+import { KlingError, KLING_API_BASE, REQUEST_TIMEOUT_MS, } from './types.js';
+/**
+ * Get user-friendly resolution for common Kling error codes.
+ */
+function getErrorResolution(code, message) {
+    const msg = message?.toLowerCase() || '';
+    // Kling-specific error codes
+    if (code >= 1000 && code <= 1004) {
+        return 'Authentication failed. Check your Kling API credentials in Settings. Get keys from https://app.klingai.com/global/dev/api-key';
+    }
+    if (code === 1102) {
+        return 'Insufficient credits. Purchase more at https://app.klingai.com/global/dev/billing';
+    }
+    if (code === 1201) {
+        return 'Invalid request parameters. Check the prompt, model, and other settings.';
+    }
+    // Fallback to message-based matching
+    if (msg.includes('auth') || msg.includes('token')) {
+        return 'Check your Kling API credentials in Settings. Get keys from https://app.klingai.com/global/dev/api-key';
+    }
+    if (msg.includes('insufficient') ||
+        msg.includes('balance') ||
+        msg.includes('credit') ||
+        msg.includes('not enough')) {
+        return 'Insufficient credits. Purchase more at https://app.klingai.com/global/dev/billing';
+    }
+    if (msg.includes('content') || msg.includes('policy') || msg.includes('moderation')) {
+        return 'Content policy violation. Try a different prompt without sensitive content.';
+    }
+    return 'Please try again. If the issue persists, check the Kling AI status page.';
+}
+/**
+ * Make an authenticated request to the Kling API.
+ *
+ * @param path  API path relative to base, e.g. `/videos/text2video`
+ * @param options  Additional fetch options
+ * @returns Parsed response data (unwrapped from Kling's { code, message, data } envelope)
+ */
+export async function klingFetch(path, options = {}) {
+    if (!isConfigured()) {
+        throw new KlingError('Kling API credentials not configured', 'AUTH_REQUIRED', 'Use configure_kling_api_keys to set your access key and secret key first.');
+    }
+    const jwt = await getJwtToken();
+    const url = `${KLING_API_BASE}${path}`;
+    let response;
+    try {
+        response = await fetch(url, {
+            ...options,
+            signal: options.signal ?? AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${jwt}`,
+                ...options.headers,
+            },
+        });
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === 'TimeoutError') {
+            throw new KlingError('Request to Kling API timed out', 'TIMEOUT', 'The request took too long. Try again or check if the Kling API is available.');
+        }
+        throw error;
+    }
+    // Handle rate limiting
+    if (response.status === 429) {
+        let bodyText;
+        try {
+            bodyText = await response.text();
+        }
+        catch {
+            /* ignore */
+        }
+        let parsed;
+        try {
+            parsed = bodyText ? JSON.parse(bodyText) : undefined;
+        }
+        catch {
+            /* ignore */
+        }
+        if (parsed?.code && parsed.message) {
+            throw new KlingError(parsed.message, `KLING_${parsed.code}`, getErrorResolution(parsed.code, parsed.message));
+        }
+        const retryAfter = response.headers.get('Retry-After');
+        const waitTime = retryAfter ? `${retryAfter} seconds` : '30 seconds';
+        throw new KlingError(`Rate limited by Kling API. Please wait ${waitTime} before retrying.`, 'RATE_LIMITED', `Wait ${waitTime} and try again.`);
+    }
+    if (response.status === 401 || response.status === 403) {
+        throw new KlingError('Authentication failed', 'AUTH_FAILED', 'Your Kling API credentials are invalid or expired. Use configure_kling_api_keys to set new credentials.');
+    }
+    // Handle non-OK responses that may not be JSON
+    if (!response.ok) {
+        let bodyText;
+        try {
+            bodyText = await response.text();
+        }
+        catch {
+            bodyText = '';
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(bodyText);
+        }
+        catch {
+            /* not JSON */
+        }
+        if (parsed?.code !== undefined) {
+            throw new KlingError(parsed.message || `Kling API error (HTTP ${response.status})`, `KLING_${parsed.code}`, getErrorResolution(parsed.code, parsed.message));
+        }
+        throw new KlingError(`Kling API error (HTTP ${response.status})`, `HTTP_${response.status}`, response.status === 404
+            ? 'The API endpoint was not found. The Kling API may have changed.'
+            : 'Please try again. If the issue persists, check your API credentials.');
+    }
+    const data = (await response.json());
+    // Kling API returns code 0 for success
+    if (data.code !== 0) {
+        throw new KlingError(data.message || `Kling API error: ${data.code}`, `KLING_${data.code}`, getErrorResolution(data.code, data.message));
+    }
+    return data.data;
+}
+//# sourceMappingURL=client.js.map

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * Kling AI MCP Server
+ *
+ * Provides AI video generation via Kling AI's API through Model Context Protocol.
+ *
+ * Environment variables:
+ * - KLING_ACCESS_KEY: Kling API access key (required)
+ * - KLING_SECRET_KEY: Kling API secret key (required)
+ * - MCP_HOST_BRIDGE_STATE: Path to host app bridge state file (optional)
+ * - MINDSTONE_REBEL_BRIDGE_STATE: Legacy bridge state path (optional)
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+/**
+ * Kling AI MCP Server
+ *
+ * Provides AI video generation via Kling AI's API through Model Context Protocol.
+ *
+ * Environment variables:
+ * - KLING_ACCESS_KEY: Kling API access key (required)
+ * - KLING_SECRET_KEY: Kling API secret key (required)
+ * - MCP_HOST_BRIDGE_STATE: Path to host app bridge state file (optional)
+ * - MINDSTONE_REBEL_BRIDGE_STATE: Legacy bridge state path (optional)
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from './server.js';
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('Kling MCP server running on stdio');
+}
+main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/server.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function createServer(): McpServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.js

@@ -0,0 +1,12 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { registerConfigureTools, registerVideoTools } from './tools/index.js';
+export function createServer() {
+    const server = new McpServer({
+        name: 'kling-mcp-server',
+        version: '0.1.0',
+    });
+    registerConfigureTools(server);
+    registerVideoTools(server);
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/tools/configure.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerConfigureTools(server: McpServer): void;
+//# sourceMappingURL=configure.d.ts.map

package/dist/tools/configure.js

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+import { setApiKeys } from '../auth.js';
+import { bridgeRequest, BRIDGE_STATE_PATH } from '../bridge.js';
+import { KlingError } from '../types.js';
+import { withErrorHandling } from '../utils.js';
+export function registerConfigureTools(server) {
+    server.registerTool('configure_kling_api_keys', {
+        description: 'Save Kling API credentials. Call this when the user provides their API keys.\n\n' +
+            'WHEN TO USE:\n' +
+            '- User says "here are my Kling keys" or provides access_key/secret_key\n' +
+            '- You get an AUTH_REQUIRED error from other Kling tools\n' +
+            '- User wants to update/change their Kling credentials\n\n' +
+            'WHERE TO GET KEYS:\n' +
+            'Direct user to: https://app.klingai.com/global/dev/api-key\n' +
+            '1. Sign in to Kling AI\n' +
+            '2. Go to API Keys section\n' +
+            '3. Create new API key\n' +
+            '4. Copy BOTH the Access Key and Secret Key\n\n' +
+            'IMPORTANT: Both keys are required. The Access Key identifies the account, the Secret Key signs requests.',
+        inputSchema: z.object({
+            access_key: z.string().min(1).describe('Kling API Access Key (identifies the account)'),
+            secret_key: z.string().min(1).describe('Kling API Secret Key (signs API requests)'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, withErrorHandling(async (args) => {
+        const trimmedAccessKey = args.access_key.trim();
+        const trimmedSecretKey = args.secret_key.trim();
+        // If bridge is available, persist via bridge
+        if (BRIDGE_STATE_PATH) {
+            try {
+                const result = await bridgeRequest('/bundled/kling/configure', {
+                    accessKey: trimmedAccessKey,
+                    secretKey: trimmedSecretKey,
+                });
+                if (result.success) {
+                    setApiKeys(trimmedAccessKey, trimmedSecretKey);
+                    const message = result.warning
+                        ? `Kling API keys configured successfully. Note: ${result.warning}`
+                        : 'Kling API keys configured successfully! You can now use generate_kling_video to create AI videos.';
+                    return JSON.stringify({ ok: true, message });
+                }
+                // Bridge returned failure — surface as error, do NOT fall through
+                throw new KlingError(result.error || 'Bridge configuration failed', 'BRIDGE_ERROR', 'The host app bridge rejected the configuration request. Check the host app logs.');
+            }
+            catch (error) {
+                if (error instanceof KlingError)
+                    throw error;
+                // Bridge request failed (network, timeout, etc.) — surface as error
+                throw new KlingError(`Bridge request failed: ${error instanceof Error ? error.message : String(error)}`, 'BRIDGE_ERROR', 'Could not reach the host app bridge. Ensure the host app is running.');
+            }
+        }
+        // No bridge configured — configure in-memory only
+        setApiKeys(trimmedAccessKey, trimmedSecretKey);
+        return JSON.stringify({
+            ok: true,
+            message: 'Kling API keys configured successfully! You can now use generate_kling_video to create AI videos.',
+        });
+    }));
+}
+//# sourceMappingURL=configure.js.map

package/dist/tools/index.d.ts

@@ -0,0 +1,3 @@
+export { registerConfigureTools } from './configure.js';
+export { registerVideoTools } from './video.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/index.js

@@ -0,0 +1,3 @@
+export { registerConfigureTools } from './configure.js';
+export { registerVideoTools } from './video.js';
+//# sourceMappingURL=index.js.map

package/dist/tools/video.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerVideoTools(server: McpServer): void;
+//# sourceMappingURL=video.d.ts.map

package/dist/tools/video.js

@@ -0,0 +1,215 @@
+import { z } from 'zod';
+import { klingFetch } from '../client.js';
+import { withErrorHandling } from '../utils.js';
+const MODEL_ENUM = [
+    'kling-v2-6',
+    'kling-v2-5-turbo',
+    'kling-v2-master',
+    'kling-v2-1-master',
+    'kling-v1-6',
+    'kling-v1',
+];
+export function registerVideoTools(server) {
+    // ─── generate_kling_video ──────────────────────────────────────
+    server.registerTool('generate_kling_video', {
+        description: 'Create an AI-generated video from a text description.\n\n' +
+            'WORKFLOW:\n' +
+            '1. Call this tool with your prompt → returns task_id immediately\n' +
+            '2. Wait 30 seconds, then call check_kling_task(task_id, task_type="text2video")\n' +
+            '3. Repeat step 2 until status is "succeed" (typically 2-5 minutes total)\n' +
+            '4. When complete, you\'ll get a video URL (valid for 30 days)\n\n' +
+            'MODELS (newest to oldest):\n' +
+            '- kling-v2-6 (default): Latest model with best quality and native audio support\n' +
+            '- kling-v2-5-turbo: Faster generation, still high quality\n' +
+            '- kling-v2-master: High quality model\n' +
+            '- kling-v2-1-master: Previous generation master\n' +
+            '- kling-v1-6: Good balance of speed and quality\n' +
+            '- kling-v1: Original model\n\n' +
+            'COSTS: ~100 credits for 5s standard, ~200 for 5s pro.',
+        inputSchema: z.object({
+            prompt: z
+                .string()
+                .min(1)
+                .describe('Detailed description of the video. Include: subject, action/motion, camera angle, style, lighting, mood. Max 2500 chars.'),
+            negative_prompt: z
+                .string()
+                .optional()
+                .describe('Things to avoid: "blurry, distorted faces, text, watermark, low quality"'),
+            model: z.enum(MODEL_ENUM).optional().describe('Model version. Default: kling-v2-6'),
+            aspect_ratio: z
+                .enum(['16:9', '9:16', '1:1'])
+                .optional()
+                .describe('16:9=landscape, 9:16=portrait, 1:1=square. Default: 16:9'),
+            duration: z
+                .enum(['5', '10'])
+                .optional()
+                .describe('Video length in seconds. Default: 5'),
+            mode: z
+                .enum(['std', 'pro'])
+                .optional()
+                .describe('std=standard (faster), pro=professional (higher quality). Default: std'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, withErrorHandling(async (args) => {
+        const model = args.model || 'kling-v2-6';
+        const body = {
+            prompt: args.prompt,
+            model_name: model,
+            aspect_ratio: args.aspect_ratio || '16:9',
+            duration: args.duration || '5',
+            mode: args.mode || 'std',
+        };
+        if (args.negative_prompt) {
+            body.negative_prompt = args.negative_prompt;
+        }
+        const result = await klingFetch('/videos/text2video', {
+            method: 'POST',
+            body: JSON.stringify(body),
+        });
+        return JSON.stringify({
+            ok: true,
+            task_id: result.task_id,
+            task_type: 'text2video',
+            status: 'submitted',
+            message: `Video generation started. Use check_kling_task with task_id "${result.task_id}" and task_type "text2video" to poll for completion (typically 2-5 minutes).`,
+            nextPollSeconds: 30,
+        });
+    }));
+    // ─── generate_kling_image_to_video ─────────────────────────────
+    server.registerTool('generate_kling_image_to_video', {
+        description: 'Animate a still image into a video using AI.\n\n' +
+            'WORKFLOW:\n' +
+            '1. You need a PUBLIC image URL (must start with https://)\n' +
+            '2. Call this tool with the image URL and a motion prompt → returns task_id\n' +
+            '3. Wait 30 seconds, then call check_kling_task(task_id, task_type="image2video")\n' +
+            '4. Repeat step 3 until status is "succeed" (typically 2-5 minutes)\n\n' +
+            'IMAGE REQUIREMENTS:\n' +
+            '- Must be publicly accessible (https:// URL)\n' +
+            '- High resolution works best\n\n' +
+            'IMPORTANT: If you have a local image, you must first upload it to a hosting service to get a public URL.',
+        inputSchema: z.object({
+            image_url: z
+                .string()
+                .url()
+                .describe('Public HTTPS URL of the image to animate.'),
+            prompt: z
+                .string()
+                .min(1)
+                .describe('Describe the desired motion/animation: camera movement, subject movement.'),
+            negative_prompt: z
+                .string()
+                .optional()
+                .describe('Motion to avoid: "jerky movement, face distortion, unnatural motion"'),
+            model: z.enum(MODEL_ENUM).optional().describe('Model version. Default: kling-v2-6'),
+            duration: z.enum(['5', '10']).optional().describe('Video length in seconds. Default: 5'),
+            mode: z
+                .enum(['std', 'pro'])
+                .optional()
+                .describe('std=standard, pro=professional quality. Default: std'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, withErrorHandling(async (args) => {
+        // Validate HTTPS URL
+        if (!args.image_url.startsWith('https://')) {
+            return JSON.stringify({
+                ok: false,
+                error: 'Image URL must use HTTPS',
+                code: 'INVALID_URL',
+                resolution: 'Kling requires publicly accessible HTTPS URLs. Upload your image to a hosting service first.',
+            });
+        }
+        const model = args.model || 'kling-v2-6';
+        const body = {
+            image: args.image_url,
+            prompt: args.prompt,
+            model_name: model,
+            duration: args.duration || '5',
+            mode: args.mode || 'std',
+        };
+        if (args.negative_prompt) {
+            body.negative_prompt = args.negative_prompt;
+        }
+        const result = await klingFetch('/videos/image2video', {
+            method: 'POST',
+            body: JSON.stringify(body),
+        });
+        return JSON.stringify({
+            ok: true,
+            task_id: result.task_id,
+            task_type: 'image2video',
+            status: 'submitted',
+            message: `Image-to-video generation started. Use check_kling_task with task_id "${result.task_id}" and task_type "image2video" to poll for completion.`,
+            nextPollSeconds: 30,
+        });
+    }));
+    // ─── check_kling_task ──────────────────────────────────────────
+    server.registerTool('check_kling_task', {
+        description: 'Check if a Kling video generation task is complete.\n\n' +
+            'WHEN TO CALL:\n' +
+            '- After generate_kling_video or generate_kling_image_to_video returns a task_id\n' +
+            '- Wait ~30 seconds between checks\n' +
+            '- Keep polling until status is "succeed" or "failed"\n\n' +
+            'RESPONSE STATUS VALUES:\n' +
+            '- "submitted" → Task received, generation starting\n' +
+            '- "processing" → Video being generated (wait and poll again)\n' +
+            '- "succeed" → DONE! Response includes video.url\n' +
+            '- "failed" → Error occurred, check the error message\n\n' +
+            'VIDEO URL: Valid for 30 days after generation.',
+        inputSchema: z.object({
+            task_id: z
+                .string()
+                .min(1)
+                .describe('The task_id returned by generate_kling_video or generate_kling_image_to_video'),
+            task_type: z
+                .enum(['text2video', 'image2video'])
+                .optional()
+                .describe('Use "text2video" for generate_kling_video, "image2video" for generate_kling_image_to_video. Default: text2video'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        const taskType = args.task_type || 'text2video';
+        const altType = taskType === 'text2video' ? 'image2video' : 'text2video';
+        let result;
+        try {
+            result = await klingFetch(`/videos/${taskType}/${args.task_id}`);
+        }
+        catch (error) {
+            // If task not found with the given type, try the alternative type
+            if (error instanceof Error &&
+                'code' in error &&
+                (error.code === 'HTTP_404' ||
+                    error.code === 'KLING_1201')) {
+                result = await klingFetch(`/videos/${altType}/${args.task_id}`);
+            }
+            else {
+                throw error;
+            }
+        }
+        const response = {
+            ok: true,
+            task_id: result.task_id,
+            status: result.task_status,
+        };
+        if (result.task_status_msg) {
+            response.message = result.task_status_msg;
+        }
+        if (result.task_status === 'processing') {
+            response.nextPollSeconds = 20;
+            response.hint = 'Still processing. Poll again in 20 seconds.';
+        }
+        else if (result.task_status === 'succeed' && result.task_result?.videos?.length) {
+            const video = result.task_result.videos[0];
+            response.video = {
+                url: video.url,
+                duration: video.duration,
+            };
+            response.hint = 'Video generation complete! URL is valid for 30 days.';
+        }
+        else if (result.task_status === 'failed') {
+            response.ok = false;
+            response.resolution = 'Generation failed. Try a different prompt or check your credits.';
+        }
+        return JSON.stringify(response);
+    }));
+}
+//# sourceMappingURL=video.js.map

package/dist/types.d.ts

@@ -0,0 +1,36 @@
+export declare const REQUEST_TIMEOUT_MS = 30000;
+export declare const KLING_API_BASE = "https://api-singapore.klingai.com/v1";
+export interface BridgeState {
+    port: number;
+    token: string;
+}
+export declare class KlingError extends Error {
+    readonly code: string;
+    readonly resolution: string;
+    constructor(message: string, code: string, resolution: string);
+}
+/**
+ * Kling API response wrapper.
+ * All responses return code 0 for success.
+ */
+export interface KlingApiResponse<T> {
+    code: number;
+    message: string;
+    data: T;
+}
+export interface VideoGenerationResponse {
+    task_id: string;
+}
+export interface TaskStatusResponse {
+    task_id: string;
+    task_status: 'submitted' | 'processing' | 'succeed' | 'failed';
+    task_status_msg?: string;
+    task_result?: {
+        videos?: Array<{
+            url: string;
+            duration: string;
+            aspect_ratio?: string;
+        }>;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,13 @@
+export const REQUEST_TIMEOUT_MS = 30_000;
+export const KLING_API_BASE = 'https://api-singapore.klingai.com/v1';
+export class KlingError extends Error {
+    code;
+    resolution;
+    constructor(message, code, resolution) {
+        super(message);
+        this.code = code;
+        this.resolution = resolution;
+        this.name = 'KlingError';
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/utils.d.ts

@@ -0,0 +1,14 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+type ToolHandler<T> = (args: T, extra: unknown) => Promise<CallToolResult>;
+/**
+ * Wraps a tool handler with standard error handling.
+ *
+ * - On success: returns the string result as a text content block.
+ * - On KlingError: returns a structured JSON error with code and resolution.
+ * - On unknown error: returns a generic error message.
+ *
+ * Secrets are never exposed in error messages.
+ */
+export declare function withErrorHandling<T>(fn: (args: T, extra: unknown) => Promise<string>): ToolHandler<T>;
+export {};
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.js

@@ -0,0 +1,42 @@
+import { KlingError } from './types.js';
+/**
+ * Wraps a tool handler with standard error handling.
+ *
+ * - On success: returns the string result as a text content block.
+ * - On KlingError: returns a structured JSON error with code and resolution.
+ * - On unknown error: returns a generic error message.
+ *
+ * Secrets are never exposed in error messages.
+ */
+export function withErrorHandling(fn) {
+    return async (args, extra) => {
+        try {
+            const result = await fn(args, extra);
+            return { content: [{ type: 'text', text: result }] };
+        }
+        catch (error) {
+            if (error instanceof KlingError) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                ok: false,
+                                error: error.message,
+                                code: error.code,
+                                resolution: error.resolution,
+                            }),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ ok: false, error: errorMessage }) }],
+                isError: true,
+            };
+        }
+    };
+}
+//# sourceMappingURL=utils.js.map

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@mindstone-engineering/mcp-server-kling",
+  "version": "0.1.0",
+  "description": "Kling AI video generation MCP server for Model Context Protocol hosts",
+  "license": "FSL-1.1-MIT",
+  "type": "module",
+  "bin": {
+    "mcp-server-kling": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nspr-io/mcp-servers.git",
+    "directory": "connectors/kling"
+  },
+  "homepage": "https://github.com/nspr-io/mcp-servers/tree/main/connectors/kling",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc && shx chmod +x dist/index.js",
+    "prepare": "npm run build",
+    "watch": "tsc --watch",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "jose": "^5.2.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@mindstone-engineering/mcp-test-harness": "file:../../test-harness",
+    "@types/node": "^22",
+    "@vitest/coverage-v8": "^4.1.3",
+    "msw": "^2.13.2",
+    "shx": "^0.3.4",
+    "typescript": "^5.8.2",
+    "vitest": "^4.1.3"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}