👁️ Visual Cortex MCP服务器
一个专门的MCP服务器，为盲人AI代理提供“视觉”。它检测UI元素并返回 像素完美坐标 为了实现自动化。
它运行在 怪异端口43210 默认情况下。
🚀 支持的后端
1.谷歌双子座（默认和最佳）
- 型号：
models/gemini-flash-latest - 演出 最快的原生2D接地支持。
- 成本： 非常低。
2.OpenAI/本地兼容
- 型号： 可配置（用户定义）。
- 技术支持： 适用于
gpt-4o, Qwen3 8 VL,vLLM托管视觉模型，或LM Studio. - 特征： 增强的快速工程，可更好地与各种视觉模型兼容。
🛠️ 安装
- 克隆和安装：
pip install -r requirements.txt- 配置环境：
复制 .env.example 到 .env 并设置您的提供商。
*对于谷歌：*
export GROUNDING_PROVIDER=google
export API_KEY=your_gemini_key*对于本地LLM：*
export GROUNDING_PROVIDER=openai
export BASE_URL=http://localhost:1234/v1
export MODEL_NAME=llama-3.2-vision
export API_KEY=local- 运行：
python grounding_server.py*服务器侦听端口43210*
🤖 用法
输入： Base64编码图像。 输出： JSON格式 box_px （绝对像素坐标）。
代理说明
“使用analyze_screenshot看看。该工具返回组件列表。使用center_x和center_y内部box_px单击元素。"
✨ 最近的改进
增强的兼容性和稳健性
- ✅ 完全兼容OpenAI API -与Qwen3 8 VL和其他视觉模型无缝协作
- ✅ 改进了错误处理 -全面的验证和特定的错误消息
- ✅ 更好的响应解析 -优雅地处理各种模型输出格式
- ✅ 增强的提示 -针对Gemini和OpenAI兼容模型进行了优化
- ✅ 增加代币限额 -现在，复杂UI最多支持4096个令牌（之前为2048个）
- ✅ 强大的图像处理 -更好的EXIF方向支持和格式检测
- ✅ 输入验证 -验证base64格式、图像尺寸和文件大小
- ✅ 方框坐标验证 -自动校正反转坐标并验证范围
- ✅ 键入提示 -完整的类型注释，以获得更好的IDE支持和代码质量
🎯 新功能：最佳UI捕获，实现最高精度
- ✅ 根和非根支持 -适用于root和标准Android设备
- ✅ 自动设备配置 -用于配置最佳视觉设置的ADB工具
- ✅ 混合捕获模式 -结合屏幕截图和用户界面层次结构，实现地面实况准确性
- ✅ 布局边界支持 -UI组件的视觉标记化
- ✅ 设置指南 -两种模式的全面说明
🐳 码头工人
docker build -t visual-cortex .
docker run -p 43210:43210 --env-file .env visual-cortex📱 Android设备设置（可选但推荐）
对于 最大精度 在UI组件识别中，使用最佳视觉设置配置您的Android设备。这对两者都有效 扎根的 和 未点火 设备。
通过ADB快速设置
服务器提供自动配置设备的工具：
# Get setup instructions for your device type
get_optimal_setup_guide(rooted=False) # or True for rooted devices
# Automatically configure connected device
configure_device_for_capture()
# Capture screenshot + UI hierarchy for enhanced accuracy
capture_with_hierarchy()
# Restore device to normal settings when done
restore_device_settings()配置了什么？
- 布局边界 -每个UI元素周围的视觉矩形（MVP设置！）
- 动画禁用 -零延迟捕获（无中间过渡模糊）
- 示范模式 -清洁状态栏（固定时间、电池、无通知）
- 层次结构转储 -地面实况坐标和元数据
手动设置
如果您更喜欢手动配置或ADB不可用，请使用 get_optimal_setup_guide 工具以获取详细的分步说明。
🎯 使用UI层次结构增强分析
使用混合方法获得最佳结果：
# Standard analysis (screenshot only)
analyze_screenshot(image_base64)
# Enhanced analysis (screenshot + UI hierarchy)
analyze_screenshot_with_hierarchy(image_base64, ui_hierarchy_xml)混合方法给出了VL模型：
- 视觉语境：带有布局边界的屏幕截图
- 地面实况：XML中的精确坐标、资源ID和文本
- 结果：尽可能高的准确性和减少幻觉
🔧 可用的MCP工具
| 工具 | 说明 |
|---|---|
analyze_screenshot | 从屏幕截图中检测标准UI组件 |
analyze_screenshot_with_hierarchy | 使用屏幕截图+UI层次结构增强检测 |
get_optimal_setup_guide | 获取已根/未根设备的设置说明 |
configure_device_for_capture | 通过ADB自动配置设备 |
capture_with_hierarchy | 从设备捕获屏幕截图+UI层次结构 |
restore_device_settings | 将设备还原为默认设置 |
🧪 测试
运行测试套件以验证功能：
pytest test_grounding.py -v测试包括：
- 框坐标缩放和验证
- 后端初始化（谷歌和OpenAI）
- 图像格式处理
- 错误处理和边缘情况
📚 为什么采用这种混合方法？
VL型号的“最佳模式”不是单个开关，而是一种创建 “干净但语义密集”的视觉提要:
- 布局边界：显式红色/蓝色矩形“标记”屏幕
- 无动画：确保清晰、确定的捕获
- 示范模式：从状态栏中删除视觉噪音
- UI层次结构：提供消除猜测的基本事实
这种组合赋予了模型“X射线视觉”——像素级视觉和结构语义。