Metadata-Version: 2.4
Name: vision-bridge-mcp
Version: 0.1.0
Summary: MCP Server：用 MiniMax 多模态模型把图片解析成文字描述，供 DeepSeek 等纯文本模型使用
License: MIT
Keywords: mcp,minimax,vision,deepseek,图片识别,ocr
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp<2.0,>=1.2
Requires-Dist: python-dotenv>=1.0.0

# vision-bridge MCP Server

图片视觉桥接服务：当对话里出现图片时，先由 **MiniMax 多模态模型** 把图片解析成文字描述，
再交给 **DeepSeek（纯文本模型）** 继续推理。以 MCP Server 形式接入 ZCode / Trae 客户端。

> 📄 **给其他机器/其他人部署**：请参考 [INTEGRATION.md](./INTEGRATION.md)（通用集成文档）。
> 本文档描述的是本机已完成的配置。

```
用户发图 ──► ZCode/Trae (DeepSeek 对话) ──调用 MCP 工具──► vision-bridge ──► MiniMax 多模态
                                                                    ◄── 图片的文字描述 ──
         DeepSeek 基于文字描述继续回答 ◄────────────────────────────────────┘
```

## 提供的工具

| 工具 | 作用 |
|------|------|
| `analyze_image(image?, question?)` | 图片理解：返回图片内容的文字描述，或回答关于图片的具体问题 |
| `extract_text_from_image(image?, language?)` | 图片 OCR：按原始顺序提取图中所有文字（标题/正文/按钮/水印等） |

`image` 参数支持：本地文件路径、`http(s)` 链接、base64 data URI。
**也可以不传**：工具会自动定位用户在当前 ZCode 会话中最新上传的图片附件
（`~/.zcode/cli/artifacts/<session>/prompt-attachment-upload-*.txt`，毫秒级定位）。
定位逻辑：ZCode 的 UserPromptSubmit hook 会把当前会话 id 写入
`~/.zcode/vision-inbox/current-session.txt`，server 据此**只扫当前会话目录**，
不受其他会话干扰；当前会话无附件时才兜底取全局最新。

## 安装

```bash
cd /Users/wjc/mcp-vision-server
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/pip install -e .          # 生成本机 vision-bridge 命令（editable，改代码即时生效）
```

## 配置 API Key

`.env` 有两个位置（server 启动时会依次加载，环境变量优先级最高）：

1. **当前工作目录**的 `.env` —— 本地开发（本机已配置）
2. **`~/.config/vision-bridge/.env`** —— 全局配置，**推荐**：MCP 客户端启动 server 时
   cwd 通常是工作区而非项目目录，放这里任何场景都能加载（本机已配置）

```ini
MINIMAX_API_KEY=你的密钥
MINIMAX_GROUP_ID=      # 国内版 (api.minimax.chat) 必填；国际版 (api.minimaxi.com) 留空
MINIMAX_BASE_URL=https://api.minimax.chat/v1   # 国际版改为 https://api.minimaxi.com/v1
MINIMAX_MODEL=MiniMax-M2                        # 按你账号开通的模型调整（如 MiniMax-M3）
```

> 密钥只放 `.env`，不要提交到 git（已加入 `.gitignore`）。

## 接入 ZCode（已完成注册）

已写入 `~/.zcode/cli/config.json`（使用安装生成的 `vision-bridge` 命令，无需关心项目路径）：

```json
{
  "mcp": {
    "servers": {
      "vision-bridge": {
        "command": "/Users/wjc/mcp-vision-server/.venv/bin/vision-bridge",
        "args": []
      }
    }
  }
}
```

**重启 ZCode 后**在「设置 → MCP」中应能看到 vision-bridge 已连接。也可以在那里检查/修复配置。

### 会话精确匹配 hook（已配置）

`~/.zcode/cli/config.json` 中还注册了一个 `UserPromptSubmit` hook：每次用户提交消息时，
把当前会话 id 写入 `~/.zcode/vision-inbox/current-session.txt`（供 server 定位附件时
按当前会话精确匹配，不受其他会话干扰）：

```json
{
  "hooks": {
    "enabled": true,
    "events": {
      "UserPromptSubmit": [
        {
          "matcher": ".*",
          "hooks": [
            {
              "type": "process",
              "command": "/bin/sh",
              "args": [
                "-c",
                "mkdir -p \"$HOME/.zcode/vision-inbox\" && printf '%s' \"$ZCODE_SESSION_ID\" > \"$HOME/.zcode/vision-inbox/current-session.txt\""
              ],
              "timeoutMs": 5000
            }
          ]
        }
      ]
    }
  }
}
```

> 无 hook 时功能也可用（退化为全局最新附件），只是多会话并发时可能取到其他会话的图。

## 接入 Trae

1. 打开 Trae → **设置** → **MCP Servers**（或 模型设置 → MCP）
2. 添加服务器：
   - Name：`vision-bridge`
   - Command：`/Users/wjc/mcp-vision-server/.venv/bin/vision-bridge`
   - Args：（空）
3. 确认连接状态为已连接

> Trae 也支持 CLI：`trae-cli mcp add`，或在项目根目录添加 `.mcp.json`（`mcpServers` 键）后自动发现。

## 让 DeepSeek 知道要"先看图"（关键一步）

DeepSeek 是纯文本模型，需要提示它主动调用工具。把下面这段加入你的全局指令：

- **ZCode**：写入 `~/.zcode/AGENTS.md`
- **Trae**：设置 → 自定义规则（Custom Rules）

```markdown
当用户在对话中发送图片、或询问图片相关问题时：
1. 直接调用 analyze_image（或 extract_text_from_image）工具，不要传 image 参数，
   工具会自动读取用户刚上传的图片并返回文字描述；
2. 再基于返回的描述回答用户，不要编造图中没有的内容。
```

## 验证

```bash
cd /Users/wjc/mcp-vision-server
.venv/bin/python smoke_test.py     # 连接并列出工具
```

## 常见问题

- **提示缺少 MINIMAX_API_KEY**：`.env` 里填好密钥后重启客户端。
- **国内版报 401**：确认 `MINIMAX_GROUP_ID` 已填写（国内版必须带 GroupId 请求头）。
- **换模型**：`MINIMAX_MODEL` 改成你账号实际开通的多模态模型名（如 `MiniMax-M3`）。
- **图片传不进去**：客户端传的图片通常是本地临时文件路径，工具会自动转 base64；若客户端传的是 URL 也支持。
