@z_ai/mcp-server 0.0.13 → 0.0.14-beta.0

package/README.md

@@ -1,7 +1,5 @@
 # ZAI MCP Server
 
-[中文文档](https://docs.bigmodel.cn//cn/guide/tools/mcp-server) | [English Document](https://docs.z.ai/guides/tools/mcp-server)
-
 A Model Context Protocol (MCP) server that provides AI capabilities powered by Z.AI.
 
 ## Environment Variables
@@ -9,55 +7,32 @@ A Model Context Protocol (MCP) server that provides AI capabilities powered by Z
 - `Z_AI_MODE` - The platform to use for AI services (default: `ZHIPU`)  ZHIPU or ZAI
 - `Z_AI_API_KEY` - Your API key
  
-For ZAI: Use ZAI platform https://z.ai/model-api , the api base url is `https://api.z.ai/api/paas/v4/`    
-For ZHIPU: Use Zhipu AI platform https://bigmodel.cn , the api base url is `https://open.bigmodel.cn/api/paas/v4/`
+For ZAI: Use ZAI platform https://z.ai/model-api
+
+For ZHIPU: Use Zhipu AI platform https://bigmodel.cn
 
 ## Usage
 
 ### Use this MCP Server in Claude Code
 
-It is recommended to use the version Node.js 22+, Claude Code 1.0.100+.
+It is recommended to use the version Node.js 18+, Claude Code 2.0.14+.
+
+**Note**: You need to configure `Z_AI_MODE` as `ZAI` or `ZHIPU` depending on the platform.
 
 For ZAI Use,
 
 ```shell
-claude mcp add zai-mcp-server --env Z_AI_API_KEY=your_api_key Z_AI_MODE=ZAI -- npx -y @z_ai/mcp-server
+claude mcp add zai-mcp-server --env Z_AI_API_KEY=your_api_key Z_AI_MODE=ZAI -- npx -y "@z_ai/mcp-server"
 ```
 
 For ZHIPU Use,
 
 ```shell
-claude mcp add zai-mcp-server --env Z_AI_API_KEY=your_api_key Z_AI_MODE=ZHIPU -- npx -y @z_ai/mcp-server
+claude mcp add zai-mcp-server --env Z_AI_API_KEY=your_api_key Z_AI_MODE=ZHIPU -- npx -y "@z_ai/mcp-server"
 ```
 
 ### Use this MCP Server in Others MCP Client
 
-**Note**: You need to configure `Z_AI_MODE` as `ZAI` or `ZHIPU` depending on the platform.
-
-```json
-{
-  "mcpServers": {
-    "zai-mcp-server": {
-      "type": "stdio",
-      "command": "npx",
-      "args": [
-        "-y",
-        "@z_ai/mcp-server"
-      ],
-      "env": {
-        "Z_AI_API_KEY": "your_api_key",
-        "Z_AI_MODE": "ZHIPU"
-      }
-    }
-  }
-}
-```
-
-### Run with MCP Inspector
-
-```
-node ./build/index.js
-
-npx @modelcontextprotocol/inspector node ./build/index.js
+For Z.ai Use, refer the [Vision MCP Doc](https://docs.z.ai/devpack/mcp/vision-mcp-server)
 
-```
+For ZhiPU Use, refer the [Vision MCP Doc](https://docs.bigmodel.cn/cn/coding-plan/mcp/vision-mcp-server)

package/README.zh-CN.md

@@ -30,37 +30,9 @@ npm i @z_ai/mcp-server
 ### 在 Claude Code 中使用此 MCP 服务器
 
 ```shell
-claude mcp add zai-mcp-server --env Z_AI_API_KEY=your_api_key  -- npx -y @z_ai/mcp-server
+claude mcp add zai-mcp-server --env Z_AI_API_KEY=your_api_key  -- npx -y "@z_ai/mcp-server"
 ```
 
 ### 在其他客户端中使用此 MCP 服务器
 
-```json
-{
-  "mcpServers": {
-    "zai-mcp-server": {
-      "type": "stdio",
-      "command": "npx",
-      "args": [
-        "-y",
-        "@z_ai/mcp-server"
-      ],
-      "env": {
-        "Z_AI_API_KEY": "your_api_key",
-        "Z_AI_MODE": "ZHIPU"
-      }
-    }
-  }
-}
-```
-
-### 使用 MCP Inspector 运行
-
-```
-pnpm build
-
-node ./build/index.js
-
-npx @modelcontextprotocol/inspector node ./build/index.js
-
-```
+参考文档 [视觉理解 MCP](https://docs.bigmodel.cn/cn/coding-plan/mcp/vision-mcp-server)

package/build/{utils/common.js → core/api-common.js}

@@ -120,5 +120,3 @@ export function withRetry(fn, maxRetries = 3, delay = 1000) {
         throw lastError;
     };
 }
-// Backward compatible exports
-export const createMessage = createMultiModalMessage;

package/build/core/chat-service.js

@@ -12,19 +12,18 @@ export class ChatService {
     /**
      * ZAI chat completions API for vision analysis
      */
-    async visionCompletions(messages, options = {}) {
+    async visionCompletions(messages) {
         const visionConfig = configurationService.getVisionConfig();
-        const modelName = this.environmentService.getModelName('vision');
         const requestBody = {
-            model: modelName,
+            model: visionConfig.model,
             messages,
             thinking: { type: 'enabled' },
             stream: false,
-            temperature: options.temperature ?? visionConfig.temperature,
-            top_p: options.topP ?? visionConfig.topP,
-            ...(options.maxTokens && { max_tokens: options.maxTokens })
+            temperature: visionConfig.temperature,
+            top_p: visionConfig.topP,
+            max_tokens: visionConfig.maxTokens
         };
-        console.info('Request ZAI chat completions API for vision analysis', { model: modelName, messageCount: messages.length });
+        console.info('Request ZAI chat completions API for vision analysis', { model: visionConfig.model, messageCount: messages.length });
         try {
             const response = await this.chatCompletions(visionConfig.url, requestBody);
             const result = response.choices?.[0]?.message?.content;

package/build/core/environment.js

@@ -1,6 +1,3 @@
-import * as fs from 'fs';
-import * as path from 'path';
-import * as dotenv from 'dotenv';
 import { ApiError } from '../types/index.js';
 /**
  * Environment configuration service using singleton pattern
@@ -28,25 +25,14 @@ export class EnvironmentService {
         return this.config;
     }
     /**
-     * Load environment configuration from .env files and process.env
+     * Load environment configuration from process.env
      */
     loadEnvironmentConfig() {
         const envConfig = { ...process.env };
-        const envPaths = [
-            path.join(process.cwd(), '.env'),
-            path.join(path.dirname(import.meta.dirname), '..', '.env'),
-        ];
-        for (const envPath of envPaths) {
-            if (fs.existsSync(envPath)) {
-                const env = dotenv.parse(fs.readFileSync(envPath));
-                Object.assign(envConfig, env);
-                console.debug('Loaded environment file', { path: envPath });
-            }
-        }
         if (!envConfig.Z_AI_BASE_URL) {
             // for z.ai paas is https://api.z.ai/api/paas/v4/
             // for zhipuai is https://open.bigmodel.cn/api/paas/v4/
-            envConfig.Z_AI_BASE_URL = 'https://api.z.ai/api/paas/v4/';
+            envConfig.Z_AI_BASE_URL = 'https://open.bigmodel.cn/api/paas/v4/';
         }
         if (envConfig.PLATFORM_MODE != null) {
             console.info('Running in mode', { mode: envConfig.PLATFORM_MODE });
@@ -64,53 +50,34 @@ export class EnvironmentService {
             envConfig.PLATFORM_MODE = 'ZHIPU';
         }
         if (!envConfig.Z_AI_API_KEY) {
-            throw new ApiError('ZAI_API_KEY environment variable is required');
+            if (envConfig.ZAI_API_KEY) {
+                envConfig.Z_AI_API_KEY = envConfig.ZAI_API_KEY;
+            }
+            else {
+                throw new ApiError('Z_AI_API_KEY environment variable is required');
+            }
         }
         return {
             Z_AI_BASE_URL: envConfig.Z_AI_BASE_URL,
             Z_AI_API_KEY: envConfig.Z_AI_API_KEY,
             Z_AI_VISION_MODEL: envConfig.Z_AI_VISION_MODEL,
-            Z_AI_VIDEO_MODEL: envConfig.Z_AI_VIDEO_MODEL,
-            Z_AI_IMAGE_MODEL: envConfig.Z_AI_IMAGE_MODEL,
+            Z_AI_VISION_MODEL_TEMPERATURE: envConfig.Z_AI_VISION_MODEL_TEMPERATURE,
+            Z_AI_VISION_MODEL_TOP_P: envConfig.Z_AI_VISION_MODEL_TOP_P,
+            Z_AI_VISION_MODEL_MAX_TOKENS: envConfig.Z_AI_VISION_MODEL_MAX_TOKENS,
             Z_AI_TIMEOUT: envConfig.Z_AI_TIMEOUT,
             Z_AI_RETRY_COUNT: envConfig.Z_AI_RETRY_COUNT,
-            Z_AI_TEMPERATURE: envConfig.Z_AI_TEMPERATURE,
-            Z_AI_TOP_P: envConfig.Z_AI_TOP_P,
-            Z_AI_MAX_TOKENS: envConfig.Z_AI_MAX_TOKENS,
             SERVER_NAME: envConfig.SERVER_NAME,
             SERVER_VERSION: envConfig.SERVER_VERSION,
             PLATFORM_MODE: envConfig.PLATFORM_MODE
         };
     }
-    /**
-     * Get model configuration (implements ConfigurationService)
-     */
-    getModelConfig(type) {
-        const modelName = this.getModelName(type === 'image' ? 'vision' : type === 'video' ? 'vision' : 'image');
-        return {
-            name: modelName,
-            version: '1.0.0',
-            capabilities: this.getCapabilitiesForModel(type)
-        };
-    }
-    /**
-     * Get capabilities for model type
-     */
-    getCapabilitiesForModel(type) {
-        const capabilityMap = {
-            image: ['image_analysis', 'multimodal_understanding'],
-            video: ['video_analysis', 'temporal_understanding'],
-            generation: ['image_generation', 'creative_synthesis']
-        };
-        return capabilityMap[type] || [];
-    }
     /**
      * Get server configuration
      */
     getServerConfig() {
         const config = this.getConfig();
         return {
-            name: config.SERVER_NAME || 'zai-mcp',
+            name: config.SERVER_NAME || 'zai-mcp-server',
             version: config.SERVER_VERSION || '0.1.0'
         };
     }
@@ -127,12 +94,13 @@ export class EnvironmentService {
     getVisionConfig() {
         const config = this.getConfig();
         return {
+            model: config.Z_AI_VISION_MODEL || 'glm-4.5v',
             timeout: parseInt(config.Z_AI_TIMEOUT || '300000'),
-            retryCount: parseInt(config.Z_AI_RETRY_COUNT || '2'),
+            retryCount: parseInt(config.Z_AI_RETRY_COUNT || '1'),
             url: config.Z_AI_BASE_URL + 'chat/completions',
-            temperature: parseFloat(config.Z_AI_TEMPERATURE || '0.8'),
-            topP: parseFloat(config.Z_AI_TOP_P || '0.6'),
-            maxTokens: parseInt(config.Z_AI_MAX_TOKENS || '16384')
+            temperature: parseFloat(config.Z_AI_VISION_MODEL_TEMPERATURE || '0.8'),
+            topP: parseFloat(config.Z_AI_VISION_MODEL_TOP_P || '0.6'),
+            maxTokens: parseInt(config.Z_AI_VISION_MODEL_MAX_TOKENS || '16384')
         };
     }
     /**
@@ -141,14 +109,6 @@ export class EnvironmentService {
     getApiKey() {
         return this.getConfig().Z_AI_API_KEY;
     }
-    /**
-     * Get model name for specific type (image, file)
-     */
-    getModelName(type) {
-        const config = this.getConfig();
-        const envVar = `Z_AI_${type.toUpperCase()}_MODEL`;
-        return config[envVar] || `glm-4.5v`; // Default fallback
-    }
 }
 /**
  * Global environment service instance

package/build/index.js

@@ -9,6 +9,7 @@ setupConsoleRedirection();
 // Import tool registration functions
 import { registerImageAnalysisTool } from './tools/image-analysis.js';
 import { registerVideoAnalysisTool } from './tools/video-analysis.js';
+import { McpError } from "./types/index.js";
 /**
  * MCP Server Application class
  */
@@ -145,7 +146,12 @@ async function main() {
         await app.start();
     }
     catch (error) {
-        console.error('Application startup failed:', { error });
+        if (error instanceof McpError) {
+            console.error('Application startup failed:', { message: error.message });
+        }
+        else {
+            console.error('Application startup failed:', { error });
+        }
         process.exit(1);
     }
 }

package/build/tools/image-analysis.js

@@ -1,8 +1,8 @@
 import { z } from 'zod';
 import { FileNotFoundError, ApiError } from '../types/index.js';
 import { ToolExecutionError } from '../core/error-handler.js';
-import { CommonSchemas, ToolSchemaBuilder } from '../core/validation.js';
-import { createMultiModalMessage, createImageContent, formatMcpResponse, createSuccessResponse, createErrorResponse, withRetry } from '../utils/common.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';
 /**
@@ -46,13 +46,7 @@ export class ImageAnalysisService {
             }
             // Create multimodal message
             const messages = createMultiModalMessage([imageContent], request.prompt);
-            // Call API for analysis
-            const analysisOptions = {
-                temperature: request.options?.temperature,
-                topP: request.options?.topP,
-                maxTokens: request.options?.maxTokens
-            };
-            const result = await this.chatService.visionCompletions(messages, analysisOptions);
+            const result = await this.chatService.visionCompletions(messages);
             console.info('Image analysis completed', {
                 imageSource: request.imageSource
             });
@@ -98,12 +92,7 @@ export function registerImageAnalysisTool(server) {
             // Build request object
             const request = {
                 imageSource: params.image_source,
-                prompt: params.prompt,
-                options: {
-                    temperature: params.temperature,
-                    topP: params.top_p,
-                    maxTokens: params.max_tokens
-                }
+                prompt: params.prompt
             };
             // Execute analysis
             const result = await retryableAnalyze(request);

package/build/tools/video-analysis.js

@@ -1,8 +1,8 @@
 import { z } from 'zod';
 import { FileNotFoundError, ApiError } from '../types/index.js';
 import { ToolExecutionError } from '../core/error-handler.js';
-import { CommonSchemas, ToolSchemaBuilder } from '../core/validation.js';
-import { createMultiModalMessage, createVideoContent, formatMcpResponse, createSuccessResponse, createErrorResponse, withRetry } from '../utils/common.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';
 /**
@@ -46,13 +46,7 @@ export class VideoAnalysisService {
             }
             // Create multimodal message
             const messages = createMultiModalMessage([videoContent], request.prompt);
-            // Call API for analysis
-            const analysisOptions = {
-                temperature: request.options?.temperature,
-                topP: request.options?.topP,
-                maxTokens: request.options?.maxTokens
-            };
-            const result = await this.chatService.visionCompletions(messages, analysisOptions);
+            const result = await this.chatService.visionCompletions(messages);
             console.info('Video analysis completed', {
                 videoSource: request.videoSource
             });
@@ -98,12 +92,7 @@ export function registerVideoAnalysisTool(server) {
             // Build request object
             const request = {
                 videoSource: params.video_source,
-                prompt: params.prompt,
-                options: {
-                    temperature: params.temperature,
-                    topP: params.top_p,
-                    maxTokens: params.max_tokens
-                }
+                prompt: params.prompt
             };
             // Execute analysis
             const result = await retryableAnalyze(request);

package/build/utils/logger.js

@@ -1,29 +1,90 @@
 /**
- * Logger utility that redirects console output to stderr
- * This ensures MCP JSON communication on stdout remains clean
+ * 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 {
-    writeToStderr(level, message, ...args) {
+    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 logMessage = args.length > 0
-            ? `[${timestamp}] ${level.toUpperCase()}: ${message} ${JSON.stringify(args)}`
-            : `[${timestamp}] ${level.toUpperCase()}: ${message}`;
+        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.writeToStderr('info', message, ...args);
+        this.write('info', message, ...args);
     }
     error(message, ...args) {
-        this.writeToStderr('error', message, ...args);
+        this.write('error', message, ...args);
     }
     warn(message, ...args) {
-        this.writeToStderr('warn', message, ...args);
+        this.write('warn', message, ...args);
     }
     debug(message, ...args) {
-        this.writeToStderr('debug', message, ...args);
+        this.write('debug', message, ...args);
     }
     log(message, ...args) {
-        this.writeToStderr('info', message, ...args);
+        this.write('info', message, ...args);
     }
 }
 export const logger = new Logger();
@@ -33,6 +94,23 @@ export const logger = new Logger();
  */
 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);

package/build/{core → utils}/validation.js

@@ -161,13 +161,7 @@ export const CommonSchemas = {
     /** 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'),
-    /** API key */
-    apiKey: z.string().min(10, 'API key must be at least 10 characters'),
-    /** Temperature parameter */
-    temperature: z.number().min(0).max(2, 'Temperature must be between 0 and 2'),
-    /** Maximum token count */
-    maxTokens: z.number().int().min(1).max(4096, 'Max tokens must be between 1 and 4096')
+    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
@@ -202,12 +196,3 @@ export class ToolSchemaBuilder {
         return z.object(this.schema);
     }
 }
-/**
- * Global validator instance
- */
-export const validator = RuntimeValidator;
-/**
- * Convenient validation functions
- */
-export const validate = RuntimeValidator.validate.bind(RuntimeValidator);
-export const safeValidate = RuntimeValidator.safeValidate.bind(RuntimeValidator);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@z_ai/mcp-server",
-  "version": "0.0.13",
+  "version": "0.0.14-beta.0",
   "description": "MCP Server for Z.AI - A Model Context Protocol server that provides AI capabilities",
   "main": "build/index.js",
   "type": "module",
@@ -14,15 +14,20 @@
   "scripts": {
     "build": "tsc && chmod 755 build/index.js",
     "start": "node build/index.js",
-    "dev": "ts-node src/index.ts",
-    "prepublishOnly": "npm run build",
-    "prepare": "npm run build"
+    "prepare": "npm run build",
+    "prerelease": "npm version prerelease --preid=beta",
+    "publish-beta": "npm publish --tag beta",
+    "publish": "npm publish"
   },
   "keywords": [
     "zai",
-    "mcp"
+    "mcp",
+    "vision"
   ],
   "author": "Z.AI",
+  "contributors": [
+    "Chao Gong (https://github.com/tomsun28)"
+  ],
   "license": "Apache-2.0",
   "files": [
     "build",
@@ -30,15 +35,14 @@
     "README.md"
   ],
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=18.0.0"
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
     "zod": "^3.23.8",
-    "@modelcontextprotocol/sdk": "1.17.5",
-    "dotenv": "17.2.2"
+    "@modelcontextprotocol/sdk": "1.17.5"
   },
   "devDependencies": {
     "@types/node": "24.3.1",