web-analyzer-mcp

v1.2.7

Published

6 months ago

基于MCP协议的网页界面分析工具，使用OpenAI Vision AI智能解析页面布局和UI元素

Downloads

0High
0Medium
0Low

zpzhaoa

mcp openai screenshot web-analysis vision-api layout-detection

页面截图解析MCP工具

一个基于npx运行的本地MCP（Model Context Protocol）工具，支持传入WEB页面截图文件路径，通过OpenAI的API进行图片解析，返回页面基本布局区域和其中的页面要素信息。

功能特性

🖼️ 截图解析：支持PNG、JPG、JPEG格式的网页截图文件
🧠 AI驱动：使用OpenAI GPT-4 Vision API进行智能图片分析
🎯 布局识别：自动识别页面中的导航栏、侧边栏、内容区、页脚等布局区域
🔍 要素提取：识别并提取页面中的按钮、表单、文本、图片等页面要素
📄 DOCX图片提取：从Word文档中提取所有图片并保存为独立文件
⚙️ 灵活配置：支持通过环境变量配置OpenAI baseURL和API Token
🚀 零安装：基于npx运行，无需全局安装
📊 结构化输出：返回JSON格式的结构化布局信息
🛠️ 双重接口：支持CLI命令和MCP服务器两种使用方式
✨ 参数统一：CLI参数命名与schema定义保持一致，提升使用体验

技术栈

核心依赖

TypeScript：提供类型安全和更好的开发体验
@modelcontextprotocol/sdk：MCP协议官方SDK
openai：OpenAI官方Node.js客户端
zod：运行时类型验证和JSON Schema生成
mammoth：DOCX文档解析和图片提取
commander：命令行接口构建

开发工具

esbuild：快速TypeScript构建和打包
tsx：TypeScript执行环境（开发时使用）
@types/node：Node.js类型定义

运行环境

Node.js：≥18.0.0
npx：npm 5.2+ 内置工具

快速开始

环境准备

设置OpenAI配置环境变量：

# 必需：OpenAI API Token
export OPENAI_API_KEY="your-openai-api-key"

# 可选：自定义OpenAI API Base URL（默认：https://api.openai.com/v1）
export OPENAI_BASE_URL="https://your-custom-openai-endpoint.com/v1"

Windows系统：

set OPENAI_API_KEY=your-openai-api-key
set OPENAI_BASE_URL=https://your-custom-openai-endpoint.com/v1

使用方法

安装

#安装或更新到最新版本
npm install -g web-analyzer-mcp@latest

作为MCP服务器使用

在支持MCP的客户端中配置：

{
  "mcpServers": {
    "webpage-screenshot-analyzer": {
      "command": "npx",
      "args": ["web-analyzer-mcp", "server"],
      "env": {
        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY",
        "OPENAI_BASE_URL": "https://api.openai.com/v1"
      }
    }
  }
}

命令行使用

网页截图分析：

# 直接运行
npx web-analyzer-mcp analyze --image ./screenshot.png

# 开发模式运行
git clone https://github.com/lyra-ai/web-analyzer-mcp.git
cd web-analyzer-mcp
npm install
npm run dev -- analyze --image ./test-screenshot.png

DOCX图片提取：

# 提取Word文档中的所有图片
npx web-analyzer-mcp extract-docx-images --docx ./document.docx --output ./images

# 自定义图片文件名前缀
npx web-analyzer-mcp extract-docx-images --docx ./report.docx --output ./output --prefix report_image

输入输出格式

网页截图分析

输入参数

imagePath: 截图文件路径（必需）
model: OpenAI模型名称（可选，默认：gpt-4o）

输出格式

