# 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

## 安装与构建

```bash
npm install
npm run build
```

## 配置

复制 `.env.example` 为 `.env` 并填写（`.env` 从**本包根目录**加载，与启动目录无关，因此 Codex / Claude Code / Cursor / Claude Desktop 等各宿主都能读到）：

| 变量 | 说明 |
| --- | --- |
| `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_*` 自动降级到备用模型。

## 工具

```text
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 工具安装：

```bash
npm install
npm run build
npm run install:mcp
```

`install:mcp` 会把 server 写入 `~/.codex/config.toml`，然后重启 Codex 即可。
安装脚本还会把 [AGENTS.md](./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.toml) 或 [codex-mcp.example.json](./codex-mcp.example.json) 手动配置，路径替换为实际项目路径。

## 接入 Claude Code

### 一键安装

```bash
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](./AGENTS.md) 的规则写入**用户级** `~/.claude/CLAUDE.md`（已有相同规则时跳过，写入前生成 `.bak` 备份），让所有项目都遵守「仅当主模型不支持图片输入时才调用本工具」的使用规则。

### 手动配置

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

如果只想对**当前项目**生效，可以复制 `.env` 到项目外，并把 [claude-mcp.example.json](./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](./AGENTS.md) 的规则内容追加到 `~/.claude/CLAUDE.md`。
- **server 只在某个项目里用** → 规则放该项目根目录：把仓库的 [CLAUDE.md](./CLAUDE.md) 与 [AGENTS.md](./AGENTS.md) 一起复制过去（`CLAUDE.md` 通过 `@AGENTS.md` 导入同一套规则），随仓库共享。

### 验证

```bash
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](./AGENTS.md) 写入 Codex 全局 `~/.codex/AGENTS.md`：文件不存在时直接创建，已有其他内容时追加，已经包含“图片分析使用规则”时跳过；写入前会把原文件备份为 `AGENTS.md.bak`。

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

## 验证

```bash
npm run smoke
```

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