STARWARCLOUD STARWAR.AI
返回市场
MCP开放视觉

MCP开放视觉

作者：Nazruden11 星标更新：2025-04-01
安装使用来源：spider==github.com

项目介绍

MCP OpenVision

CI PyPI version Python Versions License: MIT Buy Me A Coffee smithery badge

概述

MCP OpenVision 是一个基于 Model Context Protocol (MCP) 的服务器，它提供了由 OpenRouter 视觉模型驱动的图像分析能力。它使AI助手能够通过简单的接口在MCP生态系统中分析图像。

安装

通过 Smithery 安装

要通过 Smithery 自动安装 mcp-openvision 到 Claude Desktop：

npx -y @smithery/cli install @Nazruden/mcp-openvision --client claude

使用 pip 安装

pip install mcp-openvision

使用 UV 安装（推荐）

uv pip install mcp-openvision

配置

MCP OpenVision 需要一个 OpenRouter API 密钥，并可以通过环境变量进行配置：

  • OPENROUTER_API_KEY（必需）：您的 OpenRouter API 密钥
  • OPENROUTER_DEFAULT_MODEL（可选）：要使用的视觉模型

OpenRouter 视觉模型

MCP OpenVision 可以与任何支持视觉能力的 OpenRouter 模型一起工作。默认模型是 qwen/qwen2.5-vl-32b-instruct:free，但您可以指定任何其他兼容模型。

一些通过 OpenRouter 可用的流行视觉模型包括：

  • qwen/qwen2.5-vl-32b-instruct:free（默认）
  • anthropic/claude-3-5-sonnet
  • anthropic/claude-3-opus
  • anthropic/claude-3-sonnet
  • openai/gpt-4o

您可以通过设置 OPENROUTER_DEFAULT_MODEL 环境变量或直接传递给 image_analysis 函数的 model 参数来指定自定义模型。

使用方法

使用 MCP Inspector 测试

测试 MCP OpenVision 最简单的方法是使用 MCP Inspector 工具：

npx @modelcontextprotocol/inspector uvx mcp-openvision

与 Claude Desktop 或 Cursor 集成

  1. 编辑您的 MCP 配置文件：

    • Windows: %USERPROFILE%\.cursor\mcp.json
    • macOS: ~/.cursor/mcp.json 或 ~/Library/Application Support/Claude/claude_desktop_config.json

  2. 添加以下配置：

{
  "mcpServers": {
    "openvision": {
      "command": "uvx",
      "args": ["mcp-openvision"],
      "env": {
        "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
        "OPENROUTER_DEFAULT_MODEL": "anthropic/claude-3-sonnet"
      }
    }
  }
}

开发时本地运行

# 设置所需的 API 密钥
export OPENROUTER_API_KEY="your_api_key"

# 直接运行服务器模块
python -m mcp_openvision

功能

MCP OpenVision 提供了以下核心工具：

  • image_analysis：使用视觉模型分析图像，支持各种参数：
    • image：可以提供为：
      • Base64 编码的图像数据
      • 图像 URL（http/https）
      • 本地文件路径
    • query：用户对图像分析任务的指令
    • system_prompt：定义模型角色和行为的指令（可选）
    • model：要使用的视觉模型
    • temperature：控制随机性（0.0-1.0）
    • max_tokens：最大响应长度

制作有效的查询

query 参数对于从图像分析中获得有用的结果至关重要。精心制作的查询提供了关于以下方面的上下文：

  1. 目的：为什么你要分析这张图片
  2. 关注区域：需要特别注意的具体元素或细节
  3. 所需信息：你需要提取的信息类型
  4. 格式偏好：你希望结果如何组织

有效查询示例

基本查询增强查询
"描述这张图片""识别出这张商店货架图片中可见的所有零售产品并估计它们的价格范围"
"这张图片里有什么？""分析这张医学扫描图中的异常情况，重点关注高亮区域并提供可能的诊断"
"分析这个图表""从这张展示季度销售的柱状图中提取数值数据，并确定2022-2023年的关键趋势"
"读取文本""转录这张餐厅菜单上所有可见的文字，保留项目名称、描述和价格"

