# mimo-vision MCP Server

本地 stdio MCP Server：给 Claude Code（主模型可以是 DeepSeek 等任何模型）提供"视觉眼睛"。
把本地图片交给小米 **MiMo-V2.5** 图片理解模型分析，返回文本结果供主 Agent 继续工作。

- 安装位置：`C:\Users\MR\.claude\mcp\mimo-vision`
- 视觉模型：`mimo-v2.5`（官方 OpenAI-compatible 接口 `https://api.xiaomimimo.com/v1/chat/completions`，直接调用无中间层）
- 安全：只做"读图片 → 调 MiMo API → 返回文本"，无文件写入/删除/shell 能力
- API Key 运行时从环境变量 `MIMO_API_KEY` 读取，绝不写入源码、配置或日志

## 配置 MIMO_API_KEY（Windows）

PowerShell 或 CMD 执行：

```
setx MIMO_API_KEY "你的Key"
```

然后**完全退出并重启 Claude Code**（MCP 无需重新注册）。

## 注册到 Claude Code（user scope，所有项目可用）

```
claude mcp add -s user mimo-vision -- "C:\Program Files\nodejs\node.exe" "C:\Users\MR\.claude\mcp\mimo-vision\server.js"
```

验证：

```
claude mcp list    # 应显示: mimo-vision ✔ Connected
```

## 三个 Tool

| Tool | 参数 | 用途 |
|---|---|---|
| `analyze_image` | `image_path` 必填；`prompt` 可选 | 分析一张图：布局、排版、间距、配色、视觉问题 |
| `compare_images` | `image_paths` 必填（2~8 张，按顺序）；`prompt` 可选 | 一次跨图对比：相同点/差异/布局/排版/间距/颜色/组件/比例/层级 + 对改代码最有价值的信息 |
| `inspect_ui` | `image_path` 或 `image_paths`；`task` 可选；`project_context` 可选 | UI 工程化分析，13 项结构化结果（Layout、尺寸比例、Grid、Spacing、Typography、Colors、边框圆角阴影、组件层级、图片比例、响应式线索、交互线索、差异问题、实现建议），可直接用于写 HTML/CSS/React |

图片路径支持：Windows 绝对路径（含中文/空格/反斜杠）或相对项目根目录的路径。
格式：JPEG/JPG/PNG/WebP/GIF/BMP；单张 Base64 不超过 50MB（超限返回明确错误并提示压缩）。

## 使用示例（对主 Agent 直接说）

- "看一下 ./screenshots/home.png，分析为什么这个页面显得太拥挤。"
- "对比 ./current.png 和 ./reference.png，然后修改当前页面使它更接近参考图。"
- "检查 ./result.png，看看这次前端修改还有哪些视觉问题。"
- "我要复刻 ./design.png 这个页面，先做 UI 分析再写代码。"

## 自测

```
cd C:\Users\MR\.claude\mcp\mimo-vision
node test/mcp-client-test.mjs          # 14 项基础+失败测试（无需 Key）
node test/mcp-client-test.mjs --real   # 再加真实 MiMo 调用（需已设置 MIMO_API_KEY）
```

测试图生成：`node test/make-test-images.mjs`（纯 Node 零依赖生成 PNG）。

## 排错

| 现象 | 处理 |
|---|---|
| 报错 `MIMO_API_KEY 未设置` | 按上文 setx 设置后重启 Claude Code |
| 报错 `MiMo 返回了空内容` | 常见于部分 WebP 编码（如带 ICC profile）MiMo 无法解析：把图片转成 PNG 后重试（可用图片查看器另存为，或 `msedge --headless=new --disable-gpu --screenshot=输出.png --window-size=<宽>,<高> "file:///原图"`） |
| 报错 `[HTTP 401]` | Key 错误或失效，到小米 MiMo 开放平台检查 |
| 报错 `[HTTP 429]` | 限流，稍后重试（服务端已自动重试 2 次） |
| 报错 `图片过大` | 压缩/缩小图片（单张 Base64 ≤ 50MB） |
| 报错 `不支持的图片格式` | 转成 PNG/JPG 等支持的格式 |
| 网络错误 | 检查网络/代理；服务端对网络错误自动退避重试 |

## 卸载

```
claude mcp remove mimo-vision
```

然后删除目录 `C:\Users\MR\.claude\mcp\mimo-vision`；如不再使用 MiMo，再执行 `setx MIMO_API_KEY ""`。