# vision-analyzer 

**Repository Path**: stonelf/vision-analyzer

## Basic Information

- **Project Name**: vision-analyzer 
- **Description**: 一个提供精确视觉理解能力的mcp server
- **Primary Language**: JavaScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-05
- **Last Updated**: 2025-10-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Vision Analyzer MCP Server

一个提供精确视觉理解能力的 MCP (Model Context Protocol) 服务器，支持多种视觉分析功能。

## 功能特性

### 🖼️ 图片分析工具
- **analyze_image**: 通用图片内容分析
- **analyze_design_screenshot**: 设计截图分析，返回详细UI元素描述
- **extract_component_hierarchy**: 提取组件层次结构
- **get_exact_layout_specifications**: 获取精确布局规格
- **identify_visual_tokens**: 识别设计令牌（颜色、字体、圆角等）
- **analyze_design_with_precision**: 精确设计分析

### 🔍 图片对比工具
- **compare_image**: 快速对比两张图片，返回整体差异评分
- **compare_image_with_bounding_boxes**: 返回带坐标的差异框数组，可直接用于生成红色高亮overlay

### 🤖 LLM 模型管理
- **list_models**: 列出可用的视觉模型
- **use_model**: 切换使用的LLM模型
- **list_provider_models**: 列出指定服务商的所有模型

### ⚙️ 配置管理工具 (在 Claude Code 中直接配置)

#### 🔧 MCP配置工具 (新增)
- **check_config**: 检查当前配置状态，显示详细的服务商信息
- **config_provider**: 启动Web配置界面，完整的图形化配置管理
- **open_config_page**: 一键启动配置界面并自动打开浏览器

#### 📋 其他配置工具
实际项目中已移除部分传统配置工具，请优先使用Web配置界面进行配置管理。

#### 💡 推荐配置流程
1. 使用 `check_config` 检查当前配置状态
2. 如需配置，使用 `open_config_page` 一键启动配置界面
3. 完成配置后再次使用 `check_config` 确认配置成功

## 快速开始

### 🚀 一键配置（推荐）
```bash
npm run setup
```
运行交互式配置向导，引导您完成所有配置。

### 🔧 MCP配置 (新功能)
在Claude Code中直接使用MCP配置工具：
```
启动配置页面
```
无需离开对话环境即可完成配置。

### 📋 手动配置

#### 1. 安装依赖
```bash
npm install
```

#### 2. 配置环境变量
**简单方式：复制配置模板**
```bash
cp .env.example .env
```
然后编辑 `.env` 文件，填入您的实际 API 密钥。

**配置示例：**
```env
# 当前使用的模型 (格式: provider-model 或 provider)
current_provider_model=tencent

# 服务商列表
providers=["moonshot","tencent","zai"]

# Moonshot Configuration
moonshot={"base":"https://api.moonshot.cn/v1","api_key":"your-moonshot-api-key-here","models":["moonshot-v1-8k-vision-preview","moonshot-v1-32k-vision-preview","moonshot-v1-128k-vision-preview"]}

# 腾讯混元
tencent={"base":"https://api.hunyuan.cloud.tencent.com/v1","api_key":"your-tencent-api-key-here","models":["hunyuan-vision","hunyuan-turbo-vision","hunyuan-t1-vision","hunyuan-large-vision","hunyuan-turbos-vision-20250619","hunyuan-t1-vision-20250619","hunyuan-vision-7b-20250720","hunyuan-t1-vision-20250916"]}

# 智谱AI
zai={"base":"https://open.bigmodel.cn/api/paas/v4","api_key":"your-zhipu-api-key-here","models":["glm-4.5v","glm-4.5","glm-4.6"]}
```

**📖 获取 API 密钥：**
- 腾讯混元: https://console.cloud.tencent.com/hunyuan
- 智谱AI: https://open.bigmodel.cn/
- Moonshot: https://platform.moonshot.cn/

### 3. 验证配置
```bash
npm start
```
如果配置正确，您将看到配置成功的确认信息。

### 4. 测试服务器
```bash
npm run test:quick
# 或
node test-mcp.js
```

## 在 Claude Code 中使用

### 1. 配置 MCP 服务器
在 Claude Code 的设置中添加以下 MCP 服务器配置：

