Universal MCP

MCP桌面可视化

🖥️ 通过MCP控制和了解您的Windows桌面

一个强大的MCP（模型上下文协议）服务器，允许LLM查看您的Windows桌面并与之交互。它捕获屏幕，检测UI元素（按钮、输入、文本），并提供鼠标和键盘控制工具。

✨ 特性

• 增量屏幕截图：只处理更改的区域，大大减少令牌使用
• UI元素检测：自动检测按钮、输入、文本、复选框等
• OCR文本提取：使用Tesseract OCR从屏幕读取文本
• 视觉状态缓存：维护“虚拟桌面DOM”以实现高效查询
• 鼠标控制：单击、双击、右键单击、拖动、滚动、悬停
• 键盘控制：键入文本（包括Unicode）、按键、热键
• 窗口管理：列出、查找和跟踪窗口

🚀 快速开始

先决条件

1. Python 3.10+ - 下载
2. 泰瑟光学字符识别 （可选，用于文本识别）- Windows版下载

安装

运行自动安装脚本：

# Clone or download the project
cd universal-mcp

# Run setup (creates venv, installs dependencies, configures VS Code)
.\setup.ps1

这将：

• 创建虚拟环境(.venv)
• 安装所有依赖项
• 检查/安装Tesseract OCR
• 创建VS代码配置(.vscode/mcp.json)
• 创建默认配置(mcp-desktop-config.json)

手动安装（替代）

如果您更喜欢手动设置：

# Create virtual environment
python -m venv .venv
.venv\Scripts\Activate.ps1

# Install dependencies
pip install -e .

配置VS代码

安装脚本创建 .vscode/mcp.json 自动。如果您进行了手动安装，请手动创建：

{
  "servers": {
    "desktop-visual": {
      "command": "C:/path/to/universal-mcp/.venv/Scripts/python.exe",
      "args": ["-m", "mcp_desktop_visual.server"]
    }
  }
}

或添加到您的全球VS代码 settings.json:

{
  "mcp": {
    "servers": {
      "desktop-visual": {
        "command": "python",
        "args": ["-m", "mcp_desktop_visual.server"],
        "cwd": "C:/path/to/universal-mcp"
      }
    }
  }
}

📚 可用工具

屏幕状态工具

鼠标工具

键盘工具

窗口工具

实用工具

🎯 使用示例

示例：单击按钮

// Find and click a button by label
{ "tool": "mouse_click", "target": "Save" }

// Or by coordinates
{ "tool": "mouse_click", "target": [500, 300] }

示例：填写表格

// Type in an input field
{ "tool": "keyboard_type_in", "target": "Username", "text": "myuser" }

// Press Tab to move to next field
{ "tool": "keyboard_press", "key": "tab" }

// Type password
{ "tool": "keyboard_type", "text": "mypassword" }

// Click submit
{ "tool": "mouse_click", "target": "Submit" }

示例：使用键盘快捷键

// Copy (Ctrl+C)
{ "tool": "keyboard_hotkey", "keys": ["ctrl", "c"] }

// Save (Ctrl+S)
{ "tool": "keyboard_hotkey", "keys": ["ctrl", "s"] }

// Close window (Alt+F4)
{ "tool": "keyboard_hotkey", "keys": ["alt", "f4"] }

示例：窗口管理

// List all windows
{ "tool": "window_list" }

// Find a specific window
{ "tool": "window_find", "title": "Chrome" }

// Activate a window
{ "tool": "window_activate", "title": "VS Code" }

// Get active window info
{ "tool": "window_active" }

示例：查询屏幕状态

// Get all buttons
{ "tool": "screen_query", "element_type": "button" }

// Find elements by text
{ "tool": "screen_query", "label": "Settings" }

// Get incremental changes
{ "tool": "screen_capture" }

📁 例子

这 examples/ 文件夹包含演示常见用例的示例脚本：

• basic_usage.py -基本屏幕截图和元素检测
• form_filling.py -通过键盘输入自动填写表单
• screen_monitoring.py -连续屏幕监控和变化检测

举个例子：

# Activate virtual environment
.venv\Scripts\Activate.ps1

# Run basic usage example
python examples/basic_usage.py

⚙️ 配置

创建 mcp-desktop-config.json 在您的项目或主目录中：

{
  "capture": {
    "diff_threshold": 30,
    "min_region_area": 100,
    "capture_interval": 0.5
  },
  "ocr": {
    "tesseract_path": "C:/Program Files/Tesseract-OCR/tesseract.exe",
    "language": "eng",
    "confidence_threshold": 60
  },
  "input": {
    "click_delay": 0.1,
    "typing_delay": 0.02,
    "failsafe": true
  },
  "cache": {
    "max_elements": 1000,
    "max_history": 10
  }
}

🔧 建筑

┌─────────────────────────────────────────────────────────────┐
│                     MCP Server (stdio)                       │
├─────────────────────────────────────────────────────────────┤
│                    Desktop Visual Engine                     │
├─────────────┬──────────────┬──────────────┬────────────────┤
│   Screen    │   Element    │    Input     │   Visual State │
│   Capture   │   Detector   │  Controller  │     Cache      │
│ (MSS/OpenCV)│  (OCR/CV)    │ (PyAutoGUI)  │ (Virtual DOM)  │
└─────────────┴──────────────┴──────────────┴────────────────┘

增量处理流程

1. 捕捉：截图
2. 差异：与前一帧进行比较，查找更改的区域
3. 检测：仅在更改的区域上运行OCR/元素检测
4. 缓存：用新元素更新虚拟DOM
5. 返回：将JSON差异发送到LLM（只发送更改的内容！）

与每次全屏分析相比，这种方法通常将处理量减少80-95%。

🧪 测试

运行测试套件：

# Activate virtual environment
.venv\Scripts\Activate.ps1

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Or run specific test files
python test_mcp.py

\> Nota: a integração via Chrome DevTools Protocol (CDP) foi removida. Para automação dentro do navegador, use a extensão em `browser_extension/`.

🐛 故障排除

未找到Tesseract

如果OCR不起作用，请确保Tesseract已安装且可访问：

# Test Tesseract
tesseract --version

# Or specify path in config
{
  "ocr": {
    "tesseract_path": "C:/Program Files/Tesseract-OCR/tesseract.exe"
  }
}

权限问题

在某些系统上，您可能需要以管理员身份运行VS Code，以便输入控制正常工作。

屏幕截图问题

确保没有屏幕录制或DRM保护处于活动状态，因为这些可能会阻止屏幕截图。

📝 许可证

MIT许可证-请参阅 许可证 了解详情。

🤝 贡献

欢迎投稿！请随时提交拉取请求。