# @visionengine/image-recognize

[![English](https://img.shields.io/badge/English-Click-yellow)](README.md)
[![中文文档](https://img.shields.io/badge/中文文档-点击查看-orange)](README-zh.md)

VisionEngine Image Recognition MCP Server - Analyze visual design elements, extract text, and reverse image generation prompts.

## Features

- **Visual Design Analysis** - Analyze layout, colors, typography, composition and design principles
- **Text & Data Extraction** - Extract text, tables, charts and structured data from images (OCR)
- **Image Prompt Reverse** - Infer the most likely prompt used to generate an image
- **Flexible Prompts** - Custom prompts or use intelligent defaults
- **Multiple Image Formats** - Support for JPG, PNG, GIF, WebP

## Installation

### As MCP Server

Add to your MCP client configuration:

```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": "sk-xxx",
        "WORKDIR": "./public"
      }
    }
  }
}
```

### As NPM Package

```bash
npm install -g @visionengine/image-recognize
```

## Configuration

Environment variables:

- `BASE_URL` - VisionEngine API base URL (default: https://api.visionengine-tech.com)
- `VEC_AI_API_KEY` - Your VisionEngine API key (required)
- `WORKDIR` - Base directory for relative image paths (default: ./)

## Tools

### visual

Analyze visual design elements in an image.

**Parameters:**
- `imagePath` (string, required) - Image file path (relative to WORKDIR or absolute)
- `prompt` (string, optional) - Custom analysis prompt

**Default Analysis:**
- Layout and composition
- Color scheme and palette
- Typography and text styling
- Visual hierarchy
- Design style and characteristics
- Visual focal points
- Design principles (contrast, balance, alignment, etc.)

**Example:**

```typescript
// Using default prompt
await visual({
  imagePath: "./design.png"
});

// Using custom prompt
await visual({
  imagePath: "./design.png",
  prompt: "分析这个网页设计的配色方案和视觉层次"
});
```

### text

Extract text content and data information from an image.

**Parameters:**
- `imagePath` (string, required) - Image file path (relative to WORKDIR or absolute)
- `prompt` (string, optional) - Custom extraction prompt

**Default Extraction:**
- All text content (OCR)
- Table data
- Chart data
- Numbers and statistics
- Labels, titles, captions
- Structured data

**Example:**

```typescript
// Using default prompt
await text({
  imagePath: "./document.jpg"
});

// Using custom prompt
await text({
  imagePath: "./document.jpg",
  prompt: "提取图片中的所有表格数据，并转换为 Markdown 格式"
});
```

### prompt_reverse

Reverse-engineer the most likely image generation prompt from an image.

**Parameters:**
- `imagePath` (string, required) - Image file path (relative to WORKDIR or absolute) or public image URL
- `outputLanguage` (`"zh" | "en"`, optional) - Output language, defaults to `en`
- `userPrompt` (string, optional) - Extra instruction for prompt reverse
- `modelId` (string, optional) - Platform model override

**Example:**

```typescript
await prompt_reverse({
  imagePath: "./poster.png",
  outputLanguage: "en"
});
```

## Usage Examples

### MCP Client

Once configured as an MCP server, the tools are available through your MCP client:

```
> Use visual tool on screenshot.png
> Use text tool to extract data from invoice.jpg
```

### Direct Usage

```bash
# Install globally
npm install -g @visionengine/image-recognize

# Set environment variables
export VEC_AI_API_KEY="your_api_key"
export WORKDIR="./images"

# Run the server
ve-image-recognize
```

## Development

### Build

```bash
pnpm build
```

### Local Testing

```bash
# Build first
pnpm build

# Run locally
node dist/index.js
```

## Support

For issues and questions:

- Email: team@visionengine-tech.com
- Website: https://visionengine-tech.com
