local vision

本地视觉MCP

基于MCP（模型上下文协议）的原生视觉分析工具，使用LM Studio的视觉模型来分析图像。

功能特性

• 🔍 局部图像分析：支持分析本地PNG、JPG、JPEG、WEBP格式的图像
• 🤖 可视化模型集成：整合LM Studio的视觉模型以实现图像理解
• 🛡️ 安全限制：只允许访问本地现有的图像文件，以防止路径遍历攻击
• ⚡ 快速响应：支持自定义分析提示的异步处理

系统要求

• Python 3.8+
• LM Studio（或其他本地服务器）服务正在运行
• 支持的图像格式：PNG、JPG、JPEG、WEBP

安装配置

1.环境准备（不必要）

确保已安装Conda并创建“mlx”环境：

conda create -n mlx python=3.10
conda activate mlx

2.安装依赖项

要在项目目录中安装所需的依赖项，请执行以下操作：

pip install mcp httpx

3.配置LM Studio

1. 启动LM工作室
2. 下载并加载愿景模型（例如“qwen3.5:2b-bf16”）
3. 请确保LM Studio API服务正在“”上运行http://localhost:11434'

4.环境变量配置（可选）

可以设置以下环境变量：

# Set the LM Studio service address (default: http://localhost:11434)
export LM_STUDIO_URL="http://localhost:11434"

# Set the visual model name (default: qwen3.5:2b-bf16)
export VISION_MODEL="qwen3.5:2b-bf16"

# Set the Conda environment name (default: mlx)
export MCP_CONDA_ENV="mlx"

如何使用

作为MCP服务器运行

1. 直接运行:

python main.py

1. 在Opencode中配置:

添加您的 opencode.json:

{
 "mcp": {
    "local_vision": {
      "type": "local",
      "command": ["python", "your path"],
      "environment": {
        "LM_STUDIO_URL": "http://localhost:11434",
        "VISION_MODEL": "qwen3.5:2b-bf16"
      }
    }
}

可用工具

“analyze_image”-分析本地图像

参数:

• 'image_path'（必填）：图像文件的本地绝对路径
• “提示”（可选）：对于有关图像的特定问题，默认提示将要求提供图像内容的描述

示例调用：

{
  "name": "analyze_image",
  "arguments": {
    "image_path": "/Users/username/Pictures/photo.png",
    "prompt": "What objects are in the image? What is their positional relationship? "
  }
}

默认提示:

Please answer strictly based on the information visible in the picture, do not guess. First, outline the image, then extract the visible text, explain the key elements and positional relationships, and finally answer my question directly. Where you can't see clearly, please clearly write "uncertain". My question: Please describe this image

运作原理

1. 环境检查：自动检测并切换到指定的Conda环境
2. 文件验证：检查图像文件是否存在以及格式是否受支持
3. 图像编码：将图像转换为base64格式
4. 模型调用：通过LM Studio API调用视觉模型
5. 结果解读：提取并返回模型生成的文本描述

安全功能

• ✅ 仅允许访问本地现有文件
• ✅ 限制文件扩展名（仅限图像格式）
• ✅ 防止路径遍历攻击
• ✅ 输入参数验证

故障排除

常见问题

1. “找不到Conda环境mlx的Python”

- 确保已创建“mlx”环境：“conda create-n mlx python=3.10” - 或者设置“MCP_CONDA_ENV”环境变量以指定其他环境名称

1. 调用可视化模型失败

- 检查LM Studio是否正在运行：'curlhttp://localhost:11434/v1/models' - 确认模型已加载并支持视觉功能 - 检查您的网络连接和防火墙设置

1. 支持的文件格式

- 确保图像格式为：PNG、JPG、JPEG、WEBP - 检查文件扩展名是否正确

1. '文件不存在'

- 验证映像路径是否正确以及文件是否存在 - 使用绝对路径而不是相对路径

调试模式

您可以添加调试输出以排除问题：

# Add debugging information to main.py
import logging
logging.basicConfig(level=logging. DEBUG)

开发指南

项目结构

local_vision_mcp/
├── main.py # Master program file
├── README.md # Instructions
├── .gitignore # Git ignores files
└── __pycache__/ # Python cache file

扩展功能

要添加新功能，您可以：

1. 添加新工具：在“handle_list_tools（）”中注册一个新工具
2. 支持更多格式：在“allowe_ext”中添加新的图像格式
3. 自定义提示：修改默认提示模板
4. 添加缓存：实现图像分析结果的缓存机制

代码贡献

1. Fork项目
2. 创建要素分支
3. 提交更改
4. 创建拉取请求

许可证

该项目根据麻省理工学院许可证获得许可。有关详细信息，请参阅\[许可证\]（LICENSE）文档。

支持和反馈

如有疑问或建议，请：

1. 检查 故障排除 部分
2. 向项目存储库提交问题
3. 或通过邮件联系维护人员

______________________________________________________________________

提示：确保LM Studio服务正在运行，并且加载了支持视觉的模型。