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 并填写（.env 从本包根目录加载，与启动目录无关，因此 Codex / Claude Code / Cursor / Claude Desktop 等各宿主都能读到）：

主视觉模型失败时，会按 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 手动配置，路径替换为实际项目路径。

接入 Claude Code

一键安装

npm install
npm run build
npm run install:mcp:claude

install:mcp:claude 通过 claude mcp add image-analyzer-mcp -s user -- node dist/index.js 注册到 Claude Code 用户级全局配置（~/.claude.json），对所有工作区生效。脚本是幂等的：重复执行会先移除旧注册再添加。

脚本不内联任何环境变量：server 会读取自己包根目录的 .env（见「配置」一节），所以 API Key 只存在 .env（已在 .gitignore 中），不会写进 ~/.claude.json 或任何会被提交的文件。

脚本还会把 AGENTS.md 的规则写入用户级 ~/.claude/CLAUDE.md（已有相同规则时跳过，写入前生成 .bak 备份），让所有项目都遵守「仅当主模型不支持图片输入时才调用本工具」的使用规则。

手动配置

claude mcp add image-analyzer-mcp -s user -- node /绝对路径/image-analyzer-mcp/dist/index.js

如果只想对当前项目生效，可以复制 .env 到项目外，并把 claude-mcp.example.json 内容放到项目根目录的 .mcp.json（注意：.mcp.json 会被提交，请把密钥放在 server 目录的 .env，不要在 .mcp.json 里写密钥）。

使用规则（让 Claude 知道何时该调用）

Claude Code 读取 CLAUDE.md（不读取 AGENTS.md）。规则放在用户级还是项目级，取决于 server 装在哪里：

• server 装在用户级（install:mcp:claude 默认） → 规则也放用户级：脚本会自动写入 ~/.claude/CLAUDE.md，所有项目生效。也可手动把 AGENTS.md 的规则内容追加到 ~/.claude/CLAUDE.md。

• server 只在某个项目里用 → 规则放该项目根目录：把仓库的 CLAUDE.md 与 AGENTS.md 一起复制过去（CLAUDE.md 通过 @AGENTS.md 导入同一套规则），随仓库共享。

验证

claude mcp list   # 应显示 image-analyzer-mcp ✔ Connected
npm run smoke

提示：Claude Code 中 MCP 工具以 mcp__image-analyzer-mcp__analyze_image 形式暴露；模型调用时按规则使用 analyze_image / compare_images / analyze_clipboard_image 即可。

接入 Cursor / Claude Desktop

Cursor 和 Claude Desktop 也支持 stdio MCP server：在各自的 MCP 配置界面添加一个命令类型的 server，命令填 Node 路径、参数填 dist/index.js 的绝对路径即可。.env 同样从包根目录加载，无需额外配置环境变量。

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 两种模拟请求。