image-analyzer-mcp

基于官方 MCP SDK 的图片分析 Server。通过 OpenAI 兼容的视觉 API 分析 PNG/JPG/WebP 截图和设计图，返回结构化 JSON，供主模型继续实现页面、组件或修复还原度问题。

功能

• analyze_image(path, prompt?)：分析单张图片，返回布局、区块、组件、颜色、字体、间距、问题与实现建议

• compare_images(referencePath, currentPath, prompt?)：对比参考图与当前实现图，返回差异清单和修复计划

• analyze_clipboard_image(prompt?)：读取 macOS 剪贴板图片并分析

• 支持 OpenAI 兼容的 Chat Completions 和 Responses API

• 支持主视觉模型与备用视觉模型自动切换

Related MCP server: Vision MCP

要求

• Node.js 18.17+

• npm

安装与构建

npm install
npm run build

配置

复制 .env.example 为 .env 并填写：

主视觉模型失败时，会按 VISION_FALLBACK_* 自动降级到备用模型。

工具

analyze_image(path="screenshots/home.png", prompt="重点分析 Hero 区")

compare_images(
  referencePath="screenshots/design.png",
  currentPath="screenshots/implementation.png",
  prompt="重点对比间距和颜色"
)

analyze_clipboard_image(prompt="介绍这张图片")

工具返回结构化 JSON，包含 summary、layout、sections、components、colors、typography、issues、fix_plan 等字段。

接入 Codex / 其他 AI 工具

构建后可直接让 AI 工具安装：

npm install
npm run build
npm run install:mcp

install:mcp 会把 server 写入 ~/.codex/config.toml，然后重启 Codex 即可。

默认安装到全局用户配置（~/.codex/config.toml），对所有工作区生效。本工具只在主模型无法直接识图时使用（例如 DeepSeek 经代理接入）；如果主模型本身支持图片输入，应直接使用图片，不需要调用本工具。

不要把你的 API Key 发送给任何 AI 工具。安装完成后请自行编辑 ~/.codex/config.toml，在 [mcp_servers.image-analyzer.env] 中配置 VISION_API_KEY，然后重启 Codex。

也可以参考 codex-mcp.example.toml 或 codex-mcp.example.json 手动配置，路径替换为实际项目路径。

AGENTS.md

把项目内的 AGENTS.md 复制到工作区，AI 工具遇到截图或设计图时会自动调用对应工具。

验证

npm run smoke

smoke 会构建项目、启动 MCP Server，并验证工具列表、错误处理以及 chat/responses 两种模拟请求。