{"_id":"@bestmfy/vision-understanding-mcp","_rev":"5-c328045f4d19bd45b9d60dd89098e20f","name":"@bestmfy/vision-understanding-mcp","dist-tags":{"latest":"1.0.4"},"versions":{"1.0.0":{"name":"@bestmfy/vision-understanding-mcp","version":"1.0.0","keywords":["mcp","vision","ai","image-analysis","video-analysis","doubao","volcengine"],"author":{"name":"bestmfy","email":"longdong1996@qq.com"},"license":"MIT","_id":"@bestmfy/vision-understanding-mcp@1.0.0","maintainers":[{"name":"bestmfy","email":"longdong1996@qq.com"}],"bin":{"vision-understanding-mcp":"bin/vision-understanding-mcp"},"dist":{"shasum":"c0a8bec341192499e479d601dda9b1743b16de05","tarball":"https://registry.npmjs.org/@bestmfy/vision-understanding-mcp/-/vision-understanding-mcp-1.0.0.tgz","fileCount":6,"integrity":"sha512-EhMwwUz2d0ulA7/rXumMhJvx8MgbBCgZzNQzZ0VonRYZZnRoEull5oWkO2JTR03ZWYrz6b1vbdX+HCdIpNfKEw==","signatures":[{"sig":"MEUCIQDRBenEmjsRZQQaY3aSts2qBVyiU8rGwAyTTztoegcxrgIgEjgJR9zjwcwj7Iw/0XAnpe1qvnC3SSsWSxM8FNoHj6k=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":37520},"main":"index.js","engines":{"node":">=14.0.0","python":">=3.9.0"},"scripts":{"test":"node test-npm-package.js","start":"python3 vision_mcp_server.py","prepack":"npm test","postinstall":"python3 -m pip install -r requirements.txt","test:python":"python3 test_vision_server.py","prepublishOnly":"npm test"},"_npmUser":{"name":"bestmfy","email":"longdong1996@qq.com"},"_npmVersion":"11.4.2","description":"MCP Server for Image/Video Understanding using Doubao Vision Model","directories":{},"_nodeVersion":"24.3.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"peerDependencies":{"python3":">=3.9.0"},"_npmOperationalInternal":{"tmp":"tmp/vision-understanding-mcp_1.0.0_1752724561919_0.3864946599466863","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@bestmfy/vision-understanding-mcp","version":"1.0.1","keywords":["mcp","vision","ai","image-analysis","video-analysis","doubao","volcengine"],"author":{"name":"bestmfy","email":"longdong1996@qq.com"},"license":"MIT","_id":"@bestmfy/vision-understanding-mcp@1.0.1","maintainers":[{"name":"bestmfy","email":"longdong1996@qq.com"}],"bin":{"vision-understanding-mcp":"bin/vision-understanding-mcp"},"dist":{"shasum":"9129255bc25eabb9dc4821a8d880b0d2e412ef80","tarball":"https://registry.npmjs.org/@bestmfy/vision-understanding-mcp/-/vision-understanding-mcp-1.0.1.tgz","fileCount":6,"integrity":"sha512-J9vxgS6yUGtnY95guHOAc3jv0Rjj+1W0QSkX0IuvfR2L7iBSal1s1RVaSiD04ehmmyCkfxOeqWKhv+Gy98ndyg==","signatures":[{"sig":"MEUCICTDVSAaDccrn+DtNFaTeA5IFBNgLKTLW04pngwW0qFPAiEAtvI1jrgJdR3DP10XkcEyk7Fm6S7eARMrMqSciKIQCok=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":37466},"main":"index.js","engines":{"node":">=14.0.0","python":">=3.9.0"},"scripts":{"test":"node test-npm-package.js","start":"python3 vision_mcp_server.py","prepack":"npm test","postinstall":"python3 -m pip install -r requirements.txt","test:python":"python3 test_vision_server.py","prepublishOnly":"npm test"},"_npmUser":{"name":"bestmfy","email":"longdong1996@qq.com"},"_npmVersion":"11.4.2","description":"MCP Server for Image/Video Understanding using Doubao Vision Model","directories":{},"_nodeVersion":"24.3.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/vision-understanding-mcp_1.0.1_1752724878809_0.10744036799726953","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@bestmfy/vision-understanding-mcp","version":"1.0.2","keywords":["mcp","vision","ai","image-analysis","video-analysis","doubao","volcengine"],"author":{"name":"bestmfy","email":"longdong1996@qq.com"},"license":"MIT","_id":"@bestmfy/vision-understanding-mcp@1.0.2","maintainers":[{"name":"bestmfy","email":"longdong1996@qq.com"}],"bin":{"vision-understanding-mcp":"bin/vision-understanding-mcp"},"dist":{"shasum":"f44663a7b934f52eaae688ede97352b5f5f2fbcf","tarball":"https://registry.npmjs.org/@bestmfy/vision-understanding-mcp/-/vision-understanding-mcp-1.0.2.tgz","fileCount":6,"integrity":"sha512-23mM4mgSKMcVN3LSJUpDlK7/UQW3otCS9+gN9r08YkGrrfY3mXZs3igELJWpAvkxBljNbxE2PgMvP+uCyl3O0w==","signatures":[{"sig":"MEQCIBVj0PXMJ1Eezu8NL8MT6XSVeEPd0iv2cAwxh8Kl56tVAiB5dEeX/ibxBqG91coz0iOTQbpe2jtqMJEkTb8VqR0/Uw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":39842},"main":"index.js","engines":{"node":">=14.0.0","python":">=3.9.0"},"scripts":{"test":"node test-npm-package.js","start":"python3 vision_mcp_server.py","prepack":"npm test","postinstall":"python3 -m pip install -r requirements.txt","test:python":"python3 test_vision_server.py","prepublishOnly":"npm test"},"_npmUser":{"name":"bestmfy","email":"longdong1996@qq.com"},"_npmVersion":"11.4.2","description":"MCP Server for Image/Video Understanding using Doubao Vision Model","directories":{},"_nodeVersion":"24.3.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/vision-understanding-mcp_1.0.2_1752725490949_0.97506512545079","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"@bestmfy/vision-understanding-mcp","version":"1.0.3","keywords":["mcp","vision","ai","image-analysis","video-analysis","doubao","volcengine"],"author":{"name":"bestmfy","email":"longdong1996@qq.com"},"license":"MIT","_id":"@bestmfy/vision-understanding-mcp@1.0.3","maintainers":[{"name":"bestmfy","email":"longdong1996@qq.com"}],"bin":{"vision-understanding-mcp":"bin/vision-understanding-mcp"},"dist":{"shasum":"bbdef24ee37569bc03346f1dd7ecbc39bdbde566","tarball":"https://registry.npmjs.org/@bestmfy/vision-understanding-mcp/-/vision-understanding-mcp-1.0.3.tgz","fileCount":7,"integrity":"sha512-YIDYlt52DDYooo7sJGib6PurwgRstnFFlE+Kkmw/ZKRSy1dGoQZMIo0Mu1TERcMc4hZ18j5wez9e2SrsEAFN5A==","signatures":[{"sig":"MEYCIQCg7Ef6LDIFmjfJ43cjMroaQenyz8sjyTgl2+9Rqg3YgwIhAJXasZQcv9Uvc5wJDQkv1km3MzalPyClc9mnbd/I8Sp3","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":64285},"main":"index.js","engines":{"node":">=14.0.0","python":">=3.9.0"},"scripts":{"test":"node test-npm-package.js","start":"python3 vision_mcp_server.py","prepack":"npm test","postinstall":"python3 -m pip install -r requirements.txt","test:python":"python3 test_vision_server.py","prepublishOnly":"npm test"},"_npmUser":{"name":"bestmfy","email":"longdong1996@qq.com"},"_npmVersion":"11.4.2","description":"MCP Server for Image/Video Understanding using Doubao Vision Model","directories":{},"_nodeVersion":"24.3.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/vision-understanding-mcp_1.0.3_1752725532988_0.9981024798733966","host":"s3://npm-registry-packages-npm-production"}},"1.0.4":{"name":"@bestmfy/vision-understanding-mcp","version":"1.0.4","description":"MCP Server for Image/Video Understanding using Doubao Vision Model","main":"index.js","bin":{"vision-understanding-mcp":"bin/vision-understanding-mcp"},"scripts":{"start":"python3 vision_mcp_server.py","test":"node test-npm-package.js","test:python":"python3 test_vision_server.py","postinstall":"python3 -m pip install -r requirements.txt","prepublishOnly":"npm test","prepack":"npm test"},"keywords":["mcp","vision","ai","image-analysis","video-analysis","doubao","volcengine"],"author":{"name":"bestmfy","email":"longdong1996@qq.com"},"license":"MIT","engines":{"node":">=14.0.0","python":">=3.9.0"},"publishConfig":{"access":"public"},"_id":"@bestmfy/vision-understanding-mcp@1.0.4","_nodeVersion":"24.3.0","_npmVersion":"11.4.2","dist":{"integrity":"sha512-E7PmU21SzIzjcOgOGRGt71nhrPp3OKf6FWHuWzr+lcQvzK9OGemtwBmpDb0EdIGSAqzap25yMZLKqL+vg9vsyw==","shasum":"4ced417ea16a17aa542ab71b6b589b6c48b36ed6","tarball":"https://registry.npmjs.org/@bestmfy/vision-understanding-mcp/-/vision-understanding-mcp-1.0.4.tgz","fileCount":7,"unpackedSize":64261,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIAP8/Kc6O8gJiyiiDABX/Sm4oDoeU9oGmfrCUX9tbiURAiBSGWhelXvFbE0eNKOwQJ3Jel1O6XSuz0cjjCrRejKLrg=="}]},"_npmUser":{"name":"bestmfy","email":"longdong1996@qq.com"},"directories":{},"maintainers":[{"name":"bestmfy","email":"longdong1996@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/vision-understanding-mcp_1.0.4_1752725979246_0.08213833149843786"},"_hasShrinkwrap":false}},"time":{"created":"2025-07-17T03:56:01.800Z","modified":"2025-07-17T04:19:39.647Z","1.0.0":"2025-07-17T03:56:02.117Z","1.0.1":"2025-07-17T04:01:19.093Z","1.0.2":"2025-07-17T04:11:31.107Z","1.0.3":"2025-07-17T04:12:13.170Z","1.0.4":"2025-07-17T04:19:39.449Z"},"author":{"name":"bestmfy","email":"longdong1996@qq.com"},"license":"MIT","keywords":["mcp","vision","ai","image-analysis","video-analysis","doubao","volcengine"],"description":"MCP Server for Image/Video Understanding using Doubao Vision Model","maintainers":[{"name":"bestmfy","email":"longdong1996@qq.com"}],"readme":"# Vision Understanding MCP Server\n\n这是一个基于Model Context Protocol (MCP)的图像/视频理解服务器，使用豆包视觉模型进行内容分析。\n\n## 功能特性\n\n- 🖼️ **图像分析**: 支持多种图像格式的内容分析\n- 📁 **本地文件支持**: 支持本地图片文件上传和分析\n- 🌐 **URL支持**: 支持在线图片URL分析\n- 🎬 **视频分析**: 支持视频内容的智能理解\n- 🎯 **预设提示**: 内置多种分析场景的提示模板\n- 🔧 **自定义提示**: 支持用户自定义分析提示\n- 🔒 **安全设计**: API密钥由客户端提供，不在服务器存储\n- 📚 **资源管理**: 提供预定义的分析提示资源\n- 🚀 **简化部署**: 无需复杂依赖，易于部署和使用\n- 🔄 **自动编码**: 自动将本地图片转换为base64格式\n\n## 主要特性\n\n### 1. 标准MCP协议实现\n- ✅ 完整的JSON-RPC 2.0协议支持\n- ✅ 标准的工具注册和参数schema\n- ✅ 环境变量配置，安全可靠\n- ✅ 完善的错误处理机制\n\n### 2. 灵活的图像输入\n- 🖼️ 支持本地图片文件路径\n- 🌐 支持网络图片URL\n- 🔄 自动Base64编码处理\n- 📁 多种图片格式支持\n\n### 3. 智能分析功能\n- 🤖 基于豆包视觉模型\n- 📝 自定义分析提示\n- 🎯 多种预设分析模板\n- 📊 详细的结构化结果\n\n### 4. 易于集成\n- 🔧 标准MCP服务器实现\n- 🔌 即插即用配置\n- 📖 完整的使用文档\n- 🧪 丰富的测试示例\n\n## 安装和配置\n\n### 方式一：使用 npm 包（推荐）\n\n```bash\n# 直接运行（推荐）\nnpx @bestmfy/vision-understanding-mcp\n\n# 或全局安装\nnpm install -g @bestmfy/vision-understanding-mcp\nvision-understanding-mcp\n```\n\n### 方式二：从源码安装\n\n```bash\n# 1. 克隆项目\ngit clone <repository-url>\ncd mcp_demo\n\n# 2. 安装依赖\npip3 install -r requirements.txt\n```\n\n**注意**: 此MCP服务器兼容Python 3.9+版本，使用简化的MCP协议实现，无需安装复杂的MCP库。\n\n## 使用方法\n\n### 1. 启动MCP服务器\n\n**方法1: 使用启动脚本（推荐）**\n```bash\n./start_server.sh\n```\n\n**方法2: 直接运行**\n```bash\npython3 vision_mcp_server.py stdio\n```\n\n### 2. 在MCP客户端中配置\n\n#### 方式一：使用 npm 包（推荐）\n\n**Trae AI 配置**\n\n```json\n{\n  \"mcpServers\": {\n    \"vision-understanding\": {\n      \"command\": \"npx\",\n      \"args\": [\"@bestmfy/vision-understanding-mcp\"],\n      \"env\": {\n        \"DOUBAO_API_KEY\": \"your-doubao-api-key\"\n      }\n    }\n  }\n}\n```\n\n**Claude Desktop 配置**\n\n```json\n{\n  \"mcpServers\": {\n    \"vision-understanding\": {\n      \"command\": \"npx\",\n      \"args\": [\"@bestmfy/vision-understanding-mcp\"],\n      \"env\": {\n        \"DOUBAO_API_KEY\": \"your-doubao-api-key\"\n      }\n    }\n  }\n}\n```\n\n#### 方式二：使用本地源码\n\n**Trae AI 配置**\n\n快速配置：\n```bash\ncp trae_mcp_config.json \"/Users/bytedance/Library/Application Support/Trae/User/mcp.json\"\n```\n\n**Claude Desktop 配置**\n\n在Claude Desktop的配置文件中添加:\n\n```json\n{\n  \"mcpServers\": {\n    \"vision-understanding\": {\n      \"command\": \"python\",\n      \"args\": [\"/path/to/vision_mcp_server.py\", \"stdio\"],\n      \"env\": {}\n    }\n  }\n}\n```\n\n### 🚨 遇到问题？\n\n如果在使用过程中遇到以下问题:\n- ❌ \"API密钥未设置\" 错误\n- ❌ \"Bearer 空值\" 错误  \n- ❌ MCP服务无法启动\n- ❌ 图像/视频分析失败\n\n**快速解决方案**: 查看 [TROUBLESHOOTING.md](TROUBLESHOOTING.md) 获取详细的故障排除指南\n\n详细配置说明请参考：[CONFIGURATION.md](CONFIGURATION.md)\n\n### 3. 使用MCP Inspector测试\n\n```bash\nuv run mcp dev vision_mcp_server.py\n```\n\n## 可用工具\n\n### analyze_image\n分析图像内容（支持URL和本地文件）\n\n**参数:**\n- `image_input` (必需): 图像URL或本地文件路径\n- `api_key` (必需): 豆包API密钥\n- `custom_prompt` (可选): 自定义分析提示\n- `model` (可选): 模型名称，默认为 \"doubao-seed-1-6-flash-250615\"\n\n**支持格式**: JPG, JPEG, PNG, GIF, BMP, WEBP\n\n**示例:**\n```python\nresult = await analyze_image(\n    image_url=\"https://example.com/image.jpg\",\n    api_key=\"your_api_key_here\",\n    custom_prompt=\"请描述这张图片的主要内容\"\n)\n```\n\n### analyze_video\n分析视频内容\n\n**参数:**\n- `video_url` (必需): 视频URL\n- `api_key` (必需): 豆包API密钥\n- `custom_prompt` (可选): 自定义分析提示\n- `model` (可选): 模型名称\n\n## 可用资源\n\n### vision://prompts/{prompt_type}\n获取预定义的分析提示\n\n**可用类型:**\n- `general`: 通用描述\n- `detailed`: 详细分析\n- `artistic`: 艺术角度分析\n- `technical`: 技术角度分析\n- `objects`: 对象识别\n- `scene`: 场景描述\n- `emotion`: 情感分析\n\n## 可用提示模板\n\n### create_vision_analysis_prompt\n创建自定义的视觉分析提示\n\n**参数:**\n- `analysis_type`: 分析类型 (general, detailed, artistic, technical)\n- `focus_areas`: 关注领域 (objects, scene, emotion, composition, all)\n\n## API密钥说明\n\n**重要**: API密钥由MCP客户端提供，不会硬编码在服务器中。使用时需要:\n\n1. 在调用工具时传入有效的豆包API密钥\n2. 确保API密钥有访问视觉模型的权限\n3. 妥善保管API密钥，避免泄露\n\n## 返回结果格式\n\n所有分析工具返回 `VisionAnalysisResult` 结构:\n\n```python\n{\n    \"description\": \"分析结果描述\",\n    \"model_used\": \"使用的模型名称\",\n    \"success\": true,\n    \"error_message\": null  # 仅在失败时包含错误信息\n}\n```\n\n## 错误处理\n\n- 网络请求超时: 图像分析30秒，视频分析60秒\n- API错误: 返回详细的错误状态码和消息\n- 参数验证: 使用Pydantic进行输入验证\n\n## 注意事项\n\n1. 确保图像/视频URL可公开访问\n2. 支持的图像格式: JPEG, PNG, GIF等常见格式\n3. 视频分析功能取决于豆包API的视频支持能力\n4. 请遵守豆包API的使用条款和限制\n\n## 技术实现\n\n- 基于MCP (Model Context Protocol) 标准\n- 使用简化的MCP协议实现，兼容Python 3.9+\n- 异步HTTP客户端处理API调用\n- JSON-RPC 2.0协议通信\n\n## 测试\n\n### 基本功能测试\n```bash\npython3 test_vision_server.py\n```\n\n### 示例使用（需要API密钥）\n```bash\n# 设置API密钥\nexport DOUBAO_API_KEY='your_api_key_here'\n\n# 创建测试图片\npython3 create_test_image.py\n\n# 运行本地图片分析演示\npython3 demo_local_image.py\n\n# 运行完整示例\npython3 example_usage.py\n\n# 或仅测试prompts和resources\npython3 example_usage.py test\n```\n\n## 项目结构\n\n```\nmcp_demo/\n├── vision_mcp_server.py          # 主服务器文件\n├── vision_mcp_server_debug.py    # Debug版本MCP服务器\n├── requirements.txt              # 依赖列表\n├── start_server.sh              # 启动脚本\n├── test_vision_server.py         # 测试脚本\n├── example_usage.py              # 使用示例\n├── demo_local_image.py           # 本地图片分析演示\n├── quick_test.py                 # 快速测试脚本（推荐）\n├── debug_env.py                  # 环境诊断脚本\n├── create_test_image.py          # 创建测试图片\n├── test_image.jpg               # 测试图片文件\n├── claude_desktop_config.json    # Claude Desktop配置示例\n├── trae_mcp_config.json          # Trae AI完整配置文件\n├── CONFIGURATION.md              # Trae AI配置指南\n├── IMPROVEMENTS.md               # 重要改进说明文档\n├── TROUBLESHOOTING.md            # 故障排除指南\n└── README.md                     # 说明文档\n```\n\n## 本地图片分析\n\n### 支持的图片格式\n- JPG/JPEG\n- PNG\n- GIF\n- BMP\n- WEBP\n\n### 使用方法\n1. **直接使用文件路径**:\n   ```python\n   result = await client.call_tool(\"analyze_image\", {\n       \"image_input\": \"/path/to/your/image.jpg\",\n       \"api_key\": \"your_api_key\"\n   })\n   ```\n\n2. **相对路径**:\n   ```python\n   result = await client.call_tool(\"analyze_image\", {\n       \"image_input\": \"./test_image.jpg\",\n       \"api_key\": \"your_api_key\"\n   })\n   ```\n\n### 快速演示\n\n#### 方法一：快速测试（推荐）\n```bash\n# 1. 创建测试图片\npython3 create_test_image.py\n\n# 2. 设置API密钥（必需）\nexport DOUBAO_API_KEY=\"your_doubao_api_key\"\n\n# 3. 运行快速测试\npython3 quick_test.py\n```\n\n**输出示例：**\n```\n🚀 快速测试 Vision MCP 服务\n✅ 服务器启动成功\n🔍 分析图片: test_image.jpg\n✅ 分析成功!\n📝 描述: 图片包含红色圆形、绿色长方形、黄色三角形...\n🤖 模型: doubao-seed-1-6-flash-250615\n```\n\n#### 方法二：完整演示\n```bash\n# 1. 创建测试图片\npython3 create_test_image.py\n\n# 2. 设置API密钥（必需）\nexport DOUBAO_API_KEY=\"your_doubao_api_key\"\n\n# 3. 运行完整演示\npython3 demo_local_image.py\n```\n\n**功能特点：**\n- 🔄 自动从环境变量读取API密钥\n- 📝 支持自定义分析提示\n- 🎯 基本分析和定制分析对比\n- 📊 详细的结果展示\n\n## 许可证\n\nMIT License","readmeFilename":"README.md"}