vision-graft-mcp

# 视觉移植 MCP（VGMCP） **English** · [한국어](README.ko.md) > ⚠️ **正在进行中**。该项目仍在积极开发中，本 README 将再次修订。步骤、命令和行为可能会更改。 给一个“盲目”的AI编码模型一个**眼睛**。许多快速或本地的LLMs看不到图像——它们只读取你的HTML/CSS/JSX，所以它们无法判断一个按钮是否被剪切或两个元素是否重叠。VGMCP捕获你的屏幕，将其发送到具有视觉能力的模型，并为AI提供一份它可以读取的书面报告，以便它可以实际调试视觉错误。 它同时以两种方式工作： - **AI使用它**，通过 [MCP](https://modelcontextprotocol.io) 标准（在Cursor、Claude Desktop、oh-my-pi等中）。 - **你使用它**，从一个小的**菜单栏图标（macOS）** / **系统托盘图标（Windows）**（捕获屏幕/窗口/区域，分析最后的图片，复制一个可以直接粘贴的提示）。 > 平台：**macOS 14（Sonoma）或更新版本**，或 **Windows 10/11**。 --- ## 目录 1. [工作原理（30秒版本）](#工作原理) 2. [开始前](#开始前) 3. [步骤 1 — 安装](#步骤-1--安装) 4. [步骤 2 — 添加视觉提供者（API密钥）](#步骤-2--添加视觉提供者-api密钥) 5. [步骤 3 — 授予屏幕录制权限](#步骤-3--授予屏幕录制权限) 6. [步骤 4 — 启动应用](#步骤-4--启动应用) 7. [步骤 5 — 连接你的AI工具（MCP）](#步骤-5--连接你的ai工具-mcp) 8. [每天使用](#每天使用) 9. [命令参考](#命令参考) 10. [故障排除](#故障排除) 11. [隐私和存储位置](#隐私和存储位置) 12. [开发者](#开发者) --- ## 工作原理 ``` 你的AI工具（Cursor / Claude / oh-my-pi） │ 请求截图和分析（MCP） ▼ vgmcp-adapter ── 与 ──▶ VGMCP 应用（菜单栏，一直运行） • 捕获屏幕 • 发送到视觉模型 • 返回书面报告 ▲ └─ 你也可以从菜单栏图标驱动同样的事情。 ``` **菜单栏应用必须运行**，AI端才能工作——它是持有摄像头和设置的部分。 --- ## 开始前 安装需要使用终端——**Terminal**（macOS）或 **PowerShell**（Windows）。只需复制和粘贴几行代码。（大多数步骤也有**双击**选项，因此您可以完全跳过终端。） **检查您是否有Python 3.11或更新版本：** ```bash python3 --version # macOS python --version # Windows ``` - 如果打印 `Python 3.11.x` 或更高版本 → 没问题。 - 如果更旧或“找不到命令”→ 从 [python.org/downloads](https://www.python.org/downloads/) 安装最新的Python（macOS + Homebrew：`brew install python`；在 **Windows** 上勾选 **"Add Python to PATH"** ）。 您还需要来自视觉提供者的 **API密钥**（选择一个）： | 提供者 | 获取密钥位置 | 备注 | |---|---|---| | **OpenRouter** | <https://openrouter.ai/keys> | 一个密钥，多个模型。良好的默认选择。 | | **Anthropic（Claude）** | <https://console.anthropic.com/> | | | **OpenAI（GPT-4o）** | <https://platform.openai.com/api-keys> | | | **Ollama（本地）** | *无需密钥* — <https://ollama.com> | 在您的计算机上运行，免费，无内容离开。 | --- ## 步骤 1 — 安装 克隆或下载并解压项目后： ### macOS **最简单 - 双击 `install_mac.command`** 在项目文件夹（Finder）中。一个终端窗口运行安装程序（它创建了一个隔离的Python环境并安装了VGMCP）。当它打印 **"✅ 安装完成"** 时，您就完成了。 > 如果macOS不允许运行（右键单击或“权限被拒绝”）：右键单击 `install_mac.command` → **打开** （然后确认），或在终端中运行 `chmod +x install_mac.command && ./install_mac.command`。 终端替代方案： ```bash cd <项目文件夹> ./install_mac.command # 完全手动： python3 -m venv .venv && .venv/bin/pip install -e ".[macos]" ``` ### Windows **最简单 - 双击 `install_win.bat`** 在项目文件夹中。一个PowerShell窗口运行安装程序；当它打印 **"✅ 安装完成"** 时，您就完成了。（`.bat`为您处理PowerShell执行策略提示。） PowerShell 替代方案： ```powershell cd <项目文件夹> .\install_win.ps1 # 如果阻止：powershell -ExecutionPolicy Bypass -File .\install_win.ps1 # 完全手动： python -m venv .venv ; .\.venv\Scripts\pip install -e ".[windows]" ``` > **📌 本指南其余部分的命令路径** 以macOS格式编写 `/.venv/bin/vgmcp …` 。 **在Windows上，请改用 `/.venv\Scripts\vgmcp.exe …`** （以及 `python` 而不是 `python3`）。前缀后的所有内容都相同。 --- ## 步骤 2 — 添加视觉提供者（API密钥） 您可以 **两种方式** 执行此操作 - 使用您喜欢的方式： > **🖱️ 更喜欢点击？使用菜单栏（无需终端）**。首先启动应用程序（[步骤 4](#步骤-4--启动应用)），然后打开菜单栏图标 → **设置 → 管理视觉后端 → 添加…**。它依次询问提供者类型、名称、模型（对于 `custom`）、端点URL和API密钥（密钥字段被遮蔽）。同意是 **允许外部传输** 项，在同一子菜单中，您也可以在那里设置默认值。如果您走这条路，您可以跳过下面的命令。 **⌨️ 或使用终端**。注册您选择的提供者。使用 `--key -` 会使终端使用 **隐藏提示** 请求密钥，因此您的密钥永远不会在屏幕上或历史记录中显示。 **OpenRouter（推荐）：** ```bash .venv/bin/vgmcp provider add --type openrouter --model "anthropic/claude-sonnet-4.6" --key - --set-default .venv/bin/vgmcp provider consent openrouter ``` **Anthropic（Claude）：** ```bash .venv/bin/vgmcp provider add --type anthropic --model "claude-sonnet-4-6" --key - --set-default .venv/bin/vgmcp provider consent anthropic ``` **OpenAI：** ```bash .venv/bin/vgmcp provider add --type openai --model "gpt-5.4" --key - --set-default .venv/bin/vgmcp provider consent openai ``` **Ollama（本地，无密钥，无云数据发送）：** ```bash # 首先从 https://ollama.com 安装 Ollama 并拉取视觉模型： ollama pull llava:7b .venv/bin/vgmcp provider add --type ollama --model "llava:7b" --set-default # 无需同意 - 它永远不会离开您的计算机。 ``` > **选择本地模型**。使用 **非推理** 视觉模型来适应您的 **VRAM** - 推理型VLM（例如 `qwen3-vl`）倾向于花费整个token预算进行“思考”，并返回空/不稳定的答案，因此不建议在此使用。对于 **8 GB** GPU， **`llava:7b`**（~4.7 GB）是推荐的选择。VRAM越小，尝试更小的模型（例如 `moondream`）；VRAM越大，尝试更大的模型。注意，小型本地模型适合快速检查，但准确性远低于云模型 - 当您需要精确分析时使用云提供者。 `consent` 行是一次性 **"是的，您可以向此云服务发送我的截图"** 的确认。（Ollama 不需要。） 检查是否成功： ```bash .venv/bin/vgmcp provider list ``` 您应该看到您的提供者，`"has_key": true` 和 `"consented": true`。 --- ## 步骤 3 — 授予屏幕录制权限 ### Windows 无需操作 - Windows 不需要特殊的屏幕捕获权限。跳到 [步骤 4](#步骤-4--启动应用)。（您仍然可以使用 `.venv\Scripts\vgmcp.exe check` 进行验证。） ### macOS macOS 必须允许 VGMCP 查看屏幕。 1. 打开 **系统设置 → 隐私和安全 → 屏幕录制**。 2. 为您的 **终端** （和稍后 VGMCP 应用）打开开关。 3. 如果 macOS 要求您退出并重新打开应用，请这样做。 您只需执行此操作一次。（在macOS上，启动VGMCP的应用是需要权限的 - 通常是设置期间的终端。） 使用以下命令验证所有准备工作是否就绪： ```bash .venv/bin/vgmcp check ``` 如果它打印缺少的项目列表，请按照每个 `guide` / `install_command` 的提示进行操作。完全设置完成后，它会显示环境正常。 --- ## 步骤 4 — 启动应用 - **macOS:** 双击 **`start_mac.command`** （或运行 `.venv/bin/vgmcp`）。一个小的 **图标出现在菜单栏** （屏幕右上角）。 - **Windows:** 双击 **`start_win.bat`** （或运行 `.venv\Scripts\vgmcp.exe`）。一个小的 **图标出现在系统托盘** （右下角时钟旁边 - 您可能需要点击 **^** 溢出箭头）。它隐藏启动，因此您可以关闭窗口。 然后，在任一平台上： - 🟢 绿色 / **白色·黑色** （Windows，根据任务栏适配）= 就绪 · - 🟡 黄色 = 有效但缺少某些可选内容 · - 🔴 红色 = 需要关注（单击它以获取指导）。 - 在首次启动时，您将看到一个简短的欢迎通知 - 阅读并单击确定。 - 单个 **左键单击** （或右键单击）打开菜单。 保持它运行。要停止它，请单击图标 → **退出 / Quit**。 **希望它在每次登录时自动启动？** ```bash .venv/bin/vgmcp autostart enable ``` （或在菜单中切换 **设置 → 登录时自动启动 / Settings → Start at login**。） --- ## 步骤 5 — 连接您的AI工具（MCP） 您的AI工具通过一个名为适配器的微型帮助程序与VGMCP通信。您在工具的MCP设置中注册它一次。使用 **完整路径** 到适配器（用下面项目位置替换）： ```json { "mcpServers": { "vgmcp": { "command": "/Users/yourname/Projects/vision-graft-mcp/.venv/bin/vgmcp-adapter" } } } ``` 在 **Windows** 上，命令是 `Scripts` 下的 `.exe` （在JSON中使用双反斜杠），例如： ```json { "mcpServers": { "vgmcp": { "command": "C:\\Users\\yourname\\Projects\\vision-graft-mcp\\.venv\\Scripts\\vgmcp-adapter.exe" } } } ``` 使用以下命令查找确切的路径： ```bash echo "$(pwd)/.venv/bin/vgmcp-adapter" # macOS ``` ```powershell "$(Get-Location)\.venv\Scripts\vgmcp-adapter.exe" # Windows ``` 此JSON的位置取决于工具： - **Cursor:** `~/.cursor/mcp.json`（全局）或 `.cursor/mcp.json` 在您的项目中。 - **Claude Desktop（macOS）：** `~/Library/Application Support/Claude/claude_desktop_config.json`。 - **Claude Desktop（Windows）：** `%APPDATA%\Claude\claude_desktop_config.json`。 - **oh-my-pi / others:** 工具列出"MCP服务器"的位置。 在编辑后重启AI工具。它现在应该显示VGMCP的工具（例如 `take_screenshot` 和 `analyze_vision`）。 > **重要：** 来自步骤 4 的菜单栏应用必须运行，否则适配器会礼貌地报告应用已关闭并要求您启动它。 --- ## 每天使用 **让AI自己做。** 只需问您的编码模型这样的问题： > “运行应用程序，截取屏幕截图，并检查布局是否损坏。” 它将调用 `take_screenshot` → `analyze_vision`，并使用书面报告修复CSS - 即使它本身看不到图像。 **或从菜单栏图标（macOS）/系统托盘（Windows）图标自己做：** - **捕获 / Capture** → 整个显示器、特定窗口或 **拖选区域**，或打开现有图像文件。 - **平台说明 - 窗口最小化：** 在 **Windows** 上，应用程序窗口列表包括最小化窗口并自动恢复它们以进行捕获。 在 **macOS** 上，最小化窗口被跳过（ScreenCaptureKit 没有它们的渲染表面，因此需要单独的Accessibility权限），因此请先恢复窗口以捕获它。 - **分析最后的图片 / Analyze last image** → 将最近的捕获内容发送到您的视觉模型并显示摘要。 - **最近的图片 / Recent images** → 点击一个以复制可以直接粘贴的提示（带有图像路径）到您的剪贴板。将其粘贴到您的AI工具中。 **终端快速测试（无需AI工具）： ```bash .venv/bin/vgmcp capture-analyze --target region --x 0 --y 0 --w 800 --h 500 ``` 这会捕获屏幕的一部分并打印视觉模型的报告。 --- ## 命令参考 ```bash # 应用 / 主机 vgmcp # 启动菜单栏应用 + 后台主机 vgmcp --no-tray # 仅运行主机，在前台（高级） vgmcp check # 检查环境并打印缺少的内容 # 视觉提供者 vgmcp provider add --type <anthropic|openai|openrouter|custom|ollama> [--model M] [--key -] [--set-default] vgmcp provider list # 显示提供者（密钥/同意状态） vgmcp provider update <id> [--model M] [--key -] [--set-default] vgmcp provider remove <id> # 也会删除其存储的密钥 vgmcp provider consent <id> [--revoke] # 允许/拒绝将截图发送到云 # 运行真正的视觉循环 vgmcp capture-analyze --target monitor # 捕获屏幕 + 分析 vgmcp capture-analyze --target window --app-name "Safari" # 特定应用窗口 vgmcp capture-analyze --target region --x 100 --y 100 --w 600 --h 400 vgmcp analyze /path/to/image.png # 分析现有图像 # 登录时启动 vgmcp autostart enable | disable | status ``` 对于 `custom`（自托管 / 网关）提供者，还需要 `--base-url "https://your-endpoint/v1 disable | disable | status ``` --- ## 故障排除 **菜单栏 / 系统托盘图标不见了。** 应用程序未运行。运行 `.venv/bin/vgmcp`（macOS）或 `.venv\Scripts\vgmcp.exe`（Windows）。在 Windows 上，检查 **^** 系统托盘溢出。（关闭启动终端可能会停止它 - 启用自动启动，或使用双击启动器。） **捕获内容为黑色或失败。** - **macOS：** 屏幕录制权限丢失或过期。重复 [步骤 3](#步骤-3--授予屏幕录制权限)，然后退出并重启应用程序。运行 `.venv/bin/vgmcp check` 以确认。 - **Windows：** 无需权限；黑色边框通常意味着 DirectX/全屏应用（超出范围）。捕获 **整个显示屏** 而不是使用普通应用窗口。 **AI 工具说主机不可达。** 启动菜单栏应用（`.venv/bin/vgmcp`）- 适配器需要它运行。 **`AUTH_FAILED` / 来自视觉模型的 401。** 您的 API 密钥错误或过期。重新存储它： `.venv/bin/vgmcp provider update <id> --key -` **`consent_required`.** 您尚未批准向该云提供者发送截图： `.venv/bin/vgmcp provider consent <id>` （或菜单切换）。本地 Ollama 永远不需要。 **`OLLAMA_UNAVAILABLE`.** 启动 Ollama (`ollama serve`) 并确保模型已拉取 (`ollama pull llava:7b`). **`command not found: python3`.** 从 [python.org/downloads](https://www.python.org/downloads/) 安装Python。 --- ## 隐私和存储位置 - **API 密钥** 存储在操作系统凭证存储中 - **macOS 钥匙串** / **Windows 凭证管理器** - 从不存储在纯文本文件中。 - **设置** 位于 `~/.config/vgmcp/config.json`（macOS）/ `%USERPROFILE%\.config\vgmcp\config.json`（Windows）- 提供者、目标文件夹、偏好设置，但 **不包括** 密钥。 - **截图** 默认保存在 `~/Pictures/vgmcp/`（macOS）/ `%USERPROFILE%\Pictures\vgmcp\`（Windows）（可在设置 > 目标文件夹中更改）。 - **云提供者** 仅在您授予 **同意** 后接收您的截图。大型图像会被缩放到发送前；小型图像会原样发送。优先使用 **Ollama**，如果您希望没有任何内容离开您的计算机。 --- ## 开发者 ```bash # macOS .venv/bin/pip install -e ".[macos,dev]" .venv/bin/python -m pytest -q # 运行测试 .venv/bin/ruff check src/ tests/ # 语法检查 ``` ```powershell # Windows .\.venv\Scripts\pip install -e ".[windows,dev]" .\.venv\Scripts\python -m pytest -q .\.venv\Scripts\ruff check src/ tests/ ``` - **语言：** 应用、安装程序和启动器显示 **如果操作系统偏好韩语，则为韩语，否则为英语**。强制使用 `VGMCP_LANG=ko` 或 `VGMCP_LANG=en`。 - **自定义托盘图标：** 图标来自单个 SVG 文件 `src/vgmcp/assets/aperture.svg`（真实来源）。在 **macOS** 上，它被渲染为 `~/.config/vgmcp/icons/` 中的缓存 PNG 文件（删除后重新生成）；正常状态为黑色 **模板** 图像（自动黑色/白色根据 light/dark）+ **琥珀色/红色** 用于警告/错误。在 **Windows** 上，使用Pillow内存中绘制相同的几何形状（坐标镜像SVG文件 `tray/windows.py`）；OK状态适应任务栏主题（白色/黑色）+警告/错误时为琥珀色/红色。如果更改 `aperture.svg`，请更新Windows坐标以匹配。 - 架构、里程碑和完整规范： [`docs/plan.md`](docs/plan.md)；原始概念： [`docs/idea.md`](docs/idea.md)。 - 托盘应用托管一个环回MCP服务器（`127.0.0.1:8765`）持有共享核心（捕获/视觉/剪贴板/环境）。MCP客户端通过薄 `vgmcp-adapter` 连接，它代理到它 - 所以用户（托盘）和AI（MCP）驱动相同的核心，目标文件夹和配置。 - 如果在非默认位置运行主机，请使用 `VGMCP_SERVER_URL`（或 `VGMCP_HOST` / `VGMCP_PORT`）覆盖适配器的目标。 Requires Python ≥ 3.11. macOS target is 14 (Sonoma)+ (ScreenCaptureKit); Windows target is 10/11 (mss + Win32, pystray tray).