# dsh-vision-mcp

本地识图 MCP 服务器：给**任何** MCP 客户端的 agent 装上眼睛——DeepSeek Harness、Claude Desktop、Codex CLI、Cursor 通用。视觉大脑是你自己的 OpenAI 兼容视觉端点（默认对接本机 [chatgpt2api](https://github.com/basketikun/chatgpt2api)，也可指向任何标准 vision API），主模型无需自带视觉能力。

```
任意 MCP 客户端（stdio JSON-RPC）
        │
┌───────▼────────────────────┐    HTTP POST /v1/chat/completions
│ dsh-vision-mcp             │ ──────────────────────────────→ OpenAI 兼容视觉端点
│ analyze_image/extract_text/│     {image_url: dataURL}         （chatgpt2api :8000
│ compare_images             │                                   或任何标准 vision API）
└────────────────────────────┘
```

## 快速开始

```sh
git clone https://github.com/alwaysalone1/dsh-vision-mcp.git
cd dsh-vision-mcp
npm install && npm run build

# 环境体检：端点可达性 + key 校验 + 模型列表
export VISION_API_KEY='<你的 chatgpt2api auth-key>'
npm run doctor
```

## 接入各客户端

以下配置通用：`command` 跑构建产物，`env` 传入视觉后端的地址与 key。

**DeepSeek Harness**（`packages/mcp` 桥，一行 patch，工具名为 `mcp__vision__analyze_image` 等）：

```yaml
- insert:
    - id: vision-mcp
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: vision
        transport: stdio
        command: node
        args: ['D:/path/to/dsh-vision-mcp/dist/index.js']
        env:
          VISION_API_BASE: http://127.0.0.1:8000
          VISION_API_KEY: !!js process.env.VISION_API_KEY
```

**Claude Desktop / 通用 JSON**（`claude_desktop_config.json` 的 `mcpServers`，Cursor 的 `mcp.json` 同构）：

```json
{
  "mcpServers": {
    "dsh-vision": {
      "command": "node",
      "args": ["D:/path/to/dsh-vision-mcp/dist/index.js"],
      "env": {
        "VISION_API_BASE": "http://127.0.0.1:8000",
        "VISION_API_KEY": "<your-key>"
      }
    }
  }
}
```

**Codex CLI**（`~/.codex/config.toml`）：

```toml
[mcp_servers.dsh-vision]
command = "node"
args = ["D:/path/to/dsh-vision-mcp/dist/index.js"]
env = { "VISION_API_BASE" = "http://127.0.0.1:8000", "VISION_API_KEY" = "your-key" }
```

## 工具

| 工具 | 作用 | 参数 |
|---|---|---|
| `analyze_image` | 理解图片：描述内容、回答问题、定位界面元素（可问"红色按钮的坐标"） | `source`、`prompt?`、`model?` |
| `extract_text` | OCR：按原始排版提取全部文字（代码/公式/多语言） | `source`、`model?` |
| `compare_images` | 对比两张图片的相同与不同 | `sourceA`、`sourceB`、`prompt?`、`model?` |

`source` 四种写法任选：本地文件路径（如 `C:/shots/1.png`）、`http(s)://` 图片 URL、`data:image/png;base64,...`、裸 base64。格式按**文件头魔数**判定（PNG/JPEG/GIF/WebP/BMP），不看扩展名。

## 模型选择

默认使用 **`gpt-5-6`**（账号池里最强的推理+视觉对话模型）。三种调整方式：

- 每次调用传 `model` 参数临时覆盖（如 `gpt-5-6-mini` 省额度）；
- 全局默认：环境变量 `VISION_MODEL`（如设为 `auto` 交由后端路由）；
- 注意 `gpt-image-2` 是**生图**模型，不用于识图。

## 配置（环境变量）

| 变量 | 默认 | 说明 |
|---|---|---|
| `VISION_API_KEY` | 必填 | 视觉后端的 Bearer key（chatgpt2api 的 `config.json` → `auth-key`） |
| `VISION_API_BASE` | `http://127.0.0.1:8000` | OpenAI 兼容端点地址 |
| `VISION_MODEL` | `gpt-5-6` | 全局默认模型 |
| `VISION_TIMEOUT_MS` | `120000` | 单次请求硬超时（账号池繁忙时可调大） |
| `VISION_MAX_IMAGE_BYTES` | `20971520` | 单图字节上限（编码前） |
| `VISION_MAX_RETRIES` | `2` | 传输错误/429/5xx 的重试次数（退避递增） |

## 排障

- **`token_expired`** —— 账号池上游 token 过期：到 chatgpt2api 面板刷新/重登账号（配置里有 `auto_relogin_after_refresh`）。
- **HTTP 502 / TLS connect error** —— 池子的上游代理（WARP/Privoxy）不健康：检查 chatgpt2api 的稳定代理运行时面板。
- **HTTP 401** —— `VISION_API_KEY` 与后端 `auth-key` 不一致。
- **请求超时** —— 调大 `VISION_TIMEOUT_MS`；池子空闲时通常 10-30 秒内返回。
- **格式不识别** —— 图片按文件头判定；损坏或非图片文件会被拒绝。

## 隐私与边界

- 发给视觉端点的图片会到达其后端模型（默认为你自己的 chatgpt2api 账号池→ChatGPT）：**不要用公共 vision API 处理敏感截图**。
- 本服务器只做工具桥接：无状态、不落盘、不写日志文件（诊断仅到 stderr）。

## 开发

```sh
npm run typecheck   # 严格模式类型检查
npm run build       # 产物到 dist/
npm run smoke       # 真实 stdio 端到端冒烟（需 VISION_API_KEY + 测试图）
npm run doctor      # 环境体检
```

## 许可

[MIT](LICENSE)