Image Converter MCP Server

Instructions

Implementation Reference

• src/converter.ts:222-290 (handler)

  The core handler function for batch converting images. It processes either file paths or input file data (buffers/base64), calls single convertImage for each, and returns array of results with success/error info.

  async batchConvertImages(options: BatchConvertOptions): Promise<BatchConvertResult[]> {
    const { input_paths, input_files, output_format, quality, width, height, maintain_aspect_ratio, output_directory } = options;
    const results: BatchConvertResult[] = [];
  
    // 处理文件路径方式
    if (input_paths && input_paths.length > 0) {
      for (const inputPath of input_paths) {
        try {
          const outputPath = output_directory 
            ? path.join(output_directory, this.generateOutputFilename(inputPath, output_format))
            : this.generateOutputPath(inputPath, output_format);
  
          await this.convertImage({
            input_path: inputPath,
            output_format,
            quality,
            width,
            height,
            maintain_aspect_ratio,
            output_path: outputPath
          });
  
          results.push({
            success: true,
            output_path: outputPath
          });
        } catch (error) {
          results.push({
            success: false,
            error: error instanceof Error ? error.message : String(error)
          });
        }
      }
    }
  
    // 处理上传文件方式
    if (input_files && input_files.length > 0) {
      for (const inputFile of input_files) {
        try {
          const outputPath = output_directory 
            ? path.join(output_directory, this.generateOutputFilename(inputFile.filename, output_format))
            : this.generateOutputPath(inputFile.filename, output_format);
  
          await this.convertImage({
            input_data: inputFile.data,
            input_filename: inputFile.filename,
            output_format,
            quality,
            width,
            height,
            maintain_aspect_ratio,
            output_path: outputPath
          });
  
          results.push({
            success: true,
            output_path: outputPath
          });
        } catch (error) {
          results.push({
            success: false,
            error: error instanceof Error ? error.message : String(error)
          });
        }
      }
    }
  
    return results;
  }

• src/converter.ts:18-46 (schema)

  TypeScript interfaces defining the input (BatchConvertOptions) and output (BatchConvertResult) types for the batch_convert_images tool.

  export interface BatchConvertOptions {
    input_paths?: string[];
    input_files?: Array<{
      data: Buffer | string;
      filename: string;
    }>; // 支持上传的文件数据
    output_format: string;
    quality?: number;
    width?: number;
    height?: number;
    maintain_aspect_ratio?: boolean;
    output_directory?: string;
  }
  
  export interface ConvertResult {
    output_path: string;
    file_size: number;
    dimensions: {
      width: number;
      height: number;
    };
    format: string;
  }
  
  export interface BatchConvertResult {
    success: boolean;
    output_path?: string;
    error?: string;
  }

• src/index.ts:111-172 (registration)

  Tool registration in the MCP server's listTools handler, defining the name, description, and JSON input schema.

  {
    name: 'batch_convert_images',
    description: '批量转换多个图片文件',
    inputSchema: {
      type: 'object',
      properties: {
        input_paths: {
          type: 'array',
          items: { type: 'string' },
          description: '源图片文件路径数组（与input_files二选一）'
        },
        input_files: {
          type: 'array',
          items: {
            type: 'object',
            properties: {
              data: {
                type: 'string',
                description: '文件数据（Buffer或base64字符串）'
              },
              filename: {
                type: 'string',
                description: '文件名'
              }
            },
            required: ['data', 'filename']
          },
          description: '上传的文件数据数组（与input_paths二选一）'
        },
        output_format: {
          type: 'string',
          description: '目标格式'
        },
        quality: {
          type: 'number',
          minimum: 1,
          maximum: 100,
          description: '压缩质量'
        },
        width: {
          type: 'number',
          minimum: 1,
          description: '目标宽度'
        },
        height: {
          type: 'number',
          minimum: 1,
          description: '目标高度'
        },
        maintain_aspect_ratio: {
          type: 'boolean',
          default: true,
          description: '保持宽高比'
        },
        output_directory: {
          type: 'string',
          description: '输出目录'
        }
      },
      required: ['output_format']
    }
  },

• src/index.ts:25-37 (schema)

  Zod schema for validating batch_convert_images input arguments before calling the handler.

  const BatchConvertArgsSchema = z.object({
    input_paths: z.array(z.string()).optional().describe('源图片文件路径数组'),
    input_files: z.array(z.object({
      data: z.string().describe('文件数据（Buffer或base64字符串）'),
      filename: z.string().describe('文件名')
    })).optional().describe('上传的文件数据数组'),
    output_format: z.string().describe('目标格式'),
    quality: z.number().min(1).max(100).optional().describe('压缩质量'),
    width: z.number().positive().optional().describe('目标宽度'),
    height: z.number().positive().optional().describe('目标高度'),
    maintain_aspect_ratio: z.boolean().default(true).describe('保持宽高比'),
    output_directory: z.string().optional().describe('输出目录（可选）')
  });

• src/index.ts:221-262 (helper)

  MCP tool call dispatcher case that validates args with Zod, invokes the converter handler, formats results into text response.

  case 'batch_convert_images': {
    const validatedArgs = BatchConvertArgsSchema.parse(args);
    const results = await this.converter.batchConvertImages(validatedArgs);
    const successCount = results.filter(r => r.success).length;
    const failureCount = results.length - successCount;
    
    let resultText = `批量转换完成！\n成功：${successCount} 个文件\n失败：${failureCount} 个文件\n\n`;
    
    // 确定输入源的总数
    const totalInputs = (validatedArgs.input_paths?.length || 0) + (validatedArgs.input_files?.length || 0);
    
    results.forEach((result, index) => {
      let inputName = `文件${index + 1}`;
      
      // 优先从input_paths获取名称
      if (validatedArgs.input_paths && index < validatedArgs.input_paths.length) {
        inputName = validatedArgs.input_paths[index];
      } 
      // 然后从input_files获取名称
      else if (validatedArgs.input_files) {
        const fileIndex = index - (validatedArgs.input_paths?.length || 0);
        if (fileIndex >= 0 && fileIndex < validatedArgs.input_files.length) {
          inputName = validatedArgs.input_files[fileIndex].filename;
        }
      }
      
      if (result.success) {
        resultText += `✓ ${inputName} -> ${result.output_path}\n`;
      } else {
        resultText += `✗ ${inputName}: ${result.error}\n`;
      }
    });
  
    return {
      content: [
        {
          type: 'text',
          text: resultText
        }
      ]
    };
  }