dsh-vision

支持 OpenAI 协议的 vision MCP 服务器：为 dsh 及其他 harness 提供视觉理解工具。图片/视频/文档理解通过任意 OpenAI 兼容的 chat-completions 端点完成，默认指向智谱 GLM 视觉模型。

• 工具：vision_analyze（图片/图表问答）、vision_ocr（文字提取）、vision_video（视频理解）、vision_document（文档问答）

• 输入支持：http(s) URL、本地文件路径、file:// URI、data:...;base64,... URI

• 传输：stdio（harness 默认）与 streamable-http（远程/Web 场景）

• 后端：OpenAI 协议 chat-completions；图片走标准 image_url，视频/文档/思考链为智谱扩展（见下方兼容性说明）

安装

git clone <repo> dsh-vision
cd dsh-vision
uv sync                 # 建 .venv 并安装依赖

Related MCP server: glm-vision-mcp

配置（环境变量）

运行

# stdio（harness 用）
$env:VISION_API_KEY = "<你的智谱 API Key>"
uv run dsh-vision                          # 或 .venv\Scripts\dsh-vision.exe

# streamable-http
uv run dsh-vision --transport streamable-http --host 127.0.0.1 --port 8000

工具用法

vision_analyze — 图片/图表问答

vision_ocr — 文字提取

vision_video — 视频理解

vision_document — 文档问答

智谱端点的文档走文件解析服务：本地/URL 文档先经解析器（lite 免费 / expert / prime，见配置）提取文本，再把文本与问题一起交给模型回答；扫描版 PDF 建议把 VISION_DOC_TOOL_TYPE 设为 expert（带 OCR）。其他 OpenAI 兼容端点使用通用 file_url 内容块直传。

失败时工具返回 [vision error] ... 文本而不是让 MCP 会话报错，方便模型自行修正重试。

兼容性说明

• ✅ 已实测：智谱 GLM —— glm-4v-plus（图片/视频）、glm-4.6v（文档、复杂图表、thinking），均用真实图片、视频和数学建模竞赛 PDF 验证过。

• ⚠️ 尚未用其他供应商测试：OpenAI、DeepSeek、Qwen/DashScope、本地 vLLM 等只是按 OpenAI 协议实现，没有实测。其中：

  • 图片理解（vision_analyze/vision_ocr）走标准 image_url，兼容性预期较好；

  • video_url、file_url 内容块与 thinking 参数是智谱对 OpenAI 协议的扩展，其他供应商可能不支持或格式不同，使用前请先验证；

  • 智谱端点下 vision_document 使用智谱文件解析服务（非 OpenAI 协议），仅适用于 bigmodel.cn 的 base_url。

• 欢迎在其他供应商上测试后反馈结果（issue/PR）。

接入 dsh

在 harness 的 MCP 配置中注册 stdio 服务器：

command: .venv\Scripts\dsh-vision.exe   # 或 uv run --directory <项目路径> dsh-vision
env:
  VISION_API_KEY: "<你的智谱 API Key>"

（具体写入位置按 dsh-mcp-install 技能 / harness 文档执行。）

开发

uv run pytest            # 单元测试 + stdio 端到端冒烟
uv build                 # 打包 wheel

端到端脚本（需要智谱 API Key）：

uv run python scripts/e2e_zhipu.py --mcp          # 图片链路
uv run python scripts/e2e_media.py                # 视频/文档/图表思考链路

测试智谱视觉模型

1. 到 open.bigmodel.cn 创建 API Key

2. 设置 VISION_API_KEY 后启动服务器

3. 调用工具，例如：

{"images": ["https://example.com/photo.png"], "prompt": "描述图片内容"}
{"videos": ["C:\\videos\\clip.mp4"], "prompt": "总结这个视频"}
{"files": ["https://example.com/report.pdf"], "prompt": "总结要点", "model": "glm-4.6v"}