<p align="center">
  <img src="主图.png" width="480" alt="ImageMCP">
</p>

# ImageMCP — 给文本模型配一双"眼睛"

> 部分大模型（如 DeepSeek）不具备图片识别能力。ImageMCP 是一个常驻系统托盘的桌面应用，内置标准 **MCP 服务**，把图片交给具备多模态能力的模型（默认小米 **MiMo** `mimo-v2.5`）识别后，把答案返回给文本模型。任何支持 MCP 的 Code Agent（Claude Code、opencode、Cline、Cursor、Windsurf 等）都能接入。

## 文件说明

| 文件 | 作用 |
| ---- | ---- |
| `imagemcp.exe` | **单文件应用**。双击启动：常驻系统托盘 + 内嵌设置窗口 + 本机 HTTP MCP 服务 |
| `config.json` | 配置文件（与 exe 同目录，由设置窗口写入） |
| `ai_rules/IMAGE_RULES.md` | **通用 AI 规则模板**：AI 读取后自查身份，只把规则安装到它自己所在 agent 的全局规则文件 |

## 快速开始（接收方，无需安装 Python）

### 第 1 步：放置并启动

把 `imagemcp.exe` 和 `config.json` 放到同一目录（如 `D:\ImageMCP\`），**双击 `imagemcp.exe`**：

- 桌面右下角出现托盘图标；
- 自动弹出设置窗口，顶部横幅显示服务状态；
- 后台自动启动 MCP 服务：**`http://127.0.0.1:9847/mcp`**。

### 第 2 步：填写 API 配置

在设置窗口填入：

| 字段 | 说明 |
| ---- | ---- |
| API 地址 (api_base) | 默认 `https://api.xiaomimimo.com/v1`（OpenAI 兼容即可） |
| API 密钥 (api_key) | 你的多模态模型 API Key |
| 模型 ID | 默认 `mimo-v2.5`（**填错会导致"返回内容为空"**，见下方排查） |

点「**保存并检测**」→ 顶部横幅变绿色「✓ 服务正常：图片识别可用」即配置成功。

### 第 3 步：让 AI 自助安装到全局（推荐）

点设置窗口的「**复制安装提示词**」按钮（或直接打开 `ai_rules/IMAGE_RULES.md`），
把内容**粘贴给你的 AI agent**（Claude Code、opencode、Cursor、Codex、Windsurf、Cline…都行）。

AI 收到后按提示词执行：

1. **自查身份**——判断自己是什么 agent（查看运行环境 / 检测自己的全局配置目录）；
2. **只安装到当前 agent**——把「图片识别规则」写入**它自己**的全局规则文件
   （如 Claude Code → `~/.claude/CLAUDE.md`，opencode → `~/.config/opencode/AGENTS.md`）；
   ⚠️ **不会安装到其他 agent**，不会枚举安装所有；
3. 幂等（重复安装不会产生重复内容）；可选顺手注册 MCP（`claude mcp add --scope user` 等）。

规则核心一句话：

> **图片必须调用 `analyze_image` 工具；禁止用 Read 工具或模型自身视觉读图。**
> 你是一个纯文本模型，不具备直接查看或理解图片的能力。当用户上传图片或提及图片时，严禁尝试直接分析图片内容或使用内置的 Read/View 功能，必须且只能调用 MCP 工具 [imagemcp] 来处理图片。图片必须调用 analyze_image 工具；禁止用 Read 工具或模型自身视觉读图。

之后**所有项目、所有会话**都会自动生效，AI 收到图片会直接走 MCP 识别，不再用自己的视觉硬试。

> 卸载：让 AI 删除规则文件中 `<!-- ImageMCP-rules-start -->` 与 `<!-- ImageMCP-rules-end -->` 之间的内容。

### 第 4 步：开始使用

在对话中让助手"看这张图"，它会按全局规则调用 `analyze_image` 识别图片并回答。

## 各 MCP 客户端手动接入方式

所有客户端都连同一个地址：

```
地址：http://127.0.0.1:9847/mcp
类型：Streamable HTTP（部分客户端写作 HTTP / SSE）
```

| 客户端 | 手动接入方式 |
| ---- | ---- |
| **Claude Code** | `claude mcp add --transport http --scope user imagemcp http://127.0.0.1:9847/mcp`（`--scope user` = 全局；去掉则为当前项目） |
| **opencode** | `opencode.json` 里 `mcp.imagemcp = {"type":"remote","url":"http://127.0.0.1:9847/mcp","enabled":true}`（放 `~/.config/opencode/opencode.json` = 全局） |
| **Cline / Roo Code / Kilo Code** | MCP Servers → 添加远程/HTTP 服务器，URL 填上面地址 |
| **Claude Desktop** | `claude_desktop_config.json` 的 mcpServers 用 HTTP 类型 |

