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
• 支持主视觉模型与备用视觉模型自动切换

要求

• Node.js 18.17+
• npm

安装与构建

npm install
npm run build

配置

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

变量	说明
VISION_API_KEY	主视觉 API 密钥（必填，真实调用时）
VISION_BASE_URL	主视觉 API 地址
VISION_MODEL	主视觉模型
VISION_API_STYLE	chat 或 responses
VISION_FALLBACK_API_KEY	备用视觉 API 密钥
VISION_FALLBACK_BASE_URL	备用视觉 API 地址
VISION_FALLBACK_MODEL	备用视觉模型
VISION_MAX_IMAGE_MB	单张图片大小上限，默认 8
VISION_TIMEOUT_MS	请求超时，默认 120000
VISION_MAX_TOKENS	返回 token 上限，默认 4096
VISION_JSON_MODE	是否启用 JSON 模式
VISION_BASE_DIR	相对路径解析根目录

主视觉模型失败时，会按 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 即可。 安装脚本还会把 AGENTS.md 自动写入 Codex 全局 ~/.codex/AGENTS.md（已有内容时追加，已包含相同规则时跳过，修改前生成 .bak 备份）。规则写明：只有通过 CC Switch 切换到 DeepSeek 等不支持多模态图片输入的模型时，才调用本工具；Codex 内置的 ChatGPT 等支持视觉的模型应直接识图，不调用本工具。 安装脚本还会自动检测 ~/.codex/cc-switch-model-catalog.json，把模型标记为支持图片输入（会先生成 .imagebak 备份），避免 DeepSeek 等文本模型在粘贴图片时被 Codex 拦截。

默认安装到全局用户配置（~/.codex/config.toml），对所有工作区生效。本工具只在主模型无法直接识图时使用（例如通过 CC Switch 切换到 DeepSeek 等不支持多模态图片输入的模型）；如果主模型本身支持图片输入（例如 Codex 内置的 ChatGPT 视觉模型），应直接使用图片，不需要调用本工具。

不要把你的 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

npm run install:mcp 会自动把项目内的 AGENTS.md 写入 Codex 全局 ~/.codex/AGENTS.md：文件不存在时直接创建，已有其他内容时追加，已经包含“图片分析使用规则”时跳过；写入前会把原文件备份为 AGENTS.md.bak。

如需只对某个工作区生效，也可以手动把 AGENTS.md 复制到该工作区根目录。

验证

npm run smoke

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