# MiMo Vision MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)

A lightweight **Model Context Protocol (MCP)** stdio server that enables LLM agents (such as Codex CLI/Desktop, Claude Desktop) to invoke the **MiMo Vision** model (`mimo-v2.5`) for local image understanding and OCR.

---

## 架构流程 (Architecture)

```text
Codex / Claude (Client)
   │ (JSON-RPC 2.0 via stdio)
   ▼
src/mimo_vision_mcp.py
   │ (curl.exe with stream base64 payload)
   ▼
https://opencode.ai/zen/go/v1/chat/completions (model: mimo-v2.5)
   │ (JSON Response)
   ▼
Recognition / Description Text returned to Client
```

> **Why `curl.exe`?**  
> Some API gateways reject standard Python HTTP user agents / connection handshakes. Using native system `curl.exe` ensures robust connections.

---

## 目录结构 (Project Structure)

```text
mimo-vision-mcp/
├── src/
│   └── mimo_vision_mcp.py    # MCP stdio 服务端核心实现（纯标准库，零三方依赖）
├── tests/
│   └── test_mcp.py           # 自动化测试脚本（生成测试图并验证协议连通性）
├── .env.example              # 环境变量配置模版
├── .gitignore                # Git 忽略配置
├── pyproject.toml            # Python 打包与元数据配置
├── LICENSE                   # MIT 开源协议
└── README.md                 # 项目文档
```

---

## 环境变量配置 (Environment Variables)

| 变量名 | 默认值 | 说明 |
|---|---|---|
| `MIMO_API_KEY` | *(必填)* | MiMo / OpenCode API 密钥 |
| `MIMO_API_BASE` | `https://opencode.ai/zen/go/v1/chat/completions` | Chat Completions 接口地址 |
| `MIMO_MODEL` | `mimo-v2.5` | 视觉模型名称 |
| `MIMO_DEFAULT_PROMPT` | `请详细描述这张图片的内容。` | 默认识别提示词 |
| `MIMO_CURL` | `curl.exe` | 用于发起 HTTP 请求的 curl 可执行程序 |

---

## 工具接口 (Tool Definition)

### `mimo_vision`
向 MiMo 视觉模型发送本地图片，返回文字识别或描述结果。

- **参数：**
  - `image_path` *(string, 必填)*: 本地图片文件的绝对路径（支持 `.png`, `.jpg`, `.jpeg`, `.webp`, `.gif`, `.bmp` 等）。
  - `prompt` *(string, 可选)*: 自定义提示词，如 `"识别图中的文字"`、`"这张图里有什么物体？"`。
  - `model` *(string, 可选)*: 模型名称覆盖，默认 `mimo-v2.5`。

---

## 安装与接入配置 (Setup Guide)

### 1. Codex 接入配置 (`~/.codex/config.toml`)

在你的 `config.toml` 中添加以下配置：

```toml
[mcp_servers.mimo_vision]
type = "stdio"
command = "python"
args = ["C:\\Users\\user\\Documents\\Codex\\2026-08-17\\mimo-vision-mcp\\src\\mimo_vision_mcp.py"]
startup_timeout_sec = 120

[mcp_servers.mimo_vision.env]
MIMO_API_KEY = "your-api-key"
MIMO_API_BASE = "https://opencode.ai/zen/go/v1/chat/completions"
MIMO_MODEL = "mimo-v2.5"
```

### 2. Claude Desktop 接入配置 (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "mimo-vision": {
      "command": "python",
      "args": ["C:/Users/user/Documents/Codex/2026-08-17/mimo-vision-mcp/src/mimo_vision_mcp.py"],
      "env": {
        "MIMO_API_KEY": "your-api-key",
        "MIMO_API_BASE": "https://opencode.ai/zen/go/v1/chat/completions",
        "MIMO_MODEL": "mimo-v2.5"
      }
    }
  }
}
```

---

## 运行测试 (Testing)

```powershell
$env:MIMO_API_KEY="your-api-key"
python tests/test_mcp.py
```

---

## 许可协议 (License)

本项目采用 [MIT License](LICENSE) 授权。