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 包（推荐）

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

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

方式二：从源码安装

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

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

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

使用方法

1. 启动MCP服务器

方法1: 使用启动脚本（推荐）

./start_server.sh

方法2: 直接运行

python3 vision_mcp_server.py stdio

2. 在MCP客户端中配置

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

Trae AI 配置

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

Claude Desktop 配置

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

方式二：使用本地源码

Trae AI 配置

快速配置：

cp trae_mcp_config.json "/Users/bytedance/Library/Application Support/Trae/User/mcp.json"

Claude Desktop 配置

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

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

🚨 遇到问题？

如果在使用过程中遇到以下问题:

• ❌ "API密钥未设置" 错误
• ❌ "Bearer 空值" 错误
• ❌ MCP服务无法启动
• ❌ 图像/视频分析失败

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

详细配置说明请参考：CONFIGURATION.md

3. 使用MCP Inspector测试

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

示例:

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 结构:

{
    "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协议通信

测试

基本功能测试

python3 test_vision_server.py

示例使用（需要API密钥）

# 设置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. 直接使用文件路径:

   result = await client.call_tool("analyze_image", {
       "image_input": "/path/to/your/image.jpg",
       "api_key": "your_api_key"
   })

2. 相对路径:

   result = await client.call_tool("analyze_image", {
       "image_input": "./test_image.jpg",
       "api_key": "your_api_key"
   })

快速演示

方法一：快速测试（推荐）

# 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

方法二：完整演示

# 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