create_collage
Combine multiple images into a single collage with customizable layouts, spacing, and background colors for visual organization or presentation.
Instructions
创建图片拼贴
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| image_sources | Yes | 图片源列表，每个元素可以是文件路径或base64编码的图片数据 | |
| layout | No | 布局方式：grid（网格）、horizontal（水平）、vertical（垂直） | grid |
| spacing | No | 图片间距（像素） | |
| background_color | No | 背景颜色，支持十六进制颜色代码 | #FFFFFF |
| output_format | No | 输出格式：PNG、JPEG、WEBP 等 | PNG |
Implementation Reference
- tools/advanced.py:440-592 (handler)Core implementation of the create_collage tool: loads multiple images, arranges them in specified layout (grid, horizontal, vertical, mosaic), scales to fit max dimensions, creates composite image, and returns base64 output.
async def create_collage(arguments: Dict[str, Any]) -> List[TextContent]: """ 创建图片拼贴 Args: arguments: 包含图片源列表和拼贴参数的字典 Returns: List[TextContent]: 处理结果 """ try: # 参数验证 image_sources = arguments.get("image_sources", []) if len(image_sources) < 2: raise ValidationError("至少需要2张图片") layout = arguments.get("layout", "grid") spacing = arguments.get("spacing", 10) background_color = arguments.get("background_color", "#FFFFFF") max_width = arguments.get("max_width", 1200) max_height = arguments.get("max_height", 1200) output_format = arguments.get("output_format", DEFAULT_IMAGE_FORMAT) # 验证参数 validate_numeric_range(spacing, 0, 50, "spacing") validate_color_hex(background_color) validate_numeric_range(max_width, 200, MAX_IMAGE_SIZE, "max_width") validate_numeric_range(max_height, 200, MAX_IMAGE_SIZE, "max_height") processor = ImageProcessor() images = [] # 加载所有图片 for source in image_sources: ensure_valid_image_source(source) image = processor.load_image(source) images.append(image) # 根据布局创建拼贴 if layout == "horizontal": # 水平排列 total_width = sum(img.width for img in images) + spacing * (len(images) - 1) max_height_img = max(img.height for img in images) # 缩放以适应最大尺寸 if total_width > max_width: scale = max_width / total_width images = [img.resize((int(img.width * scale), int(img.height * scale)), Image.Resampling.LANCZOS) for img in images] total_width = max_width max_height_img = max(img.height for img in images) collage = Image.new("RGB", (total_width, max_height_img), background_color) x_offset = 0 for img in images: y_offset = (max_height_img - img.height) // 2 collage.paste(img, (x_offset, y_offset)) x_offset += img.width + spacing elif layout == "vertical": # 垂直排列 max_width_img = max(img.width for img in images) total_height = sum(img.height for img in images) + spacing * (len(images) - 1) # 缩放以适应最大尺寸 if total_height > max_height: scale = max_height / total_height images = [img.resize((int(img.width * scale), int(img.height * scale)), Image.Resampling.LANCZOS) for img in images] max_width_img = max(img.width for img in images) total_height = max_height collage = Image.new("RGB", (max_width_img, total_height), background_color) y_offset = 0 for img in images: x_offset = (max_width_img - img.width) // 2 collage.paste(img, (x_offset, y_offset)) y_offset += img.height + spacing else: # grid 或 mosaic # 网格排列 import math cols = math.ceil(math.sqrt(len(images))) rows = math.ceil(len(images) / cols) # 计算每个单元格的大小 cell_width = (max_width - spacing * (cols - 1)) // cols cell_height = (max_height - spacing * (rows - 1)) // rows # 调整所有图片到单元格大小 resized_images = [] for img in images: img.thumbnail((cell_width, cell_height), Image.Resampling.LANCZOS) resized_images.append(img) # 创建拼贴 collage_width = cols * cell_width + spacing * (cols - 1) collage_height = rows * cell_height + spacing * (rows - 1) collage = Image.new("RGB", (collage_width, collage_height), background_color) for i, img in enumerate(resized_images): row = i // cols col = i % cols x = col * (cell_width + spacing) y = row * (cell_height + spacing) # 居中放置图片 x_offset = x + (cell_width - img.width) // 2 y_offset = y + (cell_height - img.height) // 2 collage.paste(img, (x_offset, y_offset)) # 转换为base64 output_info = processor.output_image(collage, "batch_resize", output_format) return [TextContent( type="text", text=json.dumps({ "success": True, "message": f"成功创建{layout}拼贴", "data": { **output_info, "metadata": { "image_count": len(images), "layout": layout, "size": f"{collage.width}x{collage.height}", "spacing": spacing, "background_color": background_color, "format": output_format } } }, ensure_ascii=False) )] except ValidationError as e: return [TextContent( type="text", text=json.dumps({ "success": False, "error": f"参数验证失败: {str(e)}" }, ensure_ascii=False) )] except Exception as e: return [TextContent( type="text", text=json.dumps({ "success": False, "error": f"创建拼贴失败: {str(e)}" }, ensure_ascii=False) )] - tools/advanced.py:81-135 (registration)Tool registration in get_advanced_tools() including name, description, and detailed inputSchema for validation.
Tool( name="create_collage", description="创建图片拼贴", inputSchema={ "type": "object", "properties": { "image_sources": { "type": "array", "description": "图片源列表（文件路径或base64编码）", "items": {"type": "string"}, "minItems": 2, "maxItems": 9 }, "layout": { "type": "string", "description": "拼贴布局", "enum": ["grid", "horizontal", "vertical", "mosaic"], "default": "grid" }, "spacing": { "type": "integer", "description": "图片间距（像素）", "minimum": 0, "maximum": 50, "default": 10 }, "background_color": { "type": "string", "description": "背景颜色（十六进制格式）", "default": "#FFFFFF" }, "max_width": { "type": "integer", "description": "最大宽度", "minimum": 200, "maximum": MAX_IMAGE_SIZE, "default": 1200 }, "max_height": { "type": "integer", "description": "最大高度", "minimum": 200, "maximum": MAX_IMAGE_SIZE, "default": 1200 }, "output_format": { "type": "string", "description": "输出格式", "enum": ["PNG", "JPEG", "WEBP"], "default": "PNG" } }, "required": ["image_sources"] } ), - main.py:674-697 (registration)Final MCP server registration of the create_collage tool using @mcp.tool() decorator, which wraps the advanced implementation call.
@mcp.tool() def create_collage( image_sources: Annotated[list, Field(description="图片源列表，每个元素可以是文件路径或base64编码的图片数据")], layout: Annotated[str, Field(description="布局方式：grid（网格）、horizontal（水平）、vertical（垂直）", default="grid")], spacing: Annotated[int, Field(description="图片间距（像素）", ge=0, default=10)], background_color: Annotated[str, Field(description="背景颜色，支持十六进制颜色代码", default="#FFFFFF")], output_format: Annotated[str, Field(description="输出格式：PNG、JPEG、WEBP 等", default="PNG")] ) -> str: """创建图片拼贴""" try: arguments = { "image_sources": image_sources, "layout": layout, "spacing": spacing, "background_color": background_color, "output_format": output_format } result = safe_run_async(advanced_create_collage(arguments)) return result[0].text except Exception as e: return json.dumps({ "success": False, "error": f"创建拼贴失败: {str(e)}" }, ensure_ascii=False, indent=2)