mcp-page-vision

README

mcp-page-vision

基于 MCP（Model Context Protocol）的网页截图视觉分析服务。接入 OpenAI 兼容的视觉模型，将网页截图解析为结构化的文字描述，供下游 Agent 生成代码。

功能

• 截图分析：接收网页截图，通过视觉模型输出详细的页面结构和 UI 组件描述
• 两种输入方式：
  • analyze_screenshot — Base64 编码的图片数据
  • analyze_screenshot_url — 远程图片 URL
• 双传输模式：支持 stdio 和 SSE 两种 MCP 传输协议
• 兼容 OpenAI 协议：支持任意兼容 OpenAI Vision API 的服务（GPT-4o、Claude 等）

安装

go install github.com/241x/mcp-page-vision@latest

或指定版本：

go install github.com/241x/mcp-page-vision@v0.0.1

快速开始

1. 配置环境变量

export OPENAI_API_KEY="sk-xxxxxxxx"

2. 配置 MCP Client

在 Claude Desktop / Cursor / VS Code 等 MCP 客户端中添加：

{
  "mcpServers": {
    "page-vision": {
      "command": "mcp-page-vision",
      "env": {
        "OPENAI_API_KEY": "sk-xxxxxxxx"
      }
    }
  }
}

3. 使用

Agent 可调用以下两个工具：

analyze_screenshot — 分析 Base64 截图

{
  "name": "analyze_screenshot",
  "arguments": {
    "image_base64": "iVBORw0KGgo..."
  }
}

analyze_screenshot_url — 分析远程截图

{
  "name": "analyze_screenshot_url",
  "arguments": {
    "image_url": "https://example.com/screenshot.png"
  }
}

配置项

环境变量	默认值	说明
OPENAI_API_KEY	—	（必填）API Key
OPENAI_BASE_URL	—	API 地址，兼容第三方服务
VISION_MODEL	gpt-4o	视觉模型名称
MCP_TRANSPORT	stdio	传输协议：stdio 或 sse
MCP_SSE_ADDR	:8080	SSE 监听地址
LOG_LEVEL	info	日志级别：debug/info/warn/error
LOG_FILE	logs/mcp-page-vision.log	日志文件路径

SSE 模式

export MCP_TRANSPORT=sse
export MCP_SSE_ADDR=127.0.0.1:8080
mcp-page-vision

兼容第三方 API

export OPENAI_BASE_URL="https://api.openai.com/v1"
export VISION_MODEL="gpt-4o-mini"

项目结构

.
├── main.go                  # 入口
├── internal/
│   ├── config/              # 配置加载 & 校验
│   ├── image/               # 图片获取（Base64 解码 / URL 下载）
│   ├── vision/              # 视觉模型客户端
│   ├── tool/                # MCP 工具定义 & 处理
│   └── server/              # MCP Server 组装 & 启动

运行测试

# 单元测试
go test ./...

# 集成测试
go test -tags=integration ./...

许可

MIT License