@bestmfy/vision-understanding-mcp/README.md

MCP Server for Image/Video Understanding using Doubao Vision Model

# Vision Understanding MCP Server

这是一个基于Model Context Protocol (MCP)的图像/视频理解服务器，使用豆包视觉模型进行内容分析。

## 功能特性

- 🖼️ **图像分析**: 支持多种图像格式的内容分析
- 📁 **本地文件支持**: 支持本地图片文件上传和分析
- 🌐 **URL支持**: 支持在线图片URL分析
- 🎬 **视频分析**: 支持视频内容的智能理解
- 🎯 **预设提示**: 内置多种分析场景的提示模板
- 🔧 **自定义提示**: 支持用户自定义分析提示
- 🔒 **安全设计**: API密钥由客户端提供，不在服务器存储
- 📚 **资源管理**: 提供预定义的分析提示资源
- 🚀 **简化部署**: 无需复杂依赖，易于部署和使用
- 🔄 **自动编码**: 自动将本地图片转换为base64格式

## 主要特性

### 1. 标准MCP协议实现
- ✅ 完整的JSON-RPC 2.0协议支持
- ✅ 标准的工具注册和参数schema
- ✅ 环境变量配置，安全可靠
- ✅ 完善的错误处理机制

### 2. 灵活的图像输入
- 🖼️ 支持本地图片文件路径
- 🌐 支持网络图片URL
- 🔄 自动Base64编码处理
- 📁 多种图片格式支持

### 3. 智能分析功能
- 🤖 基于豆包视觉模型
- 📝 自定义分析提示
- 🎯 多种预设分析模板
- 📊 详细的结构化结果

### 4. 易于集成
- 🔧 标准MCP服务器实现
- 🔌 即插即用配置
- 📖 完整的使用文档
- 🧪 丰富的测试示例

## 安装和配置

### 方式一：使用 npm 包（推荐）

```bash
# 直接运行（推荐）
npx @bestmfy/vision-understanding-mcp

# 或全局安装
npm install -g @bestmfy/vision-understanding-mcp
vision-understanding-mcp
```

### 方式二：从源码安装

```bash
# 1. 克隆项目
git clone <repository-url>
cd mcp_demo

# 2. 安装依赖
pip3 install -r requirements.txt
```

**注意**: 此MCP服务器兼容Python 3.9+版本，使用简化的MCP协议实现，无需安装复杂的MCP库。

## 使用方法

### 1. 启动MCP服务器

**方法1: 使用启动脚本（推荐）**
```bash
./start_server.sh
```

**方法2: 直接运行**
```bash
python3 vision_mcp_server.py stdio
```

### 2. 在MCP客户端中配置

#### 方式一：使用 npm 包（推荐）

**Trae AI 配置**

```json
{
  "mcpServers": {
    "vision-understanding": {
      "command": "npx",
      "args": ["@bestmfy/vision-understanding-mcp"],
      "env": {
        "DOUBAO_API_KEY": "your-doubao-api-key"
      }
    }
  }
}
```

**Claude Desktop 配置**

```json
{
  "mcpServers": {
    "vision-understanding": {
      "command": "npx",
      "args": ["@bestmfy/vision-understanding-mcp"],
      "env": {
        "DOUBAO_API_KEY": "your-doubao-api-key"
      }
    }
  }
}
```

#### 方式二：使用本地源码

**Trae AI 配置**

快速配置：
```bash
cp trae_mcp_config.json "/Users/bytedance/Library/Application Support/Trae/User/mcp.json"
```

**Claude Desktop 配置**

在Claude Desktop的配置文件中添加:

```json
{
  "mcpServers": {
    "vision-understanding": {
      "command": "python",
      "args": ["/path/to/vision_mcp_server.py", "stdio"],
      "env": {}
    }
  }
}
```

### 🚨 遇到问题？

如果在使用过程中遇到以下问题:
- ❌ "API密钥未设置" 错误
- ❌ "Bearer 空值" 错误  
- ❌ MCP服务无法启动
- ❌ 图像/视频分析失败

**快速解决方案**: 查看 [TROUBLESHOOTING.md](TROUBLESHOOTING.md) 获取详细的故障排除指南

详细配置说明请参考：[CONFIGURATION.md](CONFIGURATION.md)

### 3. 使用MCP Inspector测试

```bash
uv run mcp dev vision_mcp_server.py
```

## 可用工具

### analyze_image
分析图像内容（支持URL和本地文件）

**参数:**
- `image_input` (必需): 图像URL或本地文件路径
- `api_key` (必需): 豆包API密钥
- `custom_prompt` (可选): 自定义分析提示
- `model` (可选): 模型名称，默认为 "doubao-seed-1-6-flash-250615"

**支持格式**: JPG, JPEG, PNG, GIF, BMP, WEBP

**示例:**
```python
result = await analyze_image(
    image_url="https://example.com/image.jpg",
    api_key="your_api_key_here",
    custom_prompt="请描述这张图片的主要内容"
)
```

### analyze_video
分析视频内容