```json
{
  "mcpServers": {
    "vision-analyzer": {
      "type": "stdio",
      "command": "node",
      "args": [
        "index.js"
      ],
      "cwd": "/path/to/vision-analyzer",
      "auto_approve": [
        "analyze_image",
        "analyze_design_screenshot",
        "extract_component_hierarchy",
        "get_exact_layout_specifications",
        "identify_visual_tokens",
        "analyze_design_with_precision",
        "list_models",
        "use_model",
        "list_provider_models",
        "add_provider",
        "set_provider",
        "add_model_for_provider",
        "delete_model",
        "update_providers_list",
        "config_status",
        "config_provider",
        "switch_provider",
        "remove_provider",
        "provider_info"
      ],
      "env": {}
    }
  }
}
```

**配置说明：**
- `type: "stdio"`: 使用标准输入输出进行通信
- `command`: 运行 MCP 服务器的命令
- `args`: 服务器文件名（使用相对路径，因为设置了 cwd）
- `cwd`: MCP 服务器项目根目录（**请修改为你的实际路径**）
- `auto_approve`: 自动批准的工具列表，无需手动确认即可使用
- `env`: 环境变量配置（通常为空，因为服务器会读取项目根目录的 .env 文件）

**快速配置：**
项目根目录提供了多种配置文件，你可以选择使用：

1. **自动路径检测** (`auto-path-config.json` + `start-server.js`)：
```bash
# 修改 auto-path-config.json 中的路径后复制配置
# 启动脚本会自动检测项目根目录，无需设置 cwd
```

2. **基础模板** (`claude-config-template.json`)：
```bash
cp claude-config-template.json ~/.claude/claude_desktop_config.json
# 只需修改 cwd 中的路径为你本地的 vision-analyzer 项目路径
```

3. **多平台示例** (`claude-config-examples.json`)：
包含 macOS、Windows、Linux 的配置示例，选择适合你的配置并修改路径。

4. **相对路径配置** (`relative-path-configs.json`)：
提供多种相对路径配置方案，适用于不同的项目布局。

**优势：**
- **自动路径检测**：启动脚本自动找到项目根目录，最便携
- **环境变量正确加载**：确保 `.env` 文件能正确加载
- **多种配置方案**：支持不同使用场景和偏好
- **便于项目迁移**：减少硬编码路径，提高可移植性

### 2. 重启 Claude Code
重启 Claude Code 以加载新的工具。

### 3. 配置 API 密钥（推荐）
首次使用时，你可以直接在 Claude Code 会话中配置 API 密钥：

#### 查看配置状态
```
请检查当前的配置状态
```

#### 获取服务商信息
```
请告诉我如何注册和获取腾讯混元的API密钥
```

#### 配置服务商（支持以下服务商）
```
请帮我配置 moonshot 服务商，API密钥是 sk-xxxxx
```

支持的服务商：
- `moonshot` - 月之暗面
- `tencent` - 腾讯混元
- `zai` - 智谱AI

#### 切换服务商
```
请切换到 tencent 服务商
```

#### 删除服务商配置
```
请删除 moonshot 服务商的配置
```

### 4. 使用工具

#### 🔧 配置管理示例 (新增功能)
```
检查当前配置状态
启动配置页面
打开Web配置界面
```

#### 🖼️ 图片分析示例
```
请分析这个截图：[上传图片文件]
```

#### 🎨 设计分析示例
```
请提取这个设计的组件层次结构：[上传设计稿]
```

#### 🤖 模型管理示例
```
列出所有可用的视觉模型
切换到 zai 服务商的 glm-4.5v 模型
```

## 支持的服务商

目前支持以下 OpenAI 兼容的服务商：

- **腾讯混元** (hunyuan-vision, hunyuan-turbo-vision 等)
- **智谱AI** (glm-4.5v)
- **Moonshot** (moonshot-v1-8k)
- **其他 OpenAI 兼容的服务商**

## 开发和测试

### 运行完整测试套件
```bash
npm test
```

### MCP 功能单元测试

#### ⚠️ 重要说明：MCP 测试独立运行

**为什么 MCP 测试需要独立运行？**

MCP (Model Context Protocol) 功能的单元测试由于技术限制无法在主测试流程中运行，需要独立执行。主要原因包括：

