Huide Vision MCP

一个部署在 Cloudflare Workers 上的远程 MCP：让纯文本开发 Agent 通过 SenseNova 6.7 Flash-Lite 理解网页截图、报错截图和带标记截图。

它只暴露一个工具：analyze_development_image。

能做什么

• 网页截图：识别布局、遮挡、溢出、对齐与响应式异常，并给出可验证的 CSS / DOM 排查方向。
• 报错截图：提取可见错误、堆栈、路径、行号、状态码，再给出诊断。
• 标记截图：理解红框、箭头、圆圈与编号对应的目标和问题。
• 完整盘点：当问题包含“全部、逐一、清单、从上到下/从左到右”等要求时，本地适配器会将长图或密集图分成最多 6 张有重叠的切片，作为一次多图视觉请求按原始顺序盘点，避免遗漏和重复猜测。

工具只接受原图的 base64 Data URL（例如 data:image/png;base64,...）。不接受远程 URL，避免服务端替用户请求任意地址。

本地启动

npm install
cp .dev.vars.example .dev.vars
# 在 .dev.vars 中填入真实的两个 secret
npm run cf-typegen
npm run dev

本地端点：http://localhost:8787/mcp。所有 MCP 请求需带：

Authorization: Bearer <MCP_ACCESS_TOKEN>

部署到 Cloudflare

首次部署前，在项目目录交互式写入密钥；不要把密钥放进 wrangler.jsonc：

npx wrangler secret put SENSENOVA_API_KEY
npx wrangler secret put MCP_ACCESS_TOKEN
npm run deploy

随后在 Cloudflare Dashboard 为 Worker 配置自定义域名 vision.huidecode.com，MCP 地址为：

https://vision.huidecode.com/mcp

健康检查：https://vision.huidecode.com/health。

给其他人使用（生产客户端配置）

不要复制开发者电脑的绝对路径，也不要把服务端的 .dev.vars 或 SENSENOVA_API_KEY 发给客户端。每位使用者都应在自己的电脑创建独立的私有文件：

mkdir -p ~/.config/huide-vision-mcp
cp client.env.example ~/.config/huide-vision-mcp/client.env
# 编辑 client.env，只填服务管理员发放的 MCP_ACCESS_TOKEN

客户端默认读取 ~/.config/huide-vision-mcp/client.env，默认连接生产地址 https://vision.huidecode.com/mcp。也可用环境变量 HUIDE_MCP_ACCESS_TOKEN 提供令牌，不必建立文件。

Pi 的 ~/.pi/agent/huide-vision.json 可保持最简：

{
  "remoteUrl": "https://vision.huidecode.com/mcp"
}

先安装本地适配器：

npm install -g huide-vision-mcp

Claude Code 配置示例：

{
  "mcpServers": {
    "huide-vision": {
      "type": "stdio",
      "command": "huide-vision-mcp",
      "env": {
        "HUIDE_VISION_MCP_URL": "https://vision.huidecode.com/mcp"
      }
    }
  }
}

安装完成后，huide-vision-mcp 会成为系统命令；Claude Code 不需要克隆仓库、构建项目或填写任何本机路径。

当前授权限制： Worker 现在只校验一个 MCP_ACCESS_TOKEN。因此它适合你本人或受信任的小范围测试；如果要给不受控的外部用户长期使用，下一步应实现“每人一个、可单独撤销”的令牌机制或 Cloudflare Access，不能把你自己的共享令牌公开出去。

客户端注意事项

这是标准远程 Streamable HTTP MCP。客户端必须既支持远程 MCP，又支持把图片附件作为工具参数传入。若某个客户端在模型调用前就拒绝图片附件，MCP 无法拦截该附件；这是客户端能力边界。

客户端在调用工具时应传入原图，而不是文本描述：

{
  "image_data": "data:image/png;base64,...",
  "question": "红框中的按钮为什么会溢出容器？",
  "analysis_mode": "annotation_analysis"
}

Pi（文本模型）自动截图分析

Pi 的图片附件是内存中的 base64 数据，而本项目原有的 local-adapter 只允许读取 Claude Code 的附件路径。为避免 Pi 的文本模型因看不到图片而拒绝调用或猜测图片内容，本项目提供了 Pi 专用桥接扩展：它会在 Pi 收到图片时直接调用同一个 Worker，再把分析结果作为文本交给 Pi 模型。Worker 返回 401 或任何错误时，Pi 会中止该轮，而不是让文本模型继续猜图。

安装本项目的 Pi 扩展：

pi install npm:huide-vision-mcp

随后在 ~/.pi/agent/huide-vision.json 配置生产地址和你的项目访问令牌：

{
  "remoteUrl": "https://vision.huidecode.com/mcp",
  "accessToken": "你收到的 MCP_ACCESS_TOKEN"
}

若要测试本地 Worker，可把 remoteUrl 临时改为本机地址。生产环境中，在 Pi 粘贴或拖入开发截图即可；Pi 终端会输出 [Huide Vision] analyzing ...、成功或失败日志。

验证

npm run check
npm test