**参数:**
- `video_url` (必需): 视频URL
- `api_key` (必需): 豆包API密钥
- `custom_prompt` (可选): 自定义分析提示
- `model` (可选): 模型名称

## 可用资源

### vision://prompts/{prompt_type}
获取预定义的分析提示

**可用类型:**
- `general`: 通用描述
- `detailed`: 详细分析
- `artistic`: 艺术角度分析
- `technical`: 技术角度分析
- `objects`: 对象识别
- `scene`: 场景描述
- `emotion`: 情感分析

## 可用提示模板

### create_vision_analysis_prompt
创建自定义的视觉分析提示

**参数:**
- `analysis_type`: 分析类型 (general, detailed, artistic, technical)
- `focus_areas`: 关注领域 (objects, scene, emotion, composition, all)

## API密钥说明

**重要**: API密钥由MCP客户端提供，不会硬编码在服务器中。使用时需要:

1. 在调用工具时传入有效的豆包API密钥
2. 确保API密钥有访问视觉模型的权限
3. 妥善保管API密钥，避免泄露

## 返回结果格式

所有分析工具返回 `VisionAnalysisResult` 结构:

```python
{
    "description": "分析结果描述",
    "model_used": "使用的模型名称",
    "success": true,
    "error_message": null  # 仅在失败时包含错误信息
}
```

## 错误处理

- 网络请求超时: 图像分析30秒，视频分析60秒
- API错误: 返回详细的错误状态码和消息
- 参数验证: 使用Pydantic进行输入验证

## 注意事项

1. 确保图像/视频URL可公开访问
2. 支持的图像格式: JPEG, PNG, GIF等常见格式
3. 视频分析功能取决于豆包API的视频支持能力
4. 请遵守豆包API的使用条款和限制

## 技术实现

- 基于MCP (Model Context Protocol) 标准
- 使用简化的MCP协议实现，兼容Python 3.9+
- 异步HTTP客户端处理API调用
- JSON-RPC 2.0协议通信

## 测试

### 基本功能测试
```bash
python3 test_vision_server.py
```

### 示例使用（需要API密钥）
```bash
# 设置API密钥
export DOUBAO_API_KEY='your_api_key_here'

# 创建测试图片
python3 create_test_image.py

# 运行本地图片分析演示
python3 demo_local_image.py

# 运行完整示例
python3 example_usage.py

# 或仅测试prompts和resources
python3 example_usage.py test
```

## 项目结构

```
mcp_demo/
├── vision_mcp_server.py          # 主服务器文件
├── vision_mcp_server_debug.py    # Debug版本MCP服务器
├── requirements.txt              # 依赖列表
├── start_server.sh              # 启动脚本
├── test_vision_server.py         # 测试脚本
├── example_usage.py              # 使用示例
├── demo_local_image.py           # 本地图片分析演示
├── quick_test.py                 # 快速测试脚本（推荐）
├── debug_env.py                  # 环境诊断脚本
├── create_test_image.py          # 创建测试图片
├── test_image.jpg               # 测试图片文件
├── claude_desktop_config.json    # Claude Desktop配置示例
├── trae_mcp_config.json          # Trae AI完整配置文件
├── CONFIGURATION.md              # Trae AI配置指南
├── IMPROVEMENTS.md               # 重要改进说明文档
├── TROUBLESHOOTING.md            # 故障排除指南
└── README.md                     # 说明文档
```

## 本地图片分析

### 支持的图片格式
- JPG/JPEG
- PNG
- GIF
- BMP
- WEBP

### 使用方法
1. **直接使用文件路径**:
   ```python
   result = await client.call_tool("analyze_image", {
       "image_input": "/path/to/your/image.jpg",
       "api_key": "your_api_key"
   })
   ```

2. **相对路径**:
   ```python
   result = await client.call_tool("analyze_image", {
       "image_input": "./test_image.jpg",
       "api_key": "your_api_key"
   })
   ```

### 快速演示

#### 方法一：快速测试（推荐）
```bash
# 1. 创建测试图片
python3 create_test_image.py

# 2. 设置API密钥（必需）
export DOUBAO_API_KEY="your_doubao_api_key"

# 3. 运行快速测试
python3 quick_test.py
```

**输出示例：**
```
🚀 快速测试 Vision MCP 服务
✅ 服务器启动成功
🔍 分析图片: test_image.jpg
✅ 分析成功!
📝 描述: 图片包含红色圆形、绿色长方形、黄色三角形...
🤖 模型: doubao-seed-1-6-flash-250615
```

#### 方法二：完整演示
```bash
# 1. 创建测试图片
python3 create_test_image.py

# 2. 设置API密钥（必需）
export DOUBAO_API_KEY="your_doubao_api_key"

# 3. 运行完整演示
python3 demo_local_image.py
```

**功能特点：**
- 🔄 自动从环境变量读取API密钥
- 📝 支持自定义分析提示
- 🎯 基本分析和定制分析对比
- 📊 详细的结果展示

## 许可证

MIT License