Metadata-Version: 2.4
Name: visual-understanding
Version: 0.1.0
Summary: Multi-provider visual understanding MCP server & CLI — caption, OCR, Q&A, grounding
Author: JayceVane
License-Expression: MIT
License-File: LICENSE
Keywords: grounding,mcp,multimodal,ocr,vision,vlm
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp[cli]<2,>=1.27
Requires-Dist: pillow>=10.0
Requires-Dist: pyyaml>=6.0
Description-Content-Type: text/markdown

# visual-understanding

多提供商视觉理解工具——**MCP 服务器 + CLI 双模式**。通过统一的接口调用
智谱 GLM-V、OpenAI GPT-4o、Anthropic Claude 或任何 OpenAI 兼容端点，
完成图片/视频/文档的多模态理解与目标定位。

## 功能

| 能力 | 说明 | 支持的输入 |
|------|------|-----------|
| **多模态理解** (`vision_analyze`) | 图片描述、OCR、视觉问答、文档解读、多图对比 | 图片 URL/路径/base64、视频 URL、文档 URL |
| **目标定位** (`vision_ground`) | 定位图像中的目标，输出归一化坐标，可选画框可视化 | 图片 URL/路径/base64 |
| **提供商查询** (`list_providers`) | 查看已配置的提供商、模型、能力 | — |

## 快速开始

### 安装

```bash
cd mcp-servers/visual-understanding
pip install -e .
```

### 配置 API Key

至少设置一个提供商的 API Key（环境变量）：

```bash
# 智谱（推荐——支持原生定位、视频、文件）
export ZHIPU_API_KEY="your_key"       # https://bigmodel.cn/usercenter/proj-mgmt/apikeys

# OpenAI
export OPENAI_API_KEY="your_key"      # https://platform.openai.com/api-keys

# Anthropic
export ANTHROPIC_API_KEY="your_key"   # https://console.anthropic.com/settings/keys
```

### 验证安装

```bash
visual-understanding list-providers
```

## 模式一：MCP 服务器

在 ZCode / Claude Desktop / Cursor 等 MCP 客户端中注册：

**ZCode** (`~/.zcode/cli/config.json`):

```json
{
  "mcpServers": {
    "visual-understanding": {
      "command": "visual-understanding",
      "args": ["serve"]
    }
  }
}
```

**Claude Desktop** (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "visual-understanding": {
      "command": "visual-understanding",
      "args": ["serve"]
    }
  }
}
```

注册后即可在对话中直接使用 `vision_analyze`、`vision_ground`、`list_providers` 工具。

## 模式二：CLI / Skill

```bash
# 描述图片
visual-understanding analyze --images photo.jpg

# OCR 文字提取
visual-understanding analyze --images scan.png --prompt "Extract all text"

# 视觉问答
visual-understanding analyze --images photo.jpg --prompt "What color is the car?"

# 目标定位 + 画框
visual-understanding ground --image photo.jpg --prompt "all people" --visualize --save-path result.png

# 使用特定提供商/模型
visual-understanding analyze --images photo.jpg --provider openai --model gpt-4o
```

> Agent 可通过 `SKILL.md` 中的指引调用 CLI。两种模式共享同一套核心逻辑。

## 提供商配置

### 内置默认

不创建配置文件时，内置三个提供商：

| 提供商 | 类型 | 模型 | 视频 | 文件 | 原生定位 |
|--------|------|------|------|------|---------|
| `zhipu` | OpenAI 兼容 | GLM-V 系列 | ✅ | ✅ | ✅ |
| `openai` | OpenAI 兼容 | GPT-4o 系列 | ❌ | ❌ | ❌ |
| `anthropic` | Anthropic | Claude 系列 | ❌ | ❌ | ❌ |

### 自定义配置

```bash
# 方式一：环境变量指定路径
export VISUAL_UNDERSTANDING_CONFIG=/path/to/config.yaml

# 方式二：默认路径
mkdir -p ~/.config/visual-understanding
cp config.example.yaml ~/.config/visual-understanding/config.yaml
```

配置文件格式见 `config.example.yaml`。

### 添加自定义 OpenAI 兼容端点

任何 OpenAI 兼容的视觉模型服务都可以添加（vLLM、Ollama、Together、Azure 等）：

```yaml
providers:
  my-vlm:
    type: openai_compat
    api_key_env: MY_API_KEY              # 环境变量名
    base_url: http://localhost:8080/v1   # API 地址
    chat_models: [qwen-vl-max]
    default_chat_model: qwen-vl-max
    max_images: 10
```

然后：

```bash
export MY_API_KEY="your_key_or_dummy"
visual-understanding analyze --images photo.jpg --provider my-vlm
```

## 架构

```
                    ┌─────────────┐
                    │   config    │  YAML / env vars
                    └──────┬──────┘
                           │
              ┌────────────┼────────────┐
              ▼            ▼            ▼
        ┌──────────┐ ┌──────────┐ ┌──────────┐
        │ ops.py   │ │ ops.py   │ │ ops.py   │   ← 共享业务逻辑
        │ do_analyze│ │ do_ground│ │ do_list  │
        └────┬─────┘ └────┬─────┘ └──────────┘
             │             │
     ┌───────┴──────┐     │
     ▼              ▼     ▼
 ┌────────┐   ┌────────┐ ┌──────────┐
 │server.py│  │ cli.py │ │grounding │
 │ (MCP)  │   │ (CLI)  │ │  .py     │
 └───┬────┘   └────────┘ └──────────┘
     │
     ▼
 ┌──────────────────────────────────┐
 │         providers/               │
 │  ┌────────────┐ ┌────────────┐  │
 │  │openai_compat│ │ anthropic  │  │
 │  │(OpenAI/智谱)│ │ (Claude)   │  │
 │  └────────────┘ └────────────┘  │
 └──────────────────────────────────┘
```

- **`config.py`** — Pydantic 配置模型 + YAML 加载（三级查找）
- **`media.py`** — 输入解析（URL/路径/base64 归一化 + SSRF 防护）
- **`providers/`** — 提供商抽象 + 实现（OpenAI 兼容、Anthropic）
- **`grounding.py`** — 定位 prompt 构造、坐标解析、Pillow 画框
- **`ops.py`** — 共享操作逻辑（MCP 工具与 CLI 子命令的唯一调用入口）
- **`server.py`** — FastMCP 服务器（3 个 MCP 工具）
- **`cli.py`** — CLI 入口（4 个子命令：analyze / ground / list-providers / serve）

## 安全设计

- **API 密钥**始终通过环境变量名引用（`api_key_env`），配置文件中不出现明文密钥
- **`base_url`** 仅在配置中指定，工具参数不接受覆盖（防止密钥泄露到恶意端点）
- **URL 输入**仅允许 http/https 公网地址，拒绝 localhost/内网 IP（防 SSRF）
- **`.gitignore`** 排除 `config.yaml`、`.env`

## 技术栈

- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) (FastMCP v1.x)
- `httpx` 异步 HTTP
- `pydantic` 配置校验
- `pyyaml` 配置文件
- `pillow` grounding 画框可视化

## License

MIT
