luma-mcp 1.0.0 → 1.0.2

package/mcp-server/build/tools/image-analysis.js

@@ -0,0 +1,125 @@
+import { z } from 'zod';
+import { FileNotFoundError, ApiError } from '../types/index.js';
+import { ToolExecutionError } from '../core/error-handler.js';
+import { CommonSchemas, ToolSchemaBuilder } from '../utils/validation.js';
+import { createMultiModalMessage, createImageContent, formatMcpResponse, createSuccessResponse, createErrorResponse, withRetry } from '../core/api-common.js';
+import { fileService } from '../core/file-service.js';
+import { chatService } from '../core/chat-service.js';
+/**
+ * Image analysis service class
+ */
+export class ImageAnalysisService {
+    chatService = chatService;
+    fileService = fileService;
+    MAX_IMAGE_SIZE_MB = 5;
+    /**
+     * Execute image analysis
+     * @param request Image analysis request
+     * @returns Analysis result
+     */
+    async analyzeImage(request) {
+        console.info('Starting image analysis', {
+            imageSource: request.imageSource,
+            prompt: request.prompt
+        });
+        try {
+            // Validate image source (file or URL) and size
+            await this.fileService.validateImageSource(request.imageSource, this.MAX_IMAGE_SIZE_MB);
+            // Validate prompt
+            if (!request.prompt || request.prompt.trim().length === 0) {
+                throw new ToolExecutionError('Prompt is required for image analysis', 'image-analysis', 'VALIDATION_ERROR', {
+                    toolName: 'image-analysis',
+                    operation: 'analyzeImage',
+                    metadata: { imageSource: request.imageSource }
+                });
+            }
+            // Handle image source (URL or local file)
+            let imageContent;
+            if (this.fileService.isUrl(request.imageSource)) {
+                // For URLs, pass directly without base64 encoding
+                imageContent = createImageContent(request.imageSource);
+            }
+            else {
+                // For local files, encode to base64
+                const imageData = await this.fileService.encodeImageToBase64(request.imageSource);
+                imageContent = createImageContent(imageData);
+            }
+            // Create multimodal message
+            const messages = createMultiModalMessage([imageContent], request.prompt);
+            const result = await this.chatService.visionCompletions(messages);
+            console.info('Image analysis completed', {
+                imageSource: request.imageSource
+            });
+            return result;
+        }
+        catch (error) {
+            console.error('Image analysis failed', {
+                error: error instanceof Error ? error.message : String(error),
+                imageSource: request.imageSource
+            });
+            if (error instanceof ToolExecutionError) {
+                throw error;
+            }
+            // Wrap unknown errors
+            throw new ToolExecutionError(`Image analysis failed: ${error.message}`, 'image-analysis', 'EXECUTION_ERROR', {
+                toolName: 'image-analysis',
+                operation: 'analyzeImage',
+                metadata: { imageSource: request.imageSource, originalError: error }
+            }, error);
+        }
+    }
+}
+/**
+ * Register image analysis tool with MCP server
+ * @param server MCP server instance
+ */
+export function registerImageAnalysisTool(server) {
+    const analysisService = new ImageAnalysisService();
+    const retryableAnalyze = withRetry(analysisService.analyzeImage.bind(analysisService), 2, // Maximum 2 retries
+    1000 // 1 second delay
+    );
+    server.tool('analyze_image', 'Analyze an image using advanced AI vision models with comprehensive understanding capabilities. Supports both local files and remote URL. Maximum file size: 5MB', {
+        image_source: z.string().describe('Local file path or remote URL to the image (supports PNG, JPG, JPEG)'),
+        prompt: z.string().describe('Detailed text prompt. If the task is **front-end code replication**, the prompt you provide must be: "Describe in detail the layout structure, color style, main components, and interactive elements of the website in this image to facilitate subsequent code generation by the model." + your additional requirements. \ For **other tasks**, the prompt you provide must clearly describe what to analyze, extract, or understand from the image.')
+    }, async (params) => {
+        try {
+            // Validate parameters
+            const validationSchema = new ToolSchemaBuilder()
+                .required('image_source', CommonSchemas.nonEmptyString)
+                .required('prompt', CommonSchemas.nonEmptyString)
+                .build();
+            validationSchema.parse(params);
+            // Build request object
+            const request = {
+                imageSource: params.image_source,
+                prompt: params.prompt
+            };
+            // Execute analysis
+            const result = await retryableAnalyze(request);
+            const response = createSuccessResponse(result);
+            return formatMcpResponse(response);
+        }
+        catch (error) {
+            console.error('Tool execution failed', {
+                error: error instanceof Error ? error.message : String(error),
+                params
+            });
+            let errorResponse;
+            if (error instanceof z.ZodError) {
+                const validationErrors = error.issues.map((e) => `${e.path.join('.')}: ${e.message}`).join(', ');
+                errorResponse = createErrorResponse(`Validation failed: ${validationErrors}`);
+            }
+            else if (error instanceof FileNotFoundError) {
+                errorResponse = createErrorResponse(`Image file not found: ${error.message}`);
+            }
+            else if (error instanceof ApiError) {
+                errorResponse = createErrorResponse(`API error: ${error.message}`);
+            }
+            else {
+                errorResponse = createErrorResponse(`Unexpected error: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            return formatMcpResponse(errorResponse);
+        }
+    });
+    console.info('Image analysis tool registered successfully');
+}

package/mcp-server/build/tools/video-analysis.js

@@ -0,0 +1,125 @@
+import { z } from 'zod';
+import { FileNotFoundError, ApiError } from '../types/index.js';
+import { ToolExecutionError } from '../core/error-handler.js';
+import { CommonSchemas, ToolSchemaBuilder } from '../utils/validation.js';
+import { createMultiModalMessage, createVideoContent, formatMcpResponse, createSuccessResponse, createErrorResponse, withRetry } from '../core/api-common.js';
+import { fileService } from '../core/file-service.js';
+import { chatService } from '../core/chat-service.js';
+/**
+ * Video analysis service class
+ */
+export class VideoAnalysisService {
+    chatService = chatService;
+    fileService = fileService;
+    MAX_VIDEO_SIZE_MB = 8;
+    /**
+     * Execute video analysis
+     * @param request Video analysis request
+     * @returns Analysis result
+     */
+    async analyzeVideo(request) {
+        console.info('Starting video analysis', {
+            videoSource: request.videoSource,
+            prompt: request.prompt
+        });
+        try {
+            // Validate video source (file or URL) and size
+            await this.fileService.validateVideoSource(request.videoSource, this.MAX_VIDEO_SIZE_MB);
+            // Validate prompt
+            if (!request.prompt || request.prompt.trim().length === 0) {
+                throw new ToolExecutionError('Prompt is required for video analysis', 'video-analysis', 'VALIDATION_ERROR', {
+                    toolName: 'video-analysis',
+                    operation: 'analyzeVideo',
+                    metadata: { videoSource: request.videoSource }
+                });
+            }
+            // Handle video source (URL or local file)
+            let videoContent;
+            if (this.fileService.isUrl(request.videoSource)) {
+                // For URLs, pass directly without base64 encoding
+                videoContent = createVideoContent(request.videoSource);
+            }
+            else {
+                // For local files, encode to base64
+                const videoData = await this.fileService.encodeVideoToBase64(request.videoSource);
+                videoContent = createVideoContent(videoData);
+            }
+            // Create multimodal message
+            const messages = createMultiModalMessage([videoContent], request.prompt);
+            const result = await this.chatService.visionCompletions(messages);
+            console.info('Video analysis completed', {
+                videoSource: request.videoSource
+            });
+            return result;
+        }
+        catch (error) {
+            console.error('Video analysis failed', {
+                error: error instanceof Error ? error.message : String(error),
+                videoSource: request.videoSource
+            });
+            if (error instanceof ToolExecutionError) {
+                throw error;
+            }
+            // Wrap unknown errors
+            throw new ToolExecutionError(`Video analysis failed: ${error.message}`, 'video-analysis', 'EXECUTION_ERROR', {
+                toolName: 'video-analysis',
+                operation: 'analyzeVideo',
+                metadata: { videoSource: request.videoSource, originalError: error }
+            }, error);
+        }
+    }
+}
+/**
+ * Register video analysis tool with MCP server
+ * @param server MCP server instance
+ */
+export function registerVideoAnalysisTool(server) {
+    const analysisService = new VideoAnalysisService();
+    const retryableAnalyze = withRetry(analysisService.analyzeVideo.bind(analysisService), 2, // Maximum 2 retries
+    1000 // 1 second delay
+    );
+    server.tool('analyze_video', 'Analyze a video using advanced AI vision models with comprehensive understanding capabilities. Supports both local files and remote URL. Maximum local file size: 8MB', {
+        video_source: z.string().describe('Local file path or remote URL to the video (supports MP4, MOV, M4V)'),
+        prompt: z.string().describe('Detailed text prompt describing what to analyze, extract, or understand from the video')
+    }, async (params) => {
+        try {
+            // Validate parameters
+            const validationSchema = new ToolSchemaBuilder()
+                .required('video_source', CommonSchemas.nonEmptyString)
+                .required('prompt', CommonSchemas.nonEmptyString)
+                .build();
+            validationSchema.parse(params);
+            // Build request object
+            const request = {
+                videoSource: params.video_source,
+                prompt: params.prompt
+            };
+            // Execute analysis
+            const result = await retryableAnalyze(request);
+            const response = createSuccessResponse(result);
+            return formatMcpResponse(response);
+        }
+        catch (error) {
+            console.error('Tool execution failed', {
+                error: error instanceof Error ? error.message : String(error),
+                params
+            });
+            let errorResponse;
+            if (error instanceof z.ZodError) {
+                const validationErrors = error.issues.map((e) => `${e.path.join('.')}: ${e.message}`).join(', ');
+                errorResponse = createErrorResponse(`Validation failed: ${validationErrors}`);
+            }
+            else if (error instanceof FileNotFoundError) {
+                errorResponse = createErrorResponse(`Video file not found: ${error.message}`);
+            }
+            else if (error instanceof ApiError) {
+                errorResponse = createErrorResponse(`API error: ${error.message}`);
+            }
+            else {
+                errorResponse = createErrorResponse(`Unexpected error: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            return formatMcpResponse(errorResponse);
+        }
+    });
+    console.info('Video analysis tool registered successfully');
+}

package/mcp-server/build/types/index.js

@@ -0,0 +1,35 @@
+// Error types
+export class McpError extends Error {
+    code;
+    context;
+    constructor(message, code, context) {
+        super(message);
+        this.code = code;
+        this.context = context;
+        this.name = 'McpError';
+    }
+}
+export class ValidationError extends McpError {
+    field;
+    constructor(message, context, field) {
+        super(message, 'VALIDATION_ERROR', context);
+        this.field = field;
+        this.name = 'ValidationError';
+    }
+}
+export class ApiError extends McpError {
+    statusCode;
+    details;
+    constructor(message, context, statusCode, details) {
+        super(message, 'API_ERROR', context);
+        this.statusCode = statusCode;
+        this.details = details;
+        this.name = 'ApiError';
+    }
+}
+export class FileNotFoundError extends McpError {
+    constructor(filePath) {
+        super(`File not found: ${filePath}`, 'FILE_NOT_FOUND', { filePath });
+        this.name = 'FileNotFoundError';
+    }
+}

package/mcp-server/build/types/validation-types.js

@@ -0,0 +1 @@
+export {};

package/mcp-server/build/utils/logger.js

@@ -0,0 +1,120 @@
+/**
+ * Logger utility that writes to stderr and a log file.
+ * Stderr keeps MCP JSON on stdout clean; file provides persistent logs.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+class Logger {
+    logStream;
+    logFilePath;
+    constructor(logFilePath) {
+        if (logFilePath) {
+            this.setLogFile(logFilePath);
+        }
+    }
+    setLogFile(logFilePath) {
+        try {
+            this.logFilePath = logFilePath;
+            const dir = path.dirname(logFilePath);
+            fs.mkdirSync(dir, { recursive: true });
+            if (this.logStream) {
+                this.logStream.end();
+            }
+            this.logStream = fs.createWriteStream(logFilePath, { flags: 'a' });
+        }
+        catch (err) {
+            const timestamp = new Date().toISOString();
+            const msg = `[${timestamp}] ERROR: Failed to initialize log file '${logFilePath}': ${String(err)}`;
+            process.stderr.write(msg + '\n');
+        }
+    }
+    safeStringify(obj) {
+        // Serialize Error objects so that message/stack and custom fields are visible
+        const replacer = (_key, value) => {
+            if (value instanceof Error) {
+                const base = {
+                    name: value.name,
+                    message: value.message,
+                    stack: value.stack
+                };
+                // Include enumerable own properties (e.g., code, statusCode, details, context)
+                for (const k of Object.keys(value)) {
+                    if (!(k in base)) {
+                        base[k] = value[k];
+                    }
+                }
+                return base;
+            }
+            return value;
+        };
+        try {
+            return JSON.stringify(obj, replacer);
+        }
+        catch {
+            try {
+                return String(obj);
+            }
+            catch {
+                return '[Unserializable]';
+            }
+        }
+    }
+    write(level, message, ...args) {
+        const timestamp = new Date().toISOString();
+        const serializedArgs = args.length > 0 ? ` ${this.safeStringify(args)}` : '';
+        const logMessage = `[${timestamp}] ${level.toUpperCase()}: ${message}${serializedArgs}`;
+        // Write to stderr (visible console output without polluting stdout)
+        process.stderr.write(logMessage + '\n');
+        // Write to log file if configured
+        if (this.logStream) {
+            this.logStream.write(logMessage + '\n');
+        }
+    }
+    info(message, ...args) {
+        this.write('info', message, ...args);
+    }
+    error(message, ...args) {
+        this.write('error', message, ...args);
+    }
+    warn(message, ...args) {
+        this.write('warn', message, ...args);
+    }
+    debug(message, ...args) {
+        this.write('debug', message, ...args);
+    }
+    log(message, ...args) {
+        this.write('info', message, ...args);
+    }
+}
+export const logger = new Logger();
+/**
+ * Override global console to redirect to stderr
+ * This prevents console output from interfering with MCP JSON protocol
+ */
+export function setupConsoleRedirection() {
+    const originalConsole = { ...console };
+    // Cross-platform log file path:
+    // - If env ZAI_MCP_LOG_PATH is set, use it
+    // - Otherwise use user home directory: ~/.zai/zai-mcp-YYYY-MM-DD.log (Windows/macOS/Linux)
+    const resolveLogFilePath = () => {
+        const envPath = process.env.ZAI_MCP_LOG_PATH;
+        if (envPath && envPath.trim().length > 0) {
+            return path.resolve(envPath);
+        }
+        const homeDir = os.homedir();
+        const now = new Date();
+        const yyyy = now.getFullYear();
+        const mm = String(now.getMonth() + 1).padStart(2, '0');
+        const dd = String(now.getDate()).padStart(2, '0');
+        const dateStr = `${yyyy}-${mm}-${dd}`;
+        return path.join(homeDir, '.zai', `zai-mcp-${dateStr}.log`);
+    };
+    logger.setLogFile(resolveLogFilePath());
+    console.info = logger.info.bind(logger);
+    console.error = logger.error.bind(logger);
+    console.warn = logger.warn.bind(logger);
+    console.debug = logger.debug.bind(logger);
+    console.log = logger.log.bind(logger);
+    return originalConsole;
+}

package/mcp-server/build/utils/validation.js

@@ -0,0 +1,198 @@
+import { z } from 'zod';
+import { ValidationError } from '../types/index.js';
+/**
+ * Runtime type validator
+ */
+export class RuntimeValidator {
+    /**
+     * Validate data against specified Zod schema
+     */
+    static validate(data, schema, options = {}) {
+        const { throwOnError = true, customMessage, logErrors = true } = options;
+        try {
+            const result = schema.parse(data);
+            return {
+                success: true,
+                data: result
+            };
+        }
+        catch (error) {
+            const validationErrors = this.parseZodError(error);
+            if (logErrors) {
+                console.warn('Validation failed', {
+                    errors: validationErrors,
+                    data: this.sanitizeData(data)
+                });
+            }
+            if (throwOnError) {
+                const message = customMessage || `Validation failed: ${validationErrors.map(e => e.message).join(', ')}`;
+                throw new ValidationError(message, { errors: validationErrors });
+            }
+            return {
+                success: false,
+                error: {
+                    message: validationErrors.map(e => e.message).join(', '),
+                    code: 'VALIDATION_ERROR'
+                }
+            };
+        }
+    }
+    /**
+     * Safe validation, does not throw exceptions
+     */
+    static safeValidate(data, schema) {
+        return this.validate(data, schema, { throwOnError: false });
+    }
+    /**
+     * Parse Zod error to standard validation error format
+     */
+    static parseZodError(error) {
+        return error.issues.map(issue => ({
+            message: issue.message,
+            field: issue.path.join('.'),
+            code: issue.code,
+            expected: this.getExpectedType(issue),
+            received: 'received' in issue ? String(issue.received) : 'unknown'
+        }));
+    }
+    /**
+     * Get expected type description
+     */
+    static getExpectedType(issue) {
+        switch (issue.code) {
+            case 'invalid_type':
+                return issue.expected;
+            case 'too_small':
+                return `minimum ${issue.minimum}`;
+            case 'too_big':
+                return `maximum ${issue.maximum}`;
+            default:
+                return 'valid value';
+        }
+    }
+    /**
+     * Sanitize sensitive data for logging
+     */
+    static sanitizeData(data) {
+        if (typeof data !== 'object' || data === null) {
+            return data;
+        }
+        const sensitiveKeys = ['password', 'token', 'secret', 'key', 'auth'];
+        const sanitized = { ...data };
+        for (const key of Object.keys(sanitized)) {
+            if (sensitiveKeys.some(sensitive => key.toLowerCase().includes(sensitive))) {
+                sanitized[key] = '[REDACTED]';
+            }
+        }
+        return sanitized;
+    }
+}
+/**
+ * Parameter validation decorator
+ */
+export function ValidateParams(schema, options = {}) {
+    return function (target, propertyKey, descriptor) {
+        const originalMethod = descriptor.value;
+        descriptor.value = async function (...args) {
+            // Assume the first parameter is the parameter object to validate
+            const params = args[0];
+            try {
+                const validationResult = RuntimeValidator.validate(params, schema, options);
+                if (!validationResult.success) {
+                    throw new ValidationError('Parameter validation failed', { errors: validationResult.errors });
+                }
+                // Replace original parameters with validated data
+                args[0] = validationResult.data;
+                return await originalMethod.apply(this, args);
+            }
+            catch (error) {
+                console.error(`Parameter validation failed for ${propertyKey}`, {
+                    error: error instanceof Error ? error.message : String(error),
+                    params: RuntimeValidator['sanitizeData'](params)
+                });
+                throw error;
+            }
+        };
+        return descriptor;
+    };
+}
+/**
+ * Return value validation decorator
+ */
+export function ValidateReturn(schema, options = {}) {
+    return function (target, propertyKey, descriptor) {
+        const originalMethod = descriptor.value;
+        descriptor.value = async function (...args) {
+            const result = await originalMethod.apply(this, args);
+            try {
+                const validationResult = RuntimeValidator.validate(result, schema, options);
+                if (!validationResult.success) {
+                    throw new ValidationError('Return value validation failed', { errors: validationResult.errors });
+                }
+                return validationResult.data;
+            }
+            catch (error) {
+                console.error(`Return value validation failed for ${propertyKey}`, {
+                    error: error instanceof Error ? error.message : String(error),
+                    result: RuntimeValidator['sanitizeData'](result)
+                });
+                throw error;
+            }
+        };
+        return descriptor;
+    };
+}
+/**
+ * Common validation schemas
+ */
+export const CommonSchemas = {
+    /** Non-empty string */
+    nonEmptyString: z.string().min(1, 'String cannot be empty'),
+    /** Positive integer */
+    positiveInteger: z.number().int().positive('Must be a positive integer'),
+    /** Non-negative integer */
+    nonNegativeInteger: z.number().int().min(0, 'Must be a non-negative integer'),
+    /** URL format */
+    url: z.string().url('Must be a valid URL'),
+    /** Email format */
+    email: z.string().email('Must be a valid email address'),
+    /** UUID format */
+    uuid: z.string().uuid('Must be a valid UUID'),
+    /** File path */
+    filePath: z.string().min(1).refine((path) => !path.includes('..'), 'File path cannot contain ".."'),
+    /** Tool name */
+    toolName: z.string().regex(/^[a-z][a-z0-9-]*[a-z0-9]$/, 'Tool name must be lowercase, start with letter, and contain only letters, numbers, and hyphens')
+};
+/**
+ * Tool parameter validation schema builder
+ */
+export class ToolSchemaBuilder {
+    schema = {};
+    /**
+     * Add required field
+     */
+    required(name, schema) {
+        this.schema[name] = schema;
+        return this;
+    }
+    /**
+     * Add optional field
+     */
+    optional(name, schema) {
+        this.schema[name] = schema.optional();
+        return this;
+    }
+    /**
+     * Add field with default value
+     */
+    withDefault(name, schema, defaultValue) {
+        this.schema[name] = schema.default(() => defaultValue);
+        return this;
+    }
+    /**
+     * Build final validation schema
+     */
+    build() {
+        return z.object(this.schema);
+    }
+}

package/mcp-server/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@z_ai/mcp-server",
+  "version": "0.1.0",
+  "description": "MCP Server for Z.AI - A Model Context Protocol server that provides AI capabilities",
+  "main": "build/index.js",
+  "type": "module",
+  "bin": {
+    "zai-mcp-server": "./build/index.js"
+  },
+  "homepage": "https://docs.z.ai/",
+  "bugs": {
+    "url": "https://docs.z.ai/"
+  },
+  "scripts": {
+    "build": "tsc && chmod 755 build/index.js",
+    "start": "node build/index.js",
+    "prepare": "npm run build",
+    "prerelease": "npm version prerelease --preid=beta",
+    "publish-beta": "npm publish --tag beta",
+    "publish": "npm publish"
+  },
+  "keywords": [
+    "zai",
+    "mcp",
+    "vision"
+  ],
+  "author": "Z.AI",
+  "contributors": [
+    "Chao Gong (https://github.com/tomsun28)",
+    "Lei Yuan (https://github.com/Web-Life)"
+  ],
+  "license": "Apache-2.0",
+  "files": [
+    "build",
+    "README.zh-CN.md",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "zod": "^3.23.8",
+    "@modelcontextprotocol/sdk": "1.17.5"
+  },
+  "devDependencies": {
+    "@types/node": "24.3.1",
+    "ts-node": "10.9.2",
+    "typescript": "5.9.2"
+  }
+}

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "luma-mcp",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "A vision understanding MCP server powered by GLM-4.5V",
   "type": "module",
   "bin": {
-    "luma-mcp": "./build/index.js"
+    "luma-mcp": "build/index.js"
   },
   "main": "./build/index.js",
   "scripts": {
@@ -25,7 +25,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/JochenYang/luma-mcp.git"
+    "url": "git+https://github.com/JochenYang/luma-mcp.git"
   },
   "bugs": {
     "url": "https://github.com/JochenYang/luma-mcp/issues"