Total PC Control

Total PC Control

一个 MCP（Model Context Protocol）服务，使用 nut.js 控制屏幕、鼠标和键盘。

⚠️ 警告：请谨慎使用

本软件支持以编程方式控制鼠标、键盘和其他系统操作。使用本软件即表示你知悉并接受以下事项：

• 通过此工具让 AI 模型直接控制你的计算机可能导致意外后果
• 本软件可以控制鼠标、键盘和其他系统功能
• 你完全自行承担使用本软件的风险
• 本项目的创建者和贡献者对使用本软件可能造成的任何损害、数据丢失或其他后果概不负责

功能

• 📷 屏幕捕获：截取整个屏幕或特定区域
• 🖱️ 鼠标控制：移动鼠标光标、单击、双击和滚动
• ⌨️ 键盘输入：输入文本并按下键盘快捷键
• 🪟 窗口管理：查找、聚焦和操作应用程序窗口
• 📋 剪贴板访问：复制和粘贴文本

先决条件

• Node.js 16 或更高版本
• npm 或 yarn
• cmake-js（用于构建原生依赖项）

安装

1. 克隆代码库：

git clone https://github.com/jasondsmith72/total-pc-control.git
cd total-pc-control

2. 全局安装 cmake-js（构建原生依赖项所需）：

npm install -g cmake-js

3. 安装 libnut 核心库（nut.js 所需）：

git clone https://github.com/nut-tree/libnut.git libnut-core
cd libnut-core
npm install
cmake-js rebuild
cd ..

4. 安装依赖项并构建项目：

npm install
npm run build

与 Claude for Desktop 搭配使用

1. 编辑 Claude for Desktop 配置文件：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

2. 将以下内容添加到配置中：

{
  "mcpServers": {
    "total-pc-control": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/total-pc-control/build/index.js"
      ]
    }
  }
}

将 /ABSOLUTE/PATH/TO/ 替换为克隆代码库的实际路径。

3. 重启 Claude for Desktop

4. 在 Claude 界面中查找锤子图标，确认可用工具。

可用工具

屏幕捕获

• capture_screen：将整个屏幕捕获为图像。支持 format（png/jpeg）和 quality（仅 jpeg）参数。
• capture_region：捕获屏幕的特定区域。需要 left、top、width、height。支持 format 和 quality。
• get_screen_size：获取屏幕的尺寸（宽度和高度）。

鼠标控制

• move_mouse：将鼠标光标移动到指定的 x、y 位置。
• get_mouse_position：获取鼠标光标当前的 x、y 位置。
• click_mouse：在当前位置单击鼠标。可选参数 button（left、middle、right）。
• click_at：在指定的 x、y 位置单击鼠标。可选参数 button。
• double_click：在当前位置双击鼠标。
• double_click_at：在指定的 x、y 位置双击鼠标。
• scroll_mouse：滚动鼠标滚轮。需要 direction（up/down）。可选参数 amount。
• drag_mouse：将鼠标从当前位置拖动到目标 x、y 位置。
• drag_mouse_from_to：将鼠标从 startX、startY 位置拖动到 endX、endY 位置。

键盘输入

• type_text：在当前光标位置输入文本。需要 text。
• type_text_with_delay：以按键间隔延迟的方式输入文本。需要 text。可选参数 delayMs。
• press_key：按下指定的键盘按键。需要 key。
• press_key_shortcut：按下键盘快捷键（组合按键）。需要 keys 数组。
• hold_key：按住键盘按键。需要 key。
• release_key：释放按住的键盘按键。需要 key。

剪贴板操作

• get_clipboard_text：获取剪贴板中的文本。
• set_clipboard_text：将文本设置到剪贴板中。需要提供 text。
• copy_selected_text：将所选文本复制到剪贴板并返回（使用 Ctrl+C/Cmd+C）。
• paste_text：在当前光标位置粘贴文本（使用 Ctrl+V/Cmd+V）。需要提供 text。
• get_clipboard_image：以 Base64 数据的形式获取剪贴板中的图像（如果有）。

UI 自动化工具（仅限 Windows）

这些工具通过 PowerShell 使用 Windows UI Automation 与 UI 元素交互。

• get_ui_element_info：在指定窗口中查找 UI 元素，并返回其属性（Name、AutomationId、ClassName、ControlType、BoundingRectangle、IsEnabled、IsOffscreen、Value、Children）。
  • 需要提供 windowTitle（可以是部分匹配）。
  • 要查找特定元素，至少需要提供 elementName、automationId 或 className 之一。
  • 如果未提供元素标识符，则列出窗口的直接子元素。
• invoke_ui_element_action：对指定的 UI 元素执行操作。
  • 需要提供 windowTitle。
  • 需要提供 action（Click、SetValue 或 Focus）。
  • 至少需要提供 elementName、automationId 或 className 之一。
  • 如果 action 为 SetValue，则需要提供 valueToSet（字符串）。

开发

在开发模式下运行服务：

npm run dev

运行测试：

npm test

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。