截图服务器 (聚焦文件路径)

本项目提供了一个 MCP (模块化通信协议) 服务器，旨在捕获屏幕截图并方便其他进程或 AI 助手使用，主要通过将屏幕截图保存到客户端（主机）指定的文件路径。

核心问题 & 解决方案

在测试中，AI 助手直接解释通过 MCP 发送的屏幕截图图像数据被证明是不可靠的。此服务器采用更强大的、以文件路径为中心的工作流程：

推荐工作流程 (WSL 主机 -> Windows 服务器):

1. MCP 主机（例如在 WSL 中运行的 AI 助手）调用 save_screenshot_to_host_workspace 工具，并将其 WSL 工作区路径 作为参数提供。
2. 此服务器（在 Windows 上运行）捕获屏幕。
3. 服务器将接收到的 WSL 路径转换为 Windows 可访问的 UNC 路径（例如，\\wsl$\Distro\path）。
4. 服务器通过 UNC 路径将屏幕截图保存到主机 WSL 文件系统中的指定位置。
5. 服务器返回 "success" 或 "failed:..."。
6. MCP 主机知道该文件已保存在其工作区（或路径参数中指定的子目录）中。
7. 然后，MCP 主机可以将 WSL 路径 传递给另一个专门的 MCP 服务器（在 WSL 中运行）进行图像分析。

替代工作流程 (通用):

1. MCP 主机调用 take_screenshot_and_return_path，可以选择指定文件名。
2. 服务器将屏幕截图保存到其本地 images/ 目录。
3. 服务器返回已保存文件的绝对路径（例如，Windows 路径）。
4. MCP 主机接收路径并将其（可能经过转换）传递给分析服务器。

可用工具

此服务器提供以下工具，按推荐使用顺序排列：

• save_screenshot_to_host_workspace(host_workspace_path: str, name: str = "workspace_screenshot.jpg")

  • 推荐用途： 将屏幕截图直接保存到 AI 助手（主机）的当前 WSL 工作区中。这是实现无缝集成的首选方法。
  • 操作： 截取屏幕截图，将提供的 WSL 路径转换为 UNC 路径，并将文件保存到主机的工作区。自动检测 WSL 发行版名称。
  • 参数：
    • host_workspace_path (str): 主机工作区的绝对 WSL 路径（例如，/home/user/project）。
    • name (str, 可选): 文件名。默认为 workspace_screenshot.jpg。
  • 返回值： str - "success" 或 "failed: [错误消息]"。

• take_screenshot_and_return_path(name: str = "latest_screenshot.jpg")

  • 用例： 将屏幕截图保存到相对于服务器位置的固定 images/ 目录，并返回绝对路径（通常是 Windows 路径）。如果调用者需要该路径进行外部处理，则很有用。
  • 参数：
    • name (str, 可选): 文件名。默认为 latest_screenshot.jpg。
  • 返回值： str - 绝对路径或 "failed: [错误消息]"。

• take_screenshot_path(path: str = "./", name: str = "screenshot.jpg")

  • 用例： 将屏幕截图保存到由 Windows 路径或 UNC 路径指定的任意位置（例如，用于保存在主机工作区之外）。需要调用者仔细指定路径。
  • 参数：
    • path (str, 可选): 目标目录（Windows 或 UNC 路径）。默认为服务器的工作目录。
    • name (str, 可选): 文件名。默认为 screenshot.jpg。
  • 返回值： str - "success" 或 "failed: [错误消息]"。

设置和使用

1. 前提条件

• Python 3.x： 运行服务器的机器上需要安装。
• 依赖项： 使用 uv 安装：

  uv sync
  

  所需的库包括 mcp[cli]>=1.4.1、pyautogui 和 Pillow。

2. 运行服务器

此服务器通常 由 MCP 主机根据其配置启动。

3. 环境注意事项（尤其是 WSL2）

关键点： 要捕获 Windows 屏幕，此 screenshot.py 服务器必须直接在 Windows 上运行。

推荐的 WSL2 主机 -> Windows 服务器设置：

1. 项目位置： 将此 screenshot-server 项目文件夹放置在您的 Windows 文件系统上（例如，C:\Users\YourUser\projects\screenshot-server）。

2. Windows 依赖项： 直接在 Windows 上的项目文件夹中安装 Python、uv 和项目依赖项 (uv sync ...)。

3. MCP 主机配置（在 WSL 中）： 配置您的 MCP 主机（在 WSL 中运行）以使用 PowerShell 在 Windows 上启动服务器。更新 mcp_settings.json（或等效文件）：

   {
     "mcpServers": {
       "Screenshot-server": {
         "command": "powershell.exe",
         "args": [
           "-Command",
           "Invoke-Command -ScriptBlock { cd '<YOUR_WINDOWS_PROJECT_PATH>'; & '<YOUR_WINDOWS_UV_PATH>' run screenshot.py }"
         ]
       }
       // ... 其他服务器 ...
     }
   }
   

   • 将路径替换为您的实际 Windows 路径。

4. 工作流程示例（WSL 中的 AI 助手）

1. AI 助手识别其当前工作区路径（例如，/home/user/current_project）。
2. AI 助手使用 use_mcp_tool 在 Screenshot-server 上调用 save_screenshot_to_host_workspace，传递 host_workspace_path="/home/user/current_project"，并可选择传递 name。
3. 接收 "success"。
4. AI 助手知道屏幕截图现在位于 /home/user/current_project/workspace_screenshot.jpg（或指定的名称）。
5. AI 助手使用 use_mcp_tool 调用 图像分析 服务器/工具（也在 WSL 中运行），传递 WSL 路径 /home/user/current_project/workspace_screenshot.jpg。
6. 图像分析服务器读取文件并执行其任务。

文件结构

• screenshot.py: 核心 MCP 服务器脚本。
• README.md: 此文档文件。
• pyproject.toml: 项目定义和 uv 的依赖项。
• uv.lock: 依赖项锁定文件。
• .gitignore: Git 忽略配置。
• .python-version: (可选) Python 版本说明符。
• server.log: 服务器生成的日志文件。
• images/: take_screenshot_and_return_path 的默认目录。