# readpic MCP Server

通过 MCP 协议暴露 VL(Vision-Language)模型,让 AI 客户端(Claude Code / Claude 桌面版 / WorkBuddy)能直接理解、分析、描述本地图片。
图片识别模型所需连接信息可以从 onerouter dev 租户下的 vl 模型获取。

## 快速开始

readpic-mcp 通过 **npx** 分发,无需手动装 Python 依赖。首次启动时 shim 自动用 uv(或回退 venv)装 `fastmcp`/`httpx`,耗时数秒;之后走缓存秒启。

### 在 MCP 客户端配置

**Claude Code(CLI):**

```bash
claude mcp add readpic -s user \
  -e READPIC_API_URL=https://openapi-ai.cmaiot.cn/v1 \
  -e READPIC_API_KEY=sk-... \
  -e READPIC_MODEL=Qwen3-VL-8B-Instruct \
  -- npx -y github:tain-alphanume/readpic-mcp
```

**Claude 桌面版 / WorkBuddy**(`claude_desktop_config.json` 或 `mcp.json`):

```json
{
  "mcpServers": {
    "readpic": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "github:tain-alphanume/readpic-mcp"],
      "env": {
        "READPIC_API_URL": "https://openapi-ai.cmaiot.cn/v1",
        "READPIC_API_KEY": "sk-...",
        "READPIC_MODEL": "Qwen3-VL-8B-Instruct"
      }
    }
  }
}
```

> **固定版本**:args 改为 `["-y", "github:tain-alphanume/readpic-mcp#v0.1.0"]`(用 git tag)。
> **前置要求**:Node 18+(npx 自带);Python 3.10+ 或 uv(shim 自动探测)。

## 功能

- 将 PNG / JPG / JPEG / WEBP / GIF / BMP 图片发送给 VL 模型,返回文本描述
- 单模型调用,同步返回结果
- 支持自定义 prompt、system prompt、temperature、seed
- 支持 `response_format`(`json_object` / `json_schema`)做结构化输出
- API 地址、密钥、模型名均从环境变量读取,不内嵌凭据

## 环境变量

| 变量 | 必填 | 说明 |
|---|---|---|
| `READPIC_API_URL` | 是 | VL 模型 OpenAI 兼容 API 基址(如 `https://openapi-ai.cmaiot.cn/v1`) |
| `READPIC_API_KEY` | 是 | API 密钥(纯 `sk-...`,server 自动补 `Bearer ` 前缀;请勿自带前缀) |
| `READPIC_MODEL` | 是 | 模型名(如 `Qwen3-VL-8B-Instruct`) |

三项缺失任一,server 启动即报 `EnvironmentError`。

## MCP Tools

### `read_pic`

读取/理解一张或多张图片,返回 JSON 字符串。

| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `image_paths` | list[str] | 必填 | 本地图片路径(支持 PNG/JPG/JPEG/WEBP/GIF/BMP) |
| `prompt` | str | `请详细描述这张图片中的内容` | 给模型的文本指令 |
| `system_prompt` | str | `None` | 可选 system prompt |
| `temperature` | float | `None` | 采样温度 0.0-1.0(vLLM 默认 ~0.7) |
| `seed` | int | `None` | 随机种子(可复现) |
| `response_format` | dict | `None` | 透传 vLLM `response_format`,如 `{"type":"json_object"}` 或 `{"type":"json_schema","json_schema":{"name":"foo","schema":{...}}}` |

返回 JSON 结构:
```json
{
  "images": [
    {"path": "E:/tmp/demo.png", "size_kb": 12.3}
  ],
  "prompt": "请详细描述这张图片中的内容",
  "response_format": null,
  "mode": "single",
  "results": [
    {
      "image": "demo.png",
      "model": "Qwen3-VL-8B-Instruct",
      "success": true,
      "result": "图中为一只橘色猫咪,趴在木质桌面上...",
      "error": null
    }
  ]
}
```

多图时 `mode` 为 `"multi"`,`image` 为 `"all"`(所有图片一次性发给同一模型)。失败时 `success` 为 `false`、`result` 为 `null`、`error` 填错误信息。

> `results[].model` 取响应中的 `model` 字段(后端实际处理请求的模型名),响应缺该字段时回退到请求的 `READPIC_MODEL`。

## 运行时

- **uv 优先**:shim 自动 `uv run --with-requirements`,uv 管理 ephemeral venv + 缓存,二次启动快。
- **无 uv 回退 venv**:在 `~/.readpic-mcp/venv` 建独立 venv 并 `pip install -r requirements.txt`;依赖就绪后跳过安装(哨兵文件 `.installed` 标记)。
- Python 3.10+,Node 18+。

## 注册辅助脚本(install.py)

若不想手写 MCP 配置,可用 `install.py` 交互式收集 url/key/model 并自动注册到各宿主。
**install.py 不再安装依赖、不再拷贝 server.py**,仅做注册(command 已配置为 `npx -y github:tain-alphanume/readpic-mcp`)。

```bash
# clone 仓库后本地运行
git clone https://github.com/tain-alphanume/readpic-mcp.git
cd readpic-mcp/python
python install.py                 # 自动检测宿主
python install.py --host claude   # 指定 Claude Code
python install.py --host claude-desktop  # 指定 Claude 桌面版
python install.py --host workbuddy       # 指定 WorkBuddy
```

安装流程(两步):

1. **交互式输入** `READPIC_API_URL` / `READPIC_API_KEY` / `READPIC_MODEL`(回车采用默认值)
2. 按宿主类型注册 MCP 服务器,把三个变量写入 `env`

> install 脚本不内嵌凭据,每次安装时交互收集,避免源码泄露密钥。

## 支持平台

| 宿主 | `--host` | 注册方式 |
|---|---|---|
| Claude Code (CLI) | `claude` | `claude mcp add -s user` 自动注册 |
| Claude 桌面版 | `claude-desktop` | 自动写入 `claude_desktop_config.json`(深度合并) |
| WorkBuddy (腾讯) | `workbuddy` | 打印 JSON 配置 + GUI 操作指引 |
| 自动检测 | `auto` | 按优先级自动选择 |

**操作系统:** Windows、macOS、Linux

## 注意事项

- 单张图片上限 20 MB
- 模型调用为同步阻塞,超时 300s
- 多图调用时,所有图片一次性发给同一模型(不再做分布/对比分发)

## 许可

内部使用。