1. **Jest Worker 进程冲突**
   - MCP 测试涉及复杂的 Mock 架构和异步操作
   - 在主测试流程中会导致 Jest Worker 进程崩溃
   - 错误：`Jest worker encountered 4 child process exceptions, exceeding retry limit`

2. **Mock 架构冲突**
   - 主测试流程：需要真实的 API 调用验证
   - MCP 测试：需要完全 Mock 的 analyze.js 模块
   - 两种 Mock 需求在同一个测试流程中不兼容

3. **全局状态污染**
   - 环境变量、模块状态在测试间相互干扰
   - MCP 测试要求完全隔离的测试环境

4. **依赖加载顺序问题**
   - Jest Mock 必须在模块首次导入前设置
   - 在主流程中 analyze.js 可能已被其他测试加载，导致 Mock 失效

#### 运行 MCP 单元测试

**MCP 处理器单元测试 (15个测试)**
```bash
npx jest --config jest.mcp-unit.config.js
```
测试内容：
- JSON-RPC 协议处理
- 工具调用处理
- 错误处理机制
- 请求验证

**MCP 服务器集成测试 (19个测试)**
```bash
npx jest --config jest.mcp-server.config.js
```
测试内容：
- handleMCPRequest 函数
- handleToolCall 函数
- MCP_TOOLS 常量验证
- 所有分析工具的集成测试

**总计：34个 MCP 核心功能测试**

#### 测试文件说明

- **mcp-handler.standalone.test.js**: 独立的 MCP 处理器测试
- **mcp.standalone.test.js**: 独立的 MCP 服务器测试
- **jest.mcp-unit.config.js**: MCP 处理器测试配置
- **jest.mcp-server.config.js**: MCP 服务器测试配置
- **test/mcp-setup.js**: MCP 测试专用环境设置

这些独立测试确保 MCP 功能的完整覆盖，同时不影响主测试套件的稳定性。

### 快速测试 MCP 服务器
```bash
node test-mcp.js
```

### 测试配置工具
```bash
node test-config-tools.js
```
测试新增的MCP配置工具功能。

### 启动 MCP 服务器 (用于调试)
```bash
node index.js
```

## 项目结构

```
vision-analyzer/
├── index.js                      # MCP 服务器主文件
├── start-server.js               # 智能启动脚本（自动检测项目根目录）
├── analyze.js                    # 核心视觉分析功能
├── test-mcp.js                   # MCP 服务器测试
├── package.json                  # 项目配置
├── auto-path-config.json         # 自动路径检测配置模板
├── claude-config-template.json   # Claude Code 基础配置模板
├── claude-config-examples.json   # 多平台配置示例
├── relative-path-configs.json    # 相对路径配置方案
├── .env                         # 环境变量配置
└── README.md                    # 项目说明
```

## 故障排除

### 常见问题

1. **模型调用失败**
   - 检查 `.env` 文件中的 API 密钥是否正确
   - 确认网络连接正常
   - 验证服务商 API 端点是否可访问

2. **MCP 服务器无法启动**
   - 确保所有依赖已正确安装
   - 检查 Node.js 版本 (建议 16+)
   - 运行 `node test-mcp.js` 进行诊断

3. **Claude Code 中看不到工具**
   - 确认 MCP 服务器配置路径正确
   - 重启 Claude Code
   - 检查服务器是否正常启动

4. **工具需要手动确认**
   - 检查 `auto_approve` 列表是否包含所需工具
   - 确认配置格式正确，特别是 JSON 语法
   - 重启 Claude Code 以应用新的 auto_approve 配置

5. **配置文件路径错误**
   - 确保 `cwd` 指向正确的 vision-analyzer 项目根目录
   - 确认项目根目录下存在 `index.js` 文件
   - 使用绝对路径配置 `cwd`，避免相对路径问题
   - 确保 `.env` 文件在项目根目录下

6. **环境变量加载失败**
   - 检查 `cwd` 是否正确设置为项目根目录
   - 确认 `.env` 文件存在且格式正确
   - 验证 API 密钥等配置是否有效
   - 运行 `node test-mcp.js` 进行环境检查

### 调试模式

启用详细日志输出：
```bash
DEBUG=* node index.js
```

## 贡献

欢迎提交 Issue 和 Pull Request！

## 许可证

ISC License