Image Processing MCP Server

Instructions

Implementation Reference

• tools/color_adjust.py:209-281 (handler)

  Core handler function that loads the image, adjusts the alpha channel opacity using PIL, processes output with ImageProcessor, and returns JSON result.

  async def adjust_opacity(image_source: str, opacity: float) -> list[TextContent]:
      """
      调整图片不透明度
      
      Args:
          image_source: 图片数据（base64编码）或文件路径
          opacity: 不透明度值（0.0-1.0）
          
      Returns:
          调整后的图片数据
      """
      try:
          # 验证参数
          if not image_source:
              raise ValidationError("图片数据不能为空")
          
          if not validate_numeric_range(opacity, 0.0, 1.0):
              raise ValidationError(f"不透明度值必须在0.0-1.0范围内: {opacity}")
          
          # 加载图片
          image = processor.load_image(image_source)
          original_mode = image.mode
          
          # 确保图片有alpha通道
          if image.mode != 'RGBA':
              image = image.convert('RGBA')
          
          # 获取图片数据
          data = image.getdata()
          
          # 调整alpha通道
          new_data = []
          for item in data:
              # item是(R, G, B, A)元组
              r, g, b, a = item
              # 计算新的alpha值
              new_alpha = int(a * opacity)
              new_data.append((r, g, b, new_alpha))
          
          # 创建新图片
          opacity_image = Image.new('RGBA', image.size)
          opacity_image.putdata(new_data)
          
          # 输出处理后的图片
          output_info = processor.output_image(opacity_image, "opacity")
          
          result = {
              "success": True,
              "message": f"不透明度调整成功: {opacity}",
              "data": {
                  **output_info,
                  "opacity_value": opacity,
                  "original_mode": original_mode,
                  "new_mode": opacity_image.mode,
                  "size": image.size
              }
          }
          
          return [TextContent(type="text", text=json.dumps(result, ensure_ascii=False))]
          
      except ValidationError as e:
          error_result = {
              "success": False,
              "error": f"参数验证失败: {str(e)}"
          }
          return [TextContent(type="text", text=json.dumps(error_result, ensure_ascii=False))]
          
      except Exception as e:
          error_result = {
              "success": False,
              "error": f"不透明度调整失败: {str(e)}"
          }
          return [TextContent(type="text", text=json.dumps(error_result, ensure_ascii=False))]

• main.py:473-487 (registration)

  MCP tool registration using @mcp.tool() decorator. Defines input schema via Annotated Fields, wraps and calls the core handler from color_adjust.py.

  @mcp.tool()
  def adjust_opacity(
      image_source: Annotated[str, Field(description="图片源，可以是文件路径或base64编码的图片数据")],
      opacity: Annotated[float, Field(description="不透明度，范围 0.0-1.0，0.0为完全透明，1.0为完全不透明", ge=0.0, le=1.0)]
  ) -> str:
      """调整图片不透明度"""
      try:
          result = safe_run_async(color_adjust_opacity(image_source, opacity))
          return result[0].text
      except Exception as e:
          return json.dumps({
              "success": False,
              "error": f"调整不透明度失败: {str(e)}"
          }, ensure_ascii=False, indent=2)

• tools/color_adjust.py:139-158 (schema)

  Tool schema definition used in get_color_adjust_tools(), matching the input parameters for adjust_opacity.

  Tool(
      name="adjust_opacity",
      description="调整图片不透明度",
      inputSchema={
          "type": "object",
          "properties": {
              "image_source": {
                  "type": "string",
                  "description": "图片数据（base64编码）或文件路径"
              },
              "opacity": {
                  "type": "number",
                  "description": "不透明度值（0.0-1.0，0.0为完全透明，1.0为完全不透明）",
                  "minimum": 0.0,
                  "maximum": 1.0
              }
          },
          "required": ["image_source", "opacity"]
      }
  )