opencode 全局配置示例（`~/.config/opencode/opencode.json`）：

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "imagemcp": {
      "type": "remote",
      "url": "http://127.0.0.1:9847/mcp",
      "enabled": true
    }
  }
}
```

> 代理提示：若连接失败且本机开了系统代理，请把 `127.0.0.1`、`localhost` 加入代理排除（`NO_PROXY`），否则本机 HTTP 流量可能被代理拦截。

## 托盘应用操作

| 操作 | 效果 |
| ---- | ---- |
| 双击托盘图标 | 打开设置窗口 |
| 托盘菜单「复制 MCP 地址」 | 复制 `http://127.0.0.1:9847/mcp` 到剪贴板 |
| 关闭设置窗口 | 最小化到托盘，程序继续运行 |
| 托盘菜单「退出」 | 停止 HTTP 服务并退出程序 |

## 环境变量覆盖（可选）

`IMAGE_MCP_API_BASE` / `IMAGE_MCP_API_KEY` / `IMAGE_MCP_MODEL` 优先级高于 `config.json`，适合不想把密钥写入配置文件时使用。

## 常见问题排查

### 「多模态 API 返回内容为空」（或报错信息含模型名 + 原始响应）

新版错误信息会自带**模型名、截断的原始响应**和排查提示，例如：

```
多模态 API 返回内容为空（模型 mimo-v2.5）。原始响应：{"error": {...}}。请检查模型 ID 是否正确，详情见 imagemcp.log
```

按顺序排查：

| # | 检查项 | 说明 |
| ---- | ---- | ---- |
| 1 | **模型 ID 是否正确** | `config.json` 的 `model` 字段必须是 API 真实支持的模型名（MiMo 官方如 `mimo-v2.5`），填错 API 会返回空或报错 |
| 2 | **API Key 是否有效** | 打开设置窗口点「测试连接」，401 表示密钥无效 |
| 3 | **API 是否兼容** | 部分 OpenAI 兼容 API 拒绝 `max_completion_tokens`；新版已自动降级重试 `max_tokens`，若仍失败请查看日志 |
| 4 | **看日志** | `imagemcp.log`（exe 同目录）记录了每次调用的输入/输出/原始错误，是最直接的排查依据 |
| 5 | **图片格式** | 仅支持 JPEG / PNG / GIF / WebP / BMP，单图 ≤ 50MB |

### AI 不用 MCP，反而用自己视觉/Read 工具看图

这是全局规则没生效。检查：

1. 让 AI 重新按第 3 步安装（粘贴 `ai_rules/IMAGE_RULES.md` 内容给它）；
2. 确认你所在 agent 的全局规则文件（Claude Code → `~/.claude/CLAUDE.md`，
   opencode → `~/.config/opencode/AGENTS.md`，其他 agent 见提示词中的自查表）
   已包含「ImageMCP 图片识别规则」段落（含 `<!-- ImageMCP-rules-start -->` 标记）；
3. 修改全局规则后**需要重启** agent（新会话生效）；
4. 确认 MCP 已注册（Claude Code：`claude mcp list` 应看到 `imagemcp`）。

### 其他

| 症状 | 可能原因 | 排查/修复 |
| ---- | ---- | ---- |
| 客户端连不上 MCP | 程序没运行 / 代理拦截 | 确认托盘常驻；`NO_PROXY` 排除 127.0.0.1 |
| 「未配置 API 地址」 | config.json 缺失/未保存 | 打开设置窗口填写并「保存并检测」 |
| 图片文件不存在 | 路径是相对路径或已移动 | 传绝对路径；确认文件存在 |

## 日志

程序运行后会在 **exe 同目录**生成 `imagemcp.log`，记录每次 `analyze_image` 调用的输入与输出：

```
[2026-08-03 22:58:41.172] [OK] analyze_image 耗时2232ms
  输入 image : C:\Users\...\blue.png
  输入 question: 这张图是什么颜色？一句话
  输出        : 这张图是蓝色（纯蓝色）的。
```

- 包含时间、状态（OK/ERROR）、agent 传入的图片来源与提示词、返回内容、耗时；
- 图片为 base64 data URI 时只记录前缀与长度，避免日志膨胀；
- **自动轮转**：单个日志默认超过 5MB 归档为 `imagemcp.log.<时间戳>`，默认保留 3 份；
- 环境变量控制：
  - `IMAGEMCP_LOG=0` 关闭日志；
  - `IMAGEMCP_LOG_MAX_MB=<数字>` 调整单文件上限（MB）；
  - `IMAGEMCP_LOG_KEEP=<数字>` 调整保留归档份数。

## 开发者运行（源码方式）

```bash
pip install -r requirements.txt
python main.py            # 托盘应用（默认）
python main.py --serve    # stdio MCP 服务（给只支持 stdio 的客户端）
python main.py --http     # headless HTTP 服务（调试用）
```

## 二次打包

```bash
pip install -r requirements-dev.txt
build.bat                # 产出 dist\imagemcp.exe（已包含 ai_rules 数据）
```

## 工作原理

```
任意 MCP 客户端 ──HTTP──▶ imagemcp.exe (127.0.0.1:9847/mcp) ──HTTP──▶ 多模态 API (MiMo)
                              ▲ 常驻托盘
                              │ 读/写 config.json（与 exe 同目录）
```

`analyze_image` 工具接受 `image`（本地绝对路径 / http(s) URL / base64 data URI）与 `question`（可选，有默认值），图片统一转为 base64 内联发送，答案直接返回文本模型。限制：单图 ≤ 50MB；支持 JPEG / PNG / GIF / WebP / BMP。