Metadata-Version: 2.4
Name: vl-mcp-server
Version: 0.1.2
Summary: VL 视觉理解 MCP 服务 - 基于 tokendance 的 Qwen2.5-VL 模型
Author-email: Your Name <your.email@example.com>
License: MIT
Keywords: mcp,qwen,tokendance,vision,vl
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Description-Content-Type: text/markdown

# VL MCP Server

基于 MCP（Model Context Protocol）协议的视觉理解服务，通过 tokendance 平台调用 Qwen2.5-VL 模型，实现图片内容分析功能。

## 功能特性

- **自动识别图片来源**：无需指定类型，自动区分 URL / 本地文件 / Base64 / data URI
- **兼容 Claude Code 粘贴图片**：在对话框直接粘贴截图即可分析，无需提供文件路径
- 基于 Qwen2.5-VL-7B-Instruct 模型
- 兼容 Cherry Studio、Claude Code、Cursor 等 MCP 客户端
- 可托管部署到魔搭 MCP 广场

## 安装使用

### 环境要求

- Python >= 3.10
- uv（推荐）或 pip

### 配置

设置环境变量：

```bash
export TOKENDANCE_API_KEY="your-api-key"
```

### MCP 客户端配置

**Cherry Studio / Claude Desktop / Cursor / Claude Code：**

```json
{
  "mcpServers": {
    "vl-image-analyzer": {
      "command": "uvx",
      "args": ["vl-mcp-server"],
      "env": {
        "TOKENDANCE_API_KEY": "your-api-key",
        "VL_MODEL": "qwen2.5-vl-7b-instruct"
      }
    }
  }
}
```

> `VL_MODEL` 为可选项，默认使用 `qwen2.5-vl-7b-instruct`。  
> 如需使用更大参数模型，可修改为 `qwen2.5-vl-72b-instruct`。

## 开发

### 本地开发

```bash
# 克隆仓库
git clone <repo-url>
cd vl-mcp-server

# 使用 uv 安装依赖
uv sync

# 运行服务
uv run vl-mcp-server
```

### 调试

使用 MCP Inspector：

```bash
npx @modelcontextprotocol/inspector uv run vl-mcp-server
```

## 工具说明

### analyze_image

分析图片内容并返回描述。**图片来源自动识别，无需指定类型。**

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|-----|------|-----|-------|------|
| `image` | string | ✅ | - | 图片来源，支持多种格式（见下方）|
| `prompt` | string | ❌ | "请详细描述这张图片的内容" | 自定义分析提示词 |

**`image` 参数支持的格式：**

| 格式 | 示例 | 使用场景 |
|-----|------|---------|
| 本地文件路径 | `/Users/xxx/image.png` | 直接指定本地文件 |
| HTTP/HTTPS URL | `https://example.com/img.jpg` | 网络图片 |
| data URI | `data:image/png;base64,...` | **Claude Code 粘贴图片自动使用** |
| 裸 Base64 | `iVBORw0KGgo...` | 第三方系统传入的 base64 |

**支持的图片格式：** png, jpg, jpeg, gif, webp, bmp, tiff

**示例：**

**本地文件方式：**
```json
{
  "image": "/Users/username/Pictures/photo.jpg",
  "prompt": "描述这张图片的主要内容"
}
```

**URL 方式：**
```json
{
  "image": "https://example.com/image.jpg",
  "prompt": "描述这张图片的主要内容"
}
```

**Claude Code 粘贴图片方式（由 Claude 自动处理）：**
- 在对话框粘贴图片后，直接说"使用 analyze_image 工具分析这张图片"
- Claude 会自动将图片转为 `data:image/png;base64,...` 格式传入工具

## 许可证

MIT License
