seedream_browse_images
Browse and select image files from local directories to use as references or review generated content in Seedream 4.0 MCP workflows.
Instructions
本地图片浏览：
浏览工作目录中的图片文件，便于用户选择参考图或查看已生成内容。
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
Implementation Reference
- Core handler function that parses arguments, searches for images in the directory using find_images_in_directory, formats the list with details if requested, and returns TextContent with the image file list.async def handle_browse_images(arguments: Dict[str, Any]) -> List[TextContent]: """处理图片浏览请求。 根据提供的参数搜索指定目录下的图片文件，支持递归搜索、深度限制、 格式过滤等功能，返回格式化的图片列表。 Args: arguments: 包含搜索参数的字典，支持以下键： - directory (str, optional): 搜索目录路径，默认为当前目录。 - recursive (bool, optional): 是否递归搜索子目录，默认为 True。 - max_depth (int, optional): 递归搜索的最大深度，默认为 3。 - limit (int, optional): 返回结果的最大数量，默认为 50。 - format_filter (str, optional): 文件格式过滤条件。 - show_details (bool, optional): 是否显示文件详细信息，默认为 False。 Returns: 包含图片列表信息的 TextContent 对象列表。若未找到图片， 返回提示信息；否则返回编号的图片列表。 """ # 解析并设置默认参数 directory = arguments.get("directory") or "." recursive = bool(arguments.get("recursive", True)) max_depth = int(arguments.get("max_depth", 3)) limit = int(arguments.get("limit", 50)) format_filter = arguments.get("format_filter") show_details = bool(arguments.get("show_details", False)) resolved_dir = Path(directory).expanduser().resolve() logger.info( "浏览图片: dir={}, recursive={}, max_depth={}, limit={}", resolved_dir, recursive, max_depth, limit, ) # 搜索图片文件并限制返回数量 images = find_images_in_directory( directory=str(resolved_dir), recursive=recursive, max_depth=max_depth, extensions=format_filter, ) images = images[:limit] # 处理未找到图片的情况 if not images: return [TextContent(type="text", text="未找到图片文件，请确认目录或过滤条件。")] # 格式化图片列表输出 workspace_root = Path.cwd() lines = ["图片列表:"] for idx, img in enumerate(images, 1): display_path = get_relative_path(img, str(workspace_root)) lines.append(f"{idx}. {_format_file_info(display_path, img, show_details)}") return [TextContent(type="text", text="\n".join(lines))]
- Pydantic model defining the input schema for the browse images tool, including fields for directory, recursion options, limits, filters, with validators.class BrowseImagesInput(BaseModel): """ 本地图片浏览：浏览工作目录中的图片文件，便于用户选择参考图或查看已生成内容。 """ model_config = ConfigDict( extra="forbid", str_strip_whitespace=True, validate_assignment=True, ) directory: Optional[str] = Field( default=None, description="要浏览的目录路径，默认使用当前工作目录。", ) recursive: bool = Field( default=True, description="是否递归查找子目录。", ) max_depth: int = Field( default=3, ge=1, le=10, description="递归查找的最大深度（1-10）。", ) limit: int = Field( default=50, ge=1, le=200, description="返回的最大文件数量（1-200）。", ) format_filter: Optional[List[str]] = Field( default=None, description="需要过滤的图片后缀列表，如 ['.jpeg', '.png']。", ) show_details: bool = Field( default=False, description="是否展示文件大小、修改时间等详细信息。", ) @field_validator("directory") @classmethod def validate_directory(cls, value: Optional[str]) -> Optional[str]: """ 校验目录路径。 Args: value: 用户指定的目录路径 Returns: 规范化后的路径，None 时跳过校验 Raises: ValueError: 当路径为空字符串时 """ if value is None: return None normalized = value.strip() if not normalized: raise ValueError("目录路径不能为空字符串") return normalized @field_validator("format_filter") @classmethod def normalize_suffixes(cls, value: Optional[List[str]]) -> Optional[List[str]]: """ 规范化文件后缀列表。 Args: value: 用户提供的后缀列表 Returns: 规范化后的后缀列表（小写，含点前缀），None 时跳过 """ if value is None: return None normalized = [] for suffix in value: cleaned = suffix.strip().lower() if not cleaned.startswith("."): cleaned = f".{cleaned}" normalized.append(cleaned) return normalized @model_validator(mode="after") def validate_limits(self) -> "BrowseImagesInput": """ 校验数量限制参数的逻辑一致性。 Returns: 校验通过的模型实例 Raises: ValueError: 当 limit 小于 1 时 """ if self.limit < 1: raise ValueError("limit 必须大于等于 1") return self
- seedream_mcp/server.py:139-150 (registration)MCP tool registration decorator and thin wrapper function that delegates to run_browse_images.@mcp.tool( name="seedream_browse_images", annotations={"title": "Seedream 图片浏览", **BROWSE_TOOL_ANNOTATIONS}, ) async def seedream_browse_images(params: BrowseImagesInput) -> list[TextContent]: """ 本地图片浏览： 浏览工作目录中的图片文件，便于用户选择参考图或查看已生成内容。 """ return await run_browse_images(params)
- Wrapper function that converts Pydantic input to dict and calls the core handle_browse_images.async def run_browse_images(params: BrowseImagesInput) -> List[TextContent]: """ 执行图像浏览工具。 Args: params: 图像浏览的已验证参数对象。 Returns: 包含浏览结果的文本内容列表。 """ return await handle_browse_images(params.model_dump(exclude_none=True))