# vision-mcp-ms

云端视觉 MCP 服务：通过 **OpenAI 兼容接口**（默认硅基流动 SiliconFlow）分析图片，
为 DeepSeek 这类纯文本大模型提供「看图」能力。

- 单一工具 `analyze_image(image, prompt)`
- 支持 HTTP(S) 图片 URL 和 base64 data URL
- 多模型按顺序自动 fallback（限流 / 超时 / 5xx 时切下一个）
- 纯 API 调用、不依赖本地环境，**可部署到魔搭 MCP 广场云端托管**

## 环境变量

| 变量 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `OPENAI_API_KEY` | 是* | - | API Key（也兼容 `SILICONFLOW_API_KEY` / `API_KEY`） |
| `OPENAI_BASE_URL` | 否 | `https://api.siliconflow.cn/v1` | OpenAI 兼容接口地址 |
| `VISION_MODELS` | 否 | `Qwen/Qwen2.5-VL-7B-Instruct` | 逗号分隔的有序模型列表，靠前的优先 |
| `VISION_REQUEST_TIMEOUT_MS` | 否 | `60000` | 单次模型请求超时（毫秒） |

\* 部署时在魔搭 / MCP 客户端的 env 里配置。

## 本地使用（stdio）

在 MCP 客户端（Cherry Studio 桌面版等）里添加：

```json
{
  "mcpServers": {
    "vision-mcp-ms": {
      "command": "uvx",
      "args": ["vision-mcp-ms"],
      "env": {
        "OPENAI_API_KEY": "sk-你的硅基流动Key",
        "OPENAI_BASE_URL": "https://api.siliconflow.cn/v1",
        "VISION_MODELS": "Qwen/Qwen2.5-VL-7B-Instruct,Qwen/Qwen2.5-VL-72B-Instruct"
      }
    }
  }
}
```

> 本地 stdio 模式下，`image` 参数也支持**本地文件绝对路径**（如 `D:\Pictures\a.png`）。
> 云端托管模式下仅支持 URL / data URL（服务端读不到你的本地文件）。

## 开发 / 测试

```bash
uv sync                     # 建环境
uv run python -m vision_mcp # 以 stdio 模式启动
uv run python -c "from vision_mcp.server import _to_data_url; print(_to_data_url('https://httpbin.org/image/jpeg')[:40])"
```

## 发布到 PyPI

```bash
cd vision-mcp-ms
uv run python -m build
uv run twine upload dist/*.whl
```

## 部署到魔搭 MCP 广场（云端托管）

1. 把代码推到 GitHub 仓库（或发布到 PyPI 后）。
2. 打开 <https://www.modelscope.cn/mcp/servers/create?template=customize>
3. 托管类型选「**可托管部署**」，来源选你的 GitHub 仓库 / PyPI 包。
4. 配置 `command` / `args`（如 `uvx` / `vision-mcp-ms`），在 env 里填
   `OPENAI_API_KEY`、`OPENAI_BASE_URL`、`VISION_MODELS`。
5. 创建后魔搭会自动部署，得到一个 HTTP 地址，填入手机 MCP 客户端即可。