{
  "layout": {
    "navigation": {
      "bounds": {"x": 0, "y": 0, "width": 1920, "height": 60},
      "type": "header",
      "elements": [...]
    },
    "sidebar": {
      "bounds": {"x": 0, "y": 60, "width": 250, "height": 900},
      "type": "sidebar",
      "elements": [...]
    },
    "content": {
      "bounds": {"x": 250, "y": 60, "width": 1670, "height": 800},
      "type": "main",
      "elements": [...]
    },
    "footer": {
      "bounds": {"x": 0, "y": 860, "width": 1920, "height": 100},
      "type": "footer",
      "elements": [...]
    }
  },
  "elements": [
    {
      "type": "button",
      "text": "提交",
      "bounds": {"x": 300, "y": 200, "width": 100, "height": 40},
      "attributes": {"color": "#007bff", "style": "primary"}
    },
    {
      "type": "text",
      "content": "欢迎使用我们的服务",
      "bounds": {"x": 300, "y": 150, "width": 200, "height": 30},
      "attributes": {"fontSize": "16px", "fontWeight": "bold"}
    }
  ]
}

#### DOCX图片提取

**输入参数**
- `docxPath`: DOCX文件路径（必需）
- `outputDir`: 输出目录路径（必需）
- `prefix`: 图片文件名前缀（可选，默认："image"）

**输出格式**
```json
{
  "success": true,
  "extractedImages": 5,
  "outputDirectory": "./images",
  "imageFiles": [
    {
      "originalName": "image1.png",
      "savedPath": "./images/image_1.png",
      "format": "png",
      "width": 800,
      "height": 600,
      "size": "245KB"
    },
    {
      "originalName": "image2.jpg",
      "savedPath": "./images/image_2.jpg",
      "format": "jpeg",
      "width": 1200,
      "height": 800,
      "size": "342KB"
    }
  ]
}

项目结构

web-analyzer-mcp/
├── src/
│   ├── index.ts                    # 主入口文件
│   ├── server.ts                   # MCP服务器实现
│   ├── tools/
│   │   ├── analyze.ts              # 网页截图分析工具
│   │   └── extract-docx-images.ts  # DOCX图片提取工具
│   ├── utils/
│   │   ├── docx-parser.ts         # DOCX解析核心模块
│   │   ├── image.ts               # 图片处理工具
│   │   └── openai.ts              # OpenAI API封装
│   │   └── extract-docx-images.ts  # DOCX图片提取工具
│   ├── types/
│   │   └── schema.ts               # TypeScript类型定义
│   └── utils/
│       ├── openai.ts               # OpenAI客户端封装
│       ├── image.ts                # 图片处理工具
│       └── docx-parser.ts          # DOCX解析工具
├── package.json
├── tsconfig.json
├── README.md
└── .gitignore

版本历史

v1.2.2 (2025-03-03)

✨ 新增: 完整的日志记录系统，支持MCP服务器和CLI工具的详细操作日志
🔧 优化: 修复TypeScript类型错误和ESM模块导入问题
📝 更新: 完善README文档，添加DOCX图片提取的详细说明
✅ 测试: 验证CLI和MCP两种模式下的图片提取功能

v1.2.1 (2025-01-31)

🐛 修复: DOCX图片提取功能在MCP服务器中的异步处理问题
🔧 优化: 改进mammoth库的图片提取逻辑，确保所有图片都能正确提取

v1.2.0

✨ 新增: DOCX图片提取功能
🎯 支持: 从Word文档中提取所有图片并保存为独立文件
🔧 配置: 支持自定义输出目录和文件名前缀

开发指南

本地开发

克隆项目：

git clone https://github.com/lyra-ai/web-analyzer-mcp.git
cd web-analyzer-mcp

安装依赖：

npm install

设置环境变量：

cp .env.example .env
# 编辑 .env 文件，填入你的OpenAI配置

开发模式运行：

npm run dev -- analyze --image ./test-screenshot.png

构建项目：

npm run build

发布流程

更新版本号：

npm version patch|minor|major

构建并发布：

npm run build
npm publish

贡献指南

欢迎提交Issue和Pull Request！

开发规范

使用TypeScript进行开发
遵循ESLint代码规范
添加必要的单元测试
更新README文档

提交规范

使用清晰的提交信息
关联相关Issue
提供详细的变更说明

许可证

MIT License - 详见 LICENSE 文件

支持与联系

项目地址：https://github.com/lyra-ai/web-analyzer-mcp
问题反馈：https://github.com/lyra-ai/web-analyzer-mcp/issues
邮件联系：[email protected]