# mimo-vision-mcp

MCP Server：用小米 MiMo **v2.5** 多模态模型，为纯文本主模型（如 deepseek-v4-flash）补齐**图像识别**能力。

主模型没有视觉能力时，通过本 Server 把截图、UI 图、报错图、设计稿、照片等转成文字描述，
主模型据此继续推理。**二次开发自** [`Mriestac/mimo-image-recognition-mcp`](https://github.com/Mriestac/mimo-image-recognition-mcp)（选型记录见下文）。

## 功能

| 工具 | 说明 |
|---|---|
| `describe_image(image, prompt?)` | 单图理解（默认给详细描述） |
| `analyze_images(images, question)` | 多图联合分析（前后对比 / A/B 方案） |
| `extract_text_from_image(image)` | 纯 OCR，保留换行缩进 |
| `read_image_info(image)` | 只做本地校验，不调 API（排查输入问题） |
| `mimo://config` 资源 | 查看脱敏配置 |

图片输入支持：**本地路径**、`http(s)://` URL、`file://`、`data:image/...;base64,...`；
格式仅限 jpg/jpeg/png/gif/webp/bmp，单张 ≤10MB（官方限制）。

## 架构

```
主模型（纯文本）─ 图片路径/URL → MCP 工具
    → server 读图转 base64 → POST https://api.xiaomimimo.com/v1/chat/completions (mimo-v2.5)
    → 纯文本描述 → 主模型继续推理
```

## 安装

```powershell
cd <仓库路径>        # 例如 C:\path\to\mimo-vision-mcp
uv sync --dev        # 创建 .venv 并安装依赖（mcp[cli]<2、httpx、python-dotenv）
Copy-Item .env.example .env
# 编辑 .env 填入 MIMO_API_KEY
```

## 注册到 Claude Code（全局）

```powershell
cd <仓库路径>        # 例如 C:\path\to\mimo-vision-mcp
$key = ((Get-Content .env | Where-Object { $_ -match '^MIMO_API_KEY=' }) -split '=', 2)[1]
claude mcp add mimo-vision -s user `
  -e "MIMO_API_KEY=$key" `
  -e "MIMO_BASE_URL=https://api.xiaomimimo.com/v1" `
  -e "MIMO_VISION_MODEL=mimo-v2.5" `
  -- "$PWD\.venv\Scripts\python.exe" "$PWD\server.py"
```

验证：

```powershell
claude mcp list            # 应列出 mimo-vision
claude mcp get mimo-vision
claude mcp inspect mimo-vision   # 协议级连通性自检
```

主会话中需 **重启 Claude Code 或 `/mcp` 重连** 后工具才出现。

### 两种 Key 的差异

| Key 类型 | 前缀 | `MIMO_BASE_URL` |
|---|---|---|
| 普通按量付费 | `sk-` | `https://api.xiaomimimo.com/v1` |
| Token Plan | `tp-` | `https://token-plan-cn.xiaomimimo.com/v1` |

`mimo-v2.5-pro` 是纯文本推理模型，视觉理解**必须**用 `mimo-v2.5`。

## 使用

主会话中对模型说，例如：

> 描述这张图：C:\path\to\your\image.png
> 提取这张报错截图里的文字：C:\path\to\error.png

模型会自动调用对应工具。

## 验证

```powershell
uv run --env-file .env pytest tests/test_image_utils.py tests/smoke_test.py   # 离线单测
uv run --env-file .env pytest tests/test_api.py                               # 真实 API 直连
```

## 踩坑记录

- **MiMo API 硬性要求**：content 数组必须同时包含 `image_url` 与 `text` 对象，
  角色必须 `user`，否则返回 `400 Param Incorrect - text is not set`（见 `api_client.build_vision_message`）。
- **mcp SDK 2.x 移除了 `mcp.server.fastmcp`**：pyproject 锁定 `mcp[cli]>=1.2,<2.0`。
- **mcp 1.29 lifespan 是构造函数参数**（非 `@mcp.lifespan_context`）；工具/资源通过参数注解 `Context` 注入。
- **resource 有函数参数会被注册为模板资源**（`_templates`）而非普通资源，`list_resources` 看不到——配置资源改为无参数函数。
- 认证头用 `Authorization: Bearer`（base 项目 Mriestac 原用 `api-key`，已修正）；单图大小上限按官方改 10MB；补充 `file://` 输入支持。

## 配置项（.env）

| 变量 | 默认 | 说明 |
|---|---|---|
| `MIMO_API_KEY` | — | 必填 |
| `MIMO_BASE_URL` | `https://api.xiaomimimo.com/v1` | Token Plan 需改 |
| `MIMO_VISION_MODEL` | `mimo-v2.5` | 视觉模型名 |
| `MIMO_MAX_TOKENS` | `2048` | 最大输出 token |
| `MIMO_TIMEOUT` | `60` | 请求超时（秒） |
| `MIMO_ENABLE_THINKING` | `False` | 是否输出思考过程（更慢） |
| `MIMO_MAX_IMAGE_BYTES` | `10485760` | 单图上限（10MB） |

## 选型记录

候选仓库（均已 clone 审阅后删除 `_ref/`）：

- **选定 base**：`Mriestac/mimo-image-recognition-mcp` —— 天然用 OpenAI `chat/completions` 格式 + `api.xiaomimimo.com`，依赖轻（httpx），async 实现，工具/资源写法为标准 FastMCP。
- **备选**：`kuohao233/mimo-vision-mcp` —— 工具更全（describe/analyze/ocr）但走 Anthropic `/v1/messages` 格式，重写请求层成本高；其工具设计（默认 prompt、OCR 提示词）已借鉴到本项目。

修复自 base 的 3 处问题：认证头、10MB 上限、`file://` 支持，并新增 `read_image_info` 工具与 4 个独立工具拆分。