Image Processing MCP Server

Instructions

Implementation Reference

• tools/filters.py:179-232 (handler)

  Core handler function that applies BoxBlur filter to the image using PIL, handles validation, processes output with ImageProcessor, and returns JSON-formatted result.

  async def apply_blur(image_source: str, radius: float) -> list[TextContent]:
      """
      应用模糊滤镜
      
      Args:
          image_source: 图片源（文件路径或base64编码数据）
          radius: 模糊半径
          
      Returns:
          应用滤镜后的图片数据
      """
      try:
          # 验证参数
          if not image_source:
              raise ValidationError("图片源不能为空")
          
          if not validate_numeric_range(radius, 0.1, 10.0):
              raise ValidationError(f"模糊半径必须在0.1-10.0范围内: {radius}")
          
          # 加载图片
          image = processor.load_image(image_source)
          
          # 应用模糊滤镜
          blurred_image = image.filter(ImageFilter.BoxBlur(radius))
          
          # 输出处理后的图片
          output_info = processor.output_image(blurred_image, "blur")
          
          result = {
              "success": True,
              "message": f"模糊滤镜应用成功: 半径 {radius}",
              "data": {
                  **output_info,
                  "filter_type": "blur",
                  "radius": radius,
                  "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:240-254 (registration)

  MCP server tool registration with @mcp.tool() decorator. This wrapper calls the core handler from filters.py with safe_run_async and provides input validation via Annotated fields.

  @mcp.tool()
  def apply_blur(
      image_source: Annotated[str, Field(description="图片源，可以是文件路径或base64编码的图片数据")],
      radius: Annotated[float, Field(description="模糊半径，值越大模糊效果越强", ge=0.1)]
  ) -> str:
      """应用模糊滤镜"""
      try:
          result = safe_run_async(filters_apply_blur(image_source, radius))
          return result[0].text
      except Exception as e:
          return json.dumps({
              "success": False,
              "error": f"应用模糊效果失败: {str(e)}"
          }, ensure_ascii=False, indent=2)

• tools/filters.py:28-42 (schema)

  JSON schema definition for the apply_blur tool input, defining properties for image_data (base64) and radius with range validation.

  inputSchema={
      "type": "object",
      "properties": {
          "image_data": {
              "type": "string",
              "description": "图片数据（base64编码）"
          },
          "radius": {
              "type": "number",
              "description": "模糊半径（0.1-10.0）",
              "minimum": 0.1,
              "maximum": 10.0
          }
      },
      "required": ["image_data", "radius"]