Image Converter MCP Server

Instructions

Implementation Reference

• src/index.ts:60-110 (registration)

  Registration of the 'convert_image' tool in the ListTools handler, defining name, description, and input schema.
  { name: 'convert_image', description: '将图片转换为指定格式', inputSchema: { type: 'object', properties: { input_path: { type: 'string', description: '源图片文件路径（与input_data二选一）' }, input_data: { type: 'string', description: '图片数据（Buffer或base64字符串，与input_path二选一）' }, input_filename: { type: 'string', description: '原始文件名，用于确定格式（使用input_data时建议提供）' }, output_format: { type: 'string', description: '目标格式（png/jpg/jpeg/gif/bmp/tiff/webp/svg/ico等）' }, quality: { type: 'number', minimum: 1, maximum: 100, description: '压缩质量（1-100，仅适用于有损格式）' }, width: { type: 'number', minimum: 1, description: '目标宽度（像素）' }, height: { type: 'number', minimum: 1, description: '目标高度（像素）' }, maintain_aspect_ratio: { type: 'boolean', default: true, description: '保持宽高比' }, output_path: { type: 'string', description: '输出文件路径（可选，默认自动生成）' } }, required: ['output_format'] } },
• src/index.ts:13-23 (schema)

  Zod schema for validating arguments to the convert_image tool.
  const ConvertImageArgsSchema = z.object({ input_path: z.string().optional().describe('源图片文件路径'), input_data: z.string().optional().describe('图片数据（Buffer或base64字符串）'), input_filename: z.string().optional().describe('原始文件名，用于确定格式'), output_format: z.string().describe('目标格式（png/jpg/jpeg/gif/bmp/tiff/webp/svg/ico等）'), quality: z.number().min(1).max(100).optional().describe('压缩质量（1-100，仅适用于有损格式）'), width: z.number().positive().optional().describe('目标宽度（像素）'), height: z.number().positive().optional().describe('目标高度（像素）'), maintain_aspect_ratio: z.boolean().default(true).describe('保持宽高比'), output_path: z.string().optional().describe('输出文件路径（可选，默认自动生成）') });
• src/index.ts:208-219 (handler)

  MCP CallTool request handler case that validates args and delegates to ImageConverter.convertImage.
  case 'convert_image': { const validatedArgs = ConvertImageArgsSchema.parse(args); const result = await this.converter.convertImage(validatedArgs); return { content: [ { type: 'text', text: `图片转换成功！\n输出文件：${result.output_path}\n文件大小：${result.file_size} bytes\n图片尺寸：${result.dimensions.width}x${result.dimensions.height}\n格式：${result.format}` } ] }; }
• src/converter.ts:73-217 (handler)

  Primary handler function implementing the image conversion logic, supporting various input/output formats with resizing and quality options.
  async convertImage(options: ConvertImageOptions): Promise<ConvertResult> { const { input_path, input_data, input_filename, output_format, quality, width, height, maintain_aspect_ratio = true, output_path } = options; let inputBuffer: Buffer; let inputFormat: string; // 处理不同的输入方式 if (input_data) { // 处理上传的文件数据 if (typeof input_data === 'string') { // 处理base64数据 const base64Data = input_data.includes(',') ? input_data.split(',')[1] : input_data; inputBuffer = Buffer.from(base64Data, 'base64'); } else { // 处理Buffer数据 inputBuffer = input_data; } // 从文件名获取格式 if (input_filename) { inputFormat = this.getFileFormat(input_filename); } else { // 尝试从Buffer检测格式 inputFormat = await this.detectFormatFromBuffer(inputBuffer); } } else if (input_path) { // 处理文件路径 try { await fs.access(input_path); inputBuffer = await fs.readFile(input_path); inputFormat = this.getFileFormat(input_path); } catch { throw new Error(`输入文件不存在: ${input_path}`); } } else { throw new Error('必须提供input_path或input_data参数'); } // 验证输出格式 const normalizedFormat = output_format.toLowerCase().replace('.', ''); if (!this.supportedOutputFormats.includes(normalizedFormat)) { throw new Error(`不支持的输出格式: ${output_format}`); } // 生成输出路径 const finalOutputPath = output_path || this.generateOutputPath( input_path || input_filename || `uploaded_image.${inputFormat}`, normalizedFormat ); // 确保输出目录存在 const outputDir = path.dirname(finalOutputPath); await fs.mkdir(outputDir, { recursive: true }); // 验证输入格式是否支持 if (!this.supportedInputFormats.includes(inputFormat)) { throw new Error(`不支持的输入格式: ${inputFormat}`); } // 对于特殊格式的处理说明 if (inputFormat === 'heic' || inputFormat === 'heif') { try { // Sharp 0.32+ 支持HEIC，但需要libvips支持 await sharp(inputBuffer).metadata(); } catch { throw new Error(`HEIC/HEIF格式需要系统支持libvips，请先转换为JPG或PNG格式`); } } else if (inputFormat === 'psd') { throw new Error(`PSD格式暂不支持，请使用Photoshop导出为JPG或PNG格式`); } try { let sharpInstance = sharp(inputBuffer); // 调整尺寸 if (width || height) { const resizeOptions: sharp.ResizeOptions = { fit: maintain_aspect_ratio ? 'inside' : 'fill', withoutEnlargement: false }; if (width && height) { sharpInstance = sharpInstance.resize(width, height, resizeOptions); } else if (width) { sharpInstance = sharpInstance.resize(width, undefined, resizeOptions); } else if (height) { sharpInstance = sharpInstance.resize(undefined, height, resizeOptions); } } // 根据格式设置输出选项 switch (normalizedFormat) { case 'jpg': case 'jpeg': sharpInstance = sharpInstance.jpeg({ quality: quality || 90 }); break; case 'png': sharpInstance = sharpInstance.png({ quality: quality || 90 }); break; case 'webp': sharpInstance = sharpInstance.webp({ quality: quality || 90 }); break; case 'gif': // Sharp不直接支持GIF输出，使用Jimp return await this.convertWithJimp(inputBuffer, finalOutputPath, normalizedFormat, { width, height, quality }); case 'bmp': // 使用Jimp处理BMP return await this.convertWithJimp(inputBuffer, finalOutputPath, normalizedFormat, { width, height, quality }); case 'tiff': sharpInstance = sharpInstance.tiff({ quality: quality || 90 }); break; case 'avif': sharpInstance = sharpInstance.avif({ quality: quality || 90 }); break; case 'ico': // ICO格式需要特殊处理 return await this.convertToIco(inputBuffer, finalOutputPath, { width: width || 32, height: height || 32 }); case 'svg': // SVG格式转换 return await this.convertToSvg(inputBuffer, finalOutputPath, { width, height }); default: throw new Error(`暂不支持转换为格式: ${normalizedFormat}`); } // 执行转换 await sharpInstance.toFile(finalOutputPath); // 获取结果信息 const stats = await fs.stat(finalOutputPath); const metadata = await sharp(finalOutputPath).metadata(); return { output_path: finalOutputPath, file_size: stats.size, dimensions: { width: metadata.width || 0, height: metadata.height || 0 }, format: normalizedFormat }; } catch (error) { throw new Error(`图片转换失败: ${error instanceof Error ? error.message : String(error)}`); } }
• src/converter.ts:6-16 (schema)

  TypeScript interface defining the options for the convertImage function.
  export interface ConvertImageOptions { input_path?: string; input_data?: Buffer | string; // 支持Buffer数据或base64字符串 input_filename?: string; // 原始文件名，用于确定格式 output_format: string; quality?: number; width?: number; height?: number; maintain_aspect_ratio?: boolean; output_path?: string; }