# deepseek-vision-mcp

给 DeepSeek（以及 Codex、Claude Desktop、Cursor 等 MCP 客户端）增加“看图”能力的服务。

DeepSeek 的文本模型不接受图片输入。本项目把设计稿/UI 截图交给 Hugging Face 在线服务或本地 Ollama 上的开源视觉模型，返回结构化文字规格，再由 DeepSeek 或 Codex 完成前端代码实现。

## 特性

- MCP 工具：`analyze_design`（设计稿 → 结构化规格/代码）、`ask_vision`（通用图片问答）
- CLI 模式：不接 MCP 也能把图片转成文字
- Codex Skill + 一键安装脚本
- 配置通过 `.env` / 环境变量管理，不写死在代码里
- 兼容 Hugging Face Router、OpenRouter 等 OpenAI 兼容接口
- 本地 Ollama 原生支持，自动处理 Qwen3-VL 思考版 `/no_think`

## 工作原理

```text
设计稿图片
   │
   ▼
deepseek-vision MCP 服务（本仓库）
   │  通过 OpenAI 兼容接口发送图片
   ▼
开源视觉模型（Hugging Face 或本地 Ollama，默认 Qwen3-VL-8B）
   │  返回结构化设计规格 / 代码草稿
   ▼
DeepSeek 或 Codex 拿到文字结果，结合项目写最终代码
```

## 推荐模型

| 模型 | 许可证 | 适合场景 | 说明 |
| --- | --- | --- | --- |
| `Qwen/Qwen3-VL-8B-Instruct` | Apache-2.0 | 设计稿识别、OCR、界面理解、转代码 | 推荐默认，8B 尺寸在 API 和本地都实用 |
| `Qwen/Qwen2.5-VL-7B-Instruct` | Apache-2.0 | 成熟稳定的替代方案 | 各托管平台支持更广，作为兜底 |
| `ByteDance-Seed/UI-TARS-1.5-7B` | Apache-2.0 | GUI 理解、元素定位、UI 自动化 | 偏向“看界面并操作”，写代码不如 Qwen-VL |
| `Qwen/Qwen3-VL-4B-Instruct` | Apache-2.0 | 本地轻量运行 | 量化后占用小，适合内存有限的机器 |

## 本地 Ollama

无需 API Key。先启动 Ollama 并拉取模型：

```bash
ollama serve
ollama pull qwen3-vl:8b
```

在 `.env` 中启用本地 Ollama：

```dotenv
VISION_PROVIDER=ollama
OLLAMA_API_BASE=http://127.0.0.1:11434
OLLAMA_MODEL=qwen3-vl:8b
```

测试：

```bash
node cli.js examples/sample-design.png --mode spec --stack html+css
```

`qwen3-vl:8b` 是思考版，服务会自动应用 `/no_think` workaround，避免 token 被思考过程占满后返回空内容。追求更快更稳定可以：

```bash
ollama pull qwen3-vl:8b-instruct
```

然后把 `OLLAMA_MODEL` 改成 `qwen3-vl:8b-instruct`。

本地推理较慢时，Ollama 路径默认超时为 300 秒，可继续用 `VISION_TIMEOUT_MS` 调整。

## 快速开始

```bash
git clone <你的仓库地址>
cd deepseek-vision-mcp
npm install
cp .env.example .env
```

编辑 `.env`。使用在线服务时至少设置 `HF_TOKEN` 或 `VISION_API_KEY`；只使用本地 Ollama 时按上面「本地 Ollama」配置即可。然后测试：

```bash
node cli.js examples/sample-design.png --mode both --stack html+css
```

## 配置说明