通过提供关于为什么你需要分析以及你具体寻求什么信息的上下文，你可以帮助模型专注于相关细节并产生更有价值的见解。

使用示例

# 分析来自 URL 的图像
result = await image_analysis(
    image="https://example.com/image.jpg",
    query="详细描述这张图片"
)

# 分析来自本地文件的图像，带有聚焦查询
result = await image_analysis(
    image="path/to/local/image.jpg",
    query="识别出这张街道场景中的所有交通标志，并解释它们对驾驶课程的意义"
)

# 使用 base64 编码的图像进行分析，并具有特定的分析目的
result = await image_analysis(
    image="SGVsbG8gV29ybGQ=...",  # base64 数据
    query="检查这个产品包装设计，并突出显示可以改进的地方，以提高可见性和品牌认知度"
)

# 为专门分析定制系统提示
result = await image_analysis(
    image="path/to/local/image.jpg",
    query="分析这幅画的构图和艺术技巧，重点是如何创造情感影响",
    system_prompt="你是一位拥有深厚绘画技术和艺术运动知识的艺术史专家。专注于形式分析，如构图、色彩、笔触和风格元素。"
)

图像输入类型

image_analysis 工具接受几种类型的图像输入：

  1. Base64 编码字符串
  2. 图像 URL - 必须以 http:// 或 https:// 开头
  3. 文件路径：
    • 绝对路径：以 /（Unix）或驱动器字母（Windows）开头的完整路径
    • 相对路径：相对于当前工作目录的路径
    • 带 project_root 的相对路径：使用 project_root 参数指定基础目录

使用相对路径

当使用相对文件路径（如 "examples/image.jpg"）时，您有两个选项：

  1. 路径必须相对于服务器正在运行的当前工作目录
  2. 或者，您可以指定一个 project_root 参数：
# 带有相对路径和 project_root 的示例
result = await image_analysis(
    image="examples/image.jpg",
    project_root="/path/to/your/project",
    query="这张图片里有什么？"
)

这对于当前工作目录可能不可预测的应用程序非常有用，或者当您想要使用相对于特定目录的路径引用文件时。

开发

设置开发环境

# 克隆仓库
git clone https://github.com/modelcontextprotocol/mcp-openvision.git
cd mcp-openvision

# 安装开发依赖
pip install -e ".[dev]"

代码格式化

此项目使用 Black 进行自动代码格式化。GitHub Actions 强制执行格式化：

  • 推送到仓库的所有代码都会被自动格式化
  • 对于来自仓库协作者的拉取请求，Black 会格式化代码并直接提交到 PR 分支
  • 对于来自 fork 的拉取请求，Black 会创建一个新的带有格式化代码的 PR，该 PR 可以合并到原始 PR 中

您也可以在本地运行 Black 来格式化代码，然后再提交：

# 格式化 src 和 tests 目录下的所有 Python 代码
black src tests

运行测试

pytest

发布过程

此项目使用自动化发布流程：

  1. 更新 pyproject.toml 中的版本，遵循 语义化版本控制 原则
    • 您可以使用辅助脚本：python scripts/bump_version.py [major|minor|patch]
  2. 更新 CHANGELOG.md，添加有关新版本的详细信息
    • 脚本还会在 CHANGELOG.md 中创建一个模板条目，您可以填写
  3. 将这些更改提交并推送到 main 分支
  4. GitHub Actions 工作流将：
    • 检测版本变化
    • 自动创建新的 GitHub 发布
    • 触发发布工作流，将内容发布到 PyPI

这种自动化有助于维护一致的发布流程，并确保每次发布都得到适当的版本控制和文档记录。

支持

如果您发现这个项目很有帮助，请考虑买杯咖啡支持持续开发和维护。

<a href="https://www.buymeacoffee.com/nazruden" target="_blank"> <img src="https://img.buymeacoffee.com/button-api/?text=Buy me a coffee&emoji=&slug=nazruden&button_colour=FFDD00&font_colour=000000&font_family=Lato&outline_colour=000000&coffee_colour=ffffff" alt="Buy Me A Coffee" width="217" height="60"> </a>

许可证

此项目根据 MIT 许可证发布 - 查看 LICENSE 文件获取详情。