image-tiler-mcp-server 是一个本地 MCP 服务器，旨在解决大语言模型视觉能力在处理大尺寸图片时自动降采样导致细节丢失的问题。它通过将图片或网页截图切分为瓦片，使模型能够以原生分辨率分析每个部分。
用途
- 防止 LLM 视觉降采样：当图片长边超过一定像素（如 Claude 约 1568px）时，模型会自动压缩图片，丢失大量细节。该工具将大图切分为多个瓦片，每个瓦片保持在模型的最佳分辨率范围内。
- 网页视觉 QA：捕获完整网页截图并切分，让 LLM 以全分辨率检查布局错位、颜色错误、样式破损等问题。
- 移动端响应式测试：以移动设备视口、retina 缩放和移动用户代理捕获页面，逐瓦片审查移动端布局。
- 全分辨率图像分析：适用于图表、信息图、设计稿等需要保留细节的图像。
主要能力
- 图像切分：读取图像尺寸和目标模型的视觉配置，计算最优网格，将图像切分为独立瓦片（默认 WebP，可选 PNG），保存到磁盘。
- 网页捕获：通过无头 Chrome 启动，滚动页面触发懒加载图片，捕获全页截图（超过 16384px 时进行滚动拼接），然后送入切分流程。
- 模型特定 token 估算：为 Claude、GPT-4o、Gemini 等模型提供瓦片数量和 token 成本估算，并生成带网格覆盖和瓦片编号的交互式 HTML 预览。
- 基于熵的内容分类：每个瓦片被分类为空白、低细节、混合或高细节，LLM 可跳过空白瓦片，节省 token。
- 迭代工作流：重复切分同一源会创建 _v1、_v2 等版本化输出目录，便于对比。
- 按需获取瓦片：通过 tilesDir + start/end 参数分批获取最多 5 个瓦片。
- 自动降采样：长边超过 10000px 的图像在切分前自动降采样（可通过 maxDimension 配置，设为 0 禁用）。
使用方式
- 安装：通过 npm 包 image-tiler-mcp-server 下载运行，可自定义本地别名（如 image-tiler）。
- 配置：支持 Claude Code、Codex CLI、VS Code、Cursor、Claude Desktop 等 MCP 客户端。需在对应配置文件中添加服务器配置，重启客户端后生效。
- 基本流程：调用工具时仅提供图像源，返回各模型的瓦片数量和 token 估算对比表及 HTML 预览；然后选择模型预设和输出目录再次调用进行切分。也可在首次调用时直接提供 preset 和 outputDir 跳过对比步骤。
- 图像源：支持 filePath、sourceUrl、dataUrl、imageBase64 等参数。
- 网页捕获：提供 url 参数即可捕获并切分；若只需截图不切分，可在对比步骤后停止。
- 移动端测试：使用 mobile: true 参数，设置 390px 视口、2x retina 缩放和移动 Safari 用户代理。
- Docker 运行：官方镜像包含 Chromium，默认启用 --no-sandbox（因容器不提供用户命名空间），可通过 -e CHROME_NO_SANDBOX=0 重新启用沙箱。需使用 -i 标志（stdio 传输），挂载卷并设置 TILER_ALLOWED_DIRS 限制文件访问。
- 禁用 URL 捕获：设置环境变量可完全禁用 Chrome 和网络访问。
适用场景
- 网页视觉 QA：捕获 URL，切分，让 LLM 发现全分辨率下的布局问题，修复代码后重新捕获验证。
- 移动端响应式测试：以移动视口捕获，逐瓦片审查，发现仅在小型屏幕上出现的断点问题。
- 全分辨率图像分析：如 3600x20220px 的全页截图，Claude 原本会压缩到约 279x1568，切分后变为 76 个可分析瓦片，每个保持原生分辨率。
- 迭代视觉工作流：捕获、分析、修复、重新捕获，版本化输出目录保留每次迭代结果。
限制
- 传输方式：仅支持 stdio，服务器为单会话本地进程，不监听网络端口。
- OpenAI 配置针对 GPT-4o / o 系列视觉管线（512px 瓦片补丁），GPT-4.1 使用不同的 32x32 像素补丁管线，目前不支持。
- Gemini 3 每张图片有固定 token 预算（1120 tokens），切分会增加总 token 成本但保留细节；若细节不重要，可考虑发送单张图片。
- URL 下载保护：https 源使用 request-filtering-agent 阻止私有 IP 范围请求，支持最多 5 跳重定向并重新应用 SSRF 过滤，阻止 https 到 http 降级；http 下载绕过 SSRF 过滤，仅用于本地开发。DNS 重绑定在应用层得到缓解但未完全防止。
- 路径限制：通过 TILER_ALLOWED_DIRS 可选限制文件 I/O 到指定目录，未设置时无限制。
- Chrome URL 捕获可完全禁用，适用于无网络策略的云部署。
- 支持格式：PNG、JPEG、WebP、TIFF、GIF。
- 需要 Node.js 20+，Chrome 需安装或设置 CHROME_PATH。
- 常见问题：命令未找到、文件未找到（需绝对路径）、MCP 工具不可用（需重启客户端）、Chrome 未找到等。
