mimo-vision-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概览

mimo-vision-mcp 是一个 MCP Server：用小米 MiMo v2.5 多模态模型，为纯文本主模型（如 deepseek-v4-flash）补齐图像识别。主模型遇到图片时调用本 Server 的工具，Server 读图转 base64 调 MiMo OpenAI 兼容接口，返回纯文本描述。

常用命令

uv sync --dev                                          # 安装依赖（含 dev/pytest）
uv run python server.py                                # 启动 Server（stdio 传输，阻塞等待）
uv run --env-file .env pytest                          # 跑全部测试（离线 + 集成）
uv run --env-file .env pytest tests/test_image_utils.py -k test_too_large   # 单个测试
uv run --env-file .env pytest tests/test_api.py        # 真实 MiMo API 集成测试（无 key 自动 skip）

注册到 Claude Code（全局 user scope；--env-file 与 claude mcp add 不兼容，必须用 -e 显式传 env）：

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" -e "MIMO_MAX_TOKENS=2048" `
  "$PWD\.venv\Scripts\python.exe" "$PWD\server.py"

配置：复制 .env.example 为 .env 填 MIMO_API_KEY。普通 Key（sk-）走 https://api.xiaomimimo.com/v1；Token Plan（tp-）需把 MIMO_BASE_URL 改为 https://token-plan-cn.xiaomimimo.com/v1。视觉模型必须用 mimo-v2.5（mimo-v2.5-pro 是纯文本）。

架构

数据流：主模型 → MCP 工具（server.py）→ api_client.MimoClient.prepare_image() 读图 → POST /chat/completions → 文本返回。

四模块分层（每层职责单一，勿交叉）：

• config.py — 环境变量 → Config frozen dataclass；MIMO_API_KEY 必填（缺失时中文报错，不泄漏 token）。入口处 load_dotenv() 保证本地直接运行时也能读 .env。
• api_client.py — 唯一发 HTTP 的层。MimoClient（httpx async、Authorization: Bearer、指数退避重试、错误映射为 MimoError）；build_vision_message() 构造视觉消息；prepare_image() 调 image_utils。
• image_utils.py — 图片输入归一化：本地路径 / http(s) URL（下载转 base64，不透传任意 URL 给官方）/ file:// / data URL → data:image/...;base64,...；格式白名单 + 10MB 校验 + 魔数兜底。
• server.py — FastMCP 实例 + 4 工具（describe_image / analyze_images / extract_text_from_image / read_image_info）+ 1 资源（mimo://config）。工具层不直接碰 httpx。