| 变量 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `HF_TOKEN` | 与 `VISION_API_KEY` 二选一 | 无 | Hugging Face Token |
| `VISION_API_KEY` | 与 `HF_TOKEN` 二选一 | 无 | OpenAI 兼容服务的 API Key |
| `VISION_PROVIDER` | 否 | `auto` | 服务类型：`auto` / `openai` / `ollama` |
| `VISION_API_BASE` | 否 | `https://router.huggingface.co/v1` | OpenAI 兼容 API 地址 |
| `VISION_MODEL` | 否 | `Qwen/Qwen3-VL-8B-Instruct` | 视觉模型 ID |
| `OLLAMA_API_BASE` | Ollama 时 | `http://127.0.0.1:11434` | Ollama 服务地址 |
| `OLLAMA_MODEL` | 否 | `qwen3-vl:8b` | Ollama 视觉模型 |
| `VISION_PROXY` | 否 | 无 | 代理地址，例如 `http://127.0.0.1:7890` |
| `VISION_TIMEOUT_MS` | 否 | `120000`（Ollama 默认 `300000`） | 请求超时（毫秒） |
| `VISION_MAX_TOKENS` | 否 | `8192` | 最大输出 token |

所有配置都可以写在仓库根目录的 `.env`，服务会自动读取；也可以直接用环境变量覆盖。

## CLI 用法

```bash
node cli.js 设计稿.png --mode both --stack react+tailwind
node cli.js 设计稿.png --mode spec
node cli.js 截图.png --question "这个页面的主色和布局结构是什么？"
node cli.js 设计稿.png --provider ollama --model qwen3-vl:8b --mode both --stack vue3+tailwind
```

CLI 输出是纯文字，可以直接复制给 DeepSeek 官方 App / 网页版。

## MCP 接入（其他客户端）

Claude Desktop 的 `claude_desktop_config.json`：

```json
{
  "mcpServers": {
    "deepseek-vision": {
      "command": "node",
      "args": ["<项目绝对路径>/server.js"],
      "env": {
        "HF_TOKEN": "hf_xxx",
        "VISION_MODEL": "Qwen/Qwen3-VL-8B-Instruct"
      }
    }
  }
}
```

Cursor 的 `.cursor/mcp.json` 使用同样的结构。

Cherry Studio：设置 → MCP 服务器 → 添加，命令填 `node`，参数填 `server.js` 的绝对路径，环境变量同上。

本地 Ollama 的 MCP 环境变量示例：

```json
{
  "mcpServers": {
    "deepseek-vision": {
      "command": "node",
      "args": ["<项目绝对路径>/server.js"],
      "env": {
        "VISION_PROVIDER": "ollama",
        "OLLAMA_API_BASE": "http://127.0.0.1:11434",
        "OLLAMA_MODEL": "qwen3-vl:8b"
      }
    }
  }
}
```

## 接入 Codex

详细步骤见 [docs/CODEX.md](docs/CODEX.md)。一键安装：

```bash
bash scripts/install.sh
```

脚本会安装 npm 依赖、把 Codex Skill 安装到 `~/.codex/skills/`，并在本机有 `codex` CLI 时自动注册 MCP 服务。安装完成后重启 Codex，给一张设计稿图片说“按这张图实现前端”即可。

## 测试

```bash
npm test
```

仓库自带端到端冒烟测试，会启动 mock 视觉 API，验证 MCP 握手、工具注册和图片发送链路。

## 常见问题

- HTTP 401：`HF_TOKEN` / `VISION_API_KEY` 未配置或无效。
- 模型不可用：切换 `VISION_MODEL`，或更换 `VISION_API_BASE`（OpenRouter、Ollama 等）。
- 网络受限：设置 `VISION_PROXY`。
- 本地 Ollama 报连接失败：先运行 `ollama serve`。
- Ollama 返回内容为空：`qwen3-vl:8b` 思考版可能吃光 `VISION_MAX_TOKENS`，调大上限或改用 `qwen3-vl:8b-instruct`。
- DeepSeek 官方 App 不支持 MCP：用 CLI 把图片转成文字后粘贴，或使用支持 MCP 的客户端。

## License

MIT