# @visionengine/image-recognize

[![English](https://img.shields.io/badge/English-Click-yellow)](README.md)
[![中文文档](https://img.shields.io/badge/中文文档-点击查看-orange)](README-zh.md)

VisionEngine 图片识别 MCP 服务器 - 使用先进的 AI 视觉模型分析视觉设计元素、提取文字，并支持图片提示词反推。

## 功能特性

- **视觉设计分析** - 分析布局、色彩、字体、构图和设计原则
- **文字与数据提取** - 从图片中提取文字、表格、图表和结构化数据（OCR）
- **图片提示词反推** - 反推出生成该图片最可能使用的提示词
- **灵活的提示词** - 支持自定义提示词或使用智能默认提示
- **多种图片格式** - 支持 JPG、PNG、GIF、WebP

## 安装

### 作为 MCP 服务器使用

将以下配置添加到您的 MCP 客户端配置文件中：

```json
{
  "mcpServers": {
    "ve-image-recognize": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "@visionengine/image-recognize@latest"],
      "transport": "stdio",
      "env": {
        "BASE_URL": "https://api.visionengine-tech.com",
        "VEC_AI_API_KEY": "你的API密钥",
        "WORKDIR": "./public"
      }
    }
  }
}
```

### 作为 NPM 包安装

```bash
npm install -g @visionengine/image-recognize
```

## 配置

环境变量：

- `BASE_URL` - VisionEngine API 根地址（默认：https://api.visionengine-tech.com）
- `VEC_AI_API_KEY` - 您的 VisionEngine API 密钥（必需）
- `WORKDIR` - 相对图片路径的基础目录（默认：./）

## 工具说明

### visual - 视觉设计分析

分析图片中的视觉设计元素。

**参数：**
- `imagePath`（字符串，必需）- 图片文件路径（相对于 WORKDIR 或绝对路径）
- `prompt`（字符串，可选）- 自定义分析提示词

**默认分析内容：**
- 布局和构图
- 色彩搭配和配色方案
- 字体和排版
- 视觉层次
- 设计风格和特点
- 视觉焦点
- 设计原则的应用（如对比、平衡、对齐等）

**使用示例：**

```typescript
// 使用默认提示词
await visual({
  imagePath: "./design.png"
});

// 使用自定义提示词
await visual({
  imagePath: "./design.png",
  prompt: "分析这个网页设计的配色方案和视觉层次"
});
```

### text - 文字和数据提取

从图片中提取文字内容和数据信息。

**参数：**
- `imagePath`（字符串，必需）- 图片文件路径（相对于 WORKDIR 或绝对路径）
- `prompt`（字符串，可选）- 自定义提取提示词

**默认提取内容：**
- 所有文字内容（OCR 识别）
- 表格数据
- 图表数据
- 数字和统计信息
- 标签、标题、说明文字
- 其他结构化数据

**使用示例：**

```typescript
// 使用默认提示词
await text({
  imagePath: "./document.jpg"
});

// 使用自定义提示词
await text({
  imagePath: "./document.jpg",
  prompt: "提取图片中的所有表格数据，并转换为 Markdown 格式"
});
```

### prompt_reverse - 图片提示词反推

反推出生成该图片最可能使用的提示词。

**参数：**
- `imagePath`（字符串，必需）- 图片文件路径（相对于 WORKDIR 或绝对路径），或公网图片 URL
- `outputLanguage`（`"zh" | "en"`，可选）- 输出语言，默认 `en`
- `userPrompt`（字符串，可选）- 自定义补充要求
- `modelId`（字符串，可选）- 平台模型覆盖

**使用示例：**

```typescript
await prompt_reverse({
  imagePath: "./poster.png",
  outputLanguage: "en"
});
```

## 使用示例

### MCP 客户端

配置为 MCP 服务器后，可以通过 MCP 客户端使用这些工具：

```
> 对 screenshot.png 使用 visual 工具进行视觉分析
> 使用 text 工具从 invoice.jpg 中提取数据
```

### 直接使用

```bash
# 全局安装
npm install -g @visionengine/image-recognize

# 设置环境变量
export VEC_AI_API_KEY="你的API密钥"
export WORKDIR="./images"

# 运行服务器
ve-image-recognize
```

### Claude Desktop 配置示例

在 Claude Desktop 的配置文件中添加：

**macOS/Linux:** `~/Library/Application Support/Claude/claude_desktop_config.json`

**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "ve-image-recognize": {
      "command": "npx",
      "args": ["-y", "@visionengine/image-recognize@latest"],
      "env": {
        "BASE_URL": "https://api.visionengine-tech.com",
        "VEC_AI_API_KEY": "sk-xxxxx",
        "WORKDIR": "./"
      }
    }
  }
}
```

重启 Claude Desktop 后即可使用。

## 实际应用场景

### 1. 设计审查

```typescript
// 分析UI设计稿
await visual({
  imagePath: "./ui-mockup.png",
  prompt: "评估这个移动应用界面的用户体验设计，包括可用性、一致性和可访问性"
});
```

### 2. OCR 文字识别

```typescript
// 从截图中提取文字
await text({
  imagePath: "./screenshot.png",
  prompt: "提取所有可见文字，保持原始格式和层次结构"
});
```

### 3. 数据提取

```typescript
// 从图表中提取数据
await text({
  imagePath: "./chart.png",
  prompt: "提取这个折线图中的所有数据点，包括X轴Y轴的值，以JSON格式返回"
});
```

### 4. 表格识别

```typescript
// 识别并提取表格
await text({
  imagePath: "./table.jpg",
  prompt: "识别表格结构，提取所有单元格内容，以Markdown表格格式输出"
});
```

## 开发

### 构建

```bash
pnpm build
```

### 本地测试

```bash
# 先构建
pnpm build

# 本地运行
node dist/index.js
```

### 调试

设置环境变量后运行：

```bash
export VEC_AI_API_KEY="你的密钥"
export API_URL="https://api.visionengine-tech.com"
export WORKDIR="./"

node dist/index.js
```

## 支持的图片格式

- JPEG / JPG
- PNG
- GIF
- WebP

## 技术架构

- **MCP 协议** - Model Context Protocol，用于 AI 工具集成
- **FastMCP** - 快速构建 MCP 服务器的框架
- **VisionEngine Backend** - 统一代理图片理解与提示词反推能力
- **Qwen3-VL / 平台视觉模型** - 底层视觉语言模型

## 常见问题

### 1. 如何获取 API 密钥？

访问 [VisionEngine 官网](https://visionengine-tech.com) 注册账户并获取 API 密钥。

### 2. 相对路径是如何解析的？

相对路径会基于 `WORKDIR` 环境变量解析：
- 如果提供绝对路径，直接使用
- 如果提供相对路径，拼接为 `WORKDIR + 相对路径`

### 3. 支持远程图片 URL 吗？

支持。可以传本地图片路径，也可以直接传公网图片 URL。

### 4. 如何自定义分析维度？

通过 `prompt` 参数提供详细的分析要求：

```typescript
await visual({
  imagePath: "./design.png",
  prompt: `请从以下几个维度分析这个设计：
1. 色彩心理学应用
2. 信息层级是否清晰
3. 留白和密度是否合理
4. 是否符合Material Design规范
5. 给出具体改进建议`
});
```

## 支持与反馈

如有问题或建议：

- **邮箱:** team@visionengine-tech.com
- **官网:** https://visionengine-tech.com


