@z_ai/mcp-server 0.1.0 → 0.1.1-beta.1

package/build/tools/general-image.js

@@ -0,0 +1,78 @@
+import { z } from 'zod';
+import { FileNotFoundError, ApiError } from '../types/index.js';
+import { CommonSchemas, ToolSchemaBuilder } from '../utils/validation.js';
+import { formatMcpResponse, createSuccessResponse, createErrorResponse, withRetry } from '../core/api-common.js';
+import { BaseImageAnalysisService } from '../core/base-image-service.js';
+import { GENERAL_IMAGE_ANALYSIS_PROMPT } from '../prompts/index.js';
+/**
+ * General Image Analysis service - Fallback for any image analysis
+ */
+class GeneralImageAnalysisService extends BaseImageAnalysisService {
+    /**
+     * Analyze image with general purpose prompt
+     * @param imageSource Image file path or URL
+     * @param userPrompt User's analysis request
+     * @returns Analysis result
+     */
+    async analyzeImage(imageSource, userPrompt) {
+        console.info('Starting general image analysis', {
+            imageSource,
+            prompt: userPrompt
+        });
+        // Validate prompt
+        this.validatePrompt(userPrompt, 'analyze-image');
+        // Process image
+        const imageContent = await this.processImageSource(imageSource);
+        // Execute analysis
+        return await this.executeVisionAnalysis(GENERAL_IMAGE_ANALYSIS_PROMPT, userPrompt, [imageContent], 'analyze-image');
+    }
+}
+/**
+ * Register General Image Analysis tool with MCP server
+ * @param server MCP server instance
+ */
+export function registerGeneralImageAnalysisTool(server) {
+    const service = new GeneralImageAnalysisService();
+    const retryableAnalyze = withRetry(service.analyzeImage.bind(service), 2, 1000);
+    server.tool('analyze_image', `General-purpose image analysis for scenarios not covered by specialized tools.
+
+Use this tool as a FALLBACK when none of the other specialized tools (ui_to_artifact, extract_text_from_screenshot,
+diagnose_error_screenshot, understand_technical_diagram, analyze_data_visualization, ui_diff_check) fit the user's need.
+
+This tool provides flexible image understanding for any visual content.`, {
+        image_source: z.string().describe('Local file path or remote URL to the image'),
+        prompt: z.string().describe('Detailed description of what you want to analyze, extract, or understand from the image. Be specific about your requirements.')
+    }, async (params) => {
+        try {
+            const validationSchema = new ToolSchemaBuilder()
+                .required('image_source', CommonSchemas.nonEmptyString)
+                .required('prompt', CommonSchemas.nonEmptyString)
+                .build();
+            validationSchema.parse(params);
+            const result = await retryableAnalyze(params.image_source, params.prompt);
+            return formatMcpResponse(createSuccessResponse(result));
+        }
+        catch (error) {
+            console.error('General image analysis 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('General Image Analysis tool registered successfully');
+}

package/build/tools/text-extraction.js

@@ -0,0 +1,87 @@
+import { z } from 'zod';
+import { FileNotFoundError, ApiError } from '../types/index.js';
+import { CommonSchemas, ToolSchemaBuilder } from '../utils/validation.js';
+import { formatMcpResponse, createSuccessResponse, createErrorResponse, withRetry } from '../core/api-common.js';
+import { BaseImageAnalysisService } from '../core/base-image-service.js';
+import { TEXT_EXTRACTION_PROMPT } from '../prompts/index.js';
+/**
+ * Text Extraction service - OCR and text extraction from screenshots
+ */
+class TextExtractionService extends BaseImageAnalysisService {
+    /**
+     * Extract text from screenshot
+     * @param imageSource Image file path or URL
+     * @param userPrompt User's extraction requirements
+     * @param programmingLanguage Optional programming language hint
+     * @returns Extracted text
+     */
+    async extractText(imageSource, userPrompt, programmingLanguage) {
+        console.info('Starting text extraction', {
+            imageSource,
+            prompt: userPrompt,
+            language: programmingLanguage
+        });
+        // Validate prompt
+        this.validatePrompt(userPrompt, 'text-extraction');
+        // Enhance prompt with language hint if provided
+        let enhancedPrompt = userPrompt;
+        if (programmingLanguage && programmingLanguage.trim()) {
+            enhancedPrompt = `${userPrompt}\n\n<language_hint>The code is in ${programmingLanguage}.</language_hint>`;
+        }
+        // Process image
+        const imageContent = await this.processImageSource(imageSource);
+        // Execute analysis
+        return await this.executeVisionAnalysis(TEXT_EXTRACTION_PROMPT, enhancedPrompt, [imageContent], 'text-extraction');
+    }
+}
+/**
+ * Register Text Extraction tool with MCP server
+ * @param server MCP server instance
+ */
+export function registerTextExtractionTool(server) {
+    const service = new TextExtractionService();
+    const retryableExtract = withRetry(service.extractText.bind(service), 2, 1000);
+    server.tool('extract_text_from_screenshot', `Extract and recognize text from screenshots using advanced OCR capabilities.
+
+Use this tool ONLY when the user has a screenshot containing text and wants to extract it.
+This tool specializes in OCR for code, terminal output, documentation, and general text extraction.
+
+Do NOT use for: UI design conversion, error diagnosis, or diagram understanding.`, {
+        image_source: z.string().describe('Local file path or remote URL to the image'),
+        prompt: z.string().describe('Instructions for text extraction. Specify what type of text to extract and any formatting requirements.'),
+        programming_language: z.string().optional().describe('Optional: specify the programming language if the screenshot contains code (e.g., \'python\', \'javascript\', \'java\'). Leave empty for auto-detection or non-code text.')
+    }, async (params) => {
+        try {
+            const validationSchema = new ToolSchemaBuilder()
+                .required('image_source', CommonSchemas.nonEmptyString)
+                .required('prompt', CommonSchemas.nonEmptyString)
+                .optional('programming_language', z.string())
+                .build();
+            validationSchema.parse(params);
+            const result = await retryableExtract(params.image_source, params.prompt, params.programming_language);
+            return formatMcpResponse(createSuccessResponse(result));
+        }
+        catch (error) {
+            console.error('Text extraction 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('Text Extraction tool registered successfully');
+}

package/build/tools/ui-diff.js

@@ -0,0 +1,92 @@
+import { z } from 'zod';
+import { FileNotFoundError, ApiError } from '../types/index.js';
+import { CommonSchemas, ToolSchemaBuilder } from '../utils/validation.js';
+import { formatMcpResponse, createSuccessResponse, createErrorResponse, withRetry } from '../core/api-common.js';
+import { BaseImageAnalysisService } from '../core/base-image-service.js';
+import { UI_DIFF_CHECK_PROMPT } from '../prompts/index.js';
+/**
+ * UI Diff Check service - Compare two UI screenshots
+ */
+class UiDiffCheckService extends BaseImageAnalysisService {
+    /**
+     * Compare two UI screenshots
+     * @param expectedImageSource Expected/reference design image
+     * @param actualImageSource Actual implementation image
+     * @param userPrompt User's comparison requirements
+     * @returns Comparison analysis with differences
+     */
+    async compareUiScreenshots(expectedImageSource, actualImageSource, userPrompt) {
+        console.info('Starting UI diff comparison', {
+            expectedImage: expectedImageSource,
+            actualImage: actualImageSource,
+            prompt: userPrompt
+        });
+        // Validate prompt
+        this.validatePrompt(userPrompt, 'ui-diff-check');
+        // Enhance prompt to clarify which image is which
+        const enhancedPrompt = `<images>
+The first image is the EXPECTED/REFERENCE design (the target).
+The second image is the ACTUAL/CURRENT implementation (what needs to be checked).
+</images>
+
+${userPrompt}`;
+        // Process both images
+        const imageContents = await this.processMultipleImageSources([
+            expectedImageSource,
+            actualImageSource
+        ]);
+        // Execute analysis
+        return await this.executeVisionAnalysis(UI_DIFF_CHECK_PROMPT, enhancedPrompt, imageContents, 'ui-diff-check');
+    }
+}
+/**
+ * Register UI Diff Check tool with MCP server
+ * @param server MCP server instance
+ */
+export function registerUiDiffCheckTool(server) {
+    const service = new UiDiffCheckService();
+    const retryableCompare = withRetry(service.compareUiScreenshots.bind(service), 2, 1000);
+    server.tool('ui_diff_check', `Compare two UI screenshots to identify visual differences and implementation discrepancies.
+
+Use this tool ONLY when the user wants to compare an expected/reference UI with an actual implementation.
+This tool is specialized for UI quality assurance and design-to-implementation verification.
+
+Do NOT use for: general image comparison, error diagnosis, or analyzing single UIs.`, {
+        expected_image_source: z.string().describe('Local file path or remote URL to the image'),
+        actual_image_source: z.string().describe('Local file path or remote URL to the image'),
+        prompt: z.string().describe('Instructions for the comparison. Specify what aspects to focus on or what level of detail is needed.')
+    }, async (params) => {
+        try {
+            const validationSchema = new ToolSchemaBuilder()
+                .required('expected_image_source', CommonSchemas.nonEmptyString)
+                .required('actual_image_source', CommonSchemas.nonEmptyString)
+                .required('prompt', CommonSchemas.nonEmptyString)
+                .build();
+            validationSchema.parse(params);
+            const result = await retryableCompare(params.expected_image_source, params.actual_image_source, params.prompt);
+            return formatMcpResponse(createSuccessResponse(result));
+        }
+        catch (error) {
+            console.error('UI diff check 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('UI Diff Check tool registered successfully');
+}

package/build/tools/ui-to-artifact.js

@@ -0,0 +1,91 @@
+import { z } from 'zod';
+import { FileNotFoundError, ApiError } from '../types/index.js';
+import { CommonSchemas, ToolSchemaBuilder } from '../utils/validation.js';
+import { formatMcpResponse, createSuccessResponse, createErrorResponse, withRetry } from '../core/api-common.js';
+import { BaseImageAnalysisService } from '../core/base-image-service.js';
+import { UI_TO_ARTIFACT_PROMPTS } from '../prompts/index.js';
+/**
+ * UI to Artifact service - Convert UI screenshots to code/prompts/specs/descriptions
+ */
+class UiToArtifactService extends BaseImageAnalysisService {
+    /**
+     * Convert UI screenshot to specified artifact type
+     * @param imageSource Image file path or URL
+     * @param outputType Type of output (code, prompt, spec, description)
+     * @param userPrompt User's specific requirements
+     * @returns Generated artifact
+     */
+    async convertUiToArtifact(imageSource, outputType, userPrompt) {
+        console.info('Starting UI to artifact conversion', {
+            imageSource,
+            outputType,
+            prompt: userPrompt
+        });
+        // Validate output type
+        const normalizedType = outputType.toLowerCase();
+        const systemPrompt = UI_TO_ARTIFACT_PROMPTS[normalizedType];
+        if (!systemPrompt) {
+            throw new Error(`Invalid output_type '${outputType}'. Must be one of: code, prompt, spec, description`);
+        }
+        // Validate prompt
+        this.validatePrompt(userPrompt, 'ui-to-artifact');
+        // Process image
+        const imageContent = await this.processImageSource(imageSource);
+        // Execute analysis
+        return await this.executeVisionAnalysis(systemPrompt, userPrompt, [imageContent], 'ui-to-artifact');
+    }
+}
+/**
+ * Register UI to Artifact tool with MCP server
+ * @param server MCP server instance
+ */
+export function registerUiToArtifactTool(server) {
+    const service = new UiToArtifactService();
+    const retryableConvert = withRetry(service.convertUiToArtifact.bind(service), 2, 1000);
+    server.tool('ui_to_artifact', `Convert UI screenshots into various artifacts: code, prompts, design specifications, or descriptions.
+
+Use this tool ONLY when the user wants to:
+- Generate frontend code from UI design (output_type='code')
+- Create AI prompts for UI generation (output_type='prompt')
+- Extract design specifications (output_type='spec')
+- Get natural language description of the UI (output_type='description')
+
+Do NOT use for: screenshots containing text/code to extract, error messages, diagrams, or data visualizations.`, {
+        image_source: z.string().describe('Local file path or remote URL to the image'),
+        output_type: z.enum(['code', 'prompt', 'spec', 'description']).describe("Type of output to generate. Options: 'code' (generate frontend code), 'prompt' (generate AI prompt for recreating this UI), 'spec' (generate design specification document), 'description' (natural language description of the UI)."),
+        prompt: z.string().describe('Detailed instructions describing what to generate from this UI image. Should clearly state the desired output and any specific requirements.')
+    }, async (params) => {
+        try {
+            const validationSchema = new ToolSchemaBuilder()
+                .required('image_source', CommonSchemas.nonEmptyString)
+                .required('output_type', z.enum(['code', 'prompt', 'spec', 'description']))
+                .required('prompt', CommonSchemas.nonEmptyString)
+                .build();
+            validationSchema.parse(params);
+            const result = await retryableConvert(params.image_source, params.output_type, params.prompt);
+            return formatMcpResponse(createSuccessResponse(result));
+        }
+        catch (error) {
+            console.error('UI to artifact 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('UI to Artifact tool registered successfully');
+}

package/build/tools/video-analysis.js

@@ -78,7 +78,16 @@ export function registerVideoAnalysisTool(server) {
     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', {
+    server.tool('analyze_video', `Analyze video content using advanced AI vision models.
+
+Use this tool when the user wants to:
+- Understand what happens in a video
+- Extract key moments or actions from video
+- Analyze video content, scenes, or sequences
+- Get descriptions of video footage
+- Identify objects, people, or activities in video
+
+Supports both local files and remote URL. Maximum file size: 8MB. Supports MP4, MOV, M4V formats.`, {
         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) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@z_ai/mcp-server",
-  "version": "0.1.0",
+  "version": "0.1.1-beta.1",
   "description": "MCP Server for Z.AI - A Model Context Protocol server that provides AI capabilities",
   "main": "build/index.js",
   "type": "module",

package/build/tools/image-analysis.js

@@ -1,125 +0,0 @@
-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');
-}