Screenshot Server

截图服务（专注于文件路径）

本项目提供了一个 MCP（模块化通信协议）服务，用于截取屏幕，并方便其他进程或 AI 助手使用截图，主要方式是将截图保存到客户端（Host）指定的文件路径。

核心问题与解决方案

测试发现，AI 助手直接解读通过 MCP 发送的截图图像数据并不可靠。本服务采用了更稳健的工作流，重点关注文件路径：

推荐工作流（WSL Host -> Windows 服务）：

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

替代工作流（通用）：

1. MCP Host 调用 take_screenshot_and_return_path，可选择指定文件名。
2. 服务将截图保存到本地 images/ 目录。
3. 服务返回已保存文件的绝对路径（例如，Windows 路径）。
4. MCP Host 接收该路径，并将其传递给分析服务（可能需要先进行转换）。

可用工具

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

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

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

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

  • **用途：**将截图保存到相对于服务位置的固定 images/ 目录，并返回绝对路径（通常是 Windows 路径）。如果调用方需要路径来进行外部处理，此工具会很有用。
  • 参数：
    • name (str，可选)：文件名。默认为 latest_screenshot.jpg。
  • 返回：str - 绝对路径或 "failed: [error message]"。

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

  • **用途：**将截图保存到由 Windows 路径或 UNC 路径指定的任意位置（例如，保存到 Host 工作区之外）。调用方需要仔细指定路径。
  • 参数：
    • path (str，可选)：目标目录（Windows 或 UNC 路径）。默认为服务的工作目录。
    • name (str，可选)：文件名。默认为 screenshot.jpg。
  • 返回：str - "success" 或 "failed: [error message]"。

设置与使用

1. 先决条件

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

  uv sync
  

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

2. 运行服务

通常由 MCP Host 根据其配置启动本服务。

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 }"
         ]
       }
       // ... other servers ...
     }
   }
   

   • 将路径替换为实际的 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 的默认目录。